Workflow en quatre etapes

Le cycle de vie d’un batch

Chaque batch suit un cycle de vie strict : creation, ajout de requetes, traitement, et recuperation des resultats. Comprendre ce cycle est essentiel avant de passer a l’implementation, car chaque etape a ses contraintes et ses bonnes pratiques.

Etape 1 : Creer un batch vide

Tout commence par un appel POST /v1/batches. Cette requete cree un conteneur vide qui recevra ensuite vos requetes. L’API retourne un identifiant unique (batch_id) que vous utiliserez pour toutes les operations suivantes.

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json"

Le batch est cree dans l’etat pending. A ce stade, il ne contient aucune requete et aucun traitement n’a demarre.

Etape 2 : Ajouter des requetes

Une fois le batch cree, vous y ajoutez des requetes via POST /v1/batches/{batch_id}/requests. Deux methodes sont disponibles :

Methode JSON (requete par requete) : vous envoyez chaque requete individuellement. Cette approche convient pour les petits volumes ou quand vous construisez le lot de maniere incrementale.

Methode JSONL (en masse) : vous preparez un fichier JSONL contenant toutes vos requetes, vous l’uploadez via la Files API, puis vous l’associez au batch. Cette methode est recommandee pour les gros volumes.

Chaque requete ajoutee doit contenir un custom_id unique qui vous permettra d’associer les resultats aux requetes d’origine. Ce champ est entierement sous votre controle : vous pouvez y mettre un identifiant de base de donnees, un hash, ou toute chaine de caracteres utile a votre logique metier.

Etape 3 : Surveiller la progression

Pendant le traitement, vous pouvez interroger le statut du batch avec GET /v1/batches/{batch_id}. La reponse inclut l’etat actuel et des compteurs de progression.

curl https://api.x.ai/v1/batches/{batch_id} \
  -H "Authorization: Bearer $XAI_API_KEY"

Le delai de traitement typique est de 24 heures, mais il varie selon le volume soumis et la charge du systeme. Vous n’avez pas besoin de maintenir une connexion active pendant cette periode. Un polling periodique (toutes les 5 a 10 minutes pour les gros lots) suffit.

Etape 4 : Recuperer les resultats

Lorsque le batch atteint l’etat succeeded, vous recuperez les resultats via GET /v1/batches/{batch_id}/results. La reponse est paginee : le parametre page_size controle le nombre de resultats par page.

curl "https://api.x.ai/v1/batches/{batch_id}/results?page_size=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Chaque resultat est associe au custom_id que vous avez defini a l’etape 2. Vous pouvez ainsi reconstituer la correspondance entre vos donnees d’entree et les reponses de Grok.

Le workflow dans la pratique

Dans un pipeline de production, le workflow se traduit generalement par deux processus distincts :

• Un processus de soumission qui cree le batch, prepare et ajoute les requetes, puis enregistre le batch_id
• Un processus de recuperation qui interroge periodiquement le statut et telecharge les resultats une fois le traitement termine

Cette separation permet d’integrer la Batch API dans des architectures event-driven ou des pipelines de donnees existants (cron jobs, Apache Airflow, systemes de files d’attente).

Gestion des erreurs dans le workflow

Si certaines requetes echouent dans le batch, l’ensemble du batch ne sera pas marque comme failed. Seules les requetes individuelles en erreur sont signalees dans les resultats. Vous devez donc verifier le statut de chaque requete dans la reponse et traiter les echecs au cas par cas.

Un batch passe a l’etat failed uniquement en cas d’erreur systeme globale (probleme d’authentification, format invalide du lot entier, etc.).

Points cles a retenir

• Le workflow suit strictement l’ordre : creer, ajouter, surveiller, recuperer
• Le custom_id est votre cle de correspondance entre requetes et resultats
• Le traitement est totalement asynchrone, aucune connexion persistante n’est necessaire
• Les erreurs sont gerees au niveau de chaque requete, pas du batch entier
• Un polling periodique suffit pour surveiller l’avancement