Pipeline end-to-end complète
In questa pagina
Cours mis à jour le 2 novembre 2026 selon la documentation xAI : la réduction batch 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 · Référence REST · Tarification Batch.
Assemblage des pièces
Les leçons précédentes ont couvert chaque étape isolément. Cette leçon les assemble en un pipeline complet, de la préparation des données au traitement des résultats. Tu obtiendras un script que tu pourras adapter à ton cas d’usage.
Pipeline Python complet
import json
import time
from xai_sdk import Client
client = Client() # clé lue depuis XAI_API_KEY
# --- Étape 1 : préparer les données ---
documents = [
{"id": f"doc-{i}", "text": f"Contenu du document {i}..."}
for i in range(100)
]
# --- Étape 2 : écrire le fichier JSONL ---
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
ligne = {
"custom_id": doc["id"],
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Résume en deux phrases."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- Étape 3 : téléverser le fichier ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- Étape 4 : créer le batch depuis le fichier (il est désormais scellé) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Batch créé : {batch.batch_id}")
# --- Étape 5 : attendre la fin du traitement ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Batch annulé par xAI : {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
break
print(f"{etat.num_success + etat.num_error}/{etat.num_requests} requêtes traitées")
time.sleep(300) # toutes les 5 minutes
# --- Étape 6 : récupérer les résultats, page par page ---
resultats, echecs = {}, []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch.batch_id, limit=100, pagination_token=jeton
)
for r in page.succeeded:
resultats[r.batch_request_id] = r.response.content
echecs.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
with open("batch_results.json", "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print(f"{len(resultats)} résultats, {len(echecs)} échecs")
print("Coût total : $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Trois détails comptent. La condition d’arrêt exige num_requests > 0 car un batch créé depuis un fichier est lu en arrière-plan : juste après sa création, ses compteurs peuvent encore être tous à zéro. Le champ cancel_by_xai_message signale une annulation par xAI, par exemple due à une ligne invalide. Et le coût est exprimé en ticks, des dix-milliardièmes de dollar.
Pipeline cURL étape par étape
Si tu préfères la ligne de commande, voici l’équivalent cURL (utilisant jq pour lire les réponses) :
# 1. Téléverser le fichier JSONL
FILE_ID=$(curl -s -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl" | jq -r '.id')
echo "Fichier : $FILE_ID"
# 2. Créer le batch depuis le fichier
BATCH_ID=$(curl -s -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"resumes_documents\", \"input_file_id\": \"$FILE_ID\"}" | jq -r '.batch_id')
echo "Batch : $BATCH_ID"
# 3. Lire les compteurs
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Récupérer la première page de résultats
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Obtiens les pages suivantes en ajoutant &pagination_token=… avec la valeur renvoyée par la page précédente.
Gestion des erreurs en production
Un pipeline robuste distingue trois familles d’erreurs :
Erreurs de soumission : le téléversement du fichier ou la création du batch échoue. Réessaie les erreurs transitoires (délai d’attente, limite de débit, erreur serveur) avec un délai croissant : 1 s, 2 s, 4 s, 8 s.
Erreurs de traitement : certaines requêtes échouent au sein du batch. Elles apparaissent dans page.failed avec leur message ; resoumets-les, et elles seules, dans un nouveau batch.
Délais d’attente et expiration : la fenêtre de 24 heures est indicative, non garantie. Ce qui est impitoyable, c’est l’expiration (expire_time) : après ce point, les résultats ne sont plus accessibles. Récupère-les au fur et à mesure qu’ils arrivent plutôt que tous à la fois à la fin.
# Requêtes échouées : identifie-les pour les resoumettre dans un nouveau batch
for r in echecs:
print(f"Échec : {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Optimisation des coûts
Les économies s’accumulent grâce à quatre leviers. Le choix du modèle vient en premier, de loin le plus puissant : au tarif standard du 2 novembre 2026, grok-4.3 coûte 1,25 $ par million de tokens d’entrée et 2,50 $ pour la sortie, contre 2 $ et 6 $ pour grok-4.7 (prompts de moins de 200 000 tokens). Pour la classification ou l’extraction courte, le modèle plus léger suffit souvent, et la réduction batch de 20 % s’applique aux deux. La longueur de la réponse vient ensuite : max_output_tokens évite de payer pour des sorties inutilement longues ; pour une classification, quelques tokens suffisent. Les prompts : retirer dix tokens d’un prompt répété 50 000 fois économise 500 000 tokens d’entrée. Enfin, le cache : xAI met automatiquement en cache les débuts de requête identiques, et la réduction batch s’applique aussi aux tokens servis depuis le cache ; place donc les instructions communes au début de chaque requête, avant la partie variable.
Punti chiave
- Un pipeline complet couvre six étapes : préparation, JSONL, téléversement, création, surveillance, récupération
- Un batch issu d’un fichier est lu en arrière-plan : attends
num_requests > 0avant de conclure qu’il est terminé - Gère les trois familles d’erreurs : soumission, traitement, délai d’attente et expiration
- Récupère et sauvegarde les résultats au fur et à mesure, avant
expire_time - Le choix du modèle, la longueur de sortie, des prompts courts et des préfixes communs maximisent les économies