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

# Datasets e Formatos

> Como estruturar seus dados de treinamento

# Datasets e Formatos

Seu modelo é tão bom quanto seus dados. Aqui está como formatá-los corretamente.

## Formatos de Arquivo Suportados

O AITraining suporta múltiplas fontes de dados:

| Formato          | Como É Carregado               | Caso de Uso                    |
| ---------------- | ------------------------------ | ------------------------------ |
| JSONL            | `pandas.read_json(lines=True)` | Treinamento LLM, conversas     |
| CSV              | `pandas.read_csv()`            | Classificação, dados tabulares |
| HF Dataset ID    | `datasets.load_dataset()`      | Datasets remotos do Hub        |
| Local HF Dataset | `load_from_disk()`             | Datasets pré-processados       |

<Note>
  Arquivos Parquet são suportados indiretamente através de datasets HuggingFace que expõem formato Parquet.
</Note>

## Formatos Comuns

### CSV (Mais Comum)

Simples e universal. Funciona para classificação, regressão e tarefas básicas.

```csv theme={null}
text,label
"This product is amazing",positive
"Terrible experience",negative
"Average quality",neutral
```

### JSON/JSONL

Melhor para dados complexos, conversas e estruturas aninhadas.

```json theme={null}
{"messages": [
  {"role": "user", "content": "What is Python?"},
  {"role": "assistant", "content": "Python is a programming language"}
]}
```

### Pastas para Imagens

Organize imagens por categoria:

```
dataset/
  cats/
    cat1.jpg
    cat2.jpg
  dogs/
    dog1.jpg
    dog2.jpg
```

## Básicos de Qualidade de Dados

### Balanceie Suas Classes

Ruim:

* 1000 exemplos positivos
* 50 exemplos negativos

Bom:

* 500 exemplos positivos
* 500 exemplos negativos

### Limpe Seus Dados

Remova:

* Duplicatas
* Valores vazios
* Erros óbvios
* Formatação inconsistente

### Diretrizes de Tamanho

| Tipo de Tarefa       | Mínimo | Bom   | Excelente |
| -------------------- | ------ | ----- | --------- |
| Text Classification  | 100    | 1.000 | 10.000+   |
| Image Classification | 200    | 2.000 | 20.000+   |
| Language Generation  | 50     | 500   | 5.000+    |

## Colunas Obrigatórias por Treinador

Diferentes treinadores requerem colunas específicas:

| Treinador         | Colunas Obrigatórias           | Opcional |
| ----------------- | ------------------------------ | -------- |
| `sft` / `default` | `text` (ou `messages`)         | -        |
| `dpo`             | `prompt`, `chosen`, `rejected` | -        |
| `orpo`            | `prompt`, `chosen`, `rejected` | -        |
| `reward`          | `text` (chosen), `rejected`    | -        |

<Warning>
  Se colunas obrigatórias estiverem faltando, você receberá um erro de validação claro listando as colunas faltantes e disponíveis.
</Warning>

## Formatos Especiais

### DPO/ORPO (Dados de Preferência)

```json theme={null}
{
  "prompt": "Explain gravity",
  "chosen": "Gravity is a force that attracts objects...",
  "rejected": "gravity is thing that make stuff fall"
}
```

### Token Classification

```
John    B-PERSON
Smith   I-PERSON
visited O
Paris   B-LOCATION
```

### Formato de Conversa

Conversas esperam listas de objetos `{role, content}`:

```json theme={null}
{"messages": [
  {"role": "user", "content": "Hello"},
  {"role": "assistant", "content": "Hi there!"}
]}
```

Ou formato ShareGPT (detectado e convertido automaticamente):

```json theme={null}
{"conversations": [
  {"from": "human", "value": "Hello"},
  {"from": "assistant", "value": "Hi there!"}
]}
```

#### Suporte para Role Tool

O AITraining suporta a role `tool` para dados de treinamento com chamadas de função:

```json theme={null}
{"messages": [
  {"role": "user", "content": "Quanto é 2+2?"},
  {"role": "assistant", "content": "Deixe-me calcular."},
  {"role": "tool", "content": "4"},
  {"role": "assistant", "content": "A resposta é 4."}
]}
```

<Note>
  **Compatibilidade automática**: Para modelos que não suportam a role `tool` nativamente (como Gemma), o AITraining converte automaticamente mensagens `tool` para mensagens `user` com o prefixo `[Tool Result]`. Modelos com suporte nativo de tool (Llama 3.1+, Qwen, etc.) usam seu formato nativo.
</Note>

<Note>
  **Suporte a formato legado**: A role `function` antiga da OpenAI (usada antes de `tool` ser introduzida) também é suportada e tratada de forma idêntica à role `tool`.
</Note>

#### Tool Calls (Chamadas de Função)

O AITraining também suporta o campo `tool_calls` para treinar modelos a fazer chamadas de função:

```json theme={null}
{"messages": [
  {"role": "user", "content": "Como está o clima em Paris?"},
  {
    "role": "assistant",
    "content": "Deixe-me verificar.",
    "tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\": \"Paris\"}"}}]
  },
  {"role": "tool", "content": "Ensolarado, 20C"},
  {"role": "assistant", "content": "Está ensolarado e 20C em Paris."}
]}
```

<Note>
  **Deteccao inteligente de formato**: O AITraining detecta se seu modelo suporta `tool_calls` nativamente:

  * **Qwen, Llama 3.1+**: Usa formato nativo `<tool_call>`
  * **Gemma, modelos antigos**: Serializa tool calls como JSON formato OpenAI no conteudo

  Na inferencia, faca o parse do JSON da saida do assistente para extrair os tool calls.
</Note>

#### Transformacao de Formato de Tool Call

Para modelos sem suporte nativo de ferramentas, o AITraining serializa os tool calls como JSON formato OpenAI anexado ao conteudo do assistente:

**Entrada (mensagem com campo tool\_calls):**

```json theme={null}
{
  "role": "assistant",
  "content": "Deixe-me buscar isso.",
  "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "search", "arguments": "{\"query\": \"weather\"}"}}]
}
```

**Saida (serializado no conteudo):**

```json theme={null}
Deixe-me buscar isso.
{"content": "Deixe-me buscar isso.", "tool_calls": [{"id": "call_123", "type": "function", "function": {"name": "search", "arguments": "{\"query\": \"weather\"}"}}]}
```

<Note>
  O formato serializado preserva a estrutura completa da OpenAI com os campos `id`, `type` e `function`. Isso corresponde ao formato descrito nas instrucoes do system prompt para melhor aprendizado do modelo.
</Note>

#### Tratamento de Alternância de Mensagens

Alguns modelos (Gemma, Mistral) requerem alternância estrita user/assistant. O AITraining corrige automaticamente problemas comuns:

**Mensagens consecutivas da mesma role** são mescladas:

```json theme={null}
// Antes (falharia no Gemma)
[
  {"role": "assistant", "content": "Olá!"},
  {"role": "assistant", "content": "Como posso ajudar?"}
]

// Depois (corrigido automaticamente)
[
  {"role": "assistant", "content": "Olá!\nComo posso ajudar?"}
]
```

**User faltando antes de assistant** recebe um placeholder:

```json theme={null}
// Antes (system → assistant, sem user)
[
  {"role": "system", "content": "Você é útil"},
  {"role": "assistant", "content": "Olá!"}
]

// Depois (corrigido automaticamente)
[
  {"role": "system", "content": "Você é útil"},
  {"role": "user", "content": "[Continued]"},
  {"role": "assistant", "content": "Olá!"}
]
```

<Note>
  Essas correções só são aplicadas quando o tokenizador rejeita o formato original. Modelos que aceitam ordenação flexível de mensagens mantêm a estrutura original.
</Note>

## Conversão Automática de Dataset

O AITraining pode detectar e converter automaticamente formatos comuns de dataset. Sem pré-processamento manual necessário.

### Formatos Suportados

| Formato        | Detecção | Colunas de Exemplo                      |
| -------------- | -------- | --------------------------------------- |
| Alpaca         | Auto     | `instruction`, `input`, `output`        |
| ShareGPT       | Auto     | `conversations` com `from`/`value`      |
| Messages       | Auto     | `messages` com `role`/`content`         |
| Q\&A           | Auto     | `question`/`answer`, `query`/`response` |
| User/Assistant | Auto     | `user`, `assistant`                     |
| DPO            | Auto     | `prompt`, `chosen`, `rejected`          |
| Plain Text     | Auto     | `text`                                  |

Mapeamento de colunas é opcional - use para converter nomes de colunas variados para o formato esperado.

### Usando Auto-Conversão

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path tatsu-lab/alpaca \
  --auto-convert-dataset \
  --chat-template gemma3 \
  --trainer sft
```

### Chat Templates

Chat templates formatam seus dados na estrutura de conversa esperada do modelo.

| Opção       | Descrição                                                          |
| ----------- | ------------------------------------------------------------------ |
| `tokenizer` | Use o chat template integrado do modelo (padrão para SFT/DPO/ORPO) |
| `chatml`    | Formato padrão ChatML                                              |
| `zephyr`    | Formato Zephyr/Mistral                                             |
| `none`      | Sem template (texto simples)                                       |

Templates são auto-selecionados com base no seu treinador, ou especifique manualmente:

```bash theme={null}
--chat-template tokenizer  # Use template do modelo (recomendado)
--chat-template chatml     # Force ChatML
--chat-template none       # Desabilite para texto simples
```

<Note>
  O renderizador unificado aplica templates consistentemente. Caminhos de template legados ainda são suportados para compatibilidade reversa.
</Note>

### Extensão de Conversa

Mescle exemplos de turno único em conversas multi-turno:

```bash theme={null}
aitraining llm --train \
  --model google/gemma-3-270m \
  --data-path ./qa_pairs.jsonl \
  --auto-convert-dataset \
  --conversation-extension 3 \
  --trainer sft
```

## Saída do Dataset Processado

Após o processamento, seu dataset terá:

| Coluna               | Descrição                                                     |
| -------------------- | ------------------------------------------------------------- |
| `text`               | Dados de treinamento formatados com template de chat aplicado |
| `_original_messages` | Coluna de mensagens original (preservada para inspeção)       |
| `_original_*`        | Outras colunas originais renomeadas com prefixo               |

<Note>
  Colunas originais são renomeadas para `_original_*` para prevenir que outras ferramentas auto-detectem e usem incorretamente dados não processados.
</Note>

### Salvando Dados Processados

Controle onde os dados processados são salvos com `--save-processed-data`:

| Opção   | Comportamento                                                   |
| ------- | --------------------------------------------------------------- |
| `auto`  | Salvar localmente; também enviar para Hub se a fonte era do Hub |
| `local` | Salvar apenas em `{project}/data_processed/`                    |
| `hub`   | Enviar apenas para Hub como dataset privado                     |
| `both`  | Salvar localmente e enviar para Hub                             |
| `none`  | Não salvar dados processados                                    |

## Dicas Rápidas

1. **Comece pequeno** - Teste com 100 exemplos antes de escalar
2. **Valide cedo** - Verifique se seu formato funciona antes de coletar milhares de exemplos
3. **Mantenha consistente** - Mesmo formato em todo seu dataset
4. **Documente tudo** - Anote qualquer pré-processamento ou regras especiais
5. **Use auto-convert** - Deixe o AITraining detectar e converter formatos automaticamente

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Hyperparâmetros" href="/foundations/hyperparameters">
    Configure seu treinamento
  </Card>

  <Card title="Tarefas de Treinamento" href="/foundations/training-tasks">
    Escolha seu tipo de tarefa
  </Card>
</CardGroup>