Guide du format JSONL pour l’API Batch d’OpenAI
Apprenez à structurer vos fichiers JSONL pour l’API Batch d’OpenAI et réduisez vos coûts de 50 %
Qu’est-ce que l’API Batch d’OpenAI ?
L’API Batch d’OpenAI permet de regrouper un grand nombre de requêtes API dans un seul traitement par lots. Au lieu d’effectuer des milliers d’appels API individuels, vous envoyez un fichier JSONL contenant toutes vos requêtes. OpenAI les traite ensuite de manière asynchrone dans un délai de 24 heures.
Le principal avantage est le coût : les requêtes par lots coûtent 50 % moins cher que les appels API en temps réel. L’API Batch convient donc particulièrement aux tâches qui ne nécessitent pas de réponse immédiate, comme la génération de contenu, la classification de données, le calcul d’embeddings et les pipelines d’évaluation.
Format JSONL des requêtes
Dans le fichier JSONL d’entrée du lot, chaque ligne représente une requête API. Elle doit respecter une structure précise et contenir trois champs obligatoires.
custom_id — Identifiant unique de la requête, qui permet de l’associer à sa réponse. Il peut s’agir de n’importe quelle chaîne de caractères, dans la limite de 512 caractères.method — Méthode HTTP. Seule la méthode POST est actuellement prise en charge.url — Chemin de l’endpoint de l’API : /v1/chat/completions pour les requêtes Chat Completions, /v1/embeddings pour les embeddings.body — Corps de la requête, au même format que celui attendu par l’endpoint correspondant de l’API.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}Requêtes Chat Completions par lots
L’envoi de plusieurs requêtes Chat Completions est l’usage le plus courant de l’API Batch. Chaque ligne contient une requête complète avec le modèle, les messages et des paramètres facultatifs comme max_tokens ou temperature.
Une seule requête
Chaque ligne contient une requête Chat Completions complète avec le modèle, les messages et les paramètres facultatifs.
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}Fichier JSONL contenant plusieurs requêtes
Un fichier de traitement par lots contient généralement des centaines, voire des milliers de requêtes. Voici un fichier qui regroupe trois tâches différentes : résumé, classification et traduction.
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}Calcul d’embeddings par lots
L’API Batch prend également en charge les requêtes de calcul d’embeddings, ce qui est utile pour traiter de grandes collections de documents. Ces lots utilisent la même structure JSONL, mais ciblent l’endpoint /v1/embeddings.
Le corps d’une requête de calcul d’embeddings est plus simple : il contient le modèle et le texte d’entrée.
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}Format des réponses
Une fois le traitement du lot terminé, OpenAI fournit un fichier JSONL de sortie dont chaque ligne contient la réponse à une requête. Chaque réponse reprend le custom_id d’origine, ce qui vous permet de l’associer à la requête correspondante.
Réponse en cas de succès
En cas de succès, la réponse contient le custom_id, le code de statut et l’intégralité du corps de la réponse de l’API.
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}Réponse en cas d’erreur
Lorsqu’une requête échoue, la réponse contient un objet d’erreur avec un code et un message qui explique la cause de l’échec.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}Utiliser l’API Batch de bout en bout
Voici les cinq étapes pour utiliser l’API Batch avec le SDK Python, de la création du fichier JSONL au téléchargement et à l’analyse des résultats.
- 1Créez un fichier JSONL avec une requête par ligne
- 2Envoyez le fichier via l’API Files en définissant purpose sur batch
- 3Créez un traitement par lots en indiquant l’ID du fichier envoyé
- 4Interrogez régulièrement le statut du lot jusqu’à ce qu’il passe à completed, failed ou cancelled
- 5Téléchargez et analysez le fichier JSONL de sortie pour en extraire les résultats
from openai import OpenAI
import json
import time
client = OpenAI()
# Step 1: Create the JSONL batch file
prompts = [
"Summarize the benefits of renewable energy.",
"Classify this text as positive or negative: Great product!",
"Translate to French: Hello, how are you?",
]
requests = [
{
"custom_id": f"req-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 200,
},
}
for i, prompt in enumerate(prompts)
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# Step 2: Upload the file
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Step 3: Create the batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(f"Batch created: {batch.id}")
# Step 4: Poll for completion
while True:
status = client.batches.retrieve(batch.id)
print(f"Status: {status.status}")
if status.status in ("completed", "failed", "cancelled"):
break
time.sleep(60)
# Step 5: Download results
if status.output_file_id:
content = client.files.content(status.output_file_id)
with open("batch_output.jsonl", "wb") as f:
f.write(content.read())API Batch ou API en temps réel
Savoir quand choisir l’API Batch ou l’API standard en temps réel vous permet d’optimiser à la fois les coûts et les performances.
Pour en savoir plus sur le format JSONL utilisé pour le fine-tuning chez OpenAI, consultez notre guide du format JSONL pour OpenAI.
Préparez vos fichiers de traitement par lots
Utilisez nos outils gratuits pour créer, valider et examiner vos fichiers JSONL de traitement par lots avant de les envoyer à OpenAI.
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.
Divisez les grands fichiers JSONL en morceaux plus petits et gérables par nombre de lignes.
Validez vos fichiers JSONL ligne par ligne. Repérez immédiatement les erreurs de syntaxe et les problèmes d’encodage ou de format.
Les stratégies pour traiter des gigaoctets de données JSONL : lecture en streaming, gestion de la mémoire, découpage des fichiers, compression et outils en ligne.
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.