Varreduras de Hiperparâmetros

Pesquise automaticamente os melhores hiperparâmetros.

Início 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	Descrição	Padrão
`use_sweep`	Habilitar varredura	`False`
`sweep_backend`	Backend (`optuna`, `grid`, `random`)	`optuna`
`sweep_n_trials`	Número de tentativas	`10`
`sweep_metric`	Métrica para otimizar	`eval_loss`
`sweep_direction`	minimizar ou maximizar	`minimize`
`sweep_params`	Espaço de busca personalizado (string JSON)	`None` (automático)
`post_trial_script`	Script shell a executar após cada trial	`None`
`wandb_sweep`	Habilitar dashboard nativo de sweeps W&B	`False`
`wandb_sweep_project`	Projeto W&B para sweep	`project_name`
`wandb_sweep_entity`	Entidade W&B (equipe/usuário)	`None` (usa padrão)
`wandb_sweep_id`	ID de sweep existente para continuar	`None` (cria novo)
`wandb_run_id`	ID de run W&B para retomar (para agentes de sweep externos)	`None`

Espaços de Busca

Espaço de Busca Padrão

Por padrão, as varreduras pesquisam sobre:

Taxa de aprendizado: 1e-5 a 1e-3 (uniforme log)
Tamanho do batch: 2, 4, 8, 16 (categórico)
Razão de warmup: 0.0 a 0.2 (uniforme)

O rank LoRA NÃO está incluído na varredura padrão. Adicione manualmente via sweep_params se necessário.

Espaço de Busca Personalizado

O parâmetro sweep_params espera uma string JSON. Formatos de lista e dicionário são suportados:

import json

# Formato dict (recomendado) - especificação 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) - apenas 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 suportados:

Tipo	Descrição	Parâmetros
`categorical`	Escolher da lista	`values`: lista de opções
`loguniform`	Distribuição log-uniforme	`low`, `high`
`uniform`	Distribuição uniforme	`low`, `high`
`int`	Intervalo inteiro	`low`, `high`

Backends de Varredura

Optuna

Otimização bayesiana eficiente:

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

Busca em Grade

Busca exaustiva sobre todas as combinações:

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

Busca Aleatória

Amostragem aleatória do espaço de busca:

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

Métricas

Métricas Padrão

Métrica	Descrição
`eval_loss`	Perda de validação
`train_loss`	Perda de treinamento
`accuracy`	Precisão de classificação
`perplexity`	Perplexidade do modelo de linguagem

Métricas de Avaliação Aprimoradas

Habilite use_enhanced_eval para acessar métricas adicionais:

Métrica	Descrição
`perplexity`	Perplexidade do modelo de linguagem (padrão)
`bleu`	Pontuação BLEU para tradução/geração
`rouge`	Pontuação ROUGE para sumarização
`bertscore`	BERTScore para similaridade semântica
`accuracy`	Precisão de classificação
`f1`	Pontuação F1
`exact_match`	Precisão de correspondência exata
`meteor`	Pontuação METEOR

Parâmetros de Avaliação Aprimorada

Parâmetro	Descrição	Padrão
`use_enhanced_eval`	Habilitar métricas aprimoradas	`False`
`eval_metrics`	Métricas separadas por vírgula	`"perplexity"`
`eval_strategy`	Quando avaliar (`epoch`, `steps`, `no`)	`"epoch"`
`eval_batch_size`	Tamanho do batch para avaliação	`8`
`eval_dataset_path`	Caminho para dataset de avaliação (se diferente)	`None`
`eval_save_predictions`	Salvar predições durante avaliação	`False`
`eval_benchmark`	Executar benchmark padrão	`None`

Benchmarks Padrão

Use eval_benchmark para executar benchmarks padrão de LLM:

Benchmark	Descrição
`mmlu`	Massive Multitask Language Understanding
`hellaswag`	Raciocínio de senso comum HellaSwag
`arc`	AI2 Reasoning Challenge
`truthfulqa`	Veracidade TruthfulQA

Exemplo 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,
)

Exemplo: Encontrar Melhor 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 padrão, sweeps rodam localmente e apenas registram execuções individuais no W&B. Habilite a integração nativa de sweeps W&B para obter visualizações agregadas, gráficos de coordenadas paralelas e análise de importância de parâmetros em um dashboard de sweep dedicado.

Local vs W&B Sweeps: Sem wandb_sweep=True, cada trial é registrado como uma execução separada no W&B. Com wandb_sweep=True, todos os trials são agrupados em um único dashboard de sweep com visualizações 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 um Sweep Existente

Para adicionar mais trials a um sweep existente em vez de criar um novo, passe o ID do sweep:

# Primeira execução cria sweep (imprime "Created W&B sweep: abc123xyz")
aitraining llm --train \
  --use-sweep --sweep-n-trials 10 \
  --wandb-sweep --wandb-sweep-project my-project

# Depois, continue o mesmo sweep com mais trials
aitraining llm --train \
  --use-sweep --sweep-n-trials 10 \
  --wandb-sweep --wandb-sweep-project my-project \
  --wandb-sweep-id abc123xyz

Se você não passar wandb_sweep_id, um novo sweep é criado toda vez. O ID do sweep é impresso nos logs quando o sweep começa (procure por “Created W&B sweep: ”).

Acessando o Dashboard de Sweep

Acesse wandb.ai e abra seu projeto
Clique no ícone de Sweep (vassoura) no painel esquerdo
Selecione seu sweep da lista

Visualizações Integradas

O W&B gera automaticamente três visualizações:

Visualização	Descrição
Gráfico de Coordenadas Paralelas	Mostra relações entre hiperparâmetros e métricas de relance
Gráfico de Dispersão	Compara todas as execuções para identificar padrões
Importância de Parâmetros	Classifica quais hiperparâmetros mais afetam sua métrica

O gráfico de coordenadas paralelas é especialmente útil para identificar quais combinações de hiperparâmetros levam aos melhores resultados. Você pode arrastar em qualquer eixo para filtrar execuções.

Usando com Agentes de Sweep W&B Externos

Se você está executando AITraining a partir de um agente de sweep W&B externo (não o sweep integrado do AITraining), use --wandb-run-id para retomar o run do agente em vez de criar um duplicado:

# Agente de sweep W&B externo chama AITraining com ID do 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

Quando --wandb-run-id é definido, AITraining automaticamente configura WANDB_RESUME=allow para que o trainer retome o run especificado em vez de criar um novo.

Notas Importantes

Requer login no W&B: Execute wandb login antes de usar W&B sweeps
O ID do sweep é registrado: Procure “Created W&B sweep: ” nos logs
Trials são agrupados: Cada trial aparece como uma execução com group={sweep_id} para agregação
Optuna ainda gerencia a busca: W&B é apenas para visualização; Optuna/grid/random gerencia a busca real de hiperparâmetros

Ações Pós-Trial

Execute ações personalizadas após cada trial completar, como fazer commit de checkpoints no git, enviar notificações ou sincronizar com armazenamento remoto.

Uso no 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 com métrica $TRIAL_METRIC_VALUE"'

Variáveis de Ambiente

O script pós-trial recebe estas variáveis de ambiente:

Variável	Descrição	Exemplo
`TRIAL_NUMBER`	Índice do trial (baseado em 0)	`0`, `1`, `2`
`TRIAL_METRIC_VALUE`	Valor da métrica para este trial	`0.234`
`TRIAL_IS_BEST`	Se este é o melhor trial até agora	`true` ou `false`
`TRIAL_OUTPUT_DIR`	Diretório de saída do trial	`/path/to/sweep/trial_0`
`TRIAL_PARAMS`	Parâmetros do trial como string	`{'lr': 0.0001, 'batch_size': 8}`

Exemplo: Git Commit para Melhores Modelos

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

Python API com Callback

Para maior controle, use o Python API com uma função callback:

from autotrain.utils import HyperparameterSweep, SweepConfig, TrialInfo

def on_trial_complete(trial_info: TrialInfo):
    """Chamado após cada trial completar."""
    print(f"Trial {trial_info.trial_number} completado")
    print(f"  Params: {trial_info.params}")
    print(f"  Métrica: {trial_info.metric_value}")
    print(f"  É melhor: {trial_info.is_best}")

    if trial_info.is_best:
        # Fazer algo especial para melhores 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()

Ações pós-trial são não bloqueantes. Se um callback ou script falhar, um aviso é registrado mas o sweep continua. Isso garante que o progresso do sweep não seja perdido devido a erros de callback.

Melhores Práticas

Comece pequeno - 10-20 tentativas para exploração inicial
Use early stopping - Pare tentativas ruins cedo
Fix o que você sabe - Varre apenas parâmetros incertos
Use dados de validação - Sempre tenha divisão de avaliação
Use scripts pós-trial - Automatize checkpointing ou notificações

​Varreduras de Hiperparâmetros

​Início Rápido

​Python API

​Parâmetros

​Espaços de Busca

​Espaço de Busca Padrão

​Espaço de Busca Personalizado

​Backends de Varredura

​Optuna

​Busca em Grade

​Busca Aleatória

​Métricas

​Métricas Padrão

​Métricas de Avaliação Aprimoradas

​Parâmetros de Avaliação Aprimorada

​Benchmarks Padrão

​Exemplo de Métricas Personalizadas

​Exemplo: Encontrar Melhor LR

​Visualizando Resultados

​Dashboard Optuna

​Dashboard Nativo de Sweeps W&B

​Habilitando W&B Sweeps

​Continuando um Sweep Existente

​Acessando o Dashboard de Sweep

​Visualizações Integradas

​Usando com Agentes de Sweep W&B Externos

​Notas Importantes

​Ações Pós-Trial

​Uso no CLI

​Variáveis de Ambiente

​Exemplo: Git Commit para Melhores Modelos

​Python API com Callback

​Melhores Práticas

​Próximos Passos

Evaluation

LoRA/PEFT

Varreduras de Hiperparâmetros

Início Rápido

Python API

Parâmetros

Espaços de Busca

Espaço de Busca Padrão

Espaço de Busca Personalizado

Backends de Varredura

Optuna

Busca em Grade

Busca Aleatória

Métricas

Métricas Padrão

Métricas de Avaliação Aprimoradas

Parâmetros de Avaliação Aprimorada

Benchmarks Padrão

Exemplo de Métricas Personalizadas

Exemplo: Encontrar Melhor LR

Visualizando Resultados

Dashboard Optuna

Dashboard Nativo de Sweeps W&B

Habilitando W&B Sweeps

Continuando um Sweep Existente

Acessando o Dashboard de Sweep

Visualizações Integradas

Usando com Agentes de Sweep W&B Externos

Notas Importantes

Ações Pós-Trial

Uso no CLI

Variáveis de Ambiente

Exemplo: Git Commit para Melhores Modelos

Python API com Callback

Melhores Práticas

Próximos Passos