Barridos de Hiperparámetros

Busca automáticamente los mejores hiperparámetros.

Inicio Rápido

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

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)

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

Espacio de Búsqueda Personalizado

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

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:

params = LLMTrainingParams(
    ...
    use_sweep=True,
    sweep_backend="optuna",
)

Búsqueda en Rejilla

Búsqueda exhaustiva sobre todas las combinaciones:

params = LLMTrainingParams(
    ...
    use_sweep=True,
    sweep_backend="grid",
)

Búsqueda Aleatoria

Muestreo aleatorio del espacio de búsqueda:

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

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

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

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.

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.

Habilitando W&B Sweeps

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:

# 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

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: ”).

Accediendo al Dashboard de Sweep

Ve a wandb.ai y abre tu proyecto
Haz clic en el icono de Sweep (escoba) en el panel izquierdo
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

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.

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:

# 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: ” 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

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

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:

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()

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.

Mejores Prácticas

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

​Barridos de Hiperparámetros

​Inicio Rápido

​Python API

​Parámetros

​Espacios de Búsqueda

​Espacio de Búsqueda Por Defecto

​Espacio de Búsqueda Personalizado

​Backends de Barrido

​Optuna

​Búsqueda en Rejilla

​Búsqueda Aleatoria

​Métricas

​Métricas Estándar

​Métricas de Evaluación Mejoradas

​Parámetros de Evaluación Mejorada

​Benchmarks Estándar

​Ejemplo de Métricas Personalizadas

​Ejemplo: Encontrar Mejor LR

​Visualizando Resultados

​Dashboard Optuna

​Dashboard Nativo de Sweeps W&B

​Habilitando W&B Sweeps

​Continuando un Sweep Existente

​Accediendo al Dashboard de Sweep

​Visualizaciones Integradas

​Usando con Agentes de Sweep W&B Externos

​Notas Importantes

​Acciones Post-Trial

​Uso en CLI

​Variables de Entorno

​Ejemplo: Git Commit para Mejores Modelos

​Python API con Callback

​Mejores Prácticas

​Próximos Pasos

Evaluation

LoRA/PEFT

Barridos de Hiperparámetros

Inicio Rápido

Python API

Parámetros

Espacios de Búsqueda

Espacio de Búsqueda Por Defecto

Espacio de Búsqueda Personalizado

Backends de Barrido

Optuna

Búsqueda en Rejilla

Búsqueda Aleatoria

Métricas

Métricas Estándar

Métricas de Evaluación Mejoradas

Parámetros de Evaluación Mejorada

Benchmarks Estándar

Ejemplo de Métricas Personalizadas

Ejemplo: Encontrar Mejor LR

Visualizando Resultados

Dashboard Optuna

Dashboard Nativo de Sweeps W&B

Habilitando W&B Sweeps

Continuando un Sweep Existente

Accediendo al Dashboard de Sweep

Visualizaciones Integradas

Usando con Agentes de Sweep W&B Externos

Notas Importantes

Acciones Post-Trial

Uso en CLI

Variables de Entorno

Ejemplo: Git Commit para Mejores Modelos

Python API con Callback

Mejores Prácticas

Próximos Pasos