OpenAI JSONL-formaatgids
Alles wat u moet weten over het JSONL-formaat dat door OpenAI wordt gebruikt voor het fine-tunen van modellen en de Batch API. Inclusief formaatspecificaties, codevoorbeelden en veelvoorkomende valkuilen.
Laatst bijgewerkt: februari 2026
Wat is het OpenAI JSONL-formaat?
OpenAI gebruikt JSONL (JSON Lines) als het standaard bestandsformaat voor fine-tuning datasets en Batch API-verzoeken. Elke regel in het bestand is een compleet, onafhankelijk JSON-object — geen omsluitende array, geen komma's tussen regels.
Dit formaat is gekozen omdat het efficiënte streaming en regel-voor-regel verwerking mogelijk maakt. Elk trainingsvoorbeeld of API-verzoek kan onafhankelijk worden gevalideerd, en bestanden kunnen worden verwerkt zonder de volledige dataset in het geheugen te laden.
Het begrijpen van de exacte formaatsvereisten is cruciaal. Zelfs kleine opmaakfouten — zoals een afsluitende komma of een ontbrekend veld — zorgen ervoor dat het volledige bestand wordt afgewezen.
Fine-tuning JSONL-formaat
Voor fine-tuning van chatmodellen (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo) moet elke regel een "messages"-array bevatten met de gespreksberusten.
{"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 — Array van berichtobjecten (verplicht)
- role — Eén van: "system", "user" of "assistant" (verplicht)
- content — De tekstinhoud van het bericht (verplicht)
Het systeembericht is optioneel maar aanbevolen. Elk gesprek moet ten minste één gebruikersbericht en één assistentbericht bevatten. Het assistentbericht is wat het model leert te genereren.
Batch API JSONL-formaat
De Batch API gebruikt een ander JSONL-formaat waarbij elke regel een API-verzoek is met een aangepast ID.
{"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 identificatie voor elk verzoek (verplicht)
- method — HTTP-methode, meestal "POST" (verplicht)
- url — API-eindpuntpad (verplicht)
- body — De verzoekbody, hetzelfde als een regulier API-verzoek (verplicht)
Formaatsvereisten
Volg deze regels om ervoor te zorgen dat uw JSONL-bestand door OpenAI wordt geaccepteerd:
- Elke regel moet geldige JSON zijn — geen syntaxisfouten toegestaan
- Elke regel moet een JSON-object zijn (begint met '{' en eindigt met '}')
- Fine-tuning bestanden moeten een "messages"-array in elke regel bevatten
- Elk bericht moet zowel "role" als "content" velden bevatten
- Geldige rollen zijn: "system", "user" en "assistant"
- Het bestand moet UTF-8 gecodeerd zijn zonder BOM (Byte Order Mark)
- Geen afsluitende komma's, opmerkingen of extra witruimte tussen regels
- Lege regels zijn toegestaan en worden genegeerd
Veelvoorkomende fouten
Dit zijn de meest frequente fouten bij het maken van OpenAI JSONL-bestanden:
Een JSON-array gebruiken in plaats van JSONL
Fout: alle objecten in [ ] wikkelen. JSONL-bestanden moeten één object per regel hebben zonder omsluitende array.
['{'"messages":[...]'}', '{'"messages":[...]'}']'{'"messages":[...]'}'
'{'"messages":[...]'}'Verplichte velden ontbreken
Elk bericht moet zowel "role" als "content" bevatten. Het weglaten van een van beide zorgt ervoor dat de validatie mislukt.
'{'"messages":['{'"role":"user"'}']'}''{'"messages":['{'"role":"user","content":"Hello"'}']'}'Afsluitende komma's in JSON
JSON staat geen afsluitende komma's toe na het laatste item in een array of object.
'{'"messages":['{'"role":"user","content":"Hi",'}']'}''{'"messages":['{'"role":"user","content":"Hi"'}']'}'BOM-tekens of verkeerde codering
Sla uw bestand op als UTF-8 zonder BOM. Sommige teksteditors voegen onzichtbare BOM-tekens toe die JSON-parsing verstoren.
\uFEFF'{'"messages":[...]'}''{'"messages":[...]'}'Codevoorbeelden
Zo maakt u OpenAI JSONL-bestanden programmatisch:
import jsontraining_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`);