Par Jerry Fan

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.

Validez votre fichier JSONL

Avant d’envoyer votre fichier à OpenAI, vérifiez-le avec notre validateur gratuit. Sélectionnez « Format de fine-tuning OpenAI » pour vérifier les messages, les rôles et les réponses assistant sur chaque ligne, en plus de la syntaxe JSON.

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.

Format requis
{"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é.

Format requis
{"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.

Incorrect
[{"messages":[...]}, {"messages":[...]}]
Correct
{"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.

Incorrect
{"messages":[{"role":"user"}]}
Correct
{"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.

Incorrect
{"messages":[{"role":"user","content":"Hi",}]}
Correct
{"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.

Incorrect
\uFEFF{"messages":[...]}
Correct
{"messages":[...]}

Exemples de code

Voici comment générer des fichiers JSONL pour OpenAI en code :

Python — Créer un fichier JSONL pour le fine-tuning
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")
JavaScript — Créer un fichier JSONL pour le fine-tuning
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`);

Consulter et modifier des fichiers JSONL pour OpenAI

Utilisez notre visionneuse JSONL en ligne gratuite pour examiner vos jeux de données de fine-tuning et vos fichiers pour la Batch API. Elle propose un affichage côte à côte, la coloration syntaxique et une validation en temps réel.

Questions fréquentes

Références