Guia do Formato JSONL da OpenAI
Tudo o que você precisa saber sobre o formato JSONL usado pela OpenAI para fine-tuning de modelos e a Batch API. Inclui especificações de formato, exemplos de código e armadilhas comuns.
Última atualização: fevereiro de 2026
O que é o formato JSONL da OpenAI?
A OpenAI usa JSONL (JSON Lines) como formato de arquivo padrão para datasets de fine-tuning e requisições da Batch API. Cada linha no arquivo é um objeto JSON completo e independente — sem array envolvente, sem vírgulas entre as linhas.
Este formato é escolhido porque permite streaming eficiente e processamento linha por linha. Cada exemplo de treinamento ou requisição de API pode ser validado independentemente, e os arquivos podem ser processados sem carregar todo o dataset na memória.
Entender os requisitos exatos do formato é fundamental. Até pequenos erros de formatação — como uma vírgula final ou um campo faltando — farão com que o arquivo inteiro seja rejeitado.
Formato JSONL para Fine-tuning
Para fine-tuning de modelos de chat (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo), cada linha deve conter um array "messages" com os turnos da conversa.
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is the capital of France?"},{"role":"assistant","content":"The capital of France is Paris."}]}{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"},{"role":"assistant","content":"2+2 equals 4."}]}
Campos obrigatórios
- messages — Array de objetos de mensagem (obrigatório)
- role — Um dos seguintes: "system", "user" ou "assistant" (obrigatório)
- content — O conteúdo de texto da mensagem (obrigatório)
A mensagem do sistema é opcional, mas recomendada. Cada conversa deve ter pelo menos uma mensagem do usuário e uma mensagem do assistente. A mensagem do assistente é o que o modelo aprende a gerar.
Formato JSONL da Batch API
A Batch API usa um formato JSONL diferente, onde cada linha é uma requisição de API com um ID personalizado.
{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello, how are you?"}]}'}{"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"What is the weather today?"}]}'}
Campos obrigatórios
- custom_id — Um identificador único para cada requisição (obrigatório)
- method — Método HTTP, normalmente "POST" (obrigatório)
- url — Caminho do endpoint da API (obrigatório)
- body — O corpo da requisição, igual a uma chamada de API normal (obrigatório)
Requisitos de formato
Siga estas regras para garantir que seu arquivo JSONL seja aceito pela OpenAI:
- Cada linha deve ser JSON válido — nenhum erro de sintaxe permitido
- Cada linha deve ser um objeto JSON (começa com '{' e termina com '}')
- Arquivos de fine-tuning devem incluir um array "messages" em cada linha
- Cada mensagem deve ter os campos "role" e "content"
- Roles válidos são: "system", "user" e "assistant"
- O arquivo deve ser codificado em UTF-8 sem BOM (Byte Order Mark)
- Sem vírgulas finais, comentários ou espaços em branco extras entre as linhas
- Linhas vazias são permitidas e serão ignoradas
Erros comuns
Estes são os erros mais frequentes ao criar arquivos JSONL para a OpenAI:
Usar um array JSON em vez de JSONL
Errado: envolver todos os objetos em [ ]. Arquivos JSONL devem ter um objeto por linha sem array envolvente.
['{'"messages":[...]'}', '{'"messages":[...]'}']'{'"messages":[...]'}'
'{'"messages":[...]'}'Campos obrigatórios faltando
Cada mensagem deve ter tanto "role" quanto "content". Omitir qualquer um causará falha na validação.
'{'"messages":['{'"role":"user"'}']'}''{'"messages":['{'"role":"user","content":"Hello"'}']'}'Vírgulas finais no JSON
JSON não permite vírgulas finais após o último item em um array ou objeto.
'{'"messages":['{'"role":"user","content":"Hi",'}']'}''{'"messages":['{'"role":"user","content":"Hi"'}']'}'Caracteres BOM ou codificação errada
Salve seu arquivo como UTF-8 sem BOM. Alguns editores de texto adicionam caracteres BOM invisíveis que quebram o parsing JSON.
\uFEFF'{'"messages":[...]'}''{'"messages":[...]'}'Exemplos de código
Veja como criar arquivos JSONL para a OpenAI programaticamente:
import jsontraining_data = [{"messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "What is JSONL?"},{"role": "assistant", "content": "JSONL (JSON Lines) is a text format where each line is a valid JSON object."}]},{"messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "How do I fine-tune a model?"},{"role": "assistant", "content": "Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API."}]},]with open("training.jsonl", "w", encoding="utf-8") as f:for entry in training_data:f.write(json.dumps(entry, ensure_ascii=False) + "\n")print(f"Created training.jsonl with {len(training_data)} examples")
const fs = require('fs');const trainingData = [{ messages: [{ role: 'system', content: 'You are a helpful assistant.' },{ role: 'user', content: 'What is JSONL?' },{ role: 'assistant', content: 'JSONL (JSON Lines) is a text format where each line is a valid JSON object.' },]},{ messages: [{ role: 'system', content: 'You are a helpful assistant.' },{ role: 'user', content: 'How do I fine-tune a model?' },{ role: 'assistant', content: 'Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API.' },]},];const jsonl = trainingData.map(d => JSON.stringify(d)).join('\n');fs.writeFileSync('training.jsonl', jsonl + '\n', 'utf-8');console.log(`Created training.jsonl with ${trainingData.length} examples`);