JSONL pour les données d’entraînement en IA
Un guide complet pour préparer vos données d’entraînement au format JSONL pour l’IA et le machine learning : fine-tuning avec OpenAI, Anthropic Claude, datasets HuggingFace, validation des données et pipelines de données à grande échelle.
Pourquoi JSONL s’impose pour les données d’entraînement en IA
JSONL (JSON Lines) est devenu le standard de fait pour les données d’entraînement en IA et en machine learning. Tous les grands acteurs de l’IA, d’OpenAI à HuggingFace en passant par Anthropic, l’utilisent comme format principal pour leurs datasets de fine-tuning. La raison est simple : JSONL stocke un exemple par ligne. Il est donc très facile de lire les données en streaming pendant l’entraînement, de mélanger les exemples, de compter les enregistrements, de séparer les données en jeux d’entraînement et de test, ou encore d’ajouter de nouveaux échantillons sans réécrire tout le fichier.
Un tableau JSON doit être entièrement analysé avant de pouvoir être utilisé. Les fichiers JSONL, eux, se traitent ligne par ligne. Cet avantage devient essentiel lorsque vos datasets d’entraînement atteignent des millions d’exemples et plusieurs gigaoctets. Ce guide présente les formats JSONL exacts attendus par OpenAI, Anthropic Claude et HuggingFace. Vous y apprendrez à valider et à nettoyer vos données, ainsi qu’à préparer de grands datasets pour des entraînements en production.
Format JSONL pour le fine-tuning avec OpenAI
OpenAI utilise JSONL pour le fine-tuning comme pour l’API Batch. Pour entraîner des modèles de chat tels que GPT-4o-mini par fine-tuning, chaque ligne doit contenir un tableau messages qui reprend la structure standard des chat completions. Les trois rôles system, user et assistant définissent la conversation que le modèle doit apprendre à reproduire.
Chaque ligne correspond à un exemple d’entraînement. Le message system définit le comportement du modèle, le message user fournit l’entrée et le message assistant contient la réponse attendue que le modèle doit apprendre à produire.
{"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."}]}Pour les conversations à plusieurs échanges, incluez l’historique complet. Le modèle apprend à partir de chaque réponse assistant du tableau messages. Vous lui apprenez ainsi à répondre aux questions qui prolongent la conversation.
{"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 exige au moins 10 exemples d’entraînement, mais en recommande 50-100 pour obtenir des améliorations sensibles. Tous les messages doivent contenir les champs role et content. Le message system est facultatif, mais recommandé pour assurer un comportement cohérent. Utilisez la CLI OpenAI pour valider votre fichier avant de l’envoyer : openai tools fine_tunes.prepare_data -f training.jsonl
Format d’entraînement pour Claude d’Anthropic
Anthropic utilise JSONL pour le fine-tuning des modèles Claude. Le format décrit une conversation structurée composée d’interventions human et assistant. Le format exact dépend de la méthode de fine-tuning et de la version de l’API, mais son organisation générale reprend la structure de l’API Messages.
Chaque ligne contient une conversation avec un prompt système et une alternance de messages user et assistant. Le modèle apprend à produire les réponses de l’assistant en fonction du contexte de la conversation.
{"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."}]}Pour entraîner le modèle sur des conversations à plusieurs échanges, incluez chaque conversation dans son intégralité, en alternant les messages user et assistant. Le modèle apprend ainsi le déroulement d’une conversation et la manière de conserver le contexte d’un échange à l’autre.
{"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."}]}Utiliser JSONL avec les datasets HuggingFace
La bibliothèque datasets de HuggingFace prend nativement en charge le format JSONL en entrée. Elle permet de charger des fichiers JSONL locaux, de lire des datasets distants en streaming et de passer facilement d’un format à l’autre. JSONL est le format recommandé pour partager des datasets sur le HuggingFace Hub.
Utilisez la bibliothèque datasets pour charger vos fichiers JSONL dans un objet Dataset. Vous bénéficiez ainsi d’un accès efficace par projection en mémoire (memory mapping), de fonctions intégrées pour séparer les données d’entraînement et de test, et d’une intégration directe avec l’API Trainer.
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)
breakConvertissez n’importe quel dataset HuggingFace au format JSONL pour l’utiliser dans d’autres pipelines d’entraînement. La méthode to_json écrit chaque exemple sur une ligne JSON distincte.
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')Valider et nettoyer les données
La qualité des données d’entraînement influe directement sur les performances du modèle. Un JSON invalide, des champs manquants, des exemples trop longs ou des doublons peuvent dégrader les résultats du fine-tuning. Validez et nettoyez toujours vos fichiers JSONL avant de lancer un entraînement.
Ce script vérifie chaque ligne de votre fichier JSONL pour repérer les problèmes courants : JSON invalide, champs obligatoires manquants, contenu vide ou longueur en tokens. Exécutez-le avant d’envoyer le fichier pour détecter les problèmes au plus tôt.
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}')Les exemples d’entraînement en double gaspillent des ressources de calcul et peuvent biaiser le modèle en faveur de motifs surreprésentés. Ce script supprime les doublons exacts à partir du hash du contenu de chaque ligne.
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')Préparer les données à grande échelle
Les datasets utilisés pour entraîner des modèles en production contiennent souvent des centaines de milliers, voire des millions d’exemples. À cette échelle, il vous faut des pipelines automatisés pour mélanger vos données JSONL, les séparer en sous-ensembles et les répartir en plusieurs fichiers. Une bonne préparation permet d’éviter des problèmes d’entraînement comme l’oubli catastrophique et garantit la reproductibilité des expériences.
Ce script mélange les données de façon aléatoire, puis les sépare en jeux d’entraînement et de test. Cette étape est essentielle : les fichiers JSONL sont souvent générés dans un ordre donné, et entraîner un modèle sur des données ordonnées peut nuire à sa capacité de généralisation.
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
)Lorsque les datasets sont trop volumineux pour tenir dans un seul fichier, ou que vous devez répartir l’entraînement sur plusieurs GPU, découpez le fichier JSONL en fragments plus petits. Chaque fragment peut être traité indépendamment.
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)Validez vos données d’entraînement en ligne
Utilisez nos outils gratuits, directement dans votre navigateur, pour valider, formater et convertir vos données d’entraînement JSONL avant de les envoyer à OpenAI, Anthropic ou HuggingFace.
Un guide complet pour préparer vos fichiers JSONL destinés à OpenAI : format des données de fine-tuning, requêtes de l’API Batch, erreurs courantes et conseils de validation.
Validez vos fichiers JSONL ligne par ligne. Repérez immédiatement les erreurs de syntaxe et les problèmes d’encodage ou de format.
Divisez les grands fichiers JSONL en morceaux plus petits et gérables par nombre de lignes.
Convertissez des fichiers CSV au format JSONL pour vos migrations de données et vos traitements par lots.
Maîtrisez les bonnes pratiques JSONL : mise en forme, cohérence des schémas, gestion des erreurs, optimisation des performances et organisation des fichiers. Des exemples concrets vous aident à éviter les pièges courants.