Von Jerry Fan

JSONL für KI-Trainingsdaten

Ein umfassender Leitfaden zur Aufbereitung von JSONL-Trainingsdaten für KI und Machine Learning: mit OpenAI-Fine-Tuning, Anthropic Claude, HuggingFace-Datensätzen, Datenvalidierung und Datenpipelines für große Datenmengen.

Warum JSONL der Standard für KI-Trainingsdaten ist

JSONL (JSON Lines) hat sich als De-facto-Standard für Trainingsdaten in KI und Machine Learning etabliert. Alle großen KI-Anbieter, von OpenAI über Anthropic bis hin zu HuggingFace, setzen bei Fine-Tuning-Datensätzen vorrangig auf JSONL. Der Grund ist einfach: JSONL speichert ein Beispiel pro Zeile. Dadurch lassen sich Daten beim Training leicht streamen, Beispiele mischen, Datensätze zählen, Daten in Trainings- und Testsets aufteilen und neue Beispiele anhängen, ohne die gesamte Datei neu schreiben zu müssen.

Ein einzelnes JSON-Array muss vor der Verwendung vollständig geparst werden. JSONL-Dateien lassen sich dagegen zeilenweise verarbeiten. Das ist besonders wichtig, wenn Ihre Trainingsdatensätze auf Millionen von Beispielen und mehrere Gigabyte anwachsen. In diesem Leitfaden erfahren Sie, welche JSONL-Formate OpenAI, Anthropic Claude und HuggingFace genau erwarten, wie Sie Ihre Daten validieren und bereinigen und wie Sie große Datensätze für produktive Trainingsläufe aufbereiten.

Trainingsdaten online validieren

Mit unseren kostenlosen Tools können Sie Ihre JSONL-Trainingsdaten direkt im Browser validieren, formatieren und konvertieren, bevor Sie sie bei OpenAI, Anthropic oder HuggingFace hochladen.

JSONL-Format für das Fine-Tuning mit OpenAI

OpenAI verwendet JSONL sowohl für das Fine-Tuning als auch für die Batch API. Beim Fine-Tuning von Chat-Modellen wie GPT-4o-mini muss jede Zeile ein messages-Array in der üblichen Chat-Completion-Struktur enthalten. Die drei Rollen system, user und assistant bilden das Gespräch ab, dessen Wiedergabe das Modell lernen soll.

Jede Zeile enthält ein Trainingsbeispiel. Die Systemnachricht legt das Verhalten fest, die Benutzernachricht liefert die Eingabe und die Assistentennachricht enthält die gewünschte Ausgabe, die das Modell lernen soll.

Trainingsformat für Chat Completions
{"messages": [{"role": "system", "content": "You are a helpful customer support agent for an e-commerce platform."}, {"role": "user", "content": "Where is my order #12345?"}, {"role": "assistant", "content": "I can see that order #12345 was shipped on February 10th via FedEx. The tracking number is FX987654321. Based on the latest update, it should arrive by February 14th."}]}
{"messages": [{"role": "system", "content": "You are a helpful customer support agent for an e-commerce platform."}, {"role": "user", "content": "I want to return my purchase."}, {"role": "assistant", "content": "I would be happy to help with your return. Could you please provide the order number and the reason for the return? Our return policy allows returns within 30 days of delivery for most items."}]}

Geben Sie bei mehrteiligen Dialogen den vollständigen Gesprächsverlauf an. Das Modell lernt aus jeder assistant-Nachricht im messages-Array. So lernt es, auf Rückfragen einzugehen.

Training mit mehrteiligen Dialogen
{"messages": [{"role": "system", "content": "You are a Python programming tutor."}, {"role": "user", "content": "What is a list comprehension?"}, {"role": "assistant", "content": "A list comprehension is a concise way to create lists in Python. Instead of writing a for loop to build a list, you can write it in one line: [expression for item in iterable if condition]."}, {"role": "user", "content": "Can you show me an example?"}, {"role": "assistant", "content": "Sure! Here is an example that creates a list of squares for even numbers:\n\nsquares = [x**2 for x in range(10) if x % 2 == 0]\n# Result: [0, 4, 16, 36, 64]\n\nThis is equivalent to:\nsquares = []\nfor x in range(10):\n    if x % 2 == 0:\n        squares.append(x**2)"}]}

OpenAI setzt mindestens 10 Trainingsbeispiele voraus, empfiehlt für spürbare Verbesserungen aber 50-100. Alle Nachrichten müssen die Felder role und content enthalten. Die Systemnachricht ist optional, wird aber empfohlen, damit sich das Modell konsistent verhält. Validieren Sie Ihre Datei vor dem Hochladen mit der OpenAI-CLI: openai tools fine_tunes.prepare_data -f training.jsonl

Trainingsformat für Anthropic Claude

Anthropic verwendet JSONL für das Fine-Tuning von Claude-Modellen. Das Format bildet strukturierte Gespräche mit Beiträgen von human und assistant ab. Das genaue Format hängt von der Fine-Tuning-Methode und der API-Version ab; der grundlegende Aufbau folgt jedoch der Struktur der Messages API.

Jede Zeile enthält ein Gespräch mit einem System-Prompt und abwechselnden user/assistant-Nachrichten. Das Modell lernt, anhand des Gesprächskontexts die Antworten des Assistenten zu erzeugen.

Nachrichtenformat für Claude
{"system": "You are a medical information assistant. Provide accurate, general health information while always recommending consulting a healthcare professional.", "messages": [{"role": "user", "content": "What are the symptoms of vitamin D deficiency?"}, {"role": "assistant", "content": "Common symptoms of vitamin D deficiency include fatigue and tiredness, bone pain and muscle weakness, mood changes including depression, slow wound healing, and frequent infections. However, many people with mild deficiency may not notice symptoms. A blood test is the only way to confirm your vitamin D levels. I recommend speaking with your doctor who can order the appropriate test and recommend supplementation if needed."}]}
{"system": "You are a medical information assistant. Provide accurate, general health information while always recommending consulting a healthcare professional.", "messages": [{"role": "user", "content": "Is it safe to take ibuprofen daily?"}, {"role": "assistant", "content": "Taking ibuprofen daily for extended periods can carry risks including stomach ulcers and gastrointestinal bleeding, increased risk of heart attack and stroke, kidney problems with long-term use, and potential interactions with other medications. For occasional pain relief, short-term use at recommended doses is generally considered safe for most adults. However, if you find yourself needing daily pain relief, please consult your doctor. They can evaluate the underlying cause and recommend a safer long-term treatment plan."}]}

Nehmen Sie bei Trainingsdaten für mehrteilige Dialoge das vollständige Gespräch mit abwechselnden user- und assistant-Nachrichten auf. So lernt das Modell den Gesprächsablauf und wie es den Kontext über mehrere Gesprächsschritte hinweg beibehält.

Mehrteilige Dialoge mit Claude
{"system": "You are a cooking assistant specializing in Italian cuisine.", "messages": [{"role": "user", "content": "How do I make carbonara?"}, {"role": "assistant", "content": "Authentic carbonara uses just five ingredients: spaghetti, guanciale (cured pork cheek), eggs, Pecorino Romano cheese, and black pepper. The key technique is tempering the egg mixture with the hot pasta water so it creates a creamy sauce without scrambling."}, {"role": "user", "content": "Can I use bacon instead of guanciale?"}, {"role": "assistant", "content": "While guanciale gives the most authentic flavor, pancetta is a closer substitute. Bacon works in a pinch but its smoky flavor changes the dish significantly. If using bacon, choose an unsmoked variety. Whichever you use, cut it into small pieces and render the fat slowly over medium-low heat until crispy."}]}

HuggingFace-Datensätze mit JSONL

Die datasets-Bibliothek von HuggingFace unterstützt JSONL nativ als Eingabeformat. Damit können Sie lokale JSONL-Dateien laden, Datensätze von externen Quellen streamen und einfach zwischen Formaten konvertieren. JSONL ist das empfohlene Format, um Datensätze auf dem HuggingFace Hub zu teilen.

Mit der datasets-Bibliothek laden Sie JSONL-Dateien in ein Dataset-Objekt. Damit erhalten Sie effizienten Zugriff per Memory Mapping, integrierte Funktionen zur Aufteilung in Trainings- und Testsets und eine nahtlose Anbindung an die Trainer-API.

JSONL-Datensätze laden
from datasets import load_dataset


# Load a local JSONL file
dataset = load_dataset('json', data_files='training.jsonl')
print(dataset)
# DatasetDict({
#     train: Dataset({
#         features: ['messages', 'system'],
#         num_rows: 5000
#     })
# })


# Load with train/test split
dataset = load_dataset('json', data_files={
    'train': 'train.jsonl',
    'test': 'test.jsonl'
})


# Stream a large remote dataset
dataset = load_dataset(
    'json',
    data_files='https://example.com/large_dataset.jsonl',
    streaming=True
)
for example in dataset['train']:
    print(example)
    break

Sie können jeden HuggingFace-Datensatz ins JSONL-Format konvertieren, um ihn in anderen Trainingspipelines zu verwenden. Die Methode to_json schreibt jedes Beispiel als JSON in eine eigene Zeile.

Als JSONL exportieren
from datasets import load_dataset


# Load a dataset from the Hub
dataset = load_dataset('squad', split='train')


# Export to JSONL
dataset.to_json('squad_train.jsonl')
print(f'Exported {len(dataset)} examples')


# Export with specific columns
dataset.select_columns(['question', 'context', 'answers']).to_json(
    'squad_filtered.jsonl'
)


# Process and export
def format_for_finetuning(example):
    return {
        'messages': [
            {'role': 'user', 'content': example['question']},
            {'role': 'assistant', 'content': example['answers']['text'][0]}
        ]
    }


formatted = dataset.map(format_for_finetuning, remove_columns=dataset.column_names)
formatted.to_json('squad_chat_format.jsonl')

Daten validieren und bereinigen

Die Qualität der Trainingsdaten wirkt sich direkt auf die Leistung des Modells aus. Ungültiges JSON, fehlende Felder, zu lange Beispiele und doppelte Einträge können die Ergebnisse des Fine-Tunings verschlechtern. Validieren und bereinigen Sie Ihre JSONL-Dateien deshalb immer, bevor Sie einen Trainingslauf starten.

Dieses Skript prüft jede Zeile Ihrer JSONL-Datei auf typische Probleme: ungültiges JSON, fehlende Pflichtfelder, leere Inhalte und die Länge in Tokens. Führen Sie es vor dem Hochladen aus, um Probleme frühzeitig zu erkennen.

Validator für JSONL-Trainingsdaten
import json
import sys
from collections import Counter


def validate_training_data(path: str) -> dict:
    """Validate a JSONL file for AI fine-tuning."""
    stats = Counter()
    errors = []


    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            stats['total'] += 1


            # Check valid JSON
            try:
                data = json.loads(line)
            except json.JSONDecodeError as e:
                errors.append(f'Line {line_num}: Invalid JSON - {e}')
                stats['invalid_json'] += 1
                continue


            # Check messages field exists
            if 'messages' not in data:
                errors.append(f'Line {line_num}: Missing "messages" field')
                stats['missing_messages'] += 1
                continue


            messages = data['messages']


            # Check message structure
            for i, msg in enumerate(messages):
                if 'role' not in msg:
                    errors.append(f'Line {line_num}, msg {i}: Missing "role"')
                    stats['missing_role'] += 1
                if 'content' not in msg:
                    errors.append(f'Line {line_num}, msg {i}: Missing "content"')
                    stats['missing_content'] += 1
                elif not msg['content'].strip():
                    errors.append(f'Line {line_num}, msg {i}: Empty content')
                    stats['empty_content'] += 1


            # Check has at least one assistant message
            roles = [m.get('role') for m in messages]
            if 'assistant' not in roles:
                errors.append(f'Line {line_num}: No assistant message')
                stats['no_assistant'] += 1


            stats['valid'] += 1


    return {'stats': dict(stats), 'errors': errors[:50]}


result = validate_training_data('training.jsonl')
print(f"Total: {result['stats'].get('total', 0)}")
print(f"Valid: {result['stats'].get('valid', 0)}")
if result['errors']:
    print(f"\nFirst {len(result['errors'])} errors:")
    for err in result['errors']:
        print(f'  {err}')

Doppelte Trainingsbeispiele verschwenden Rechenleistung und können dazu führen, dass das Modell überrepräsentierte Muster bevorzugt. Dieses Skript entfernt exakte Duplikate anhand eines Hashwerts des Inhalts jeder Zeile.

Skript zum Entfernen von Duplikaten
import json
import hashlib


def deduplicate_jsonl(input_path: str, output_path: str) -> dict:
    """Remove duplicate training examples from a JSONL file."""
    seen_hashes = set()
    total = 0
    unique = 0


    with open(input_path, 'r') as fin, open(output_path, 'w') as fout:
        for line in fin:
            line = line.strip()
            if not line:
                continue
            total += 1


            # Hash the normalized JSON to catch formatting differences
            data = json.loads(line)
            canonical = json.dumps(data, sort_keys=True)
            content_hash = hashlib.sha256(canonical.encode()).hexdigest()


            if content_hash not in seen_hashes:
                seen_hashes.add(content_hash)
                fout.write(json.dumps(data) + '\n')
                unique += 1


    duplicates = total - unique
    print(f'Total: {total}, Unique: {unique}, Removed: {duplicates}')
    return {'total': total, 'unique': unique, 'duplicates': duplicates}


deduplicate_jsonl('training.jsonl', 'training_deduped.jsonl')

Große Datenmengen aufbereiten

Trainingsdatensätze für den produktiven Einsatz enthalten oft Hunderttausende oder Millionen von Beispielen. Bei diesen Datenmengen benötigen Sie automatisierte Pipelines, um Ihre JSONL-Daten zu mischen, in Trainings- und Testsets aufzuteilen und auf mehrere Dateien zu verteilen (Sharding). Eine sorgfältige Aufbereitung verhindert Trainingsprobleme wie katastrophales Vergessen und sorgt für reproduzierbare Experimente.

Dieses Skript mischt Ihre Daten zufällig und teilt sie in Trainings- und Testsets auf. Das Mischen ist entscheidend, weil JSONL-Dateien häufig in einer bestimmten Reihenfolge erzeugt werden. Wird das Modell mit solchen geordneten Daten trainiert, kann es schlechter generalisieren.

Pipeline zum Mischen und Aufteilen in Trainings- und Testsets
import json
import random
from pathlib import Path


def prepare_training_data(
    input_path: str,
    output_dir: str,
    test_ratio: float = 0.1,
    seed: int = 42
) -> dict:
    """Shuffle and split JSONL into train/test sets."""
    random.seed(seed)
    output = Path(output_dir)
    output.mkdir(parents=True, exist_ok=True)


    # Load all examples
    examples = []
    with open(input_path, 'r') as f:
        for line in f:
            line = line.strip()
            if line:
                examples.append(json.loads(line))


    # Shuffle
    random.shuffle(examples)


    # Split
    split_idx = int(len(examples) * (1 - test_ratio))
    train_data = examples[:split_idx]
    test_data = examples[split_idx:]


    # Write output files
    train_path = output / 'train.jsonl'
    test_path = output / 'test.jsonl'


    for data, path in [(train_data, train_path), (test_data, test_path)]:
        with open(path, 'w') as f:
            for example in data:
                f.write(json.dumps(example) + '\n')


    print(f'Train: {len(train_data)} examples -> {train_path}')
    print(f'Test:  {len(test_data)} examples -> {test_path}')
    return {'train': len(train_data), 'test': len(test_data)}


prepare_training_data(
    'all_examples.jsonl',
    './prepared_data/',
    test_ratio=0.1,
    seed=42
)

Wenn ein Datensatz für eine einzelne Datei zu groß ist oder Sie das Training auf mehrere GPUs verteilen müssen, teilen Sie die JSONL-Datei in kleinere Dateien auf, sogenannte Shards. Jeder Shard lässt sich unabhängig von den anderen verarbeiten.

Datei-Sharding für verteiltes Training
import json
from pathlib import Path


def shard_jsonl(
    input_path: str,
    output_dir: str,
    shard_size: int = 50000
) -> int:
    """Split a large JSONL file into smaller shards."""
    output = Path(output_dir)
    output.mkdir(parents=True, exist_ok=True)


    shard_num = 0
    line_count = 0
    current_file = None


    with open(input_path, 'r') as fin:
        for line in fin:
            line = line.strip()
            if not line:
                continue


            if line_count % shard_size == 0:
                if current_file:
                    current_file.close()
                shard_path = output / f'shard_{shard_num:04d}.jsonl'
                current_file = open(shard_path, 'w')
                shard_num += 1


            current_file.write(line + '\n')
            line_count += 1


    if current_file:
        current_file.close()


    print(f'Created {shard_num} shards from {line_count} examples')
    return shard_num


shard_jsonl('large_dataset.jsonl', './shards/', shard_size=50000)

Bereit für die Aufbereitung Ihrer Trainingsdaten?

Validieren, formatieren und prüfen Sie Ihre JSONL-Trainingsdateien direkt im Browser. Ohne Upload, ohne Anmeldung, 100 % privat.

Häufig gestellte Fragen

Quellen