Von Jerry Fan

Das JSONL-Format von OpenAI

Alles, was Sie über das JSONL-Format für das Fine-Tuning von OpenAI-Modellen und die Batch API wissen müssen: Formatspezifikationen, Codebeispiele und typische Stolperfallen.

Was ist das JSONL-Format von OpenAI?

OpenAI verwendet JSONL (JSON Lines) als Standardformat für Fine-Tuning-Datensätze und Anfragen an die Batch API. Jede Zeile der Datei enthält ein vollständiges, eigenständiges JSON-Objekt. Die Objekte stehen ohne umschließendes Array und ohne Kommas zwischen den Zeilen.

Das Format ermöglicht effizientes Streaming und eine zeilenweise Verarbeitung. Jedes Trainingsbeispiel und jede API-Anfrage lässt sich einzeln validieren. So können Dateien verarbeitet werden, ohne den gesamten Datensatz in den Arbeitsspeicher zu laden.

Die genauen Formatvorgaben müssen eingehalten werden. Schon kleine Fehler wie ein überflüssiges Komma am Ende eines Objekts oder ein fehlendes Feld führen dazu, dass die gesamte Datei abgelehnt wird.

JSONL-Datei validieren

Prüfen Sie die Datei vor dem Hochladen zu OpenAI mit unserem kostenlosen Validator. Wählen Sie das OpenAI-Fine-Tuning-Format, um neben der JSON-Syntax auch die Nachrichten, Rollen und Antworten mit der Rolle assistant in jeder Zeile zu prüfen.

JSONL-Format für das Fine-Tuning

Für das Fine-Tuning von Chat-Modellen (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo) muss jede Zeile ein "messages"-Array mit den Nachrichten des Gesprächs enthalten.

Vorgeschriebenes Format
{"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."}]}

Pflichtfelder

  • messages — Array mit Nachrichtenobjekten (erforderlich)
  • role — Einer der Werte "system", "user" oder "assistant" (erforderlich)
  • content — Textinhalt der Nachricht (erforderlich)

Die Systemnachricht ist optional, wird aber empfohlen. Jedes Gespräch muss mindestens eine Benutzernachricht und eine Assistentennachricht enthalten. Das Modell lernt, Antworten wie die jeweilige Assistentennachricht zu erzeugen.

JSONL-Format für die Batch API

Die Batch API verwendet ein anderes JSONL-Format: Jede Zeile enthält eine API-Anfrage mit einer selbst vergebenen ID.

Vorgeschriebenes Format
{"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?"}]}}

Pflichtfelder

  • custom_id — Eindeutige Kennung für jede Anfrage (erforderlich)
  • method — HTTP-Methode, in der Regel "POST" (erforderlich)
  • url — Pfad des API-Endpunkts (erforderlich)
  • body — Request-Body, wie bei einem normalen API-Aufruf (erforderlich)

Formatvorgaben

Damit OpenAI Ihre JSONL-Datei akzeptiert, müssen Sie folgende Regeln beachten:

  • Jede Zeile muss gültiges JSON enthalten; Syntaxfehler sind nicht zulässig
  • Jede Zeile muss ein JSON-Objekt enthalten (beginnt mit { und endet mit })
  • In Dateien für das Fine-Tuning muss jede Zeile ein "messages"-Array enthalten
  • Jede Nachricht muss die beiden Felder "role" und "content" enthalten
  • Zulässige Rollen sind "system", "user" und "assistant"
  • Die Datei muss in UTF-8 ohne BOM (Byte Order Mark) kodiert sein
  • Keine überflüssigen Kommas am Ende von Arrays oder Objekten, keine Kommentare und kein zusätzlicher Whitespace zwischen den Zeilen
  • Leerzeilen sind zulässig und werden ignoriert

Häufige Fehler

Beim Erstellen von JSONL-Dateien für OpenAI treten diese Fehler besonders häufig auf:

Verwendung eines JSON-Arrays anstelle von JSONL

Falsch ist es, alle Objekte in [ ] einzuschließen. In einer JSONL-Datei steht genau ein Objekt pro Zeile, ohne umschließendes Array.

Falsch
[{"messages":[...]}, {"messages":[...]}]
Richtig
{"messages":[...]}
{"messages":[...]}

Fehlende Pflichtfelder

Jede Nachricht muss sowohl "role" als auch "content" enthalten. Fehlt eines der beiden Felder, schlägt die Validierung fehl.

Falsch
{"messages":[{"role":"user"}]}
Richtig
{"messages":[{"role":"user","content":"Hello"}]}

Überflüssige Kommas in JSON

In JSON darf nach dem letzten Element eines Arrays oder Objekts kein Komma stehen.

Falsch
{"messages":[{"role":"user","content":"Hi",}]}
Richtig
{"messages":[{"role":"user","content":"Hi"}]}

BOM-Zeichen oder falsche Kodierung

Speichern Sie Ihre Datei in UTF-8 ohne BOM. Manche Texteditoren fügen unsichtbare BOM-Zeichen ein, die beim Parsen von JSON zu Fehlern führen.

Falsch
\uFEFF{"messages":[...]}
Richtig
{"messages":[...]}

Codebeispiele

So erstellen Sie JSONL-Dateien für OpenAI per Code:

Python — JSONL-Datei für das Fine-Tuning erstellen
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 — JSONL-Datei für das Fine-Tuning erstellen
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`);

JSONL-Dateien für OpenAI ansehen und bearbeiten

Mit unserem kostenlosen Online-JSONL-Viewer können Sie Fine-Tuning-Datensätze und Dateien für die Batch API prüfen – mit einer Ansicht nebeneinander, Syntaxhervorhebung und Validierung in Echtzeit.

Häufig gestellte Fragen

Quellen