- Startseite
- Anleitung
- JSONL für KI-Trainingsdaten
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.
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.
{"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.
{"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.
{"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.
{"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.
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)
breakSie 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.
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.
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.
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.
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.
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)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.
Ein umfassender Leitfaden zur Vorbereitung von JSONL-Dateien für OpenAI. Mit dem Datenformat für das Fine-Tuning, Anfragen an die Batch API, häufigen Fehlern und Tipps zur Validierung.
Validieren Sie JSONL-Dateien Zeile für Zeile und erkennen Sie Syntaxfehler, Probleme mit der Zeichenkodierung und Formatfehler sofort.
Teilen Sie große JSONL-Dateien nach Zeilenanzahl in kleinere, handliche Teile auf.
Konvertieren Sie CSV-Tabellen ins JSONL-Format. Praktisch für Datenmigrationen und die Batch-Verarbeitung.
Bewährte Vorgehensweisen für JSONL: Formatierung, einheitliche Schemas, Fehlerbehandlung, Performance-Optimierung und Dateiorganisation. Praktische Beispiele helfen Ihnen, typische Fallstricke zu vermeiden.