API Batch pour les LLM : 50 000 requêtes avec jusqu'à 50 % de réduction et trois classes d'erreurs

Tant que le nombre de requêtes vers un LLM se compte en dizaines ou en centaines, l'API synchrone se comporte correctement : vous envoyez une requête, vous recevez une réponse. Mais lorsqu'il faut traiter 50 000 contrats ou fiches produits, vous atteignez vite les limites de TPM et de RPM, et les requêtes à long contexte commencent à échouer avant même la génération. Pour ce type de tâches, OpenAI, Anthropic et Google proposent un mode par lots, l'API Batch. Vous rassemblez toutes les tâches dans un seul fichier, vous l'envoyez au fournisseur et vous attendez jusqu'à 24 heures, mais vous payez moins.

Comment fonctionne la file d'attente

Derrière le simple mot « batch » se cachent trois niveaux de limitations.

Le premier niveau est le lot lui-même. C'est un fichier JSONL dont chaque ligne contient custom_id, method, url et un body avec le modèle et les messages. En somme, c'est une requête ordinaire à Chat Completions, empaquetée sur une seule ligne. Le fichier est chargé via l'API Files avec le purpose « batch », puis la tâche est créée. Les résultats ne reviennent pas dans l'ordre d'envoi : custom_id fait donc office de clé primaire, et c'est par lui que vous rapprochez la réponse de l'enregistrement d'origine.

Le deuxième niveau est le pool de jetons en file d'attente (enqueued). La limite ne se calcule pas par fichier, mais sur le volume total de jetons de tous les lots non terminés. Si un nouveau lot fait dépasser le plafond à l'organisation, l'API renvoie token_limit_exceeded et refuse de créer le job. Chez OpenAI, le plafond dépend du tier : plus il est élevé, plus on peut garder de jetons dans la file.

Le troisième niveau est la fenêtre de complétion. Les 24 heures sont un SLA, pas une prévision. En pratique, les lots se terminent le plus souvent en quelques heures, et Anthropic indique que la plupart des batchs sont prêts en moins d'une heure. Mais il faut compter sur le pire des cas. Le paramètre completion_window n'accepte pour l'instant que la valeur « 24h ».

Où le pipeline casse

L'auteur de l'article d'origine répartit les erreurs en quatre classes, et les pièges ne sont pas triviaux.

Avant la création du lot. Une virgule en trop dans le JSONL, un doublon ou un oubli de custom_id, un mauvais endpoint. Selon l'auteur, Anthropic ne vérifie les paramètres des requêtes qu'une fois le lot entier terminé : on peut envoyer 100 000 lignes, attendre une heure et découvrir que trois d'entre elles ont un max_tokens incorrect. Validez donc le fichier en local avant de le charger : analysez chaque ligne, vérifiez l'unicité de custom_id et la présence de model et messages. Des modèles Pydantic conviennent très bien pour cela.

Au niveau de la file. L'erreur principale est ici token_limit_exceeded. On la traite en comptant les jetons avant l'envoi et en gérant sa propre file côté application. Si le budget ne passe pas, attendez la fin des lots précédents ou réessayez avec un backoff exponentiel : 30, 60, 120 secondes, etc.

À l'intérieur du lot. C'est la catégorie la plus perfide. Le lot est completed, mais dans l'export, certaines lignes sont succeeded, d'autres errored, d'autres expired. Si le code se contente de lire content et d'écrire en base, les lignes problématiques se perdent en silence. Chez Anthropic, les compteurs errored, canceled et expired de request_counts restent à zéro tant que le lot entier n'est pas terminé : impossible donc d'évaluer à l'avance l'ampleur de l'échec. Un schéma raisonnable repose sur trois corbeilles : invalid_request est corrigé puis renvoyé, les erreurs serveur sont relancées avec un délai, et expired part dans un nouveau lot, car la fenêtre est déjà fermée.

Lors de l'interrogation du statut. Si vous sollicitez le statut toutes les cinq secondes, vous risquez de recevoir un 429 sur le polling lui-même. Une boucle naïve l'interprétera comme « le lot n'est pas prêt », alors que vous avez atteint la limite de débit en lecture. Pour les lots jusqu'à mille lignes, interrogez toutes les 30 secondes ; pour les gros, toutes les 2 à 5 minutes. Si un lot reste bloqué plus de quelques heures, vérifiez qu'il n'est pas coincé à l'étape validating.

Combien cela coûte réellement

La réduction de 50 % est un plafond, pas une garantie. Le chiffre final dépend du nombre de requêtes passées en expired, du nombre de renvois nécessaires et de l'utilisation éventuelle du cache du prompt système. Dans le meilleur des cas, l'économie est même supérieure, car le cached-input coûte lui aussi moins cher. Dans le pire, vous payez deux fois les mêmes lignes. Autre nuance importante : chez OpenAI, lors de l'annulation d'un lot, les requêtes non terminées sont annulées, mais celles déjà exécutées sont facturées.

Il faut aussi mentionner que l'original est en partie rédigé sur un ton publicitaire : l'auteur propose la passerelle compatible OpenAI Bothub, avec paiement par carte russe et une économie annoncée de 45 %. L'idée d'un endpoint compatible est viable, mais les conditions et la fiabilité de tout intermédiaire doivent être vérifiées par vous-même, et non sur la foi d'un lien de parrainage.

Que faire en pratique

Le batch, c'est un autre contrat : vous obtenez une réduction et un pool de limites distinct, mais vous prenez en charge l'analyse des résultats. Si vous construisez un traitement de masse de documents, de la classification ou de l'annotation, prévoyez dans le pipeline plusieurs éléments :

• une validation locale du JSONL avant l'envoi ;
• un comptage des jetons et un sémaphore sur la limite enqueued ;
• une analyse de l'export par type de résultat et le renvoi des seules lignes en échec ;
• un polling avec backoff et la journalisation de created_at.

Et la règle d'or : ne renvoyez pas un lot entier à cause de trois lignes en échec, car vous avez déjà payé pour les lignes réussies.