Volledige end-to-end-pipeline
Op deze pagina
Cursus bijgewerkt op 2 november 2026 op basis van de xAI-documentatie: de batch-korting bedraagt 20% op in aanmerking komende tekstmodellen (niet 50%), de voorbeelden volgen de REST API en de officiële
xai-sdk(client.batch.*; de Batch API van xAI komt niet overeen met het formaat van OpenAI, dus de OpenAI SDK is niet van toepassing), en de Responses API heeft voorrang boven Chat Completions, een verouderd eindpunt bij xAI. Bronnen: Batch API · REST Reference · Batch Pricing.
De onderdelen samenvoegen
Eerdere lessen behandelden elke stap afzonderlijk. Deze les voegt ze samen tot een complete pipeline, van gegevensvoorbereiding tot het verwerken van de resultaten. U eindigt met een script dat u kunt aanpassen aan uw use case.
Complete Python-pipeline
import json
import time
from xai_sdk import Client
client = Client() # sleutel gelezen uit XAI_API_KEY
# --- Stap 1: gegevens voorbereiden ---
documents = [
{"id": f"doc-{i}", "text": f"Documentinhoud {i}..."}
for i in range(100)
]
# --- Stap 2: het JSONL-bestand schrijven ---
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": "Vat samen in twee zinnen."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- Stap 3: het bestand uploaden ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- Stap 4: de batch maken vanuit het bestand (deze is nu verzegeld) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Batch gemaakt: {batch.batch_id}")
# --- Stap 5: wachten tot de verwerking is voltooid ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Batch geannuleerd door 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} verzoeken verwerkt")
time.sleep(300) # elke 5 minuten
# --- Stap 6: resultaten ophalen, pagina per pagina ---
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)} resultaten, {len(echecs)} mislukkingen")
print("Totale kosten: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Drie details zijn belangrijk. De stopvoorwaarde vereist num_requests > 0 omdat een batch die vanuit een bestand is gemaakt op de achtergrond wordt ingelezen: direct na het maken kunnen de tellers nog allemaal op nul staan. Het veld cancel_by_xai_message signaleert annulering door xAI, bijvoorbeeld vanwege een ongeldige regel. En de kosten worden uitgedrukt in ticks, tien-miljardste delen van een dollar.
Stap-voor-stap cURL-pipeline
Als u de opdrachtregel verkiest, is hier het cURL-equivalent (met gebruik van jq om antwoorden te lezen):
# 1. Het JSONL-bestand uploaden
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 "Bestand: $FILE_ID"
# 2. De batch maken vanuit het bestand
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. Tellers uitlezen
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. De eerste pagina met resultaten ophalen
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Haal volgende pagina’s op door &pagination_token=… toe te voegen met de waarde die door de vorige pagina is geretourneerd.
Foutafhandeling in productie
Een robuuste pipeline maakt onderscheid tussen drie families fouten:
Verzendfouten: het uploaden van bestanden of het maken van de batch mislukt. Probeer tijdelijke fouten (time-out, snelheidslimiet, serverfout) opnieuw met een toenemende vertraging: 1 s, 2 s, 4 s, 8 s.
Verwerkingsfouten: sommige verzoeken binnen de batch mislukken. Deze verschijnen in page.failed met hun bericht; dien alleen deze opnieuw in, in een nieuwe batch.
Time-out en verloop: het venster van 24 uur is indicatief, niet gegarandeerd. Wat onverbiddelijk is, is verloop (expire_time): na dit punt zijn resultaten niet meer toegankelijk. Haal ze op terwijl ze binnenkomen in plaats van alles tegelijk aan het einde.
# Mislukte verzoeken: identificeer ze om opnieuw in te dienen in een nieuwe batch
for r in echecs:
print(f"Mislukt: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Kostenoptimalisatie
Besparingen accumuleren via vier hefbomen. Modelkeuze komt eerst, verreweg de krachtigste: tegen het standaardtarief per 2 november 2026 kost grok-4.3 $1,25 per miljoen input-tokens en $2,50 voor output, tegenover $2 en $6 voor grok-4.7 (prompts onder de 200.000 tokens). Voor classificatie of korte extractie volstaat het lichtere model vaak, en de batch-korting van 20% geldt voor beide. Responslengte komt daarna: max_output_tokens voorkomt dat u betaalt voor onnodig lange outputs; voor classificatie volstaan een paar tokens. Prompts: het verwijderen van tien tokens uit een prompt die 50.000 keer wordt herhaald, bespaart 500.000 input-tokens. Tot slot, cache: xAI cachet automatisch identieke beginnende verzoeken, en de batch-korting geldt ook voor tokens die uit de cache worden geserveerd; plaats dus gemeenschappelijke instructies aan het begin van elk verzoek, vóór het variërende deel.
Belangrijkste punten
- Een complete pipeline omvat zes stappen: voorbereiding, JSONL, uploaden, maken, monitoring, ophalen
- Een batch vanuit een bestand wordt op de achtergrond ingelezen: wacht op
num_requests > 0voordat u concludeert dat deze is voltooid - Handel de drie foutfamilies af: verzending, verwerking, time-out en verloop
- Haal resultaten op en sla ze op terwijl ze binnenkomen, vóór
expire_time - Modelkeuze, outputlengte, korte prompts en gemeenschappelijke prefixen maximaliseren de besparingen