Door Jerry Fan

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.

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.

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.

Trainingsformaat voor 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."}]}

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.

Trainen met gesprekken van meerdere beurten
{"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.

Claude Messages-formaat
{"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.

Claude-gesprekken met meerdere beurten
{"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.

JSONL-datasets 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

Je 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.

Exporteren naar JSONL
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.

Validator voor JSONL-trainingsdata
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.

Script om duplicaten te verwijderen
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.

Pipeline voor het shufflen en splitsen in trainings- en 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
)

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.

Bestanden opdelen in shards voor gedistribueerde 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)

Klaar om je trainingsdata voor te bereiden?

Valideer, formatteer en bekijk je JSONL-trainingsbestanden direct in je browser. Geen uploads, geen registratie, 100% privé.

Veelgestelde vragen

Bronnen