Vierstufiger Workflow
Auf dieser Seite
Aktualisiert am 2. November 2026 basierend auf der xAI-Dokumentation: Der Batch-Rabatt beträgt 20 % für berechtigte Textmodelle (nicht 50 %); die Beispiele verwenden die REST-API und das offizielle
xai-sdk(client.batch.*; die Batch-API von xAI folgt nicht dem Format von OpenAI, sodass das OpenAI-SDK nicht anwendbar ist); und die Responses API geht der Chat Completions vor, einem Legacy-Endpunkt bei xAI. Quellen: Batch API · REST-Referenz · Batch-Preise.
Der Lebenszyklus eines Batches
Jedes Batch durchläuft denselben Zyklus: Erstellen, Anfragen hinzufügen, verarbeiten, Ergebnisse abrufen. Das Verständnis dieses Zyklus ist unerlässlich, bevor Sie zur Implementierung übergehen, da jeder Schritt eigene Einschränkungen und Best Practices aufweist.
Schritt 1: Batch erstellen
Alles beginnt mit einem POST /v1/batches-Aufruf, der ein erforderliches Feld enthält: den Batch-Namen. Die API gibt eine eindeutige Kennung (batch_id) zurück, die Sie für alle nachfolgenden Operationen verwenden.
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
Die Antwort enthält zudem die Erstellungs- und Ablaufdaten des Batches (create_time, expire_time) sowie ein state-Objekt, dessen Zähler alle noch bei Null stehen.
Schritt 2: Anfragen hinzufügen
Es gibt zwei Methoden:
Über die API: Sie senden Anfragen mit POST /v1/batches/{batch_id}/requests. Jeder Aufruf enthält eine Liste von Anfragen, und Sie können diese so lange hinzufügen, bis das Batch nicht mehr storniert wurde. Dies ist der Weg für inkrementell erstellte Batches.
Über eine JSONL-Datei: Sie erstellen eine Datei, die alle Ihre Anfragen enthält, laden sie über die Files API hoch und erstellen das Batch dann aus dieser Datei. Das Batch ist dann versiegelt: keine weiteren Hinzufügungen sind möglich. Dies ist der Weg für große Volumina, die im Voraus vorbereitet wurden.
Jede Anfrage trägt eine eindeutige Kennung innerhalb des Batches: batch_request_id bei der API, custom_id in der JSONL-Datei. Wenn Sie diese bei der API weglassen, generiert xAI eine UUID; geben Sie stattdessen Ihre eigene vor (z. B. eine Datenbank-ID): Sie dient als Schlüsselschlüssel zwischen Ihren Daten und den Ergebnissen und gewährleistet, dass eine Anfrage nur einmal verarbeitet wird.
Schritt 3: Fortschritt überwachen
Die Verarbeitung beginnt sofort, sobald Anfragen eintreffen; es gibt keinen separaten „Start”-Schritt. Gleichzeitig gibt GET /v1/batches/{batch_id} das state-Objekt und seine Zähler zurück: num_requests (Gesamtzahl), num_pending (ausstehend), num_success (erfolgreich), num_error (fehlgeschlagen) und num_cancelled (storniert).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Wenn num_pending auf Null fällt, wurden alle Anfragen verarbeitet, erfolgreich oder nicht. Regelmäßiges Abfragen genügt: wenige Sekunden für ein kleines Test-Batch, wenige Minuten für ein großes Batch.
Schritt 4: Ergebnisse abrufen
Ergebnisse werden mit GET /v1/batches/{batch_id}/results abgerufen, ohne auf das Ende des Batches zu warten: Jede Anfrage ist verfügbar, sobald sie verarbeitet wurde. Die Antwort ist paginiert: limit legt die Seitengröße fest (Maximum 1.000), und das zurückgegebene pagination_token wird verwendet, um die nächste Seite anzufordern; es ist auf der letzten Seite leer.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Jedes Ergebnis enthält die batch_request_id seiner Anfrage: Dies ermöglicht es Ihnen, die Zuordnung zwischen Ihren Eingabedaten und den Antworten von Grok wiederherzustellen.
Der Workflow in der Praxis
In einer Produktionspipeline übersetzt sich der Workflow allgemein in zwei getrennte Prozesse:
- Ein Einreichungsprozess, der das Batch erstellt, Anfragen vorbereitet und hinzufügt, und dann die
batch_idspeichert - Ein Abrufprozess, der die Zähler regelmäßig prüft und Ergebnisse herunterlädt, sobald diese verfügbar sind
Diese Trennung ermöglicht es Ihnen, die Batch API in ereignisgesteuerte Architekturen oder bestehende Datenpipelines (Cron-Jobs, Apache Airflow, Warteschlangen) zu integrieren.
Fehlerbehandlung im Workflow
Ein Batch hat keinen globalen „erfolgreich” oder „fehlgeschlagen”-Status: Sie lesen ihn über seine Zähler. Eine fehlgeschlagene Anfrage erhöht num_error und erscheint in den Ergebnissen mit ihrer Fehlermeldung, ohne die anderen zu blockieren. Sie müssen daher jedes Ergebnis prüfen und Fehler einzeln behandeln.
Zwei Ereignisse betreffen das gesamte Batch. Das erste ist die Stornierung, entweder durch Sie oder durch xAI, was dann im Feld cancel_by_xai_message erläutert wird. Dies geschieht insbesondere, wenn eine Zeile in einer JSONL-Datei ungültig ist. Das zweite ist die Ablaufzeit (expire_time), nach der Ergebnisse nicht mehr zugänglich sind: Holen Sie diese umgehend ab.
Kernaussagen
- Der Workflow folgt der Reihenfolge: Erstellen (mit einem Namen), hinzufügen, überwachen, abrufen
- Die Anforderungskennung (
batch_request_idodercustom_idin JSONL) ist Ihr Zuordnungsschlüssel - Der Fortschritt wird über die
state-Zähler gelesen; alles ist verarbeitet, wennnum_pendingNull ist - Ergebnisse sind paginiert (
limit,pagination_token) und stehen so zur Verfügung, wie sie verarbeitet werden - Fehler werden Anfrage für Anfrage behandelt; Stornierung und Ablaufzeit betreffen das gesamte Batch