Sporing, status og annullering
På denne side
Opdateret 2. november 2026 baseret på xAI-dokumentation: batch-rabatten er 20 % på kvalificerede tekstmodeller (ikke 50 %), eksemplerne følger REST API’en og det officielle
xai-sdk(client.batch.*; xAI’s Batch API matcher ikke OpenAIs format, så OpenAI SDK’en gælder ikke), og Responses API’en har forrang frem for Chat Completions, som er et forældet endpoint hos xAI. Kilder: Batch API · REST Reference · Batch Pricing.
Styr batch-livscyklussen
Når du har indsendt dine anmodninger, skal du spore fremskridt, læse statusser og vide, hvornår og hvordan du annullerer en batch. Denne lektion dækker alle tilgængelige styringsoperationer.
To statusniveauer
xAI sporer fremskridt på to niveauer. Selve batchen har ingen global status som „fuldført” eller „fejlet”: den bærer tællere i sit state-objekt. Hver anmodning har derimod sin egen status:
| Anmodningsstatus | Betydning | Handling |
|---|---|---|
pending | I kø | Vent |
succeeded | Behandlet, resultat tilgængeligt | Hent resultat |
failed | Fejl under behandling | Læs besked, genforsøg hvis nyttigt |
cancelled | Annulleret, f.eks. med sin batch | Genindsend om nødvendigt |
Batchen er fuldt behandlet, når dens num_pending-tæller falder til nul. Den kan også annulleres eller udløbe: efter expire_time er resultaterne ikke længere tilgængelige.
Tjek tællere
Kaldet GET /v1/batches/{batch_id} returnerer batchen og dens tællere:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Svaret indeholder:
{
"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
}
}
Disse tællere sporer fremskridt i realtid uden at vente på, at behandlingen bliver færdig. Med SDK’en læser du dem i client.batch.get(batch_id=...).state.
List dine batches
For at finde en batch eller tjekke historik:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Listen er pagineret via limit og pagination_token. Batches forbliver der indtil udløb. Med SDK’en returnerer client.batch.list(limit=20) en batches-liste, hvor hvert element bærer sit name, batch_id og state. xAI-konsollen tilbyder samme visning i grafisk form.
Hent resultater
Du kan hente resultater når som helst, selv under behandling:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Hvert resultat bærer batch_request_id for sin anmodning. Fejlede anmodninger vises her med deres besked; med SDK’en adskiller egenskaberne succeeded og failed på hver side dem.
Tjek anmodningsmetadata
For at spore status for hver anmodning:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Hver post giver anmodningsidentifikatoren, dens endpoint, model, status samt oprettelses- og slutdatoer. Dette er dit diagnoseværktøj, når en tæller hænger, eller for at verificere, hvad der blev succesfuldt tilføjet.
Annuller en batch
Hvis du skal stoppe en igangværende behandling:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Annullering er endelig: ventende anmodninger bliver ikke behandlet, og du kan ikke længere tilføje anmodninger til batchen. Anmodninger, der allerede er behandlet, forbliver dog tilgængelige i resultaterne. Annuller hvis:
- Du har opdaget en fejl i dine anmodninger efter indsendelse
- Batchen ikke længere er nødvendig (prioritetsændring)
- Du ønsker at genindsende en korrigeret batch
Med SDK’en: client.batch.cancel(batch_id=...), hvilket returnerer batchen og dens tællere på annulleringstidspunktet.
Polling-strategi
I produktion venter du på fuldførelse med intervaller mellem forespørgsler og en maksimal forsinkelse:
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Wait until all requests in the batch are processed."""
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"Canceled by xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
return batch
print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
f"{etat.num_pending} pending out of {etat.num_requests}")
time.sleep(intervalle)
raise TimeoutError(f"Batch not finished after {delai_max} s")
Et interval på få minutter passer til store batches; xAI’s dokumentation poller hvert få sekund i sine eksempler, som dækker små batches. Og da resultater er tilgængelige, efterhånden som de kommer ind, hindrer intet dig i at hente dem under ventetiden.
Vigtige pointer
- Læs batchen via dens tællere (
num_pending,num_success,num_error…); hver anmodning har sin status:pending,succeeded,failed,cancelled GET /v1/batches/{id}giver fremskridt,/resultsgiver resultater,/requestsgiver anmodningsdetaljer- Annullering (
POST /v1/batches/{id}:cancel) er irreversibel, men bevarer allerede producerede resultater - Lister og resultater pagineres med
limitogpagination_token - Poll med intervaller på få minutter, med en maksimal forsinkelse, og hent før
expire_time