Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Verfolgung, Status und Stornierung

Lektion 11 von 12 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Verwaltung des Batch-Lebenszyklus
  2. Zwei Ebenen des Status
  3. Zähler prüfen
  4. Auflistung Ihrer Batches
  5. Ergebnisse abrufen
  6. Prüfung der Anforderungsmetadaten
  7. Stornierung eines Batches
  8. Polling-Strategie
  9. Kernaussagen

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 AnfrageBedeutungMaßnahme
pendingIn der WarteschlangeWarten
succeededVerarbeitet, Ergebnis verfügbarErgebnis abrufen
failedFehler während der VerarbeitungNachricht lesen, ggf. erneut versuchen
cancelledStorniert, z. B. mit dem BatchBei 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, /results die Ergebnisse und /requests die Anforderungsdetails zurück
  • Die Stornierung (POST /v1/batches/{id}:cancel) ist irreversibel, behält aber bereits erzeugte Ergebnisse
  • Listen und Ergebnisse werden mit limit und pagination_token paginiert
  • Fragen Sie in Intervallen von wenigen Minuten ab, mit einer maximalen Verzögerung, und rufen Sie vor expire_time ab