Suivi, statut et annulation
In questa pagina
Mis à jour le 2 novembre 2026 selon la documentation xAI : la réduction pour les lots est de 20 % sur les modèles de texte éligibles (et non 50 %), les exemples suivent l’API REST et le SDK officiel
xai-sdk(client.batch.*; l’API Batch de xAI ne correspond pas au 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 · REST Reference · Batch Pricing.
Gérer le cycle de vie du lot
Une fois tes requêtes soumises, tu dois suivre la progression du traitement, lire les statuts et savoir quand et comment annuler un lot. Cette leçon couvre toutes les opérations de gestion disponibles.
Deux niveaux de statut
xAI suit la progression à deux niveaux. Le lot lui-même n’a pas de statut global comme « terminé » ou « échoué » : il contient des compteurs dans son objet state. Chaque requête, en revanche, possède son propre statut :
| Statut de la requête | Signification | Action |
|---|---|---|
pending | En file d’attente | Attendre |
succeeded | Traité, résultat disponible | Récupérer le résultat |
failed | Erreur lors du traitement | Lire le message, réessayer si utile |
cancelled | Annulé, par exemple avec son lot | Resoumettre si nécessaire |
Le lot est entièrement traité lorsque son compteur num_pending tombe à zéro. Il peut aussi être annulé ou expirer : après expire_time, ses résultats ne sont plus accessibles.
Vérifier les compteurs
L’appel GET /v1/batches/{batch_id} renvoie le lot et ses compteurs :
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
La réponse inclut :
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "analyse_avis_clients",
"state": {
"num_requests": 500,
"num_pending": 155,
"num_success": 342,
"num_error": 3,
"num_cancelled": 0
}
}
Ces compteurs suivent la progression en temps réel, sans attendre la fin du traitement. Avec le SDK, lis-les dans client.batch.get(batch_id=...).state.
Lister tes lots
Pour trouver un lot ou vérifier l’historique :
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
La liste est paginée par limit et pagination_token. Les lots y restent jusqu’à expiration. Avec le SDK, client.batch.list(limit=20) renvoie une liste batches où chaque élément porte son name, batch_id et state. La console xAI offre la même vue, sous forme visuelle.
Récupérer les résultats
Tu peux récupérer les résultats à tout moment, même pendant le traitement :
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Chaque résultat porte le batch_request_id de sa requête. Les requêtes échouées y apparaissent avec leur message ; avec le SDK, les propriétés succeeded et failed de chaque page les séparent.
Vérifier les métadonnées des requêtes
Pour suivre le statut de chaque requête :
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Chaque entrée donne l’identifiant de la requête, son point de terminaison, le modèle, le statut, ainsi que les dates de création et de fin. C’est l’outil de diagnostic lorsqu’un compteur se bloque, ou pour vérifier ce qui a été ajouté avec succès.
Annuler un lot
Si tu dois arrêter un traitement en cours :
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
L’annulation est définitive : les requêtes en attente ne seront pas traitées et tu ne peux plus ajouter de requêtes au lot. Les requêtes déjà traitées restent cependant disponibles dans les résultats. Annule si :
- Tu as détecté une erreur dans tes requêtes après soumission
- Le lot n’est plus nécessaire (changement de priorité)
- Tu souhaites resoumettre un lot corrigé
Avec le SDK : client.batch.cancel(batch_id=...), qui renvoie le lot et ses compteurs au moment de l’annulation.
Stratégie de sondage (Polling)
En production, attends la fin avec un sondage espacé et un délai maximum :
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Wait until all requests in the batch are processed."""
debut = time.monotonic()
while time.monotonic() - debut < delai_max:
batch = client.batch.get(batch_id=batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Canceled by xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
return batch
print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
f"{etat.num_pending} pending out of {etat.num_requests}")
time.sleep(intervalle)
raise TimeoutError(f"Batch not finished after {delai_max} s")
Un intervalle de quelques minutes convient aux grands lots ; la documentation de xAI sonde toutes les quelques secondes dans ses exemples, qui couvrent de petits lots. Et comme les résultats sont disponibles au fur et à mesure, rien n’empêche de les récupérer pendant l’attente.
Punti chiave
- Lis le lot via ses compteurs (
num_pending,num_success,num_error…) ; chaque requête a son statut :pending,succeeded,failed,cancelled GET /v1/batches/{id}donne la progression,/resultsles résultats,/requestsle détail des requêtes- L’annulation (
POST /v1/batches/{id}:cancel) est irréversible, mais conserve les résultats déjà produits - Les listes et résultats se paginent avec
limitetpagination_token - Sonde à des intervalles de quelques minutes, avec un délai maximum, et récupère avant
expire_time