Rate limits and best practices
Auf dieser Seite
Aktualisiert am 2. November 2026. Basierend auf der xAI-Dokumentation: Der Batch-Rabatt beträgt 20 % für berechtigte Textmodelle. Die Beispiele folgen dem REST-API-Standard und dem offiziellen
xai-sdk(client.batch.*). Die Batch-API von xAI verwendet nicht das Format von OpenAI, sodass das OpenAI-SDK nicht anwendbar ist. Die Responses API hat Vorrang gegenüber Chat Completions, einem veralteten Endpunkt bei xAI. Quellen: Batch API · REST-Referenz · Batch-Preise.
Einschränkungen, die Sie kennen müssen
Die Batch-API unterwirft technische Grenzen, die Sie in Ihrer Architektur berücksichtigen müssen. Das Ignorieren dieser Grenzen führt zu Ablehnungen, abgebrochenen Batches oder verlorenen Ergebnissen. Diese Lektion fasst die von xAI dokumentierten Einschränkungen und Best Practices für den produktiven Einsatz zusammen.
Rate Limits
| Einschränkung | Wert | Geltungsbereich |
|---|---|---|
| Batch-Erstellung | 2 pro Sekunde | Pro Team |
| Anzahl der Batches | Unbegrenzt | Pro Team |
| Aufrufe zum Hinzufügen von Anfragen | 1.000 pro 30 Sekunden | Gleitendes Fenster, geteilt über alle Batches des Teams |
| Anfragegröße | 25 MB | Pro einzelne Anfrage |
| Anfragen pro Batch | Theoretisch unbegrenzt | Über 100.000 können die Verarbeitung verlangsamen |
Batch-Erstellung: Das Limit von 2 Erstellungen pro Sekunde stellt in der Regel kein Problem dar, da Sie normalerweise pro Operation nur einen Batch erstellen.
Hinzufügen von Anfragen: Das Limit gilt für Aufrufe, und jeder Aufruf enthält eine Liste von Anfragen. Bereits mit Blöcken von 100 Anfragen ermöglicht dies mehr als 3.000 Anfragen pro Sekunde.
Anfragegröße: Das Limit von 25 MB betrifft hauptsächlich Anfragen, die mit base64-kodierten Bildern geladen werden; eine reine Textanfrage überschreitet selten einige Kilobyte.
Im Gegensatz dazu zählen Batch-Anfragen nicht zu den Rate Limits der Echtzeit-API: Ein großer Batch verlangsamt Ihre interaktive Anwendung nicht.
JSONL-Dateilimits
| Einschränkung | Wert |
|---|---|
| Anfragen pro Datei | Maximum 50.000 |
| Dateigröße | Maximum 200 MB |
| Hinzufügungen nach Erstellung | Nicht möglich: Der Batch ist versiegelt |
Wenn Ihr Batch diese Grenzen überschreitet, teilen Sie ihn in mehrere Dateien auf und erstellen Sie einen Batch pro Datei. Die Ergebnisse aggregieren Sie anschließend.
URL-Ablauf
Gesignnte URLs für Bild- und Videergebnisse laufen nach einer Stunde ab. Dies ist die kritischste Einschränkung, die im produktiven Einsatz zu beachten ist: Ihr Abrufprozess muss die Medien sofort herunterladen, ohne manuelle Intervention (die Funktion telecharger_medias aus Lektion 9). Für den Batch müssen Sie zudem expire_time überwachen, wonach keine Ergebnisse mehr zugänglich sind.
Best Practices für den produktiven Einsatz
Deterministische IDs
Leiten Sie Ihre Anfrage-IDs (batch_request_id oder custom_id in JSONL) aus Ihren Eingabedaten ab. Wenn Sie einen Batch erneut einreichen müssen, erzeugen dieselben Daten dieselben IDs, was die Deduplizierung erleichtert:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Generiert eine deterministische Anfrage-ID."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Umgang mit partiellen Fehlern
Ein vollständig verarbeiteter Batch kann dennoch fehlgeschlagene Anfragen enthalten. Prüfen Sie jedes Ergebnis stets:
reussies, echouees = [], []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch_id, limit=1000, pagination_token=jeton
)
reussies.extend(page.succeeded)
echouees.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
if echouees:
print(f"{len(echouees)} fehlgeschlagene Anfragen zur erneuten Einreichung in einem neuen Batch")
Kostenverfolgung
Jeder Batch verfolgt seine Gesamtkosten in ticks (Zehntelmilliarden-Dollar):
batch = client.batch.get(batch_id=batch_id)
print("Gesamtkosten: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Über die REST-API erscheint die Kosten jeder Textanfrage in ihrem Ergebnis im Feld usage.cost_in_usd_ticks.
Protokolle und Nachverfolgbarkeit
Protokollieren Sie jede Operation, um Probleme diagnostizieren zu können:
import logging
logger = logging.getLogger("batch_api")
logger.info("Batch erstellt: %s", batch_id)
logger.info("Datei hochgeladen: %s, %d Anfragen", file_id, len(documents))
logger.info("Ergebnisse: %d erfolgreich, %d fehlgeschlagen", len(reussies), len(echouees))
Wiederversuch mit Backoff
Bei vorübergehenden Fehlern (Timeout, Rate Limit, Serverfehler) wiederholen Sie den Aufruf mit zunehmender Verzögerung:
import time
def appel_avec_retry(fonction, max_essais=3):
for essai in range(max_essais):
try:
return fonction()
except Exception as e:
if essai == max_essais - 1:
raise
attente = 2 ** essai
print(f"Wiederholung in {attente} s: {e}")
time.sleep(attente)
Prüfliste vor der Produktion
Bevor Sie eine Batch-API-Pipeline in die Produktion bereitstellen, prüfen Sie Folgendes:
- Das Modell unterstützt die Batch-Verarbeitung und erscheint in der Liste der rabattierten Modelle, wenn Kosten eine Rolle spielen
- Anfrage-IDs sind eindeutig und deterministisch
- Die JSONL-Datei wird vor dem Hochladen validiert (eine ungültige Zeile bricht den Batch ab)
- Der Abruf multimodaler Ergebnisse automatisiert ist und innerhalb einer Stunde erfolgt
- Partielle Fehler werden erkannt und in einem neuen Batch erneut eingereicht
- Ergebnisse werden vor
expire_timeabgerufen - Protokolle erfassen jeden Schritt des Workflows
- Der API-Schlüssel wird aus einer Umgebungsvariablen gelesen, niemals hartcodiert
Kernaussagen
- Limits: 2 Erstellungen pro Sekunde, 1.000 Aufrufe zum Hinzufügen von Anfragen pro 30 Sekunden, 25 MB pro Anfrage
- JSONL-Dateien: Maximum 50.000 Anfragen und 200 MB, ein Batch pro Datei
- Bild- und Videourls laufen in einer Stunde ab: sofort herunterladen
- Deterministische IDs, Prüfung jedes Ergebnisses, Kostenverfolgung in ticks
- Protokolle, Wiederversuch mit Backoff und eine maximale Timeout-Dauer für die Produktion
Testen Sie Ihr Wissen
Bulk-Verarbeitung: Die Batch-API ohne Grauzonen.
1. Wann ist die Batch-API die richtige Wahl?
Antwort: Für große Volumina ohne Echtzeit-Anforderungen: Klassifizierung, Anreicherung, Evaluierungen, Bulk-Generierung. Batch-Anfragen zählen nicht zu den Rate Limits, und berechtigte Textmodelle erhalten einen 20 % Rabatt.
2. Wie lautet der vierstufige Workflow?
Antwort: Erstellen Sie einen benannten Batch, fügen Sie Anfragen hinzu (über die API oder durch Erstellen des Batches aus einer hochgeladenen JSONL-Datei), verfolgen Sie die Zähler und rufen Sie die Ergebnisse ab, sobald sie verfügbar sind oder am Ende. Die Verarbeitung startet von selbst, ohne einen Startschritt.
3. Was können Sie in einen Batch aufnehmen?
Antwort: Responses-Anfragen (empfohlen) und Chat Completions (veraltet), mit Server-Tools und Funktionsaufrufen, sowie Bild- und Videogenerierungen und -bearbeitungen und Video-Erweiterungen. Nur Text-Token für berechtigte Modelle erhalten den Rabatt.
4. Wie verfolgen Sie die Ausführung?
Antwort: Über die Batch-Zähler (num_pending, num_success, num_error…), den Status jeder Anfrage (pending, succeeded, failed, cancelled) und die paginierten Ergebnisse, die Erfolge von Fehlern trennen. Der Batch ist vollständig verarbeitet, wenn num_pending null ist.
5. Welche Best Practices gelten für die Limits?
Antwort: Fügen Sie Anfragen in Blöcken hinzu, teilen Sie große Dateien in einen Batch pro Datei auf, laden Sie Medien innerhalb einer Stunde herunter, rufen Sie Ergebnisse vor expire_time ab und reichen Sie Fehler in einem neuen Batch erneut ein: Gestalten Sie den Batch als robusten Pipeline, nicht als blinden Bulk-Versand.
Gut strukturierte Batches, verfolgte Zähler und wiederholte Fehler: Die Batch-API verwandelt Volumen in Routine zum besten Preis.