JSONL voor AI-trainingsdata
Een uitgebreide gids voor het voorbereiden van JSONL-trainingsdata voor AI en machine learning. Je leest hoe je werkt met fine-tuning bij OpenAI, Anthropic Claude, HuggingFace-datasets, datavalidatie en grootschalige datapipelines.
Waarom JSONL de standaard is voor AI-trainingsdata
JSONL (JSON Lines) is inmiddels de de facto standaard voor trainingsdata voor AI en machine learning. Alle grote AI-aanbieders, van OpenAI en Anthropic tot HuggingFace, gebruiken JSONL als hun belangrijkste formaat voor datasets voor fine-tuning. De reden is simpel: JSONL slaat één voorbeeld per regel op. Daardoor kun je eenvoudig data streamen tijdens het trainen, voorbeelden in een willekeurige volgorde zetten, records tellen, de data opsplitsen in trainings- en testsets en nieuwe voorbeelden toevoegen zonder het hele bestand te herschrijven.
Een JSON-array moet je vóór gebruik volledig parsen, maar JSONL-bestanden kun je regel voor regel verwerken. Dat maakt een groot verschil zodra je trainingsdatasets uit miljoenen voorbeelden bestaan en gigabytes aan ruimte innemen. In deze gids leer je welke JSONL-formaten OpenAI, Anthropic Claude en HuggingFace precies verwachten, hoe je je data valideert en opschoont en hoe je grote datasets voorbereidt op trainingsruns voor productiemodellen.
JSONL-formaat voor fine-tuning bij OpenAI
OpenAI gebruikt JSONL voor zowel fine-tuning als de Batch API. Om chatmodellen zoals GPT-4o-mini te fine-tunen, moet elke regel een messages-array bevatten met de standaardstructuur voor chat completions. De drie rollen system, user en assistant leggen het gesprek vast dat het model moet leren reproduceren.
Elke regel bevat één trainingsvoorbeeld. Het system-bericht bepaalt het gedrag, het user-bericht bevat de invoer en het assistant-bericht bevat het gewenste antwoord dat het model moet leren geven.
{"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."}]}Neem bij gesprekken met meerdere beurten de volledige gespreksgeschiedenis op. Het model leert van elk assistant-bericht in de messages-array. Zo leer je het model om vervolgvragen te beantwoorden.
{"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 vereist minimaal 10 trainingsvoorbeelden, maar raadt 50-100 aan voor merkbare verbeteringen. Elk bericht moet de velden role en content bevatten. Het system-bericht is optioneel, maar wordt aanbevolen om het model consistent te laten reageren. Valideer je bestand vóór het uploaden met de OpenAI CLI: openai tools fine_tunes.prepare_data -f training.jsonl
Trainingsformaat voor Anthropic Claude
Anthropic gebruikt JSONL om Claude-modellen te fine-tunen. Het formaat beschrijft een gestructureerd gesprek met beurten voor de gebruiker en de assistent. Het precieze formaat hangt af van de methode voor fine-tuning en de API-versie, maar de basis volgt de structuur van de Messages API.
Elke regel bevat een gesprek met een system prompt en afwisselend user- en assistant-berichten. Het model leert om op basis van de gesprekscontext de antwoorden van de assistent te genereren.
{"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."}]}Neem voor trainingsdata met meerdere gespreksbeurten het volledige gesprek op, met afwisselend user- en assistant-berichten. Het model leert zo hoe een gesprek verloopt en hoe het de context over meerdere beurten vasthoudt.
{"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-datasets met JSONL
De datasets-library van HuggingFace ondersteunt JSONL standaard als invoerformaat. Je kunt lokale JSONL-bestanden laden, datasets vanaf een externe bron streamen en eenvoudig tussen formaten converteren. JSONL is het aanbevolen formaat om datasets te delen op de HuggingFace Hub.
Gebruik de datasets-library om JSONL-bestanden in een Dataset-object te laden. Daarmee krijg je efficiënte toegang via memory mapping, ingebouwde ondersteuning voor het splitsen in trainings- en testsets en naadloze integratie met de 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)
breakJe kunt elke HuggingFace-dataset naar JSONL converteren om deze in andere trainingspipelines te gebruiken. De methode to_json schrijft elk voorbeeld als een afzonderlijke JSON-regel weg.
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')Data valideren en opschonen
De kwaliteit van je trainingsdata heeft direct invloed op de prestaties van het model. Ongeldige JSON, ontbrekende velden, te lange voorbeelden en dubbele records kunnen allemaal tot slechtere resultaten bij fine-tuning leiden. Valideer je JSONL-bestanden daarom altijd en schoon ze op voordat je een trainingsrun start.
Dit script controleert elke regel van je JSONL-bestand op veelvoorkomende problemen: ongeldige JSON, ontbrekende verplichte velden, lege inhoud en de lengte in tokens. Voer het vóór het uploaden uit om problemen vroegtijdig op te sporen.
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}')Dubbele trainingsvoorbeelden verspillen rekenkracht en kunnen ervoor zorgen dat het model te veel nadruk legt op patronen die oververtegenwoordigd zijn. Dit script verwijdert exacte duplicaten op basis van een hash van de inhoud van elke regel.
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')Data op grote schaal voorbereiden
Trainingsdatasets voor productiemodellen bevatten vaak honderdduizenden of miljoenen voorbeelden. Op die schaal heb je geautomatiseerde pipelines nodig om je JSONL-data in een willekeurige volgorde te zetten, in trainings- en testsets te splitsen en in shards op te delen. Een goede voorbereiding voorkomt trainingsproblemen zoals catastrophic forgetting en maakt je experimenten reproduceerbaar.
Dit script zet je data in een willekeurige volgorde en splitst deze in trainings- en testsets. Die willekeurige volgorde is essentieel: JSONL-bestanden worden vaak in een vaste volgorde gegenereerd, en als je het model in die volgorde traint, kan het minder goed generaliseren.
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
)Is je dataset te groot voor één bestand of wil je de training over meerdere GPU's verdelen? Deel het JSONL-bestand dan op in kleinere stukken, zogeheten shards. Elke shard kan afzonderlijk worden verwerkt.
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)Valideer je trainingsdata online
Gebruik onze gratis tools in je browser om je JSONL-trainingsdata te valideren, te formatteren en te converteren voordat je deze naar OpenAI, Anthropic of HuggingFace uploadt.
Een complete handleiding om JSONL-bestanden voor OpenAI voor te bereiden. Met uitleg over het dataformaat voor fine-tuning, Batch API-requests, veelgemaakte fouten en tips voor validatie.
Valideer JSONL-bestanden regel voor regel. Spoor syntaxfouten, tekencoderingsproblemen en fouten in het formaat direct op.
Splits grote JSONL-bestanden op regelnummer in kleinere, beheersbare delen.
Zet CSV-spreadsheets om naar JSONL. Handig voor datamigratie en batchverwerking.
Leer de best practices voor JSONL toepassen: opmaak, consistente schema’s, foutafhandeling, prestatieoptimalisatie en het organiseren van bestanden. Vermijd veelvoorkomende valkuilen aan de hand van praktische voorbeelden.