> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monostate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Barridos de Hiperparámetros

> Encuentra automáticamente las configuraciones de entrenamiento óptimas

# Barridos de Hiperparámetros

Busca automáticamente los mejores hiperparámetros.

## Inicio Rápido

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data.jsonl \
  --project-name sweep-experiment \
  --use-sweep \
  --sweep-backend optuna \
  --sweep-n-trials 20
```

## Python API

```python theme={null}
from autotrain.trainers.clm.params import LLMTrainingParams

params = LLMTrainingParams(
    model="google/gemma-3-270m",
    data_path="./data.jsonl",
    project_name="sweep-experiment",

    # Enable sweep
    use_sweep=True,
    sweep_backend="optuna",
    sweep_n_trials=20,
    sweep_metric="eval_loss",
    sweep_direction="minimize",

    # Base parameters (sweep will vary some)
    trainer="sft",
    epochs=3,
    batch_size=4,
    lr=2e-5,
)
```

## Parámetros

| Parámetro             | Descripción                                                | Por Defecto          |
| --------------------- | ---------------------------------------------------------- | -------------------- |
| `use_sweep`           | Habilitar barrido                                          | `False`              |
| `sweep_backend`       | Backend (`optuna`, `grid`, `random`)                       | `optuna`             |
| `sweep_n_trials`      | Número de intentos                                         | `10`                 |
| `sweep_metric`        | Métrica a optimizar                                        | `eval_loss`          |
| `sweep_direction`     | minimizar o maximizar                                      | `minimize`           |
| `sweep_params`        | Espacio de búsqueda personalizado (cadena JSON)            | `None` (automático)  |
| `post_trial_script`   | Script shell a ejecutar después de cada trial              | `None`               |
| `wandb_sweep`         | Habilitar dashboard nativo de sweeps W\&B                  | `False`              |
| `wandb_sweep_project` | Proyecto W\&B para sweep                                   | `project_name`       |
| `wandb_sweep_entity`  | Entidad W\&B (equipo/usuario)                              | `None` (usa default) |
| `wandb_sweep_id`      | ID de sweep existente para continuar                       | `None` (crea nuevo)  |
| `wandb_run_id`        | ID de run W\&B a reanudar (para agentes de sweep externos) | `None`               |

## Espacios de Búsqueda

### Espacio de Búsqueda Por Defecto

Por defecto, los barridos buscan sobre:

* Tasa de aprendizaje: 1e-5 a 1e-3 (uniforme log)
* Tamaño de batch: 2, 4, 8, 16 (categórico)
* Ratio de warmup: 0.0 a 0.2 (uniforme)

<Note>
  El rango LoRA NO está incluido en el barrido por defecto. Añádelo manualmente vía `sweep_params` si es necesario.
</Note>

### Espacio de Búsqueda Personalizado

El parámetro `sweep_params` espera una cadena JSON. Se soportan formatos de lista y diccionario:

```python theme={null}
import json

# Formato dict (recomendado) - especificación explícita de tipo
sweep_params = json.dumps({
    "lr": {"type": "loguniform", "low": 1e-6, "high": 1e-3},
    "batch_size": {"type": "categorical", "values": [2, 4, 8]},
    "lora_r": {"type": "categorical", "values": [8, 16, 32, 64]},
    "warmup_ratio": {"type": "uniform", "low": 0.0, "high": 0.2},
    "epochs": {"type": "int", "low": 1, "high": 5},
})

# Formato lista (abreviado) - solo para valores categóricos
sweep_params = json.dumps({
    "batch_size": [2, 4, 8],
    "lora_r": [8, 16, 32, 64],
})

params = LLMTrainingParams(
    ...
    use_sweep=True,
    sweep_params=sweep_params,  # JSON string
)
```

**Tipos dict soportados:**

| Tipo          | Descripción               | Parámetros                  |
| ------------- | ------------------------- | --------------------------- |
| `categorical` | Elegir de lista           | `values`: lista de opciones |
| `loguniform`  | Distribución log-uniforme | `low`, `high`               |
| `uniform`     | Distribución uniforme     | `low`, `high`               |
| `int`         | Rango entero              | `low`, `high`               |

## Backends de Barrido

### Optuna

Optimización bayesiana eficiente:

```python theme={null}
params = LLMTrainingParams(
    ...
    use_sweep=True,
    sweep_backend="optuna",
)
```

### Búsqueda en Rejilla

Búsqueda exhaustiva sobre todas las combinaciones:

```python theme={null}
params = LLMTrainingParams(
    ...
    use_sweep=True,
    sweep_backend="grid",
)
```

### Búsqueda Aleatoria

Muestreo aleatorio del espacio de búsqueda:

```python theme={null}
params = LLMTrainingParams(
    ...
    use_sweep=True,
    sweep_backend="random",
)
```

## Métricas

### Métricas Estándar

| Métrica      | Descripción                        |
| ------------ | ---------------------------------- |
| `eval_loss`  | Pérdida de validación              |
| `train_loss` | Pérdida de entrenamiento           |
| `accuracy`   | Precisión de clasificación         |
| `perplexity` | Perplejidad del modelo de lenguaje |

### Métricas de Evaluación Mejoradas

Habilita `use_enhanced_eval` para acceder a métricas adicionales:

| Métrica       | Descripción                                      |
| ------------- | ------------------------------------------------ |
| `perplexity`  | Perplejidad del modelo de lenguaje (por defecto) |
| `bleu`        | Puntuación BLEU para traducción/generación       |
| `rouge`       | Puntuación ROUGE para resumen                    |
| `bertscore`   | BERTScore para similitud semántica               |
| `accuracy`    | Precisión de clasificación                       |
| `f1`          | Puntuación F1                                    |
| `exact_match` | Precisión de coincidencia exacta                 |
| `meteor`      | Puntuación METEOR                                |

### Parámetros de Evaluación Mejorada

| Parámetro               | Descripción                                  | Por Defecto    |
| ----------------------- | -------------------------------------------- | -------------- |
| `use_enhanced_eval`     | Habilitar métricas mejoradas                 | `False`        |
| `eval_metrics`          | Métricas separadas por comas                 | `"perplexity"` |
| `eval_strategy`         | Cuándo evaluar (`epoch`, `steps`, `no`)      | `"epoch"`      |
| `eval_batch_size`       | Tamaño de batch para evaluación              | `8`            |
| `eval_dataset_path`     | Ruta al dataset de evaluación (si diferente) | `None`         |
| `eval_save_predictions` | Guardar predicciones durante evaluación      | `False`        |
| `eval_benchmark`        | Ejecutar benchmark estándar                  | `None`         |

### Benchmarks Estándar

Usa `eval_benchmark` para ejecutar benchmarks estándar de LLM:

| Benchmark    | Descripción                              |
| ------------ | ---------------------------------------- |
| `mmlu`       | Massive Multitask Language Understanding |
| `hellaswag`  | Razonamiento de sentido común HellaSwag  |
| `arc`        | AI2 Reasoning Challenge                  |
| `truthfulqa` | Veracidad TruthfulQA                     |

### Ejemplo de Métricas Personalizadas

```python theme={null}
params = LLMTrainingParams(
    ...
    use_sweep=True,
    sweep_metric="bleu",
    use_enhanced_eval=True,
    eval_metrics="bleu,rouge,bertscore",
    eval_batch_size=8,
)
```

## Ejemplo: Encontrar Mejor LR

```python theme={null}
import json

params = LLMTrainingParams(
    model="google/gemma-3-270m",
    data_path="./data.jsonl",
    project_name="lr-sweep",

    use_sweep=True,
    sweep_n_trials=10,
    sweep_params=json.dumps({
        "lr": {"type": "loguniform", "low": 1e-6, "high": 1e-3},
    }),

    # Fixed parameters
    trainer="sft",
    epochs=1,
    batch_size=4,
)
```

## Visualizando Resultados

### Dashboard Optuna

```bash theme={null}
pip install optuna-dashboard
optuna-dashboard sqlite:///optuna.db
```

### Dashboard Nativo de Sweeps W\&B

Por defecto, los sweeps se ejecutan localmente y solo registran ejecuciones individuales en W\&B. Habilita la **integración nativa de sweeps W\&B** para obtener vistas agregadas, gráficos de coordenadas paralelas y análisis de importancia de parámetros en un dashboard de sweep dedicado.

<Note>
  **Local vs W\&B Sweeps**: Sin `wandb_sweep=True`, cada trial se registra como una ejecución separada de W\&B. Con `wandb_sweep=True`, todos los trials se agrupan bajo un único dashboard de sweep con visualizaciones unificadas.
</Note>

#### Habilitando W\&B Sweeps

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data.jsonl \
  --project-name sweep-experiment \
  --use-sweep \
  --sweep-backend optuna \
  --sweep-n-trials 20 \
  --log wandb \
  --wandb-sweep \
  --wandb-sweep-project my-sweep-project \
  --wandb-sweep-entity my-team
```

#### Continuando un Sweep Existente

Para agregar más trials a un sweep existente en lugar de crear uno nuevo, pasa el ID del sweep:

```bash theme={null}
# Primera ejecución crea sweep (imprime "Created W&B sweep: abc123xyz")
aitraining llm --train \
  --use-sweep --sweep-n-trials 10 \
  --wandb-sweep --wandb-sweep-project my-project

# Después, continúa el mismo sweep con más trials
aitraining llm --train \
  --use-sweep --sweep-n-trials 10 \
  --wandb-sweep --wandb-sweep-project my-project \
  --wandb-sweep-id abc123xyz
```

<Warning>
  Si no pasas `wandb_sweep_id`, **se crea un nuevo sweep cada vez**. El ID del sweep se imprime en los logs cuando comienza el sweep (busca "Created W\&B sweep: {id}").
</Warning>

#### Accediendo al Dashboard de Sweep

1. Ve a [wandb.ai](https://wandb.ai) y abre tu proyecto
2. Haz clic en el **icono de Sweep** (escoba) en el panel izquierdo
3. Selecciona tu sweep de la lista

#### Visualizaciones Integradas

W\&B genera automáticamente tres visualizaciones:

| Visualización                        | Descripción                                                       |
| ------------------------------------ | ----------------------------------------------------------------- |
| **Gráfico de Coordenadas Paralelas** | Muestra relaciones entre hiperparámetros y métricas de un vistazo |
| **Gráfico de Dispersión**            | Compara todas las ejecuciones para identificar patrones           |
| **Importancia de Parámetros**        | Clasifica qué hiperparámetros más afectan tu métrica              |

<Tip>
  El gráfico de coordenadas paralelas es especialmente útil para identificar qué combinaciones de hiperparámetros llevan a los mejores resultados. Puedes arrastrar en cualquier eje para filtrar ejecuciones.
</Tip>

#### Usando con Agentes de Sweep W\&B Externos

Si estás ejecutando AITraining desde un agente de sweep W\&B externo (no el sweep integrado de AITraining), usa `--wandb-run-id` para reanudar el run del agente en lugar de crear un duplicado:

```bash theme={null}
# Agente de sweep W&B externo llama a AITraining con ID de run
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data.jsonl \
  --wandb-run-id $WANDB_RUN_ID \
  --lr $SWEEP_LR \
  --batch-size $SWEEP_BATCH_SIZE
```

Cuando se establece `--wandb-run-id`, AITraining automáticamente configura `WANDB_RESUME=allow` para que el trainer reanude el run especificado en lugar de crear uno nuevo.

#### Notas Importantes

* **Requiere login de W\&B**: Ejecuta `wandb login` antes de usar W\&B sweeps
* **El ID del sweep se registra**: Busca "Created W\&B sweep: {id}" en los logs
* **Los trials se agrupan**: Cada trial aparece como una ejecución con `group={sweep_id}` para agregación
* **Optuna sigue gestionando la búsqueda**: W\&B es solo para visualización; Optuna/grid/random maneja la búsqueda real de hiperparámetros

## Acciones Post-Trial

Ejecuta acciones personalizadas después de que cada trial complete, como hacer commit de checkpoints a git, enviar notificaciones, o sincronizar a almacenamiento remoto.

### Uso en CLI

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data.jsonl \
  --project-name sweep-experiment \
  --use-sweep \
  --sweep-n-trials 10 \
  --post-trial-script 'echo "Trial $TRIAL_NUMBER completado con métrica $TRIAL_METRIC_VALUE"'
```

### Variables de Entorno

El script post-trial recibe estas variables de entorno:

| Variable             | Descripción                           | Ejemplo                           |
| -------------------- | ------------------------------------- | --------------------------------- |
| `TRIAL_NUMBER`       | Índice del trial (basado en 0)        | `0`, `1`, `2`                     |
| `TRIAL_METRIC_VALUE` | Valor de la métrica para este trial   | `0.234`                           |
| `TRIAL_IS_BEST`      | Si este es el mejor trial hasta ahora | `true` o `false`                  |
| `TRIAL_OUTPUT_DIR`   | Directorio de salida del trial        | `/path/to/sweep/trial_0`          |
| `TRIAL_PARAMS`       | Parámetros del trial como string      | `{'lr': 0.0001, 'batch_size': 8}` |

### Ejemplo: Git Commit para Mejores Modelos

```bash theme={null}
aitraining llm --train \
  --use-sweep \
  --sweep-n-trials 20 \
  --post-trial-script 'if [ "$TRIAL_IS_BEST" = "true" ]; then git add . && git commit -m "Mejor modelo: trial $TRIAL_NUMBER, métrica $TRIAL_METRIC_VALUE"; fi'
```

### Python API con Callback

Para mayor control, usa el API de Python con una función callback:

```python theme={null}
from autotrain.utils import HyperparameterSweep, SweepConfig, TrialInfo

def on_trial_complete(trial_info: TrialInfo):
    """Llamado después de que cada trial complete."""
    print(f"Trial {trial_info.trial_number} completado")
    print(f"  Params: {trial_info.params}")
    print(f"  Métrica: {trial_info.metric_value}")
    print(f"  Es mejor: {trial_info.is_best}")

    if trial_info.is_best:
        # Hacer algo especial para mejores trials
        save_best_model(trial_info.output_dir)

config = SweepConfig(
    parameters={"lr": (1e-5, 1e-3, "log_uniform")},
    n_trials=10,
    backend="optuna",
    post_trial_callback=on_trial_complete,
)

sweep = HyperparameterSweep(config, train_function)
result = sweep.run()
```

<Note>
  Las acciones post-trial son no bloqueantes. Si un callback o script falla, se registra una advertencia pero el sweep continúa. Esto asegura que el progreso del sweep no se pierda debido a errores de callback.
</Note>

## Mejores Prácticas

1. **Comienza pequeño** - 10-20 intentos para exploración inicial
2. **Usa early stopping** - Detén intentos malos temprano
3. **Fija lo que sabes** - Solo barre parámetros inciertos
4. **Usa datos de validación** - Siempre ten división de evaluación
5. **Usa scripts post-trial** - Automatiza checkpointing o notificaciones

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Evaluation" href="/advanced/evaluation-framework">
    Evalúa resultados del barrido
  </Card>

  <Card title="LoRA/PEFT" href="/advanced/lora-peft">
    Fine-tuning eficiente
  </Card>
</CardGroup>