Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Firetrins arbejdsgang

Lektion 2 af 12 Opdateret 2. november 2026 Udvikler
På denne side
  1. En batchs livscyklus
  2. Trin 1: Opret en batch
  3. Trin 2: Tilføj anmodninger
  4. Trin 3: Overvåg fremdriften
  5. Trin 4: Hent resultater
  6. Arbejdsgangen i praksis
  7. Håndtering af fejl i arbejdsgangen
  8. Vigtige pointer

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_id eller custom_id i JSONL) er din match-nøgle
  • Fremdriften aflæses fra state-tællerne; alt er behandlet, når num_pending er 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