Por Jerry FanAtualizado em junho de 2026

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.

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.

Formato obrigatório
'{'"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.

Formato obrigatório
'{'"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.

Wrong
['{'"messages":[...]'}', '{'"messages":[...]'}']
Correct
'{'"messages":[...]'}'
'{'"messages":[...]'}'

Campos obrigatórios faltando

Cada mensagem deve ter tanto "role" quanto "content". Omitir qualquer um causará falha na validação.

Wrong
'{'"messages":['{'"role":"user"'}']'}'
Correct
'{'"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.

Wrong
'{'"messages":['{'"role":"user","content":"Hi",'}']'}'
Correct
'{'"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.

Wrong
\uFEFF'{'"messages":[...]'}'
Correct
'{'"messages":[...]'}'

Exemplos de código

Veja como criar arquivos JSONL para a OpenAI programaticamente:

Python — Criar JSONL para Fine-tuning
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")
JavaScript — Criar JSONL para Fine-tuning
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`);

Valide seu arquivo JSONL

Antes de enviar para a OpenAI, valide seu arquivo JSONL para detectar erros de formatação antecipadamente. Nosso validador online gratuito verifica cada linha para sintaxe JSON válida instantaneamente.

Visualize e edite arquivos JSONL da OpenAI

Use nosso visualizador JSONL online gratuito para inspecionar datasets de fine-tuning e arquivos da Batch API. Visualização lado a lado, destaque de sintaxe e validação em tempo real.

Perguntas frequentes

Referências