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

# Treinamento LLM

> Treine modelos de linguagem grandes com o CLI

# Treinamento LLM

O comando `aitraining llm` treina modelos de linguagem grandes com suporte para múltiplos trainers e técnicas.

## Início Rápido

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --trainer sft
```

## Trainers Disponíveis

| Trainer                       | Descrição                                                           |
| ----------------------------- | ------------------------------------------------------------------- |
| `default` / `sft` / `generic` | Fine-tuning supervisionado                                          |
| `dpo`                         | Otimização Direta de Preferências                                   |
| `orpo`                        | Otimização de Razão de Chances de Preferências                      |
| `ppo`                         | Otimização de Política Proximal                                     |
| `grpo`                        | Otimização de Política Relativa de Grupo (ambientes personalizados) |
| `reward`                      | Treinamento de modelo de recompensa                                 |
| `distillation`                | Distilação de conhecimento                                          |

<Note>
  `generic` é um alias para `default`. Todos os três (`default`, `sft`, `generic`) produzem o mesmo comportamento.
</Note>

<Warning>
  **Requisitos do Trainer PPO**: PPO requer `--rl-reward-model-path` (caminho para um modelo de recompensa treinado) ou `--model-ref` (modelo de referência para divergência KL). Veja [Treinamento PPO](/advanced/ppo-rl-training) para documentação completa.
</Warning>

<Warning>
  **Requisitos do Trainer GRPO**: GRPO requer `--rl-env-module` (caminho do módulo Python) e `--rl-env-class` (nome da classe) para o ambiente personalizado. Veja [Treinamento GRPO](/advanced/grpo-training) para documentação completa.
</Warning>

## Grupos de Parâmetros

Os parâmetros são organizados em grupos lógicos:

### Parâmetros Básicos

| Parameter        | Description             | Default               |
| ---------------- | ----------------------- | --------------------- |
| `--model`        | Base model to fine-tune | `google/gemma-3-270m` |
| `--data-path`    | Path to training data   | `data`                |
| `--project-name` | Output directory name   | `project-name`        |
| `--train-split`  | Training data split     | `train`               |
| `--valid-split`  | Validation data split   | `None`                |

<Note>
  **Sempre especifique esses parâmetros**: Embora `--model`, `--data-path` e `--project-name` tenham padrões, você deve sempre defini-los explicitamente para seu caso de uso. O parâmetro `--project-name` define a pasta de saída - use um caminho como `--project-name ./models/my-experiment` para controlar onde o modelo treinado é salvo.
</Note>

### Configuração de Treinamento

| Parameter                 | Description               | Default       |
| ------------------------- | ------------------------- | ------------- |
| `--trainer`               | Training method           | `default`     |
| `--epochs`                | Number of training epochs | `1`           |
| `--batch-size`            | Training batch size       | `2`           |
| `--lr`                    | Learning rate             | `3e-5`        |
| `--mixed-precision`       | fp16/bf16/None            | `None`        |
| `--gradient-accumulation` | Accumulation steps        | `4`           |
| `--warmup-ratio`          | Warmup ratio              | `0.1`         |
| `--optimizer`             | Optimizer                 | `adamw_torch` |
| `--scheduler`             | LR scheduler              | `linear`      |
| `--weight-decay`          | Weight decay              | `0.0`         |
| `--max-grad-norm`         | Max gradient norm         | `1.0`         |
| `--seed`                  | Random seed               | `42`          |

### Checkpointing e Avaliação

| Parameter                  | Description                                             | Default |
| -------------------------- | ------------------------------------------------------- | ------- |
| `--eval-strategy`          | When to evaluate (`epoch`, `steps`, `no`)               | `epoch` |
| `--save-strategy`          | When to save (`epoch`, `steps`, `no`)                   | `epoch` |
| `--save-steps`             | Save every N steps (if save-strategy=steps)             | `500`   |
| `--save-total-limit`       | Max checkpoints to keep                                 | `1`     |
| `--logging-steps`          | Log every N steps (-1 for auto)                         | `-1`    |
| `--resume-from-checkpoint` | Resume from checkpoint path, or `auto` to detect latest | `None`  |

### Performance e Memória

| Parameter                          | Description                                                           | Default |
| ---------------------------------- | --------------------------------------------------------------------- | ------- |
| `--auto-find-batch-size`           | Automatically find optimal batch size                                 | `False` |
| `--disable-gradient-checkpointing` | Disable memory optimization                                           | `False` |
| `--unsloth`                        | Use Unsloth for faster training (SFT only, llama/mistral/gemma/qwen2) | `False` |
| `--use-sharegpt-mapping`           | Use Unsloth's ShareGPT mapping                                        | `False` |
| `--use-flash-attention-2`          | Use Flash Attention 2 for faster training                             | `False` |
| `--attn-implementation`            | Attention implementation (`eager`, `sdpa`, `flash_attention_2`)       | `None`  |

<Note>
  **Requisitos do Unsloth**: Unsloth funciona apenas com trainers `sft`/`default` e arquiteturas de modelo específicas (llama, mistral, gemma, qwen2). Veja [Integração Unsloth](/advanced/unsloth-integration) para detalhes.
</Note>

### Backend e Distribuição

| Parameter               | Description                               | Default |
| ----------------------- | ----------------------------------------- | ------- |
| `--backend`             | Where to run (`local`, `spaces`)          | `local` |
| `--distributed-backend` | Distribution backend (`ddp`, `deepspeed`) | `None`  |
| `--ddp-timeout`         | DDP/NCCL timeout in seconds               | `7200`  |

<Note>
  **Comportamento Multi-GPU**: Com múltiplas GPUs e `--distributed-backend` não definido, DDP é usado automaticamente. Defina `--distributed-backend deepspeed` para otimização DeepSpeed Zero-3. O treinamento é iniciado via Accelerate.
</Note>

<Warning>
  **Checkpointing DeepSpeed**: Ao usar DeepSpeed, o salvamento do modelo usa `accelerator.get_state_dict()` e desempacota o modelo. O salvamento do adaptador PEFT é tratado de forma diferente sob DeepSpeed.
</Warning>

### Parâmetros PEFT/LoRA

| Parameter          | Description               | Default      |
| ------------------ | ------------------------- | ------------ |
| `--peft`           | Enable LoRA training      | `False`      |
| `--lora-r`         | LoRA rank                 | `16`         |
| `--lora-alpha`     | LoRA alpha                | `32`         |
| `--lora-dropout`   | LoRA dropout              | `0.05`       |
| `--target-modules` | Modules to target         | `all-linear` |
| `--quantization`   | int4/int8 quantization    | `None`       |
| `--merge-adapter`  | Merge LoRA after training | `True`       |

### Processamento de Dados

| Parameter                | Description                                                 | Default                |
| ------------------------ | ----------------------------------------------------------- | ---------------------- |
| `--text-column`          | Text column name                                            | `text`                 |
| `--block-size`           | Max sequence length                                         | `-1` (model default)   |
| `--model-max-length`     | Maximum model input length                                  | Auto-detect from model |
| `--padding`              | Padding side (`left` or `right`)                            | `right`                |
| `--add-eos-token`        | Append EOS token                                            | `True`                 |
| `--chat-template`        | Chat template to use                                        | Auto by trainer        |
| `--packing`              | Enable sequence packing (requires flash attention)          | `None`                 |
| `--auto-convert-dataset` | Auto-detect and convert dataset format                      | `False`                |
| `--max-samples`          | Limit dataset size for testing                              | `None`                 |
| `--save-processed-data`  | Save processed data: `auto`, `local`, `hub`, `both`, `none` | `auto`                 |

<Note>
  **Seleção Automática de Template de Chat**: Trainers SFT/DPO/ORPO/Reward usam `tokenizer` (template integrado do modelo) por padrão. Use `--chat-template none` para treinamento de texto simples.
</Note>

<Note>
  **Salvamento de Dados Processados**: Por padrão (`auto`), dados processados são salvos localmente em `{project}/data_processed/`. Se o dataset fonte era do Hub, também é enviado como dataset privado. Colunas originais são renomeadas para `_original_*` para prevenir conflitos.
</Note>

## Exemplos de Treinamento

### SFT with LoRA

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-1B \
  --data-path ./conversations.jsonl \
  --project-name llama-sft \
  --trainer sft \
  --peft \
  --lora-r 16 \
  --lora-alpha 32 \
  --epochs 3 \
  --batch-size 4
```

### Treinamento DPO

Para DPO, você deve especificar os nomes das colunas para prompt, resposta escolhida e resposta rejeitada:

```bash theme={null}
aitraining llm --train \
  --model meta-llama/Llama-3.2-1B \
  --data-path ./preferences.jsonl \
  --project-name llama-dpo \
  --trainer dpo \
  --prompt-text-column prompt \
  --text-column chosen \
  --rejected-text-column rejected \
  --dpo-beta 0.1 \
  --peft \
  --lora-r 16
```

<Warning>
  DPO e ORPO requerem que `--prompt-text-column` e `--rejected-text-column` sejam especificados.
</Warning>

### Treinamento ORPO

ORPO combina SFT e otimização de preferências:

```bash theme={null}
aitraining llm --train \
  --model google/gemma-2-2b \
  --data-path ./preferences.jsonl \
  --project-name gemma-orpo \
  --trainer orpo \
  --prompt-text-column prompt \
  --text-column chosen \
  --rejected-text-column rejected \
  --peft
```

### Treinamento GRPO

Treine com Group Relative Policy Optimization usando seu próprio ambiente de recompensa:

```bash theme={null}
aitraining llm --train \
  --model deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B \
  --trainer grpo \
  --rl-env-module my_envs.hotel_env \
  --rl-env-class HotelEnv \
  --rl-num-generations 4 \
  --rl-max-new-tokens 256 \
  --peft \
  --lr 1e-5
```

<Note>
  GRPO gera múltiplas completações por prompt, pontua-as através do seu ambiente (0-1), e otimiza a política. Veja [Treinamento GRPO](/advanced/grpo-training) para detalhes da interface do ambiente.
</Note>

### Distilação de Conhecimento

Treine um modelo menor para imitar um maior:

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --teacher-model google/gemma-2-2b \
  --data-path ./prompts.jsonl \
  --project-name distilled-model \
  --use-distillation \
  --distill-temperature 3.0
```

<Note>
  Padrões de distilação: `--distill-temperature 3.0`, `--distill-alpha 0.7`, `--distill-max-teacher-length 512`
</Note>

## Logging e Monitoramento

### Weights & Biases (Padrão)

O logging W\&B com visualizador LEET está **habilitado por padrão**. O visualizador LEET mostra métricas de treinamento em tempo real diretamente no seu terminal.

```bash theme={null}
# W&B is on by default - just run training
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model
```

Para desabilitar W\&B ou o visualizador:

```bash theme={null}
# Disable W&B logging entirely
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --log none

# Keep W&B but disable terminal visualizer
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --no-wandb-visualizer
```

### TensorBoard

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --log tensorboard
```

## Push para Hugging Face Hub

Faça upload do seu modelo treinado:

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --push-to-hub \
  --username your-username \
  --token $HF_TOKEN
```

<Note>
  O repositório é criado como **privado** por padrão. Por padrão, o repositório será nomeado `{username}/{project-name}`.
</Note>

### Nome de Repositório Personalizado ou Organização

Use `--repo-id` para fazer upload para um repositório específico, útil para:

* Fazer upload para uma **organização** em vez da sua conta pessoal
* Usar um **nome de repo diferente** do seu `project-name` local

```bash theme={null}
# Upload para uma organização
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name ./local-training-output \
  --push-to-hub \
  --repo-id my-organization/my-custom-model-name \
  --token $HF_TOKEN

# Upload para conta pessoal com nome diferente
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name ./experiment-v3 \
  --push-to-hub \
  --repo-id your-username/production-model \
  --token $HF_TOKEN
```

| Parâmetro                            | Descrição                                  | Padrão                      |
| ------------------------------------ | ------------------------------------------ | --------------------------- |
| `--push-to-hub`                      | Habilitar upload para o Hub                | `False`                     |
| `--hub-private` / `--no-hub-private` | Criar repo como privado ou publico         | `True` (privado)            |
| `--username`                         | Usuário HF (para nomeação padrão do repo)  | `None`                      |
| `--token`                            | Token de API do HF                         | `None`                      |
| `--repo-id`                          | ID completo do repo (ex: `org/model-name`) | `{username}/{project-name}` |

<Warning>
  Ao usar `--repo-id`, você não precisa de `--username` já que o ID do repo já especifica o destino. No entanto, você ainda precisa de `--token` para autenticação.
</Warning>

## Opções Avançadas

### Varreduras de Hiperparâmetros

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

### Avaliação Aprimorada

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./data \
  --project-name my-model \
  --use-enhanced-eval \
  --eval-metrics "perplexity,bleu"
```

## Ver Todos os Parâmetros

Veja todos os parâmetros para um trainer específico:

```bash theme={null}
aitraining llm --trainer sft --help
aitraining llm --trainer dpo --help
```

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Configurações YAML" href="/cli/yaml-configs">
    Use arquivos de configuração
  </Card>

  <Card title="Treinamento DPO" href="/advanced/dpo-training">
    Mergulho profundo em DPO
  </Card>

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

  <Card title="Distilação" href="/advanced/prompt-distillation">
    Distilação de conhecimento
  </Card>

  <Card title="Treinamento GRPO" href="/advanced/grpo-training">
    RL com ambientes personalizados
  </Card>
</CardGroup>