Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Batch API : traitement asynchrone massif

Lektion 6 av 20 Uppdaterad 3 november 2026 Avancerad
På denna sida
  1. Échanger la latence contre le coût
  2. Construire et lancer un lot
  3. Prévoir les échecs partiels
  4. Cumuler les économies
  5. Viktiga punkter

Mis à jour le 3 novembre 2026 sur la base du guide Batch API et de la structure de réponse de l’API Responses : la lecture des résultats ne suppose plus que le premier élément de output est le message (un élément de raisonnement peut le précéder), et la clé du code d’erreur, écrite sans guillemets, levait une NameError. Source : Batch API.

Échanger la latence contre le coût

La Batch API repose sur un principe de marché simple : tu acceptes que tes requêtes soient traitées de manière asynchrone dans une fenêtre allant jusqu’à vingt-quatre heures, et en échange, tu paies cinquante pour cent de moins. Tout ce qui n’a pas besoin de servir un humain en attente devant son écran entre dans cette catégorie. À grande échelle, ce n’est pas une micro-optimisation ; cela divise ta ligne budgétaire par deux.

L’habitude à instaurer au sein d’une équipe est de se demander, pour chaque nouvelle tâche de traitement, si quelqu’un attend le résultat. Analyser un stock de contrats, générer des fiches produits pour un catalogue, lancer un benchmark sur des milliers de cas de test, classer un arriéré de tickets de six mois, extraire des champs depuis un lot de factures : dans tous ces cas, la réponse atterrit dans un tableau de bord ou une base de données, pas dans une interface conversationnelle. Le délai est invisible, mais les économies ne le sont pas.

Construire et lancer un lot

Le format d’entrée est un fichier JSONL : une ligne par requête, où chaque ligne est un objet complet et indépendant. Le champ custom_id est ce qui te permet de relier chaque réponse à sa requête d’origine, car rien ne garantit l’ordre du fichier de sortie. Choisis un ID stable et significatif — un ID de document issu de ta base de données plutôt qu’un numéro d’itération — sinon la phase de réconciliation deviendra un cauchemar.

import json

requests = [
    {
        "custom_id": f"doc-{i}",
        "method": "POST",
        "url": "/v1/responses",
        "body": {
            "model": "gpt-5.6-luna",
            "input": f"Summarize this document in 3 key points: {doc}",
            "max_output_tokens": 500,
        },
    }
    for i, doc in enumerate(documents_list)
]

# Écrire le fichier JSONL
with open("batch_input.jsonl", "w") as f:
    for request in requests:
        f.write(json.dumps(request) + "\n")

Le fichier est ensuite téléchargé et référencé lors de la création du lot. Les métadonnées ne servent à rien techniquement, mais elles te sauveront la mise lorsque trois lots tourneront en parallèle et que tu devras identifier lequel correspond à quelle version de prompt.

import openai

client = openai.OpenAI()

# Télécharger le fichier
file_obj = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

# Créer le lot
batch = client.batches.create(
    input_file_id=file_obj.id,
    endpoint="/v1/responses",
    completion_window="24h",
    metadata={"project": "contract-analysis", "version": "2.1"},
)

print(f"Batch created: {batch.id}")
print(f"Status: {batch.status}")

La surveillance consiste à interroger le lot jusqu’à ce qu’il quitte l’état en cours, puis à télécharger le fichier de sortie, qui est également au format JSONL. La boucle ci-dessous distingue trois issues terminales — failed, expired, cancelled — et lève une exception pour chacune : un lot expiré est un lot dont la fenêtre de vingt-quatre heures s’est écoulée avant que tout ne soit traité, et le traiter comme un succès partiel silencieux serait la pire des options.

import time

def wait_for_batch(batch_id: str, interval: int = 60) -> list:
    """Attend la fin d'un lot et renvoie les résultats."""
    while True:
        batch = client.batches.retrieve(batch_id)
        print(
            f"Status: {batch.status} | "
            f"Completed: {batch.request_counts.completed}/"
            f"{batch.request_counts.total} | "
            f"Failed: {batch.request_counts.failed}"
        )

        if batch.status == "completed":
            break
        elif batch.status in ("failed", "expired", "cancelled"):
            raise RuntimeError(f"Batch failed: {batch.status}")

        time.sleep(interval)

    # Télécharger les résultats
    content = client.files.content(batch.output_file_id)
    results = []
    for line in content.text.strip().split("\n"):
        results.append(json.loads(line))

    return results


results = wait_for_batch(batch.id)

# Traiter les résultats
for result in results:
    custom_id = result["custom_id"]
    response = result["response"]
    if response["status_code"] == 200:
        # output peut contenir d'autres éléments avant le message
        # (raisonnement, par exemple) : chercher le texte du message
        text = next(
            part["text"]
            for item in response["body"]["output"] if item["type"] == "message"
            for part in item["content"] if part["type"] == "output_text"
        )
        print(f"{custom_id}: {text[:100]}...")
    else:
        print(f"{custom_id}: ERROR {response['status_code']}")

Prévoir les échecs partiels

Sur un lot important, certaines requêtes échoueront : un document tronqué, un débordement de contexte ou une erreur transitoire côté serveur. Un lot n’est donc jamais simplement « réussi » ou « échoué » — il est partiellement réussi, et tu dois savoir isoler la partie manquante. Le schéma à adopter est de séparer immédiatement les succès des échecs et de régénérer un fichier JSONL prêt à être relancé, plutôt que de fouiller dans les logs trois jours plus tard pour reconstruire ce qui manque.

def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
    """Sépare les succès des échecs pour un retraitement."""
    successes = []
    failures = []

    for r in results:
        if r["response"]["status_code"] == 200:
            successes.append(r)
        else:
            failures.append(r)

    if failures:
        print(f"Warning: {len(failures)} failed requests out of {len(results)}")
        # Réécrire un fichier JSONL avec les échecs pour réessai
        with open("batch_retry.jsonl", "w") as f:
            for failure in failures:
                original_request = {
                    "custom_id": failure["custom_id"],
                    "method": "POST",
                    "url": "/v1/responses",
                    "body": failure["request"]["body"],
                }
                f.write(json.dumps(original_request) + "\n")

    return successes, failures

Cumuler les économies

Sur une exécution de traitement de dix mille documents avec GPT-5.6 Luna, l’API synchrone représente le coût de base, la Batch API représente la moitié de cela, et la mise en cache des prompts s’ajoute par-dessus puisque les jetons mis en cache bénéficient également de leur propre réduction. Les deux mécanismes ne sont pas en concurrence : si tes dix mille requêtes partagent le même prompt système long, structure-le comme un préfixe stable et tu cumuleras les deux effets.

Enfin, il y a la question du découpage. Un lot ne doit pas être infini, et il est plus confortable de surveiller plusieurs lots gérables qu’un seul monolithe dont l’échec coûte une journée entière. La fonction suivante découpe une liste de requêtes en lots de taille bornée.

def create_optimized_batches(
    requests: list[dict],
    max_size: int = 50_000,
) -> list[list[dict]]:
    """Découpe en lots de taille optimale."""
    batches = []
    current_batch = []

    for request in requests:
        current_batch.append(request)
        if len(current_batch) >= max_size:
            batches.append(current_batch)
            current_batch = []

    if current_batch:
        batches.append(current_batch)

    return batches

Viktiga punkter

  • La Batch API offre une réduction de 50 % pour le traitement non temps réel
  • Prépare tes requêtes dans un fichier JSONL avec un custom_id unique par requête
  • Prévois un mécanisme de réessai pour les requêtes échouées
  • Combine avec la mise en cache des prompts pour maximiser les économies