OpenAI JSONL Format Anleitung
Alles, was Sie über das von OpenAI verwendete JSONL-Format für Fine-tuning von Modellen und die Batch API wissen müssen. Inklusive Formatspezifikationen, Codebeispielen und häufigen Fallstricken.
Zuletzt aktualisiert: Februar 2026
Was ist das OpenAI JSONL-Format?
OpenAI verwendet JSONL (JSON Lines) als Standard-Dateiformat für Fine-tuning-Datensätze und Batch-API-Anfragen. Jede Zeile in der Datei ist ein vollständiges, unabhängiges JSON-Objekt — kein umschließendes Array, keine Kommas zwischen den Zeilen.
Dieses Format wurde gewählt, weil es effizientes Streaming und zeilenweise Verarbeitung ermöglicht. Jedes Trainingsbeispiel oder jede API-Anfrage kann unabhängig validiert werden, und Dateien können verarbeitet werden, ohne den gesamten Datensatz in den Speicher zu laden.
Das Verständnis der genauen Formatanforderungen ist entscheidend. Selbst kleine Formatierungsfehler — wie ein nachgestelltes Komma oder ein fehlendes Feld — führen dazu, dass die gesamte Datei abgelehnt wird.
Fine-tuning JSONL-Format
Für Chat-Modell Fine-tuning (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo) muss jede Zeile ein "messages"-Array mit den Gesprächswendungen enthalten.
{"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."}]}
Erforderliche Felder
- messages — Array von Nachrichtenobjekten (erforderlich)
- role — Eines von: "system", "user" oder "assistant" (erforderlich)
- content — Der Textinhalt der Nachricht (erforderlich)
Die Systemnachricht ist optional, wird aber empfohlen. Jede Konversation muss mindestens eine Benutzernachricht und eine Assistentennachricht enthalten. Die Assistentennachricht ist das, was das Modell zu generieren lernt.
Batch API JSONL-Format
Die Batch API verwendet ein anderes JSONL-Format, bei dem jede Zeile eine API-Anfrage mit einer benutzerdefinierten ID ist.
{"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?"}]}'}
Erforderliche Felder
- custom_id — Eine eindeutige Kennung für jede Anfrage (erforderlich)
- method — HTTP-Methode, typischerweise "POST" (erforderlich)
- url — API-Endpunkt-Pfad (erforderlich)
- body — Der Anfragekörper, identisch mit einem regulären API-Aufruf (erforderlich)
Formatanforderungen
Befolgen Sie diese Regeln, um sicherzustellen, dass Ihre JSONL-Datei von OpenAI akzeptiert wird:
- Jede Zeile muss gültiges JSON sein — keine Syntaxfehler erlaubt
- Jede Zeile muss ein JSON-Objekt sein (beginnt mit '{' und endet mit '}')
- Fine-tuning-Dateien müssen in jeder Zeile ein "messages"-Array enthalten
- Jede Nachricht muss sowohl "role"- als auch "content"-Felder haben
- Gültige Rollen sind: "system", "user" und "assistant"
- Die Datei muss UTF-8-kodiert sein, ohne BOM (Byte Order Mark)
- Keine nachgestellten Kommas, Kommentare oder zusätzliche Leerzeichen zwischen Zeilen
- Leere Zeilen sind erlaubt und werden ignoriert
Häufige Fehler
Dies sind die häufigsten Fehler beim Erstellen von OpenAI JSONL-Dateien:
Verwendung eines JSON-Arrays anstelle von JSONL
Falsch: alle Objekte in [ ] einwickeln. JSONL-Dateien müssen ein Objekt pro Zeile haben, ohne umschließendes Array.
['{'"messages":[...]'}', '{'"messages":[...]'}']'{'"messages":[...]'}'
'{'"messages":[...]'}'Fehlende erforderliche Felder
Jede Nachricht muss sowohl "role" als auch "content" haben. Das Weglassen eines der Felder führt zu einem Validierungsfehler.
'{'"messages":['{'"role":"user"'}']'}''{'"messages":['{'"role":"user","content":"Hello"'}']'}'Nachgestellte Kommas in JSON
JSON erlaubt keine nachgestellten Kommas nach dem letzten Element in einem Array oder Objekt.
'{'"messages":['{'"role":"user","content":"Hi",'}']'}''{'"messages":['{'"role":"user","content":"Hi"'}']'}'BOM-Zeichen oder falsche Kodierung
Speichern Sie Ihre Datei als UTF-8 ohne BOM. Einige Texteditoren fügen unsichtbare BOM-Zeichen hinzu, die das JSON-Parsing unterbrechen.
\uFEFF'{'"messages":[...]'}''{'"messages":[...]'}'Codebeispiele
So erstellen Sie OpenAI JSONL-Dateien 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`);