Vollständige End-to-End-Pipeline
Auf dieser Seite
Kurs aktualisiert am 2. November 2026 basierend auf der xAI-Dokumentation: Der Batch-Rabatt beträgt 20 % für berechtigte Textmodelle (nicht 50 %), die Beispiele folgen dem REST-API-Standard und dem offiziellen
xai-sdk(client.batch.*; die Batch-API von xAI entspricht nicht dem Format von OpenAI, sodass das OpenAI-SDK nicht anwendbar ist), und die Responses API hat Vorrang vor Chat Completions, einem Legacy-Endpunkt bei xAI. Quellen: Batch API · REST Reference · Batch Pricing.
Zusammenstellung der Komponenten
In den vorherigen Lektionen wurden die einzelnen Schritte isoliert behandelt. Diese Lektion fasst sie zu einer vollständigen Pipeline zusammen, von der Datenvorbereitung bis zur Verarbeitung der Ergebnisse. Am Ende verfügen Sie über ein Skript, das Sie an Ihren Anwendungsfall anpassen können.
Vollständige Python-Pipeline
import json
import time
from xai_sdk import Client
client = Client() # Schlüssel wird aus XAI_API_KEY gelesen
# --- Schritt 1: Daten vorbereiten ---
documents = [
{"id": f"doc-{i}", "text": f"Inhalt des Dokuments {i}..."}
for i in range(100)
]
# --- Schritt 2: Die JSONL-Datei schreiben ---
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
linie = {
"custom_id": doc["id"],
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Fassen Sie in zwei Sätzen zusammen."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(linie, ensure_ascii=False) + "\n")
# --- Schritt 3: Die Datei hochladen ---
with open("batch_requests.jsonl", "rb") as f:
datei = client.files.upload(f, filename="batch_requests.jsonl")
# --- Schritt 4: Batch aus der Datei erstellen (diese ist nun versiegelt) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=datei.id)
print(f"Batch erstellt: {batch.batch_id}")
# --- Schritt 5: Auf Abschluss der Verarbeitung warten ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
status = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Batch von xAI abgebrochen: {batch.cancel_by_xai_message}")
if status.num_requests > 0 and status.num_pending == 0:
break
print(f"{status.num_success + status.num_error}/{status.num_requests} Anfragen verarbeitet")
time.sleep(300) # alle 5 Minuten
# --- Schritt 6: Ergebnisse stufenweise abrufen ---
ergebnisse, fehler = {}, []
token = None
while True:
seite = client.batch.list_batch_results(
batch_id=batch.batch_id, limit=100, pagination_token=token
)
for r in seite.succeeded:
ergebnisse[r.batch_request_id] = r.response.content
fehler.extend(seite.failed)
if seite.pagination_token is None:
break
token = seite.pagination_token
with open("batch_results.json", "w", encoding="utf-8") as f:
json.dump(ergebnisse, f, ensure_ascii=False, indent=2)
print(f"{len(ergebnisse)} Ergebnisse, {len(fehler)} Fehler")
print("Gesamtkosten: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Drei Details sind von Bedeutung. Die Abbruchbedingung erfordert num_requests > 0, da ein Batch, das aus einer Datei erstellt wurde, im Hintergrund gelesen wird: Unmittelbar nach der Erstellung können die Zähler noch alle bei Null stehen. Das Feld cancel_by_xai_message signalisiert eine Absetzung durch xAI, beispielsweise aufgrund einer ungültigen Zeile. Und Kosten werden in Ticks ausgedrückt, also Zehntel-Milliarden-Dollar.
Schritt-für-Schritt cURL-Pipeline
Falls Sie die Kommandozeile bevorzugen, hier ist das cURL-Äquivalent (unter Verwendung von jq zum Auslesen der Antworten):
# 1. Die JSONL-Datei hochladen
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 "Datei: $FILE_ID"
# 2. Batch aus der Datei erstellen
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. Zähler auslesen
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Erste Seite der Ergebnisse abrufen
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Rufen Sie nachfolgende Seiten ab, indem Sie &pagination_token=… hinzufügen, wobei der Wert der vorherigen Seite verwendet wird.
Fehlerbehandlung in der Produktion
Eine robuste Pipeline unterscheidet drei Familien von Fehlern:
Einreichungsfehler: Datei-Upload oder Batch-Erstellung scheitern. Wiederholen Sie vorübergehende Fehler (Zeitüberschreitung, Rate Limit, Serverfehler) mit zunehmender Verzögerung: 1 s, 2 s, 4 s, 8 s.
Verarbeitungsfehler: Einige Anfragen scheitern innerhalb des Batches. Sie erscheinen in page.failed mit ihrer Meldung; übermitteln Sie diese erneut, und zwar nur diese, in einem neuen Batch.
Zeitüberschreitung und Ablauf: Das 24-Stunden-Fenster ist hinweisend, nicht garantiert. Unverzeihlich ist der Ablauf (expire_time): Nach diesem Zeitpunkt sind Ergebnisse nicht mehr zugänglich. Rufen Sie sie ab, sobald sie eintreffen, statt sie am Ende alle auf einmal abzurufen.
# Fehlgeschlagene Anfragen: Identifizieren Sie diese, um sie in einem neuen Batch erneut einzureichen
for r in fehler:
print(f"Fehler: {r.batch_request_id} — {r.error_message}")
wieder_einreichen = {r.batch_request_id for r in fehler}
Kostenoptimierung
Einsparungen summieren sich über vier Hebel. Modellwahl steht an erster Stelle und ist bei weitem der stärkste Faktor: Zum Standardtarif vom 2. November 2026 kostet grok-4.3 1,25 USD pro Million Eingabetokens und 2,50 USD für Ausgabetokens, gegenüber 2 USD und 6 USD für grok-4.7 (Prompts unter 200.000 Tokens). Für Klassifizierung oder kurze Extraktionen reicht oft das leichtere Modell aus, und der 20 %ige Batch-Rabatt gilt für beide. Antwortlänge folgt: max_output_tokens verhindert, dass für unnötig lange Ausgaben bezahlt wird – für Klassifizierung reichen wenige Tokens. Prompts: Das Entfernen von zehn Tokens aus einem Prompt, der 50.000 Mal wiederholt wird, spart 500.000 Eingabetokens. Schließlich Cache: xAI cacheiert automatisch identische Prompt-Starte, und der Batch-Rabatt gilt auch für aus dem Cache gelieferte Tokens; platzieren Sie daher gemeinsame Anweisungen am Anfang jeder Anfrage, vor dem variierenden Teil.
Kernaussagen
- Eine vollständige Pipeline umfasst sechs Schritte: Vorbereitung, JSONL, Upload, Erstellung, Überwachung, Abruf
- Ein Batch aus einer Datei wird im Hintergrund gelesen: Warten Sie auf
num_requests > 0, bevor Sie davon ausgehen, dass es abgeschlossen ist - Behandeln Sie die drei Fehlerfamilien: Einreichung, Verarbeitung, Zeitüberschreitung und Ablauf
- Rufen und speichern Sie Ergebnisse ab, sobald sie eintreffen, bevor
expire_timeerreicht ist - Modellwahl, Ausgabelänge, kurze Prompts und gemeinsame Präfixe maximieren die Einsparungen