Limieten voor snelheid en best practices
Op deze pagina
Bijgewerkt op 2 november 2026. Gebaseerd op de documentatie van xAI: de batch-korting bedraagt 20% op in aanmerking komende tekstmodellen, de voorbeelden volgen de REST API en de officiële
xai-sdk(client.batch.*; de Batch API van xAI gebruikt niet het formaat van OpenAI, dus de OpenAI SDK is niet van toepassing), en de Responses API heeft voorrang boven Chat Completions, een verouderd eindpunt bij xAI. Bronnen: Batch API · REST-referentie · Batch-prijzen.
Beperkingen die u moet kennen
De Batch API legt technische limieten op waarmee u rekening moet houden in uw architectuur. Als u deze negeert, leidt dit tot afwijzingen, geannuleerde batches of verloren resultaten. Deze les vat de door xAI gedocumenteerde beperkingen samen en biedt best practices voor productiegebruik.
Limieten voor snelheid (Rate limits)
| Beperking | Waarde | Bereik |
|---|---|---|
| Batch-creatie | 2 per seconde | Per team |
| Aantal batches | Onbeperkt | Per team |
| Request-add-oproepen | 1.000 per 30 seconden | Glijdend venster, gedeeld over alle batches van het team |
| Request-grootte | 25 MB | Per individueel verzoek |
| Verzoeken per batch | Theoretisch onbeperkt | Boven de 100.000 kan de verwerking trager zijn |
Batch-creatie: de limiet van 2 creaties per seconde is zelden een probleem, aangezien u doorgaans één batch per bewerking aanmaakt.
Verzoeken toevoegen: de limiet geldt voor oproepen, en elke oproep bevat een lijst met verzoeken. Met blokken van 100 verzoeken zijn al meer dan 3.000 verzoeken per seconde mogelijk.
Request-grootte: de limiet van 25 MB heeft vooral invloed op verzoeken met base64-gecodeerde afbeeldingen; een tekstverzoek overschrijdt zelden enkele kilobytes.
Daarentegen tellen batch-verzoeken niet mee voor de snelheidslimieten van de real-time API: een grote batch vertraagt uw interactieve applicatie niet.
Limieten voor JSONL-bestanden
| Beperking | Waarde |
|---|---|
| Verzoeken per bestand | Maximum 50.000 |
| Bestandsgrootte | Maximum 200 MB |
| Toevoegingen na creatie | Niet mogelijk: de batch is verzegeld |
Als uw batch deze limieten overschrijdt, splitst u deze op in meerdere bestanden en maakt u één batch per bestand aan; u voegt de resultaten afterward samen.
Verloop van URL’s
Getekende URL’s voor afbeeldings- en videoresultaten verlopen na één uur. Dit is de meest kritieke beperking om in productie af te handelen: uw ophaalproces moet de media direct downloaden, zonder handmatige tussenkomst (de functie telecharger_medias uit les 9). Monitor voor de batch ook de expire_time, waarna geen resultaten meer toegankelijk zijn.
Best practices voor productie
Deterministische ID’s
Leid uw request-ID’s af (batch_request_id, of custom_id in JSONL) van uw invoergegevens. Als u een batch opnieuw moet indienen, produceren dezelfde gegevens dezelfde ID’s, wat deduplicatie eenvoudiger maakt:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Genereert een deterministische request-ID."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Omgaan met gedeeltelijke fouten
Een volledig verwerkte batch kan nog steeds mislukte verzoeken bevatten. Controleer altijd elk resultaat:
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)} mislukte verzoeken om opnieuw in te dienen in een nieuwe batch")
Kostenbewaking
Elke batch houdt de totale kosten bij in ticks (tiendamiljardste van een dollar):
batch = client.batch.get(batch_id=batch_id)
print("Totale kosten: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Via de REST API verschijnt de kostprijs van elk tekstverzoek in het resultaat, in het veld usage.cost_in_usd_ticks.
Logs en traceerbaarheid
Log elke bewerking zodat u problemen kunt diagnosticeren:
import logging
logger = logging.getLogger("batch_api")
logger.info("Batch aangemaakt: %s", batch_id)
logger.info("Bestand geüpload: %s, %d verzoeken", file_id, len(documents))
logger.info("Resultaten: %d geslaagd, %d mislukt", len(reussies), len(echouees))
Opnieuw proberen met backoff
Voor tijdelijke fouten (time-out, snelheidslimiet, serverfout) probeert u het opnieuw met een toenemende vertraging:
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"Opnieuw proberen over {attente} s: {e}")
time.sleep(attente)
Checklist voor pre-productie
Controleer het volgende voordat u een Batch API-pipeline naar productie deployt:
- Het model accepteert batchverwerking en staat in de lijst met modellen met korting als kosten belangrijk zijn
- Request-ID’s zijn uniek en deterministisch
- Het JSONL-bestand is gevalideerd vóór uploaden (één ongeldige regel annuleert de batch)
- Downloaden van multimodale resultaten is geautomatiseerd, binnen één uur
- Gedeeltelijke fouten worden gedetecteerd en opnieuw ingediend in een nieuwe batch
- Resultaten worden opgehaald vóór
expire_time - Logs dekken elke stap van de workflow
- De API-sleutel wordt gelezen uit een omgevingsvariabele, nooit hardcoded
Belangrijkste punten
- Limieten: 2 creaties per seconde, 1.000 request-add-oproepen per 30 seconden, 25 MB per verzoek
- JSONL-bestanden: maximum 50.000 verzoeken en 200 MB, één batch per bestand
- URL’s voor afbeeldingen en video’s verlopen in één uur: direct downloaden
- Deterministische ID’s, controle van elk resultaat, kostenbewaking in ticks
- Logs, opnieuw proberen met backoff en een maximale time-out voor productie
Test uw kennis
Bulkverwerking: de Batch API zonder grijze zones.
1. Wanneer is de Batch API de juiste keuze?
Antwoord: Voor grote volumes zonder real-time vereisten: classificatie, verrijking, evaluaties, bulk-generatie. Batch-verzoeken tellen niet mee voor snelheidslimieten, en in aanmerking komende tekstmodellen krijgen 20% korting.
2. Wat is de workflow in vier stappen?
Antwoord: Maak een benoemde batch aan, voeg verzoeken toe (via de API, of door de batch aan te maken vanuit een geüpload JSONL-bestand), volg de tellers op en haal vervolgens de resultaten op, naarmate ze binnenkomen of aan het einde. De verwerking start automatisch, zonder aparte startstap.
3. Wat kunt u in een batch plaatsen?
Antwoord: Responses-verzoeken (aanbevolen) en Chat Completions (verouderd), met servertools en function calling, evenals het genereren en bewerken van afbeeldingen en video’s, en video-extensies. Alleen teksttokens voor in aanmerking komende modellen krijgen de korting.
4. Hoe volgt u de uitvoering?
Antwoord: Via de batch-tellers (num_pending, num_success, num_error…), de status van elk verzoek (pending, succeeded, failed, cancelled) en de gepagineerde resultaten, die successen scheiden van mislukkingen. De batch is volledig verwerkt wanneer num_pending nul is.
5. Welke best practices gelden voor de limieten?
Antwoord: Voeg verzoeken toe in blokken, splits grote bestanden op in één batch per bestand, download media binnen één uur, haal resultaten op vóór expire_time en dien mislukkingen opnieuw in in een nieuwe batch: ontwerp de batch als een robuuste pipeline, niet als een blinde bulk-inzending.
Goed gevormde batches, bijgehouden tellers, opnieuw geprobeerde fouten: de Batch API maakt van volume routine, tegen de beste kosten.