Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Pipeline complet de bout en bout

Lektion 7 av 12 Uppdaterad 2 november 2026 Utvecklare
På denna sida
  1. Assemblage des pièces
  2. Pipeline Python complet
  3. Pipeline cURL étape par étape
  4. Gestion des erreurs en production
  5. Optimisation des coûts
  6. Viktiga punkter

Cours mis à jour le 2 novembre 2026 sur la base de 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.

Assemblage des pièces

Les leçons précédentes ont couvert chaque étape de manière isolée. 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éparation des données ---
documents = [
    {"id": f"doc-{i}", "text": f"Contenu du document {i}..."}
    for i in range(100)
]

# --- Étape 2 : écriture du 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éversement du fichier ---
with open("batch_requests.jsonl", "rb") as f:
    fichier = client.files.upload(f, filename="batch_requests.jsonl")

# --- Étape 4 : création du lot à partir du fichier (il est désormais scellé) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Lot créé : {batch.batch_id}")

# --- Étape 5 : attente de 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"Lot 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ération des 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 sont importants. La condition d’arrêt exige num_requests > 0 car un lot créé à partir d’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 en raison d’une ligne invalide. Enfin, le coût est exprimé en ticks, soit des dix-milliardièmes de dollar.

Pipeline cURL étape par étape

Si tu préfères la ligne de commande, voici l’équivalent en cURL (en 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 lot à partir du 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 "Lot : $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 lot échoue. Réessaie les erreurs transitoires (délai d’attente dépassé, 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 lot. Elles apparaissent dans page.failed avec leur message ; resoumets-les, et elles seules, dans un nouveau lot.

Délais d’attente et expiration : la fenêtre de 24 heures est indicative, non garantie. Ce qui est implacable, c’est l’expiration (expire_time) : après ce moment, 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 lot
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 jetons d’entrée et 2,50 $ pour la sortie, contre 2 $ et 6 $ pour grok-4.7 (pour des invites de moins de 200 000 jetons). Pour la classification ou l’extraction courte, le modèle plus léger suffit souvent, et la réduction de 20 % pour les lots 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 jetons suffisent. Les invites : supprimer dix jetons d’une invite répétée 50 000 fois économise 500 000 jetons d’entrée. Enfin, le cache : xAI met automatiquement en cache les débuts de requêtes identiques, et la réduction pour les lots s’applique aussi aux jetons servis depuis le cache ; place donc les instructions communes au début de chaque requête, avant la partie variable.

Viktiga punkter

  • Un pipeline complet couvre six étapes : préparation, JSONL, téléversement, création, surveillance, récupération
  • Un lot issu d’un fichier est lu en arrière-plan : attends que num_requests > 0 avant 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 invites courtes et des préfixes communs maximisent les économies