Gemini Batch API : traiter des milliers de requêtes à moitié prix, sans urgence

Classer dix mille avis clients, résumer un fonds documentaire, évaluer un prompt sur un jeu de tests : rien de tout cela n'exige une réponse dans la seconde. Le mode par lots (« Batch API ») de l'API Gemini est fait pour ces cas. Les requêtes sont déposées en une fois, traitées en différé, et facturées 50 % du coût standard selon Google.

Le principe

Le délai visé est de 24 heures ; la documentation ajoute que, dans la majorité des cas, le traitement est bien plus rapide. Ce n'est pas un engagement ferme. Le mode par lots s'applique à la génération de contenu (generateContent) et aux embeddings.

Deux façons de soumettre un lot :

• en ligne : la liste des requêtes est passée directement dans l'appel, pour un total inférieur à 20 Mo ;
• par fichier : un fichier JSONL (une requête par ligne), téléversé au préalable, jusqu'à 2 Go. C'est la voie recommandée pour les gros volumes.

Préparer le fichier

Chaque ligne contient une clé de votre choix et la requête elle-même :

{"key": "request-1", "request": {"contents": [{"parts": [{"text": "..."}]}], "generation_config": {"temperature": 0.7}}}

La clé (key) sert à rattacher chaque réponse à sa requête : choisissez un identifiant qui a du sens dans votre système, par exemple le numéro du document traité.

Lancer et suivre le lot

Avec le kit Python de Google, les étapes sont les suivantes :

1. créer le client avec genai.Client() ;
2. téléverser le fichier avec client.files.upload(...) ;
3. créer le lot avec client.batches.create(model=..., src=..., config={'display_name': ...}), où src reçoit le nom du fichier téléversé ou la liste en ligne ;
4. interroger l'état avec client.batches.get(name=...).

Les exemples de la page utilisent le modèle gemini-3.8-flash.

Le lot passe par des états nommés :

• JOB_STATE_PENDING : en attente ;
• JOB_STATE_RUNNING : en cours ;
• JOB_STATE_SUCCEEDED : terminé, résultats disponibles ;
• JOB_STATE_FAILED : échec ;
• JOB_STATE_CANCELLED : annulé par l'utilisateur ;
• JOB_STATE_EXPIRED : resté en attente ou en cours plus de 48 heures, sans résultat disponible.

Une fois le lot réussi, les résultats d'un lot par fichier se trouvent dans batch_job.dest.file_name, à télécharger avec client.files.download(...). Pour un lot en ligne, ils sont dans batch_job.dest.inlined_responses.

Plutôt que d'interroger l'état en boucle, il est possible de s'abonner à des webhooks (batch.succeeded et batch.failed). client.batches.cancel(...) arrête un lot en cours, client.batches.delete(...) le retire de la liste.

Ce qui reste disponible en mode lot

Chaque requête garde ses réglages propres : instructions système, température, sortie structurée (response_mime_type et response_schema), outil de recherche Google, génération d'images. Le cache de contexte fonctionne aussi ; les lectures en cache sont alors facturées au tarif habituel du cache.

Les points de vigilance

• Pas de protection contre les doublons. La création d'un lot n'est pas idempotente : renvoyer la même demande après une erreur réseau crée un second lot, facturé lui aussi. Vérifiez la liste avec client.batches.list(...) avant de relancer.
• Un lot réussi peut contenir des échecs. La documentation conseille de contrôler le compteur failedRequestCount dans batchStats une fois le traitement terminé.
• L'expiration à 48 heures. Un lot expiré ne rend rien. Google suggère de découper les très gros travaux en plusieurs lots pour obtenir des résultats intermédiaires.
• Le prix exact dépend du modèle. La page renvoie à la grille tarifaire ; elle ne donne que le taux de 50 %.

Notre lecture

Le mode par lots est la première économie à envisager pour tout traitement de fond : reprise d'un historique, enrichissement d'un catalogue, tests de non-régression d'un prompt. Il ne convient pas à ce qu'un utilisateur attend devant son écran. Avant d'y déposer des données de clients ou de salariés, vérifiez les conditions de traitement des données applicables à votre compte Google : le différé ne change rien à vos obligations au titre du RGPD. Commencez par un petit lot pour valider le format des sorties.