Por Jerry Fan

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.

Valide seu arquivo JSONL

Antes de fazer o upload para a OpenAI, verifique o arquivo com nosso validador gratuito. Selecione o formato de fine-tuning da OpenAI para verificar as mensagens, os papéis e as respostas de assistant em cada linha, além da sintaxe JSON.

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.

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

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

Incorreto
[{"messages":[...]}, {"messages":[...]}]
Correto
{"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á.

Incorreto
{"messages":[{"role":"user"}]}
Correto
{"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.

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

Incorreto
\uFEFF{"messages":[...]}
Correto
{"messages":[...]}

Exemplos de código

Veja como criar arquivos JSONL para a OpenAI por meio de código:

Python — Criar um arquivo 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 um arquivo 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`);

Visualize e edite arquivos JSONL da OpenAI

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

Perguntas frequentes

Referências