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

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

Formatos Comuns

CSV (Mais Comum)

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

text,label
"This product is amazing",positive
"Terrible experience",negative
"Average quality",neutral

JSON/JSONL

Melhor para dados complexos, conversas e estruturas aninhadas.

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

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

Formatos Especiais

DPO/ORPO (Dados de Preferência)

{
  "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}:

{"messages": [
  {"role": "user", "content": "Hello"},
  {"role": "assistant", "content": "Hi there!"}
]}

Ou formato ShareGPT (detectado e convertido automaticamente):

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

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

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.

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.

Tool Calls (Chamadas de Função)

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

{"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."}
]}

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.

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

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

Saida (serializado no conteudo):

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

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.

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:

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

// 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á!"}
]

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.

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

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:

--chat-template tokenizer  # Use template do modelo (recomendado)
--chat-template chatml     # Force ChatML
--chat-template none       # Desabilite para texto simples

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

Extensão de Conversa

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

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

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

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

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

Começando

Fundamentos de Treinamento IA

Conceitos Básicos

Seleção de Interface

Datasets e Formatos

Datasets e Formatos

Formatos de Arquivo Suportados

Formatos Comuns

CSV (Mais Comum)

JSON/JSONL

Pastas para Imagens

Básicos de Qualidade de Dados

Balanceie Suas Classes

Limpe Seus Dados

Diretrizes de Tamanho

Colunas Obrigatórias por Treinador

Formatos Especiais

DPO/ORPO (Dados de Preferência)

Token Classification

Formato de Conversa

Suporte para Role Tool

Tool Calls (Chamadas de Função)

Transformacao de Formato de Tool Call

Tratamento de Alternância de Mensagens

Conversão Automática de Dataset

Formatos Suportados

Usando Auto-Conversão

Chat Templates

Extensão de Conversa

Saída do Dataset Processado

Salvando Dados Processados

Dicas Rápidas

Próximos Passos

Hyperparâmetros

Tarefas de Treinamento

Começando

Fundamentos de Treinamento IA

Conceitos Básicos

Seleção de Interface

​Datasets e Formatos

​Formatos de Arquivo Suportados

​Formatos Comuns

​CSV (Mais Comum)

​JSON/JSONL

​Pastas para Imagens

​Básicos de Qualidade de Dados

​Balanceie Suas Classes

​Limpe Seus Dados

​Diretrizes de Tamanho

​Colunas Obrigatórias por Treinador

​Formatos Especiais

​DPO/ORPO (Dados de Preferência)

​Token Classification

​Formato de Conversa

​Suporte para Role Tool

​Tool Calls (Chamadas de Função)

​Transformacao de Formato de Tool Call

​Tratamento de Alternância de Mensagens

​Conversão Automática de Dataset

​Formatos Suportados

​Usando Auto-Conversão

​Chat Templates

​Extensão de Conversa

​Saída do Dataset Processado

​Salvando Dados Processados

​Dicas Rápidas

​Próximos Passos

Hyperparâmetros

Tarefas de Treinamento

Datasets e Formatos

Formatos de Arquivo Suportados

Formatos Comuns

CSV (Mais Comum)

JSON/JSONL

Pastas para Imagens

Básicos de Qualidade de Dados

Balanceie Suas Classes

Limpe Seus Dados

Diretrizes de Tamanho

Colunas Obrigatórias por Treinador

Formatos Especiais

DPO/ORPO (Dados de Preferência)

Token Classification

Formato de Conversa

Suporte para Role Tool

Tool Calls (Chamadas de Função)

Transformacao de Formato de Tool Call

Tratamento de Alternância de Mensagens

Conversão Automática de Dataset

Formatos Suportados

Usando Auto-Conversão

Chat Templates

Extensão de Conversa

Saída do Dataset Processado

Salvando Dados Processados

Dicas Rápidas

Próximos Passos