Guide du format JSONL OpenAI
Tout ce que vous devez savoir sur le format JSONL utilisé par OpenAI pour le fine-tuning de modèles et la Batch API. Comprend les spécifications du format, des exemples de code et les pièges courants.
Dernière mise à jour : février 2026
Qu'est-ce que le format JSONL OpenAI ?
OpenAI utilise le JSONL (JSON Lines) comme format de fichier standard pour les jeux de données de fine-tuning et les requêtes Batch API. Chaque ligne du fichier est un objet JSON complet et indépendant — pas de tableau englobant, pas de virgules entre les lignes.
Ce format est choisi car il permet un streaming efficace et un traitement ligne par ligne. Chaque exemple d'entraînement ou requête API peut être validé indépendamment, et les fichiers peuvent être traités sans charger l'ensemble du jeu de données en mémoire.
Comprendre les exigences exactes du format est essentiel. Même de petites erreurs de formatage — comme une virgule en fin de ligne ou un champ manquant — entraîneront 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" avec les tours de 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 message (requis)
- role — L'un des suivants : "system", "user" ou "assistant" (requis)
- content — Le contenu textuel du message (requis)
Le message système est optionnel mais recommandé. Chaque conversation doit avoir au moins un message utilisateur et un message assistant. Le message assistant est ce que le modèle apprend à générer.
Format JSONL pour la Batch API
La Batch API utilise un format JSONL différent où chaque ligne est une requête API avec 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 — Un identifiant unique pour chaque requête (requis)
- method — Méthode HTTP, généralement "POST" (requis)
- url — Chemin de l'endpoint API (requis)
- body — Le corps de la requête, identique à un appel API classique (requis)
Exigences du format
Suivez ces règles pour vous assurer que votre fichier JSONL est accepté par OpenAI :
- Chaque ligne doit être du JSON valide — aucune erreur de syntaxe n'est tolérée
- Chaque ligne doit être un objet JSON (commence par '{' et se termine par '}')
- Les fichiers de fine-tuning doivent inclure un tableau "messages" dans chaque ligne
- Chaque message doit avoir les champs "role" et "content"
- Les rôles valides sont : "system", "user" et "assistant"
- Le fichier doit être encodé en UTF-8 sans BOM (Byte Order Mark)
- Pas de virgules en fin de ligne, pas de commentaires, pas d'espaces superflus 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 OpenAI :
Utiliser un tableau JSON au lieu de JSONL
Erreur : englober tous les objets dans [ ]. Les fichiers JSONL doivent avoir un objet par ligne sans tableau englobant.
['{'"messages":[...]'}', '{'"messages":[...]'}']'{'"messages":[...]'}'
'{'"messages":[...]'}'Champs requis manquants
Chaque message doit avoir à la fois "role" et "content". L'omission de l'un ou l'autre entraînera un échec de la validation.
'{'"messages":['{'"role":"user"'}']'}''{'"messages":['{'"role":"user","content":"Hello"'}']'}'Virgules en fin de ligne dans le JSON
Le JSON n'autorise pas les virgules après le dernier élément d'un tableau ou d'un objet.
'{'"messages":['{'"role":"user","content":"Hi",'}']'}''{'"messages":['{'"role":"user","content":"Hi"'}']'}'Caractères BOM ou mauvais encodage
Enregistrez votre fichier en UTF-8 sans BOM. Certains éditeurs de texte ajoutent des caractères BOM invisibles qui empêchent l'analyse JSON.
\uFEFF'{'"messages":[...]'}''{'"messages":[...]'}'Exemples de code
Voici comment créer des fichiers JSONL OpenAI par programmation :
import jsontraining_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`);