Grænser for forespørgsler og bedste praksis
På denne side
Opdateret 2. november 2026. Baseret på xAI-dokumentation: batch-rabatten er på 20 % for berettigede tekstmodeller, eksemplerne følger REST API og det officielle
xai-sdk(client.batch.*; xAI’s Batch API bruger ikke OpenAI-formatet, så OpenAI SDK gælder ikke), og Responses API har forrang frem for Chat Completions, som er et forældet endpoint hos xAI. Kilder: Batch API · REST-reference · Batch-prissætning.
Begrænsninger, du skal kende
Batch API’en pålægger tekniske grænser, som du skal tage højde for i din arkitektur. Ignorerer du dem, risikerer du afvisninger, annullerede batches eller mistede resultater. Denne lektion opsummerer de begrænsninger, xAI har dokumenteret, samt bedste praksis til produktionsbrug.
Grænser for forespørgsler (Rate limits)
| Begrænsning | Værdi | Omfang |
|---|---|---|
| Oprettelse af batch | 2 per sekund | Per team |
| Antal batches | Ubegrænset | Per team |
| Kald til tilføjelse af forespørgsler | 1.000 per 30 sekunder | Glidende vindue, delt på tværs af alle teamets batches |
| Størrelse på forespørgsel | 25 MB | Per individuel forespørgsel |
| Forespørgsler per batch | Teoretisk ubegrænset | Over 100.000 kan behandlingen blive langsommere |
Oprettelse af batch: Grænsen på 2 oprettelser per sekund er sjældent et problem, da du typisk kun opretter én batch per operation.
Tilføjelse af forespørgsler: Grænsen gælder for kald, hvor hvert kald indeholder en liste over forespørgsler. Med chunks på 100 forespørgsler muliggør dette allerede mere end 3.000 forespørgsler per sekund.
Størrelse på forespørgsel: Grænsen på 25 MB påvirker primært forespørgsler fyldt med base64-kodede billeder; en tekstforespørgsel overstiger sjældent få kilobytes.
Omvendt tæller batch-forespørgsler ikke med i grænserne for realtids-API’et: en stor batch sænker ikke hastigheden på din interaktive applikation.
Grænser for JSONL-filer
| Begrænsning | Værdi |
|---|---|
| Forespørgsler per fil | Maksimum 50.000 |
| Filstørrelse | Maksimum 200 MB |
| Tilføjelser efter oprettelse | Ikke muligt: batch’en er forseglet |
Hvis din batch overskrider disse grænser, skal du opdele den i flere filer og oprette én batch per fil; derefter samler du resultaterne.
Udløb af URL’er
Signerede URL’er til billede- og videoresultater udløber efter én time. Dette er den mest kritiske begrænsning at håndtere i produktion: din henteproces skal downloade medierne øjeblikkeligt uden manuel indgriben (funktionen telecharger_medias fra lektion 9). For batch’en skal du også overvåge expire_time, hvorefter ingen resultater er tilgængelige.
Beste praksis til produktion
Deterministiske ID’er
Udled dine forespørgsels-ID’er (batch_request_id eller custom_id i JSONL) fra dine inputdata. Hvis du skal indsende en batch igen, vil de samme data producere de samme ID’er, hvilket gør deduplikering lettere:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Genererer et deterministisk forespørgsels-ID."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Håndtering af delvise fejl
En fuldt behandlet batch kan stadig indeholde mislykkede forespørgsler. Tjek altid hvert enkelt resultat:
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)} mislykkede forespørgsler skal indsendes igen i en ny batch")
Omkostningssporing
Hver batch holder styr på sine samlede omkostninger i ticks (ti-milliardtedele af en dollar):
batch = client.batch.get(batch_id=batch_id)
print("Samlede omkostninger: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Gennem REST API vises omkostningerne for hver tekstforespørgsel i resultatet i feltet usage.cost_in_usd_ticks.
Logs og sporbarhed
Logfør hver operation, så du kan diagnosticere problemer:
import logging
logger = logging.getLogger("batch_api")
logger.info("Batch oprettet: %s", batch_id)
logger.info("Fil uploadet: %s, %d forespørgsler", file_id, len(documents))
logger.info("Resultater: %d succesfulde, %d mislykkede", len(reussies), len(echouees))
Genforsøg med backoff
Ved midlertidige fejl (timeout, rate limit, serverfejl) skal du genforsøge med en stigende forsinkelse:
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"Genforsøger om {attente} s: {e}")
time.sleep(attente)
Tjekliste før produktion
Før du udruller en Batch API-pipeline til produktion, skal du tjekke:
- At modellen accepterer batch-behandling og står på listen over rabatterede modeller, hvis omkostninger er vigtige
- At forespørgsels-ID’er er unikke og deterministiske
- At JSONL-filen valideres før upload (én ugyldig linje annullerer hele batch’en)
- At download af multimodale resultater er automatiseret og sker inden for én time
- At delvise fejl opdages og indsendes igen i en ny batch
- At resultater hentes før
expire_time - At logs dækker hvert trin i workflowet
- At API-nøglen læses fra en miljøvariabel og aldrig hardcodes
Vigtige pointer
- Grænser: 2 oprettelser per sekund, 1.000 kald til tilføjelse af forespørgsler per 30 sekunder, 25 MB per forespørgsel
- JSONL-filer: Maksimum 50.000 forespørgsler og 200 MB, én batch per fil
- URL’er til billeder og videoer udløber på én time: download straks
- Deterministiske ID’er, tjek af hvert resultat, omkostningssporing i ticks
- Logs, genforsøg med backoff og en maksimal timeout til produktion
Test din viden
Massebehandling: Batch API’en uden gråzoner.
1. Hvornår er Batch API det rigtige valg?
Svar: Til store mængder uden krav om realtid: klassificering, berigelse, evalueringer og massegenerering. Batch-forespørgsler tæller ikke med i grænserne, og berettigede tekstmodeller får 20 % rabat.
2. Hvad er workflowet i fire trin?
Svar: Opret en navngiven batch, tilføj forespørgsler til den (via API’et eller ved at oprette batch’en fra en uploadet JSONL-fil), følg dens tællere, og hent derefter resultaterne, efterhånden som de kommer ind eller til sidst. Behandlingen starter af sig selv uden et specifikt starttrin.
3. Hvad kan du putte i en batch?
Svar: Responses-forespørgsler (anbefales) og Chat Completions (forældet), med serverværktøjer og funktionskald, samt generering og redigering af billeder og videoer og videoudvidelser. Kun teksttokens for berettigede modeller får rabatten.
4. Hvordan sporer du eksekveringen?
Svar: Gennem batch-tællerne (num_pending, num_success, num_error…), status for hver forespørgsel (pending, succeeded, failed, cancelled) og de paginerede resultater, som adskiller succeser fra fejl. Batch’en er fuldt behandlet, når num_pending er nul.
5. Hvilken bedste praksis gælder for grænserne?
Svar: Tilføj forespørgsler i chunks, opdel store filer i én batch per fil, download medier inden for én time, hent resultater før expire_time, og indsend fejl igen i en ny batch: design batch’en som en robust pipeline, ikke som en blind masseindsendelse.
Velstrukturerede batches, sporede tællere og genforsøgte fejl: Batch API’en gør volumen til rutine til den bedste pris.