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.
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.
{"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.
{"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.
[{"messages":[...]}, {"messages":[...]}]{"messages":[...]}
{"messages":[...]}Verplichte velden ontbreken
Elk bericht moet zowel "role" als "content" bevatten. Als een van beide ontbreekt, mislukt de validatie.
{"messages":[{"role":"user"}]}{"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.
{"messages":[{"role":"user","content":"Hi",}]}{"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.
\uFEFF{"messages":[...]}{"messages":[...]}Codevoorbeelden
Zo maakt u OpenAI JSONL-bestanden met code:
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")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`);Gerelateerde tools & gidsen
Valideer JSONL-bestanden regel voor regel. Spoor syntaxfouten, tekencoderingsproblemen en fouten in het formaat direct op.
Maak JSONL-bestanden overzichtelijk met de juiste inspringing. Dat maakt debuggen en het controleren van data eenvoudiger.
Splits grote JSONL-bestanden op regelnummer in kleinere, beheersbare delen.
Leer hoe je JSONL-bestanden opbouwt voor de Batch API van OpenAI. Met uitleg over het requestformaat, het parsen van responses en de volledige workflow, inclusief codevoorbeelden.
Leer hoe je JSONL-trainingsdata voorbereidt voor fine-tuning van AI/ML-modellen. Met uitleg over de datasetformaten van OpenAI, Anthropic Claude en HuggingFace, validatie en pipelines om data voor te bereiden.