Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Rate limits and best practices

Lektion 12 von 12 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Einschränkungen, die Sie kennen müssen
  2. Rate Limits
  3. JSONL-Dateilimits
  4. URL-Ablauf
  5. Best Practices für den produktiven Einsatz
  6. Prüfliste vor der Produktion
  7. Kernaussagen
  8. Testen Sie Ihr Wissen

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änkungWertGeltungsbereich
Batch-Erstellung2 pro SekundePro Team
Anzahl der BatchesUnbegrenztPro Team
Aufrufe zum Hinzufügen von Anfragen1.000 pro 30 SekundenGleitendes Fenster, geteilt über alle Batches des Teams
Anfragegröße25 MBPro einzelne Anfrage
Anfragen pro BatchTheoretisch 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änkungWert
Anfragen pro DateiMaximum 50.000
DateigrößeMaximum 200 MB
Hinzufügungen nach ErstellungNicht 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_time abgerufen
  • 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.