Praćenje, status i otkazivanje
Na ovoj stranici
Ažurirano 2. studenoga 2026. na temelju dokumentacije xAI-ja: popust za skupne zahtjeve iznosi 20 % na odgovarajuće tekstualne modele (ne 50 %), primjeri slijede REST API i službeni
xai-sdk(client.batch.*; Batch API xAI-ja ne odgovara formatu OpenAI-ja, stoga se OpenAI SDK ne primjenjuje), a Responses API ima prednost nad Chat Completions, koji je kod xAI-ja zastarjela krajnja točka. Izvori: Batch API · REST Reference · Batch Pricing.
Upravljanje životnim ciklusom skupnog zahtjeva
Nakon što pošalješ svoje zahtjeve, moraš pratiti napredak obrade, čitati statuse te znati kada i kako otkazati skupni zahtjev. Ova lekcija pokriva sve dostupne operacije upravljanja.
Dvije razine statusa
xAI prati napredak na dvije razine. Sam skupni zahtjev nema globalni status poput „završeno“ ili „neuspješno“: on sadrži brojače u svom objektu state. Svaki pojedinačni zahtjev, međutim, ima vlastiti status:
| Status zahtjeva | Značenje | Radnja |
|---|---|---|
pending | U čekanju | Pričekaj |
succeeded | Obrađeno, rezultat dostupan | Dohvati rezultat |
failed | Pogreška tijekom obrade | Pročitaj poruku, ponovi ako je korisno |
cancelled | Otkazano, npr. zajedno sa skupnim zahtjevom | Ponovno pošalji ako je potrebno |
Skupni zahtjev je u potpunosti obrađen kada njegov brojač num_pending padne na nulu. Može se i otkazati ili isteći: nakon expire_time, njegovi rezultati više nisu dostupni.
Provjera brojača
Poziv GET /v1/batches/{batch_id} vraća skupni zahtjev i njegove brojače:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Odgovor uključuje:
{
"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
}
}
Ovi brojači prate napredak u stvarnom vremenu, bez čekanja da se obrada završi. Uz SDK, očitaš ih putem client.batch.get(batch_id=...).state.
Popis tvojih skupnih zahtjeva
Da bi pronašao skupni zahtjev ili provjerio povijest:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Popis je straniran pomoću limit i pagination_token. Skupni zahtjevi ostaju tamo do isteka. Uz SDK, client.batch.list(limit=20) vraća popis batches gdje svaki element nosi svoj name, batch_id i state. xAI konzola nudi isti pregled, u vizualnom obliku.
Dohvaćanje rezultata
Rezultate možeš dohvatiti u bilo kojem trenutku, čak i tijekom obrade:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Svaki rezultat nosi batch_request_id svog zahtjeva. Neuspjeli zahtjevi pojavljuju se ondje sa svojom porukom; uz SDK, svojstva succeeded i failed svake stranice razdvajaju ih.
Provjera metapodataka zahtjeva
Za praćenje statusa svakog zahtjeva:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Svaki unos daje identifikator zahtjeva, njegovu krajnju točku, model, status te datume stvaranja i završetka. Ovo je dijagnostički alat kada se brojač zaglavi ili za provjeru što je uspješno dodano.
Otkazivanje skupnog zahtjeva
Ako trebaš zaustaviti obradu u tijeku:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Otkazivanje je konačno: zahtjevi na čekanju neće biti obrađeni i više ne možeš dodavati zahtjeve u skupni zahtjev. Zahtjevi koji su već obrađeni, međutim, ostaju dostupni u rezultatima. Otkaži ako:
- Si nakon slanja otkrio/la pogrešku u svojim zahtjevima
- Skupni zahtjev više nije potreban (promjena prioriteta)
- Želiš ponovno poslati ispravljeni skupni zahtjev
Uz SDK: client.batch.cancel(batch_id=...), što vraća skupni zahtjev i njegove brojače u trenutku otkazivanja.
Strategija anketiranja (Polling)
U proizvodnji pričekaj završetak uz razmaknuto anketiranje i maksimalno kašnjenje:
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")
Interval od nekoliko minuta odgovara velikim skupnim zahtjevima; dokumentacija xAI-ja u svojim primjerima anketira svakih nekoliko sekundi, što pokriva male skupne zahtjeve. Budući da su rezultati dostupni kako pristižu, ništa te ne sprječava da ih dohvatiš tijekom čekanja.
Ključne točke
- Čitaj skupni zahtjev putem njegovih brojača (
num_pending,num_success,num_error…); svaki zahtjev ima svoj status:pending,succeeded,failed,cancelled GET /v1/batches/{id}daje napredak,/resultsrezultate,/requestspojedinosti o zahtjevu- Otkazivanje (
POST /v1/batches/{id}:cancel) je nepovratno, ali zadržava već proizvedene rezultate - Popisi i rezultati straniraju se s
limitipagination_token - Anketiraj u intervalima od nekoliko minuta, s maksimalnim kašnjenjem, i dohvati rezultate prije
expire_time