Firetrins arbejdsgang
På denne side
Opdateret 2. november 2026 baseret på xAI-dokumentation: batch-rabatten er 20 % på berettigede tekstmodeller (ikke 50 %); eksemplerne bruger REST API’et og det officielle
xai-sdk(client.batch.*; xAI’s Batch API følger ikke OpenAI-formatet, så OpenAI SDK’en gælder ikke); og Responses API har førsteret frem for Chat Completions, som er et forældet endpoint hos xAI. Kilder: Batch API · REST-reference · Batch-prissætning.
En batchs livscyklus
Enhver batch gennemløber den samme cyklus: opret, tilføj anmodninger, behandl, hent resultater. Det er afgørende at forstå denne cyklus, før du går i gang med implementeringen, da hvert trin har sine egne begrænsninger og bedste praksis.
Trin 1: Opret en batch
Alt starter med et POST /v1/batches-kald med ét påkrævet felt: batch-navnet. API’et returnerer en unik identifikator (batch_id), som du bruger til alle efterfølgende operationer.
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
Svaret indeholder også datoerne for oprettelse og udløb af batchen (create_time, expire_time) samt et state-objekt, hvor alle tællere stadig står på nul.
Trin 2: Tilføj anmodninger
Der findes to metoder:
Via API’et: Du sender anmodninger med POST /v1/batches/{batch_id}/requests. Hvert kald indeholder en liste over anmodninger, og du kan fortsætte med at tilføje dem, så længe batchen ikke er annulleret. Dette er vejen for batcher, der bygges løbende.
Via en JSONL-fil: Du forbereder en fil med alle dine anmodninger, uploader den via Files API’et og opretter derefter batchen ud fra denne fil. Batchen bliver herefter lås: yderligere tilføjelser er ikke mulige. Dette er vejen for store mængder data, der er forberedt på forhånd.
Hver anmodning har en unik identifikator inden for batchen: batch_request_id i API’et, custom_id i JSONL-filen. Hvis du udelader den i API’et, genererer xAI et UUID; angiv i stedet din egen (f.eks. en database-ID): den fungerer som nøgle til at matche dine data med resultaterne og garanterer, at en anmodning kun behandles én gang.
Trin 3: Overvåg fremdriften
Behandlingen starter, så snart anmodninger ankommer; der er intet “start”-trin. I mellemtiden returnerer GET /v1/batches/{batch_id} state-objektet og dets tællere: num_requests (i alt), num_pending (afventende), num_success (vellykkede), num_error (fejlede) og num_cancelled (annullerede).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Når num_pending falder til nul, er alle anmodninger behandlet – uanset om de lykkedes eller ej. Periodisk polling er tilstrækkeligt: få sekunder for en lille test-batch, få minutter for en stor batch.
Trin 4: Hent resultater
Resultater læses med GET /v1/batches/{batch_id}/results, uden at vente på, at batchen bliver færdig: hver anmodning er tilgængelig, så snart den er behandlet. Svaret er pagineret: limit angiver sidestørrelsen (maksimalt 1.000), og det returnerede pagination_token bruges til at anmode om næste side; det er tomt på den sidste side.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Hvert resultat indeholder batch_request_id fra sin anmodning: dette giver dig mulighed for at genskabe sammenhængen mellem dine inputdata og Groks svar.
Arbejdsgangen i praksis
I en produktionspipeline oversættes arbejdsgangen typisk til to separate processer:
- En indsendelsesproces, der opretter batchen, forbereder og tilføjer anmodninger og derefter gemmer
batch_id - En henteproces, der periodisk tjekker tællerne og downloader resultater, efterhånden som de bliver tilgængelige
Denne opdeling gør det muligt at integrere Batch API’et i event-drevne arkitekturer eller eksisterende datapipelines (cron-jobs, Apache Airflow, køer).
Håndtering af fejl i arbejdsgangen
En batch har ingen global tilstand for “lykkedes” eller “fejlet”: du aflæser den via dens tællere. En fejlet anmodning øger num_error og vises i resultaterne med sin fejlmeddelelse uden at blokere de andre. Du skal derfor gennemgå hvert resultat og håndtere fejl tilfælde for tilfælde.
To begivenheder påvirker hele batchen. Den første er annullering, foretaget af dig eller af xAI, som derefter forklarer årsagen i feltet cancel_by_xai_message. Dette sker især, når en linje i en JSONL-fil er ugyldig. Den anden er udløb (expire_time), hvorefter resultater ikke længere er tilgængelige: hent dem hurtigt.
Vigtige pointer
- Arbejdsgangen følger rækkefølgen: opret (med et navn), tilføj, overvåg, hent
- Anmodningsidentifikatoren (
batch_request_idellercustom_idi JSONL) er din match-nøgle - Fremdriften aflæses fra
state-tællerne; alt er behandlet, nårnum_pendinger nul - Resultater er paginerede (
limit,pagination_token) og tilgængelige, efterhånden som de behandles - Fejl håndteres anmodning for anmodning; annullering og udløb påvirker hele batchen