Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Vollständige End-to-End-Pipeline

Lektion 7 von 12 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Zusammenstellung der Komponenten
  2. Vollständige Python-Pipeline
  3. Schritt-für-Schritt cURL-Pipeline
  4. Fehlerbehandlung in der Produktion
  5. Kostenoptimierung
  6. Kernaussagen

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_time erreicht ist
  • Modellwahl, Ausgabelänge, kurze Prompts und gemeinsame Präfixe maximieren die Einsparungen