Guia do formato JSONL da OpenAI
Tudo o que você precisa saber sobre o formato JSONL usado pela OpenAI no fine-tuning de modelos e na Batch API. Inclui especificações do formato, exemplos de código e problemas comuns.
O que é o formato JSONL da OpenAI?
A OpenAI usa JSONL (JSON Lines) como formato padrão de arquivo para datasets de fine-tuning e requisições da Batch API. Cada linha do arquivo contém um objeto JSON completo e independente, sem um array que agrupe os objetos e sem vírgulas entre as linhas.
Esse formato permite fazer streaming de forma eficiente e processar os dados linha por linha. Cada exemplo de treinamento ou requisição à API pode ser validado individualmente, e os arquivos podem ser processados sem carregar o dataset inteiro na memória.
É fundamental entender os requisitos exatos do formato. Mesmo pequenos erros de formatação, como uma vírgula após o último item ou a ausência de um campo, fazem com que o arquivo inteiro seja rejeitado.
Formato JSONL para fine-tuning
Para fazer fine-tuning de modelos de chat (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo), cada linha deve conter um array "messages" com as mensagens 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 valores: "system", "user" ou "assistant" (obrigatório)
- content — Conteúdo textual da mensagem (obrigatório)
A mensagem de sistema é opcional, mas recomendada. Cada conversa deve conter pelo menos uma mensagem do usuário e uma do assistente. O modelo aprende a gerar a mensagem do assistente.
Formato JSONL da Batch API
A Batch API usa um formato JSONL diferente: cada linha representa uma requisição à 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 — Identificador único de cada requisição (obrigatório)
- method — Método HTTP, normalmente "POST" (obrigatório)
- url — Caminho do endpoint da API (obrigatório)
- body — Corpo da requisição, igual ao de uma chamada comum à API (obrigatório)
Requisitos de formato
Siga estas regras para garantir que seu arquivo JSONL seja aceito pela OpenAI:
- Cada linha deve conter JSON válido, sem erros de sintaxe
- Cada linha deve conter um objeto JSON (começar com { e terminar com })
- Arquivos de fine-tuning devem conter um array "messages" em cada linha
- Cada mensagem deve conter os campos "role" e "content"
- Os valores válidos para "role" são: "system", "user" e "assistant"
- O arquivo deve usar a codificação UTF-8 sem BOM (Byte Order Mark)
- Não use vírgulas após o último item, 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
Incorreto: colocar todos os objetos dentro de [ ]. Arquivos JSONL devem conter um objeto por linha, sem um array que agrupe os objetos.
[{"messages":[...]}, {"messages":[...]}]{"messages":[...]}
{"messages":[...]}Ausência de campos obrigatórios
Cada mensagem deve conter os campos "role" e "content". Se qualquer um deles estiver ausente, a validação falhará.
{"messages":[{"role":"user"}]}{"messages":[{"role":"user","content":"Hello"}]}Vírgulas após o último item no JSON
JSON não permite vírgulas após o último item de um array ou objeto.
{"messages":[{"role":"user","content":"Hi",}]}{"messages":[{"role":"user","content":"Hi"}]}Caracteres BOM ou codificação incorreta
Salve seu arquivo em UTF-8 sem BOM. Alguns editores de texto adicionam caracteres BOM invisíveis que impedem a leitura correta do JSON.
\uFEFF{"messages":[...]}{"messages":[...]}Exemplos de código
Veja como criar arquivos JSONL para a OpenAI por meio de código:
import json
training_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`);Ferramentas e guias relacionados
Valide arquivos JSONL linha por linha. Detecte erros de sintaxe, problemas de codificação e de formato instantaneamente.
Formate arquivos JSONL com a indentação adequada para facilitar a leitura, a depuração e a revisão dos dados.
Divida arquivos JSONL grandes em partes menores e gerenciáveis por número de linhas.
Aprenda a estruturar arquivos JSONL para a Batch API da OpenAI. Veja o formato das requisições, a interpretação das respostas e o fluxo de trabalho completo, com exemplos de código.
Aprenda a preparar dados de treinamento em JSONL para fine-tuning de IA/ML. Conheça os formatos de datasets da OpenAI, do Anthropic Claude e do HuggingFace, com validação e pipelines de preparação de dados.