Guide du format JSONL d’OpenAI
Tout ce qu’il faut savoir sur le format JSONL utilisé par OpenAI pour le fine-tuning des modèles et la Batch API : spécifications du format, exemples de code et pièges courants.
Qu’est-ce que le format JSONL d’OpenAI ?
OpenAI utilise JSONL (JSON Lines) comme format de fichier standard pour les jeux de données de fine-tuning et les requêtes de la Batch API. Chaque ligne du fichier contient un objet JSON complet et indépendant, sans tableau pour regrouper les objets ni virgule entre les lignes.
Ce format permet de lire les données efficacement en streaming et de les traiter ligne par ligne. Chaque exemple d’entraînement ou requête API peut être validé séparément, et les fichiers peuvent être traités sans charger tout le jeu de données en mémoire.
Il est essentiel de respecter précisément le format attendu. Une simple erreur de format, comme une virgule superflue après le dernier élément ou un champ manquant, suffit à entraîner le rejet du fichier entier.
Format JSONL pour le fine-tuning
Pour le fine-tuning des modèles de chat (GPT-4o, GPT-4o-mini, GPT-3.5 Turbo), chaque ligne doit contenir un tableau "messages" regroupant les échanges de la conversation.
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is the capital of France?"},{"role":"assistant","content":"The capital of France is Paris."}]}
{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"},{"role":"assistant","content":"2+2 equals 4."}]}Champs requis
- messages — Tableau d’objets représentant les messages (obligatoire)
- role — Valeur parmi "system", "user" ou "assistant" (obligatoire)
- content — Contenu textuel du message (obligatoire)
Le message système est facultatif, mais recommandé. Chaque conversation doit contenir au moins un message de l’utilisateur et une réponse de l’assistant. C’est cette réponse que le modèle apprend à générer.
Format JSONL pour la Batch API
La Batch API utilise un autre format JSONL : chaque ligne correspond à une requête API dotée d’un identifiant personnalisé.
{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello, how are you?"}]}}
{"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"What is the weather today?"}]}}Champs requis
- custom_id — Identifiant unique de chaque requête (obligatoire)
- method — Méthode HTTP, généralement "POST" (obligatoire)
- url — Chemin du point de terminaison de l’API (obligatoire)
- body — Corps de la requête, identique à celui d’un appel API classique (obligatoire)
Règles à respecter
Pour que votre fichier JSONL soit accepté par OpenAI, respectez les règles suivantes :
- Chaque ligne doit contenir du JSON valide, sans aucune erreur de syntaxe
- Chaque ligne doit contenir un objet JSON, qui commence par { et se termine par }
- Dans les fichiers de fine-tuning, chaque ligne doit contenir un tableau "messages"
- Chaque message doit comporter les deux champs "role" et "content"
- Les valeurs autorisées pour le rôle sont "system", "user" et "assistant"
- Le fichier doit être encodé en UTF-8 sans BOM (Byte Order Mark)
- Aucune virgule après le dernier élément, aucun commentaire ni espace superflu entre les lignes
- Les lignes vides sont autorisées et seront ignorées
Erreurs courantes
Voici les erreurs les plus fréquentes lors de la création de fichiers JSONL pour OpenAI :
Utiliser un tableau JSON à la place du format JSONL
Erreur : placer tous les objets dans [ ]. Un fichier JSONL doit contenir un objet par ligne, sans tableau pour les regrouper.
[{"messages":[...]}, {"messages":[...]}]{"messages":[...]}
{"messages":[...]}Oublier des champs obligatoires
Chaque message doit comporter les deux champs "role" et "content". Si l’un des deux manque, la validation échoue.
{"messages":[{"role":"user"}]}{"messages":[{"role":"user","content":"Hello"}]}Ajouter une virgule après le dernier élément
Le format JSON n’autorise pas de virgule après le dernier élément d’un tableau ou d’un objet.
{"messages":[{"role":"user","content":"Hi",}]}{"messages":[{"role":"user","content":"Hi"}]}Présence d’un BOM ou encodage incorrect
Enregistrez votre fichier en UTF-8 sans BOM. Certains éditeurs de texte ajoutent des caractères BOM invisibles qui empêchent de parser le JSON.
\uFEFF{"messages":[...]}{"messages":[...]}Exemples de code
Voici comment générer des fichiers JSONL pour OpenAI en code :
import json
training_data = [
{"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is JSONL?"},
{"role": "assistant", "content": "JSONL (JSON Lines) is a text format where each line is a valid JSON object."}
]},
{"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "How do I fine-tune a model?"},
{"role": "assistant", "content": "Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API."}
]},
]
with open("training.jsonl", "w", encoding="utf-8") as f:
for entry in training_data:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
print(f"Created training.jsonl with {len(training_data)} examples")const fs = require('fs');
const trainingData = [
{ messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'What is JSONL?' },
{ role: 'assistant', content: 'JSONL (JSON Lines) is a text format where each line is a valid JSON object.' },
]},
{ messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'How do I fine-tune a model?' },
{ role: 'assistant', content: 'Prepare a JSONL file with training examples, then use the OpenAI fine-tuning API.' },
]},
];
const jsonl = trainingData.map(d => JSON.stringify(d)).join('\n');
fs.writeFileSync('training.jsonl', jsonl + '\n', 'utf-8');
console.log(`Created training.jsonl with ${trainingData.length} examples`);Outils et guides associés
Validez vos fichiers JSONL ligne par ligne. Repérez immédiatement les erreurs de syntaxe et les problèmes d’encodage ou de format.
Mettez en forme vos fichiers JSONL avec une indentation adaptée pour les rendre plus lisibles et faciliter le débogage et la revue des données.
Divisez les grands fichiers JSONL en morceaux plus petits et gérables par nombre de lignes.
Apprenez à structurer vos fichiers JSONL pour l’API Batch d’OpenAI : format des requêtes, analyse des réponses et workflow complet avec des exemples de code.
Apprenez à préparer des données d’entraînement JSONL pour le fine-tuning de modèles d’IA et de machine learning. Retrouvez les formats de jeux de données d’OpenAI, d’Anthropic Claude et de HuggingFace, ainsi que la validation et les pipelines de préparation des données.