Verfolgung, Status und Stornierung
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 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 veralteten Endpunkt bei xAI. Quellen: Batch API · REST Reference · Batch Pricing.
Verwaltung des Batch-Lebenszyklus
Sobald Sie Ihre Anfragen eingereicht haben, müssen Sie den Verarbeitungsfortschritt verfolgen, Status lesen und wissen, wann und wie ein Batch storniert werden kann. Diese Lektion behandelt alle verfügbaren Verwaltungsoperationen.
Zwei Ebenen des Status
xAI verfolgt den Fortschritt auf zwei Ebenen. Der Batch selbst hat keinen globalen Status wie „abgeschlossen” oder „fehlgeschlagen”: Er enthält Zähler in seinem state-Objekt. Jede Anfrage hingegen verfügt über einen eigenen Status:
| Status der Anfrage | Bedeutung | Maßnahme |
|---|---|---|
pending | In der Warteschlange | Warten |
succeeded | Verarbeitet, Ergebnis verfügbar | Ergebnis abrufen |
failed | Fehler während der Verarbeitung | Nachricht lesen, ggf. erneut versuchen |
cancelled | Storniert, z. B. mit dem Batch | Bei Bedarf erneut einreichen |
Der Batch ist vollständig verarbeitet, wenn der Zähler num_pending auf null sinkt. Er kann auch storniert oder ablaufen: Nach expire_time sind seine Ergebnisse nicht mehr zugänglich.
Zähler prüfen
Der Aufruf GET /v1/batches/{batch_id} gibt den Batch und seine Zähler zurück:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Die Antwort enthält:
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "analyse_avis_clients",
"state": {
"num_requests": 500,
"num_pending": 155,
"num_success": 342,
"num_error": 3,
"num_cancelled": 0
}
}
Diese Zähler verfolgen den Fortschritt in Echtzeit, ohne auf das Ende der Verarbeitung warten zu müssen. Mit dem SDK können Sie sie in client.batch.get(batch_id=...).state auslesen.
Auflistung Ihrer Batches
Um einen Batch zu finden oder die Historie zu prüfen:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Die Liste wird paginiert mit limit und pagination_token. Batches verbleiben dort bis zum Ablauf. Mit dem SDK gibt client.batch.list(limit=20) eine batches-Liste zurück, bei der jedes Element seinen name, batch_id und state trägt. Die xAI-Konsole bietet dieselbe Ansicht in visueller Form.
Ergebnisse abrufen
Sie können Ergebnisse jederzeit abrufen, auch während der Verarbeitung:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Jedes Ergebnis trägt die batch_request_id seiner Anfrage. Fehlgeschlagene Anfragen erscheinen dort mit ihrer Nachricht; mit dem SDK trennen die succeeded- und failed-Eigenschaften jeder Seite diese voneinander.
Prüfung der Anforderungsmetadaten
Um den Status jeder Anfrage zu verfolgen:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Jeder Eintrag gibt die Anforderungs-ID, das Endpunkt, das Modell, den Status sowie die Erstellungs- und Enddaten an. Dies ist das Diagnosewerkzeug, wenn ein Zähler stecken bleibt, oder um zu überprüfen, was erfolgreich hinzugefügt wurde.
Stornierung eines Batches
Wenn Sie den laufenden Prozess stoppen müssen:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Die Stornierung ist endgültig: Ausstehende Anfragen werden nicht verarbeitet, und Sie können keine weiteren Anfragen dem Batch hinzufügen. Bereits verarbeitete Anfragen bleiben jedoch in den Ergebnissen verfügbar. Stornieren Sie, wenn:
- Sie nach der Einreichung einen Fehler in Ihren Anfragen festgestellt haben
- Der Batch nicht mehr benötigt wird (Prioritätsänderung)
- Sie einen korrigierten Batch erneut einreichen möchten
Mit dem SDK: client.batch.cancel(batch_id=...), was den Batch und seine Zähler zum Zeitpunkt der Stornierung zurückgibt.
Polling-Strategie
In der Produktion warten Sie auf Abschluss mit zeitlich abgestuften Abfragen und einer maximalen Verzögerung:
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Warten, bis alle Anfragen im Batch verarbeitet sind."""
debut = time.monotonic()
while time.monotonic() - debut < delai_max:
batch = client.batch.get(batch_id=batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Von xAI storniert: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
return batch
print(f"{etat.num_success} erfolgreich, {etat.num_error} fehlgeschlagen, "
f"{etat.num_pending} ausstehend von {etat.num_requests}")
time.sleep(intervalle)
raise TimeoutError(f"Batch nach {delai_max} s nicht abgeschlossen")
Ein Intervall von wenigen Minuten eignet sich für große Batches; die Beispiele in der xAI-Dokumentation fragen alle paar Sekunden ab und decken kleine Batches ab. Da Ergebnisse so verfügbar sind, wie sie eintreffen, schließt dies nichts davon aus, sie während des Wartens abzurufen.
Kernaussagen
- Lesen Sie den Batch über seine Zähler (
num_pending,num_success,num_error…); jede Anfrage hat ihren Status:pending,succeeded,failed,cancelled GET /v1/batches/{id}gibt den Fortschritt,/resultsdie Ergebnisse und/requestsdie Anforderungsdetails zurück- Die Stornierung (
POST /v1/batches/{id}:cancel) ist irreversibel, behält aber bereits erzeugte Ergebnisse - Listen und Ergebnisse werden mit
limitundpagination_tokenpaginiert - Fragen Sie in Intervallen von wenigen Minuten ab, mit einer maximalen Verzögerung, und rufen Sie vor
expire_timeab