Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Limites de débit et bonnes pratiques

Paskaita 12 iš 12 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Contraintes à connaître
  2. Limites de débit
  3. Limites des fichiers JSONL
  4. Expiration des URL
  5. Bonnes pratiques pour la production
  6. Liste de contrôle avant mise en production
  7. Svarbiausi punktai
  8. Teste tes connaissances

Mis à jour le 2 novembre 2026. Basé sur la documentation xAI : la réduction pour les lots 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

ContrainteValeurPortée
Création de lots2 par secondePar équipe
Nombre de lotsIllimitéPar équipe
Appels d’ajout de requêtes1 000 par 30 secondesFenêtre glissante, partagée entre tous les lots de l’équipe
Taille de requête25 MoPar requête individuelle
Requêtes par lotThé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 concerne principalement 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 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

ContrainteValeur
Requêtes par fichier50 000 maximum
Taille du fichier200 Mo maximum
Ajouts après créationImpossible : 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 la trace 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 mise en 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 est important
  • 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

Svarbiausi punktai

  • 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 maximal 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 contraintes 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 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 réessayés : l’API Batch transforme le volume en routine, au meilleur coût.