> ## 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.

# Varreduras de Hiperparâmetros

> Encontre automaticamente as configurações de treinamento ideais

# Varreduras de Hiperparâmetros

Pesquise automaticamente os melhores hiperparâmetros.

## Início 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             | 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)

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

### Espaço de Busca Personalizado

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

```python theme={null}
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:

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

### Busca em Grade

Busca exaustiva sobre todas as combinações:

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

### Busca Aleatória

Amostragem aleatória do espaço de busca:

```python theme={null}
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

```python theme={null}
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

```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 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.

<Note>
  **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.
</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 um Sweep Existente

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

```bash theme={null}
# 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
```

<Warning>
  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: {id}").
</Warning>

#### Acessando o Dashboard de Sweep

1. Acesse [wandb.ai](https://wandb.ai) e abra seu projeto
2. Clique no **ícone de Sweep** (vassoura) no painel esquerdo
3. 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    |

<Tip>
  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.
</Tip>

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

```bash theme={null}
# 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: {id}" 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

```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 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

```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 "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:

```python theme={null}
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()
```

<Note>
  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.
</Note>

## Melhores Práticas

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

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Evaluation" href="/advanced/evaluation-framework">
    Avaliar resultados da varredura
  </Card>

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