Workflow en quatre étapes

Le cycle de vie d’un batch

Chaque batch suit un cycle de vie strict : création, ajout de requêtes, traitement, et récupération des résultats. Comprendre ce cycle est essentiel avant de passer à l’implémentation, car chaque étape à ses contraintes et ses bonnes pratiques.

Étape 1 : Créer un batch vide

Tout commence par un appel POST /v1/batches. Cette requête crée un conteneur vide qui recevra ensuite vos requêtes. L’API retourne un identifiant unique (batch_id) que vous utiliserez pour toutes les opérations suivantes.

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

Le batch est créé dans l’état pending. À ce stade, il ne contient aucune requête et aucun traitement n’a démarre.

Étape 2 : Ajouter des requêtes

Une fois le batch créé, vous y ajoutez des requêtes via POST /v1/batches/{batch_id}/requests. Deux méthodes sont disponibles :

Méthode JSON (requête par requête) : vous envoyez chaque requête individuellement. Cette approche convient pour les petits volumes ou quand vous construisez le lot de manière incrémentale.

Méthode JSONL (en masse) : vous préparez un fichier JSONL contenant toutes vos requêtes, vous l’uploadez via la Files API, puis vous l’associez au batch. Cette méthode est recommandée pour les gros volumes.

Chaque requête ajoutée doit contenir un custom_id unique qui vous permettra d’associer les résultats aux requêtes d’origine. Ce champ est entièrement sous votre contrôle : vous pouvez y mettre un identifiant de base de données, un hash, ou toute chaîne de caractères utile à votre logique métier.

Étape 3 : Surveiller la progression

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

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

Le délai de traitement typique est de 24 heures, mais il varie selon le volume soumis et la charge du système. Vous n’avez pas besoin de maintenir une connexion active pendant cette période. Un polling périodique (toutes les 5 à 10 minutes pour les gros lots) suffit.

Étape 4 : Récupérer les résultats

Lorsque le batch atteint l’état succeeded, vous récupérez les résultats via GET /v1/batches/{batch_id}/results. La réponse est paginee : le paramètre page_size contrôle le nombre de résultats par page.

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

Chaque résultat est associé au custom_id que vous avez défini à l’étape 2. Vous pouvez ainsi reconstituer la correspondance entre vos données d’entrée et les réponses de Grok.

Le workflow dans la pratique

Dans un pipeline de production, le workflow se traduit généralement par deux processus distincts :

• Un processus de soumission qui crée le batch, préparé et ajoute les requêtes, puis enregistré le batch_id
• Un processus de récupération qui interroge périodiquement le statut et téléchargé les résultats une fois le traitement terminé

Cette séparation permet d’intégrer la Batch API dans des architectures event-driven ou des pipelines de données existants (cron jobs, Apache Airflow, systèmes de files d’attente).

Gestion des erreurs dans le workflow

Si certaines requêtes échouent dans le batch, l’ensemble du batch ne sera pas marque comme failed. Seules les requêtes individuelles en erreur sont signalées dans les résultats. Vous devez donc vérifier le statut de chaque requête dans la réponse et traiter les échecs au cas par cas.

Un batch passe à l’état failed uniquement en cas d’erreur système globale (problème d’authentification, format invalide du lot entier, etc.).

Points clés à retenir

• Le workflow suit strictement l’ordre : créer, ajouter, surveiller, récupérer
• Le custom_id est votre clé de correspondance entre requêtes et résultats
• Le traitement est totalement asynchrone, aucune connexion persistante n’est nécessaire
• Les erreurs sont gérées au niveau de chaque requête, pas du batch entier
• Un polling périodique suffit pour surveiller l’avancement