Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Suivi, statut et annulation

Paskaita 11 iš 12 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Gérer le cycle de vie du lot
  2. Deux niveaux de statut
  3. Vérifier les compteurs
  4. Lister tes lots
  5. Récupérer les résultats
  6. Vérifier les métadonnées des requêtes
  7. Annuler un lot
  8. Stratégie d’interrogation (Polling)
  9. Svarbiausi punktai

Mis à jour le 2 novembre 2026 selon la documentation xAI : la réduction par lot 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êteSignificationAction
pendingEn file d’attenteAttendre
succeededTraité, résultat disponibleRécupérer le résultat
failedErreur lors du traitementLire le message, réessayer si utile
cancelledAnnulé, par exemple avec son lotResoumettre 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, son modèle, son statut, ainsi que ses 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 d’interrogation (Polling)

En production, attends la fin avec une interrogation espacée 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 interroge 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.

Svarbiausi punktai

  • 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, /results les résultats, /requests le 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 limit et pagination_token
  • Interroge à des intervalles de quelques minutes, avec un délai maximum, et récupère avant expire_time