Salt la conținutul principal
Română— Alege o limbă
Meniu

Pipeline complet de bout en bout

Lecția 7 din 12 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Assemblage des composants
  2. Pipeline Python complet
  3. Pipeline cURL étape par étape
  4. Gestion des erreurs en production
  5. Optimisation des coûts
  6. Puncte cheie

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 composants

Les leçons précédentes ont traité chaque étape de manière isolée. Cette leçon les assemble pour former un pipeline complet, de la préparation des données au traitement des résultats. Vous obtiendrez un script que vous pourrez adapter à votre 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ésumez 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 vous préférez 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

Obtenez 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éessayez 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 ; resoumettez-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érez-les au fur et à mesure qu’ils arrivent plutôt que tous ensemble à la fin.

# Requêtes échouées : identifiez-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 lot 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 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 de lot s’applique également aux jetons servis depuis le cache ; placez donc les instructions communes au début de chaque requête, avant la partie variable.

Puncte cheie

  • 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 : attendez que num_requests > 0 avant de conclure qu’il est terminé
  • Gérez les trois familles d’erreurs : soumission, traitement, délai d’attente et expiration
  • Récupérez et sauvegardez 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