Rate limits et bonnes pratiques

Cours révisé le 2 novembre 2026 d’après la documentation de xAI : la remise batch est de 20 % sur les modèles texte éligibles (et non 50 %), les exemples suivent l’API REST et le SDK officiel xai-sdk (client.batch.* ; l’API Batch de xAI n’a pas le format de celle d’OpenAI, le SDK OpenAI ne s’y applique pas), et l’API Responses passe avant Chat Completions, endpoint hérité chez xAI. Sources : Batch API · Référence REST · Tarifs batch.

Les contraintes à connaître

La Batch API impose des limites techniques que vous devez intégrer dans votre architecture. Les ignorer conduit à des rejets, des batchs annulés ou des résultats perdus. Cette leçon récapitule les contraintes documentées par xAI et les bonnes pratiques d’une utilisation en production.

Rate limits

Création de batchs : la limite de 2 créations par seconde est rarement un problème, puisqu’on crée généralement un batch par opération.

Ajout de requêtes : la limite porte sur les appels, et chaque appel transporte une liste de requêtes. Avec des paquets de 100 requêtes, elle autorise déjà plus de 3 000 requêtes par seconde.

Taille par requête : les 25 MB concernent surtout les requêtes chargées d’images encodées en base64 ; une requête texte dépasse rarement quelques kilo-octets.

À l’inverse, les requêtes batch ne comptent pas dans les limites de débit de l’API temps réel : un gros lot ne ralentit pas votre application interactive.

Limites des fichiers JSONL

Si votre lot dépasse ces limites, découpez-le en plusieurs fichiers et créez un batch par fichier ; vous agrégerez les résultats ensuite.

Expiration des URL

Les URL signées des résultats d’images et de vidéos expirent au bout d’une heure. C’est la contrainte la plus critique à gérer en production : votre processus de récupération doit télécharger les médias dans la foulée, sans intervention manuelle (fonction telecharger_medias de la leçon 9). Au niveau du batch, surveillez de même expire_time, au-delà duquel plus aucun résultat n’est accessible.

Bonnes pratiques en production

Identifiants déterministes

Dérivez vos identifiants de requête (batch_request_id, ou custom_id en JSONL) de vos données d’entrée. Si vous devez resoumettre un lot, les mêmes données produiront les mêmes identifiants, ce qui facilite la déduplication :

import hashlib


def identifiant_requete(document_id: str, operation: str) -> str:
    """Génère un identifiant de requête déterministe."""
    brut = f"{document_id}:{operation}"
    return hashlib.sha256(brut.encode()).hexdigest()[:16]

Gestion des échecs partiels

Un batch entièrement traité peut contenir des requêtes en échec. Vérifiez toujours chaque résultat :

reussies, echouees = [], []
jeton = None
while True:
    page = client.batch.list_batch_results(
        batch_id=batch_id, limit=1000, pagination_token=jeton
    )
    reussies.extend(page.succeeded)
    echouees.extend(page.failed)
    if page.pagination_token is None:
        break
    jeton = page.pagination_token

if echouees:
    print(f"{len(echouees)} requêtes en échec à resoumettre dans un nouveau batch")

Suivi des coûts

Chaque batch tient le compte de son coût total, en ticks (dix-milliardièmes de dollar) :

batch = client.batch.get(batch_id=batch_id)
print("Coût total : %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))

Par l’API REST, le coût de chaque requête texte figure dans son résultat, champ usage.cost_in_usd_ticks.

Logs et traçabilité

Enregistrez chaque opération pour pouvoir diagnostiquer les problèmes :

import logging

logger = logging.getLogger("batch_api")

logger.info("Batch créé : %s", batch_id)
logger.info("Fichier téléversé : %s, %d requêtes", file_id, len(documents))
logger.info("Résultats : %d réussies, %d en échec", len(reussies), len(echouees))

Retry avec backoff

Pour les erreurs transitoires (délai dépassé, limite de débit, erreur serveur), réessayez avec un délai croissant :

import time


def appel_avec_retry(fonction, max_essais=3):
    for essai in range(max_essais):
        try:
            return fonction()
        except Exception as e:
            if essai == max_essais - 1:
                raise
            attente = 2 ** essai
            print(f"Nouvel essai dans {attente} s : {e}")
            time.sleep(attente)

Checklist pré-production

Avant de déployer un pipeline Batch API en production, vérifiez :

• Le modèle accepte le batch, et figure dans la liste des modèles remisés si le coût compte
• Les identifiants de requête sont uniques et déterministes
• Le fichier JSONL est validé avant téléversement (une ligne invalide annule le batch)
• Le téléchargement des résultats multimodaux est automatisé, dans l’heure
• Les échecs partiels sont détectés et resoumis dans un nouveau batch
• Les résultats sont récupérés avant expire_time
• Les logs couvrent chaque étape du workflow
• La clé API est lue dans une variable d’environnement, jamais écrite en dur

Points clés à retenir

• Limites : 2 créations par seconde, 1 000 appels d’ajout par 30 secondes, 25 MB par requête
• Fichiers JSONL : 50 000 requêtes et 200 MB au maximum, un batch par fichier
• Les URL d’images et de vidéos expirent en une heure : téléchargez immédiatement
• Identifiants déterministes, vérification de chaque résultat, suivi du coût en ticks
• Logs, retry avec backoff et délai maximal pour la production

Testez vos connaissances

Traitement en masse : la Batch API sans zones d’ombre.

1. Quand la Batch API est-elle le bon choix ?

Réponse : Pour les gros volumes sans contrainte temps réel : classification, enrichissement, évaluations, générations en masse. Les requêtes batch ne comptent pas dans les limites de débit, et les modèles texte éligibles sont remisés de 20 %.

2. Quel est le workflow en quatre étapes ?

Réponse : Créer un batch nommé, y ajouter des requêtes (par l’API, ou en créant le batch depuis un fichier JSONL téléversé), suivre ses compteurs, puis récupérer les résultats, au fil de l’eau ou à la fin. Le traitement démarre seul, sans étape de lancement.

3. Que peut-on mettre dans un batch ?

Réponse : Des requêtes Responses (recommandé) et Chat Completions (hérité), avec outils serveur et function calling, ainsi que des générations et éditions d’images et de vidéos, et des prolongations de vidéos. Seuls les tokens texte des modèles éligibles sont remisés.

4. Comment suit-on l'exécution ?

Réponse : Par les compteurs du batch (num_pending, num_success, num_error…), par l’état de chaque requête (pending, succeeded, failed, cancelled) et par les résultats paginés, qui séparent réussites et échecs. Le batch est entièrement traité quand num_pending vaut zéro.

5. Quelles bonnes pratiques face aux limites ?

Réponse : Ajouter les requêtes par paquets, découper les gros fichiers en un batch par fichier, télécharger les médias dans l’heure, récupérer les résultats avant expire_time et resoumettre les échecs dans un nouveau batch : le batch se conçoit comme un pipeline robuste, pas comme un envoi massif aveugle.

Lots bien formés, compteurs suivis, échecs repris : la Batch API transforme le volume en routine, au meilleur coût.