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

# Tutorial de Treinamento SFT

> Guia completo passo a passo para treinar seu primeiro LLM

# Treinando Seu Primeiro LLM com SFT

Este tutorial leva você através de cada etapa do assistente para treinar um modelo de linguagem usando Supervised Fine-Tuning (SFT). SFT é a forma mais comum de ensinar um modelo a seguir instruções.

## Antes de Começar

Certifique-se de ter:

* AITraining instalado (`pip install aitraining`)
* Pelo menos 8GB de RAM (16GB recomendado)
* Uma GPU é útil mas não obrigatória (Apple Silicon funciona muito bem!)

## Etapa 0: Iniciar o Assistente

```bash theme={null}
aitraining
```

Você verá o banner de boas-vindas e instruções.

## Etapa 1: Escolher Tipo de Trainer

```
📋 Step 0: Choose Trainer Type

Available trainer types:
   1. Large Language Models (LLM) - text generation, chat, instruction following
   2. Text Classification - categorize text into labels
   3. Token Classification - NER, POS tagging
   ...

Select trainer type [1-10, default: 1]:
```

**Digite `1` e pressione Enter** para selecionar treinamento LLM.

<Tip>
  Digite `:help` para ver explicações detalhadas do que cada tipo de trainer faz.
</Tip>

## Etapa 2: Escolher Método de Treinamento

```
📋 Step 1: Choose Training Type

Available trainers:
  1. sft             - Supervised Fine-Tuning (most common)
  2. dpo             - Direct Preference Optimization
  3. orpo            - Odds Ratio Preference Optimization
  4. ppo             - Proximal Policy Optimization (RL)
  5. reward          - Reward model training
  6. distillation    - Knowledge distillation
  7. default         - Generic training (same as SFT)

Select trainer [1-7, default: 1]:
```

**Digite `1` e pressione Enter** para selecionar SFT.

<Note>
  `default` e `sft` são idênticos - eles usam o mesmo código de treinamento. `default` é apenas o fallback se nenhum trainer for especificado.
</Note>

### O Que Isso Significa?

| Trainer           | Quando Usar                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------- |
| **SFT / default** | Ensinar o modelo a seguir instruções. Você tem exemplos de boas respostas. **Comece aqui!** |
| **DPO**           | Você tem pares de respostas boas vs ruins para o mesmo prompt                               |
| **ORPO**          | Como DPO mas funciona com menos dados                                                       |
| **PPO**           | Avançado: usando um modelo de recompensa para pontuar respostas                             |
| **Reward**        | Treinar um modelo de recompensa para pontuar saídas (usado com PPO)                         |
| **Distillation**  | Transferir conhecimento de um modelo professor maior para um estudante menor                |

## Etapa 3: Nome do Projeto

```
📋 Step 2: Basic Configuration

Project name [my-llm-project]:
```

Digite um nome para seu projeto, como `my-first-chatbot` ou pressione Enter para aceitar o padrão.

<Warning>
  Se uma pasta com esse nome existir, o assistente oferece criar um nome versionado (ex.: `my-project-v2`).
</Warning>

## Etapa 4: Seleção de Modelo

Esta é a etapa mais importante. O assistente mostra modelos em alta do HuggingFace:

```
📋 Step 3: Model Selection

Popular models (trending):
  Sort: [T]rending [D]ownloads [L]ikes [R]ecent
  Filter size: [A]ll [S]mall(<3B) [M]edium(3-10B) [L]arge(>10B) (current: all)

  1. google/gemma-3-270m (270M)
  2. google/gemma-2-2b (2B)
  3. meta-llama/Llama-3.2-1B (1B)
  4. meta-llama/Llama-3.2-3B (3B)
  5. mistralai/Mistral-7B-v0.3 (7B)
  ...

Model (number, HF ID, or command):
```

### Escolhendo o Tamanho Correto do Modelo

<AccordionGroup>
  <Accordion title="Tenho um MacBook (8-16GB RAM)">
    Use `/filter` depois `S` para modelos pequenos.

    Recomendado: `google/gemma-3-270m` ou `meta-llama/Llama-3.2-1B`

    Estes treinarão em 15-30 minutos no Apple Silicon.
  </Accordion>

  <Accordion title="Tenho um PC gamer (RTX 3060/3070, 8-12GB VRAM)">
    Use `/filter` depois `S` ou `M`.

    Recomendado: `google/gemma-2-2b` ou `meta-llama/Llama-3.2-3B`

    Habilite quantização depois para modelos maiores.
  </Accordion>

  <Accordion title="Tenho uma estação de trabalho (RTX 3090/4090, 24GB+ VRAM)">
    Qualquer modelo até 10B funciona bem.

    Recomendado: `meta-llama/Llama-3.2-8B` ou `mistralai/Mistral-7B-v0.3`
  </Accordion>

  <Accordion title="Tenho uma GPU na nuvem (A100, H100)">
    Vá em frente!

    Recomendado: `meta-llama/Llama-3.1-70B` com quantização
  </Accordion>
</AccordionGroup>

### Modelo Base vs Instruction-Tuned

Ao selecionar um modelo, você verá dois tipos:

| Nome do Modelo                     | Tipo                   | Quando Usar                                    |
| ---------------------------------- | ---------------------- | ---------------------------------------------- |
| `google/gemma-2-2b`                | Base (pré-treinado)    | Propósito geral, aprende seu estilo específico |
| `google/gemma-2-2b-it`             | Instruction-tuned (IT) | Já segue instruções, ajuste fino adicional     |
| `meta-llama/Llama-3.2-1B`          | Base                   | Tela limpa para seu caso de uso                |
| `meta-llama/Llama-3.2-1B-Instruct` | Instruction-tuned      | Já útil, refine-o                              |

<Note>
  **Regra geral**: Use modelos base se quiser controle total. Use instruction-tuned (`-it`, `-Instruct`) se quiser uma vantagem inicial.
</Note>

### Selecionando Seu Modelo

**Opção A**: Digite um número para selecionar da lista:

```
Model (number, HF ID, or command): 1
✓ Model: google/gemma-3-270m
```

**Opção B**: Digite um ID do HuggingFace diretamente:

```
Model (number, HF ID, or command): google/gemma-2-2b
✓ Model: google/gemma-2-2b
```

**Opção C**: Busque modelos específicos:

```
Model (number, HF ID, or command): /search llama
```

## Etapa 5: Configuração do Dataset

```
📋 Step 4: Dataset Configuration

Dataset options:
  • Local folder with CSV/JSON/Parquet files (e.g., ./data/my_dataset)
  • HuggingFace dataset ID (e.g., tatsu-lab/alpaca)
  • Choose from popular datasets below

Popular datasets (trending):
  1. tatsu-lab/alpaca — Instruction following dataset (52k)
  2. OpenAssistant/oasst1 — Conversation dataset
  3. HuggingFaceH4/ultrachat_200k — Multi-turn conversations
  ...
```

### Entendendo o Tamanho do Dataset

<Warning>
  **Crítico**: Combine o tamanho do seu dataset com o tamanho do seu modelo!

  * **Modelos pequenos (\< 1B params)**: Use 1.000 - 10.000 exemplos no máximo
  * **Modelos médios (1-7B params)**: 10.000 - 100.000 exemplos
  * **Modelos grandes (7B+ params)**: 50.000+ exemplos

  Por quê? Modelos pequenos fazem overfitting em datasets grandes. Um modelo de 270M treinando em 52k exemplos do Alpaca vai memorizar, não generalizar.
</Warning>

### Opções de Seleção de Dataset

**Use um dataset pré-construído** (mais fácil):

```
Dataset (number, HF ID, or command): 1
✓ Dataset: tatsu-lab/alpaca
🔍 Validating dataset...
✓ Dataset loaded. Columns found: instruction, input, output
```

**Use seus próprios dados**:

```
Dataset (number, HF ID, or command): ./my_data
```

**Use um dataset do HuggingFace**:

```
Dataset (number, HF ID, or command): username/my-dataset
```

### Análise de Formato do Dataset

O assistente analisa automaticamente seu dataset:

```
🔄 Dataset Format Analysis:
  Loading dataset sample from HuggingFace: tatsu-lab/alpaca
✓ Detected dataset format: alpaca
  • Your dataset is in alpaca format
  • This can be converted to the standard messages format for better compatibility

Do you want to analyze and convert your dataset to the model's chat format? (y/N):
```

**Digite `y`** para habilitar conversão automática. Isso garante que seus dados funcionem corretamente com o template de chat do modelo.

### Splits de Treino/Validação

```
Training split name [train]:
```

Pressione Enter para usar o split padrão `train`.

```
Validation split name (optional) [none]:
```

Se seu dataset tem um split de validação (`validation`, `test`), insira aqui. Caso contrário, pressione Enter para pular.

### Máximo de Amostras (Teste)

```
Maximum samples (optional, for testing/debugging):
```

<Tip>
  **Para seu primeiro treinamento**: Digite `100` ou `500` para fazer uma execução de teste rápida. Uma vez que funcione, remova o limite e treine no dataset completo.
</Tip>

## Etapa 6: Configuração Avançada (Opcional)

```
📋 Step 5: Advanced Configuration (Optional)

Would you like to configure advanced parameters?
  • Training hyperparameters (learning rate, batch size, etc.)
  • PEFT/LoRA settings
  • Model quantization
  • And more...

Configure advanced parameters? [y/N]:
```

Para seu primeiro treinamento, **pressione Enter** para pular isso e usar padrões inteligentes.

### Quando Configurar Opções Avançadas

| Situação                    | O Que Mudar                                      |
| --------------------------- | ------------------------------------------------ |
| Treinamento muito lento     | Habilite LoRA (`peft=True`) para reduzir memória |
| Sem memória                 | Reduza `batch_size` ou habilite quantização      |
| Modelo não está aprendendo  | Ajuste `lr` (taxa de aprendizado)                |
| Quer acompanhar treinamento | Habilite logging W\&B                            |

## Etapa 7: Revisar e Iniciar

```
📋 Configuration Summary

Basic Configuration:
  • trainer: sft
  • project_name: my-first-chatbot

Dataset:
  • data_path: tatsu-lab/alpaca
  • train_split: train
  • auto_convert_dataset: ✓

Model & Training:
  • model: google/gemma-3-270m

Logging:
  • log: wandb ✓
  • wandb_visualizer: ✓ (LEET panel will open automatically)

✓ Configuration is valid!

🚀 Start training with this configuration? [Y/n]:
```

**Pressione Enter** para iniciar o treinamento!

## O Que Acontece Depois

1. O modelo é baixado (apenas na primeira vez)
2. O dataset carrega e converte
3. O treinamento começa com atualizações de progresso
4. O painel W\&B LEET mostra métricas em tempo real (se habilitado)
5. Seu modelo treinado é salvo na pasta do projeto

```
Loading model google/gemma-3-270m...
Processing data...
Training started...
Epoch 1/1: loss=2.45, accuracy=0.52
Step 100/500: loss=1.89
Step 200/500: loss=1.42
...
Model saved to ./my-first-chatbot
```

## Testando Seu Modelo

Após o treinamento completar:

```bash theme={null}
aitraining chat
```

Abra `http://localhost:7860/inference` e carregue seu modelo de `./my-first-chatbot` para testá-lo!

## Problemas Comuns

<AccordionGroup>
  <Accordion title="Erro de falta de memória">
    * Use um modelo menor (filtrar por tamanho)
    * Habilite LoRA nas opções avançadas
    * Reduza o tamanho do batch
    * Habilite quantização (`int4`)
  </Accordion>

  <Accordion title="Modelo não está aprendendo (loss permanece alto)">
    * Verifique o formato do seu dataset
    * Tente uma taxa de aprendizado maior
    * Certifique-se de que seus dados têm as colunas corretas
  </Accordion>

  <Accordion title="Treinamento muito lento">
    * Habilite precisão mista (`bf16`) nas opções avançadas
    * Use um dataset menor primeiro
    * Habilite LoRA
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Entendendo Modelos" href="/wizard/choosing-models" icon="robot">
    Mergulho profundo na seleção de modelos
  </Card>

  <Card title="Guia de Datasets" href="/wizard/dataset-guide" icon="database">
    Prepare seus próprios dados de treinamento
  </Card>

  <Card title="Treinamento DPO" href="/advanced/dpo-training" icon="scale-balanced">
    Treine com dados de preferência
  </Card>

  <Card title="Eficiência LoRA" href="/advanced/lora-peft" icon="bolt">
    Treine modelos grandes em hardware limitado
  </Card>
</CardGroup>