Arquivos de treinamento JSONL

O que é

O JSON é a maneira mais comum de escrever dados estruturados como texto: objetos entre chaves, listas entre colchetes, chaves e valores entre aspas. O JSONL, também chamado de JSON Lines ou JSON delimitado por nova linha, adiciona uma regra extra: cada linha do arquivo é um valor JSON completo e válido, e as linhas são separadas por uma quebra de linha. Para dados de treinamento, cada valor é um objeto que contém um exemplo.

train.jsonl

{"messages":[{"role":"system","content":"You are…"},{"role":"user","content":"How do I reset my password?"},{"role":"assistant","content":"Open Settings → Security…"}]}

{"messages":[{"role":"user","content":"Hi"},{"role":"assistant","content":"Hello! How can I help?","weight":0},{"role":"user","content":"Export my report as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF…","weight":1}]}

{"messages":[{"role":"system","content":"You are…"},{"role":"user","content":"Can I change my plan mid-month?"},{"role":"assistant","content":"Yes. The difference is prorated…"}]}

…uma linha por registro, sem vírgulas entre as linhas, sem [ ] ao redor

{ … }um objeto JSON completo = um registro de treinamento"messages"a conversa, em ordem"role"quem disse: sistema, usuário ou assistente"weight"aprender esta resposta (1) ou apenas lê-la (0)\numa quebra de linha encerra o registro

Um arquivo JSONL é uma pilha de objetos JSON independentes, um por linha. Cada linha pode ser lida, verificada, contada ou embaralhada separadamente, e é por isso que todos os principais serviços de fine-tuning o utilizam.

Por que o treinamento o utiliza

Streaming: um provedor pode ler um arquivo de vários gigabytes linha por linha, em vez de carregá-lo e analisá-lo por inteiro.
Independência: os registros podem ser contados, embaralhados, divididos em treinamento e validação ou amostrados sem a necessidade de analisar o restante do arquivo.
Erros claros: um registro malformado interrompe apenas uma linha, e a mensagem de erro pode identificá-la (“linha 482: fim de entrada inesperado”).
Anexável: adicionar exemplos significa adicionar linhas; nada mais no arquivo é alterado.

As regras e como os arquivos falham

A especificação do JSON Lines possui três regras: o arquivo é UTF-8, cada linha é um valor JSON válido e cada linha termina com um caractere de avanço de linha (line-feed). É altamente recomendável terminar o arquivo com uma quebra de linha. Quase todo arquivo de treinamento corrompido viola uma dessas regras:

maneiras comuns de um arquivo apresentar erros

✗ {"messages": [ ...          ← a pretty-printed object split over lines
     {"role": "user", ... } ]}
✗ [ {"messages": ...}, {"messages": ...} ]   ← a JSON array, not one object per line
✗ {"messages": [...]},        ← trailing comma
✗                             ← a blank line in the middle
✓ {"messages":[...]}          ← one complete object, then a line break

Quebras de linha dentro do texto de uma mensagem não são um problema, pois o JSON as armazena com escape (como uma barra invertida seguida de n) dentro da string. O que não pode ocorrer é uma quebra de linha real no meio de um objeto — que é exatamente o que a formatação visual (“pretty-printing”) de um arquivo para facilitar a leitura faz.

Mesmo formato, estruturas diferentes

Todos os principais serviços de fine-tuning aceitam JSONL, mas cada um define seu próprio esquema para o conteúdo de uma linha. Alguns utilizam uma lista messages com as funções system, user e assistant; outros colocam o prompt do sistema em um campo separado; alguns chamam a lista de contents e a função do assistente de model; há também os que suportam um weight (peso) em cada mensagem do assistente, para que as respostas anteriores sirvam apenas como contexto.

um exemplo, três formatos de provedor

// chat "messages" (with an optional weight per assistant reply)
{"messages":[{"role":"user","content":"Hi"},{"role":"assistant","content":"Hello!","weight":0},{"role":"user","content":"Export as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF.","weight":1}]}

// "contents" with user / model roles
{"contents":[{"role":"user","parts":[{"text":"Export as PDF"}]},{"role":"model","parts":[{"text":"Open the report, click Export → PDF."}]}]}

// separate system field
{"system":"You are a support assistant.","messages":[{"role":"user","content":"Export as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF."}]}

Nos casos em que um formato não possui peso por mensagem, uma conversa de vários turnos com diversos alvos é gravada como um registro por alvo, cada um interrompido logo após a sua resposta alvo. Nesses registros, as respostas anteriores do assistente também são aprendidas, uma vez que o formato não tem como marcá-las apenas como contexto.

Exemplo prático: uma conversa, dois arquivos

Uma conversa tem quatro mensagens: “Oi”, uma saudação, “Exportar meu relatório como PDF” e as instruções. Apenas as instruções são marcadas como alvo.
Para um provedor que suporta pesos: uma linha, com a saudação em weight: 0 e as instruções em weight: 1.
Para um provedor sem pesos: também uma linha, terminando nas instruções. Se a saudação também fosse um alvo, haveria duas linhas — uma terminando na saudação, outra nas instruções — e a saudação seria aprendida duas vezes.
Ambos os arquivos contêm o mesmo texto limpo e anonimizado. Apenas o encapsulamento difere.

Erros comuns

Aplicar formatação visual (pretty-printing) a um arquivo de treinamento para que cada objeto ocupe várias linhas.
Salvar um array JSON de registros e nomeá-lo como .jsonl.
Editar manualmente um arquivo em uma ferramenta que altera a codificação ou adiciona aspas inteligentes, o que corrompe o JSON.
Reutilizar o arquivo de um provedor com outro provedor: o formato é o mesmo, mas o esquema interno não.

Referências e leitura complementar

Fontes externas abrem em uma nova aba.