Limites de débit et bonnes pratiques
Sellel lehel
Mis à jour le 2 novembre 2026. Basé sur la documentation xAI : la réduction par lot est de 20 % sur les modèles de texte éligibles, les exemples suivent l’API REST et le SDK officiel
xai-sdk(client.batch.*; l’API Batch de xAI n’utilise pas le format d’OpenAI, donc le SDK OpenAI ne s’applique pas), et l’API Responses prime sur Chat Completions, un point de terminaison hérité chez xAI. Sources : Batch API · Référence REST · Tarification Batch.
Contraintes à connaître
L’API Batch impose des limites techniques que tu dois intégrer dans ton architecture. Les ignorer entraîne des rejets, l’annulation de lots ou la perte de résultats. Cette leçon résume les contraintes documentées par xAI et les bonnes pratiques pour un usage en production.
Limites de débit
| Contrainte | Valeur | Portée |
|---|---|---|
| Création de lots | 2 par seconde | Par équipe |
| Nombre de lots | Illimité | Par équipe |
| Appels d’ajout de requêtes | 1 000 par 30 secondes | Fenêtre glissante, partagée entre tous les lots de l’équipe |
| Taille de requête | 25 Mo | Par requête individuelle |
| Requêtes par lot | Théoriquement illimité | Au-delà de 100 000, le traitement peut être plus lent |
Création de lots : la limite de 2 créations par seconde pose rarement problème, car tu crées généralement un lot par opération.
Ajout de requêtes : la limite s’applique aux appels, et chaque appel transporte une liste de requêtes. Avec des blocs de 100 requêtes, cela permet déjà plus de 3 000 requêtes par seconde.
Taille de requête : la limite de 25 Mo affecte principalement les requêtes chargées d’images encodées en base64 ; une requête textuelle dépasse rarement quelques kilo-octets.
À l’inverse, les requêtes par lot ne comptent pas dans les limites de débit de l’API temps réel : un gros lot ne ralentit pas ton application interactive.
Limites des fichiers JSONL
| Contrainte | Valeur |
|---|---|
| Requêtes par fichier | 50 000 maximum |
| Taille du fichier | 200 Mo maximum |
| Ajouts après création | Impossible : le lot est scellé |
Si ton lot dépasse ces limites, divise-le en plusieurs fichiers et crée un lot par fichier ; tu agrégeras les résultats ensuite.
Expiration des URL
Les URL signées pour les résultats d’images et de vidéos expirent après une heure. C’est la contrainte la plus critique à gérer en production : ton processus de récupération doit télécharger les médias immédiatement, sans intervention manuelle (la fonction telecharger_medias de la leçon 9). Pour le lot, surveille aussi expire_time, après lequel aucun résultat n’est accessible.
Bonnes pratiques pour la production
Identifiants déterministes
Déduis tes identifiants de requête (batch_request_id, ou custom_id dans le JSONL) de tes données d’entrée. Si tu dois 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 lot entièrement traité peut encore contenir des requêtes échouées. Vérifie 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 échouées à resoumettre dans un nouveau lot")
Suivi des coûts
Chaque lot conserve le suivi 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))
Via l’API REST, le coût de chaque requête texte apparaît dans son résultat, dans le champ usage.cost_in_usd_ticks.
Journaux et traçabilité
Journalise chaque opération pour pouvoir diagnostiquer les problèmes :
import logging
logger = logging.getLogger("batch_api")
logger.info("Lot créé : %s", batch_id)
logger.info("Fichier téléversé : %s, %d requêtes", file_id, len(documents))
logger.info("Résultats : %d réussis, %d échoués", len(reussies), len(echouees))
Nouvelle tentative avec backoff
Pour les erreurs transitoires (délai d’attente dépassé, limite de débit, erreur serveur), réessaie 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"Nouvelle tentative dans {attente} s : {e}")
time.sleep(attente)
Liste de contrôle avant production
Avant de déployer un pipeline API Batch en production, vérifie :
- Le modèle accepte le traitement par lot et figure dans la liste des modèles réduits si le coût importe
- Les identifiants de requête sont uniques et déterministes
- Le fichier JSONL est validé avant téléversement (une ligne invalide annule le lot)
- 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 lot
- Les résultats sont récupérés avant
expire_time - Les journaux couvrent chaque étape du flux de travail
- La clé API est lue depuis une variable d’environnement, jamais codée en dur
Peamised punktid
- Limites : 2 créations par seconde, 1 000 appels d’ajout de requêtes par 30 secondes, 25 Mo par requête
- Fichiers JSONL : 50 000 requêtes et 200 Mo maximum, un lot par fichier
- Les URL d’images et de vidéos expirent en une heure : télécharge immédiatement
- Identifiants déterministes, vérification de chaque résultat, suivi des coûts en ticks
- Journaux, nouvelle tentative avec backoff et délai d’attente maximum pour la production
Teste tes connaissances
Traitement par lots : l’API Batch sans zone d’ombre.
1. Quand l'API Batch est-elle le bon choix ?
Réponse : Pour de gros volumes sans contrainte temps réel : classification, enrichissement, évaluations, génération en masse. Les requêtes par lot ne comptent pas dans les limites de débit, et les modèles de texte éligibles bénéficient d’une réduction de 20 %.
2. Quel est le flux de travail en quatre étapes ?
Réponse : Créer un lot nommé, y ajouter des requêtes (via l’API, ou en créant le lot depuis un fichier JSONL téléversé), suivre ses compteurs, puis récupérer les résultats, au fur et à mesure ou à la fin. Le traitement démarre tout seul, sans étape de lancement.
3. Que peux-tu mettre dans un lot ?
Réponse : Des requêtes Responses (recommandé) et Chat Completions (hérité), avec des outils serveur et l’appel de fonctions, ainsi que des générations et modifications d’images et de vidéos, et des extensions vidéo. Seuls les jetons de texte pour les modèles éligibles bénéficient de la réduction.
4. Comment suivre l'exécution ?
Réponse : Via les compteurs du lot (num_pending, num_success, num_error…), le statut de chaque requête (pending, succeeded, failed, cancelled) et les résultats paginés, qui séparent les succès des échecs. Le lot est entièrement traité lorsque num_pending est à zéro.
5. Quelles bonnes pratiques s'appliquent aux limites ?
Réponse : Ajoute les requêtes par blocs, divise les gros fichiers en un lot par fichier, télécharge les médias dans l’heure, récupère les résultats avant expire_time et resoumets les échecs dans un nouveau lot : conçois le lot comme un pipeline robuste, pas comme une soumission en masse aveugle.
Des lots bien formés, des compteurs suivis, des échecs retentés : l’API Batch transforme le volume en routine, au meilleur coût.