Par Jerry Fan

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.

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.

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.
Structure de base d’une requête
{"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.

Une seule requête
{"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.

Fichier JSONL contenant plusieurs requêtes
{"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.

Format des requêtes de calcul d’embeddings
{"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.

Réponse en cas de succès
{"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.

Réponse en cas d’erreur
{"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.

  1. 1Créez un fichier JSONL avec une requête par ligne
  2. 2Envoyez le fichier via l’API Files en définissant purpose sur batch
  3. 3Créez un traitement par lots en indiquant l’ID du fichier envoyé
  4. 4Interrogez régulièrement le statut du lot jusqu’à ce qu’il passe à completed, failed ou cancelled
  5. 5Téléchargez et analysez le fichier JSONL de sortie pour en extraire les résultats
Utiliser l’API Batch de bout en bout
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.

Caractéristique
API Batch
API en temps réel
Coût
Réduction de 50 %
Tarification standard
Latence
Jusqu’à 24 heures
Quelques secondes
Limites de débit
Limites plus élevées
Limites standard
Format d’entrée
Envoi d’un fichier JSONL
Appels API individuels
Usages recommandés
Traitement en masse, évaluation, génération de données
Applications interactives, chat en temps réel, streaming

Pour en savoir plus sur le format JSONL utilisé pour le fine-tuning chez OpenAI, consultez notre guide du format JSONL pour OpenAI.

Manipulez vos fichiers JSONL en ligne

Visualisez, validez et convertissez des fichiers JSONL jusqu’à 1 Go directement dans votre navigateur. Aucun fichier n’est envoyé sur un serveur : vos données restent 100% privées.

Questions fréquentes

Références