Door Jerry Fan

Gids voor het OpenAI JSONL-formaat

Alles wat u moet weten over het JSONL-formaat dat OpenAI gebruikt voor het fine-tunen van modellen en voor de Batch API. Met formaatspecificaties, codevoorbeelden en veelvoorkomende valkuilen.

Wat is het OpenAI JSONL-formaat?

OpenAI gebruikt JSONL (JSON Lines) als standaardbestandsformaat voor datasets voor fine-tuning en voor Batch API-verzoeken. Elke regel in het bestand bevat een volledig, op zichzelf staand JSON-object. De objecten staan niet samen in een array en er staan geen komma's tussen de regels.

Met dit formaat kunt u gegevens efficiënt streamen en regel voor regel verwerken. Elk trainingsvoorbeeld of API-verzoek kan afzonderlijk worden gevalideerd. U kunt bestanden dus verwerken zonder de volledige dataset in het geheugen te laden.

Het is essentieel dat u de precieze eisen aan het formaat kent. Zelfs kleine fouten in de opmaak, zoals een komma na het laatste element of een ontbrekend veld, leiden ertoe dat het hele bestand wordt afgewezen.

Valideer uw JSONL-bestand

Controleer het bestand met onze gratis validator voordat je het naar OpenAI uploadt. Kies het OpenAI-formaat voor fine-tuning om op elke regel de berichten, rollen en antwoorden van assistant te controleren, naast de JSON-syntaxis.

JSONL-formaat voor fine-tuning

Voor het fine-tunen van chatmodellen (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo) moet elke regel een "messages"-array met de opeenvolgende berichten uit het gesprek bevatten.

Vereist formaat
{"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."}]}

Verplichte velden

  • messages — Een array met berichtobjecten (verplicht)
  • role — Een van de volgende waarden: "system", "user" of "assistant" (verplicht)
  • content — De tekst van het bericht (verplicht)

Een systeembericht is optioneel, maar wel aan te raden. Elk gesprek moet minstens één gebruikersbericht en één assistentbericht bevatten. Het model leert om het assistentbericht te genereren.

JSONL-formaat voor de Batch API

De Batch API gebruikt een ander JSONL-formaat: elke regel bevat een API-verzoek met een zelfgekozen ID.

Vereist formaat
{"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?"}]}}

Verplichte velden

  • custom_id — Een unieke ID voor elk verzoek (verplicht)
  • method — HTTP-methode, meestal "POST" (verplicht)
  • url — Het pad naar het API-endpoint (verplicht)
  • body — De request body, net als bij een gewone API-aanroep (verplicht)

Eisen aan het formaat

Houd u aan deze regels, zodat OpenAI uw JSONL-bestand accepteert:

  • Elke regel moet geldige JSON bevatten, zonder syntaxisfouten
  • Elke regel moet een JSON-object bevatten (dat begint met { en eindigt met })
  • In bestanden voor fine-tuning moet elke regel een "messages"-array bevatten
  • Elk bericht moet zowel het veld "role" als het veld "content" bevatten
  • Geldige rollen zijn: "system", "user" en "assistant"
  • Het bestand moet zijn opgeslagen in UTF-8 zonder BOM (Byte Order Mark)
  • Gebruik geen komma's na het laatste element, commentaar of extra witruimte tussen de regels
  • Lege regels zijn toegestaan en worden genegeerd

Veelvoorkomende fouten

Dit zijn de fouten die het vaakst voorkomen bij het maken van OpenAI JSONL-bestanden:

Een JSON-array gebruiken in plaats van JSONL

Fout: alle objecten samen in [ ] plaatsen. Een JSONL-bestand moet één object per regel bevatten, zonder array eromheen.

Fout
[{"messages":[...]}, {"messages":[...]}]
Goed
{"messages":[...]}
{"messages":[...]}

Verplichte velden ontbreken

Elk bericht moet zowel "role" als "content" bevatten. Als een van beide ontbreekt, mislukt de validatie.

Fout
{"messages":[{"role":"user"}]}
Goed
{"messages":[{"role":"user","content":"Hello"}]}

Komma's na het laatste element in JSON

In JSON mag na het laatste element van een array of object geen komma staan.

Fout
{"messages":[{"role":"user","content":"Hi",}]}
Goed
{"messages":[{"role":"user","content":"Hi"}]}

BOM-tekens of een verkeerde tekencodering

Sla uw bestand op in UTF-8 zonder BOM. Sommige teksteditors voegen onzichtbare BOM-tekens toe, waardoor de JSON niet kan worden geparset.

Fout
\uFEFF{"messages":[...]}
Goed
{"messages":[...]}

Codevoorbeelden

Zo maakt u OpenAI JSONL-bestanden met code:

Python — Een JSONL-bestand voor fine-tuning maken
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 — Een JSONL-bestand voor fine-tuning maken
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`);

OpenAI JSONL-bestanden bekijken en bewerken

Gebruik onze gratis online JSONL-viewer om datasets voor fine-tuning en bestanden voor de Batch API te bekijken. Met weergave naast elkaar, syntax highlighting en realtime validatie.

Veelgestelde vragen

Bronnen