JSONL-Trainingsdateien

Was es ist

JSON ist die gängigste Methode, strukturierte Daten als Text zu schreiben: Objekte in geschweiften Klammern, Listen in eckigen Klammern, Schlüssel und Werte in Anführungszeichen. JSONL, auch JSON Lines oder Newline-delimited JSON genannt, fügt eine weitere Regel hinzu: Jede Zeile der Datei ist ein vollständiger, gültiger JSON-Wert, und die Zeilen sind durch einen Zeilenumbruch getrennt. Bei Trainingsdaten ist jeder Wert ein Objekt, das ein Beispiel enthält.

train.jsonl

{"messages":[{"role":"system","content":"You are…"},{"role":"user","content":"How do I reset my password?"},{"role":"assistant","content":"Open Settings → Security…"}]}

{"messages":[{"role":"user","content":"Hi"},{"role":"assistant","content":"Hello! How can I help?","weight":0},{"role":"user","content":"Export my report as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF…","weight":1}]}

{"messages":[{"role":"system","content":"You are…"},{"role":"user","content":"Can I change my plan mid-month?"},{"role":"assistant","content":"Yes. The difference is prorated…"}]}

…eine Zeile pro Datensatz, keine Kommas zwischen den Zeilen, keine umschließenden [ ]

{ … }ein vollständiges JSON-Objekt = ein Trainingsdatensatz"messages"die Konversation, in der richtigen Reihenfolge"role"wer es gesagt hat: System, Benutzer oder Assistent"weight"diese Antwort lernen (1) oder nur lesen (0)\nein Zeilenumbruch beendet den Datensatz

Eine JSONL-Datei ist ein Stapel unabhängiger JSON-Objekte, eines pro Zeile. Jede Zeile kann für sich allein gelesen, geprüft, gezählt oder gemischt werden, weshalb jeder große Fine-Tuning-Dienst sie verwendet.

Warum es für das Training verwendet wird

Streaming: Ein Anbieter kann eine Multi-Gigabyte-Datei zeilenweise lesen, anstatt sie als Ganzes zu laden und zu parsen.
Unabhängigkeit: Datensätze können gezählt, gemischt, in Trainings- und Validierungsdaten aufgeteilt oder als Stichprobe entnommen werden, ohne den Rest der Datei zu parsen.
Eindeutige Fehler: Ein fehlerhafter Datensatz bricht nur eine Zeile ab, und die Fehlermeldung kann diese genau benennen („Zeile 482: unerwartetes Ende der Eingabe“).
Erweiterbar: Das Hinzufügen von Beispielen bedeutet das Hinzufügen von Zeilen; nichts anderes in der Datei ändert sich.

Die Regeln und wie Dateien fehlerhaft werden

Die JSON Lines-Spezifikation umfasst drei Regeln: Die Datei ist in UTF-8 codiert, jede Zeile ist ein gültiger JSON-Wert und jede Zeile endet mit einem Zeilenvorschubzeichen (Line-Feed). Es wird dringend empfohlen, die Datei mit einem Zeilenumbruch zu beenden. Fast jede fehlerhafte Trainingsdatei verstößt gegen eine dieser Regeln:

häufige Fehlerquellen in einer Datei

✗ {"messages": [ ...          ← a pretty-printed object split over lines
     {"role": "user", ... } ]}
✗ [ {"messages": ...}, {"messages": ...} ]   ← a JSON array, not one object per line
✗ {"messages": [...]},        ← trailing comma
✗                             ← a blank line in the middle
✓ {"messages":[...]}          ← one complete object, then a line break

Zeilenumbrüche innerhalb des Textes einer Nachricht sind unproblematisch, da JSON sie maskiert (als Backslash gefolgt von n) innerhalb der Zeichenfolge speichert. Was nicht passieren darf, ist ein echter Zeilenumbruch in der Mitte eines Objekts — genau das geschieht jedoch beim „Pretty-Printing“ einer Datei zur besseren Lesbarkeit.

Gleiches Format, unterschiedliche Strukturen

Jeder große Fine-Tuning-Dienst akzeptiert JSONL, aber jeder definiert sein eigenes Schema dafür, was innerhalb einer Zeile steht. Einige verwenden eine messages-Liste mit den Rollen system, user und assistant; andere setzen den System-Prompt in ein separates Feld; manche nennen die Liste contents und die Assistentenrolle model; einige unterstützen ein weight (Gewicht) für jede Assistentennachricht, sodass frühere Antworten nur als Kontext dienen.

ein Beispiel, drei Anbieterformate

// chat "messages" (with an optional weight per assistant reply)
{"messages":[{"role":"user","content":"Hi"},{"role":"assistant","content":"Hello!","weight":0},{"role":"user","content":"Export as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF.","weight":1}]}

// "contents" with user / model roles
{"contents":[{"role":"user","parts":[{"text":"Export as PDF"}]},{"role":"model","parts":[{"text":"Open the report, click Export → PDF."}]}]}

// separate system field
{"system":"You are a support assistant.","messages":[{"role":"user","content":"Export as PDF"},{"role":"assistant","content":"Open the report, click Export → PDF."}]}

Wenn ein Format kein Gewicht pro Nachricht hat, wird eine mehrstufige Konversation mit mehreren Zielen als ein Datensatz pro Ziel geschrieben, der jeweils direkt nach seiner Zielantwort abgeschnitten wird. In diesen Datensätzen werden auch die früheren Antworten des Assistenten gelernt, da das Format keine Möglichkeit bietet, sie nur als Kontext zu markieren.

Praxisbeispiel: eine Konversation, zwei Dateien

Eine Konversation besteht aus vier Nachrichten: „Hi“, einer Begrüßung, „Exportiere meinen Bericht als PDF“ und den Anweisungen. Nur die Anweisungen sind als Ziel markiert.
Für einen Anbieter, der Gewichte unterstützt: eine Zeile, mit der Begrüßung bei weight: 0 und den Anweisungen bei weight: 1.
Für einen Anbieter ohne Gewichte: ebenfalls eine Zeile, die bei den Anweisungen endet. Wäre die Begrüßung ebenfalls ein Ziel gewesen, gäbe es zwei Zeilen — eine, die bei der Begrüßung endet, und eine bei den Anweisungen — und die Begrüßung würde zweimal gelernt werden.
Beide Dateien enthalten denselben bereinigten, geschwärzten Text. Nur die Struktur unterscheidet sich.

Häufige Fehler

Das Formatieren (Pretty-Printing) einer Trainingsdatei, sodass sich jedes Objekt über mehrere Zeilen erstreckt.
Das Speichern eines JSON-Arrays von Datensätzen und dessen Benennung als .jsonl.
Das manuelle Bearbeiten einer Datei in einem Tool, das die Codierung ändert oder typografische Anführungszeichen hinzufügt, was das JSON unbrauchbar macht.
Die Wiederverwendung der Datei eines Anbieters bei einem anderen Anbieter: Das Format ist dasselbe, das Schema darin jedoch nicht.

Quellen und weiterführende Literatur

Externe Quellen werden in einem neuen Tab geöffnet.