Sledování, stav a zrušení
Na této stránce
Aktualizováno 2. listopadu 2026 na základě dokumentace xAI: sleva pro dávkové zpracování činí 20 % u způsobilých textových modelů (nikoli 50 %), příklady se řídí REST API a oficiálním
xai-sdk(client.batch.*; Batch API od xAI neodpovídá formátu OpenAI, takže SDK od OpenAI nelze použít) a API Responses má přednost před Chat Completions, což je u xAI zastaralý koncový bod. Zdroje: Batch API · REST Reference · Batch Pricing.
Správa životního cyklu dávky
Jakmile odešleš své požadavky, musíš sledovat průběh zpracování, číst stavy a vědět, kdy a jak dávku zrušit. Tato lekce pokrývá všechny dostupné operace správy.
Dvě úrovně stavu
xAI sleduje postup na dvou úrovních. Samotná dávka nemá žádný globální stav jako „dokončeno“ nebo „selhalo“: nese čítače ve svém objektu state. Každý požadavek však má svůj vlastní stav:
| Stav požadavku | Význam | Akce |
|---|---|---|
pending | Ve frontě | Čekej |
succeeded | Zpracováno, výsledek k dispozici | Získej výsledek |
failed | Chyba během zpracování | Přečti zprávu, případně zkus znovu |
cancelled | Zrušeno, například spolu s dávkou | V případě potřeby odešli znovu |
Dávka je plně zpracována, když její čítač num_pending klesne na nulu. Může být také zrušena nebo vypršet: po uplynutí expire_time již nejsou její výsledky přístupné.
Kontrola čítačů
Volání GET /v1/batches/{batch_id} vrátí dávku a její čítače:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Odpověď obsahuje:
{
"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
}
}
Tyto čítače sledují postup v reálném čase, aniž by bylo nutné čekat na dokončení zpracování. Pomocí SDK je přečteš v client.batch.get(batch_id=...).state.
Výčet dávek
Chceš-li najít dávku nebo zkontrolovat historii:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Seznam je stránkován pomocí limit a pagination_token. Dávky zde zůstávají až do vypršení platnosti. Pomocí SDK vrátí client.batch.list(limit=20) seznam batches, kde každý prvek nese své name, batch_id a state. Konzole xAI nabízí stejný pohled ve vizuální podobě.
Načítání výsledků
Výsledky můžeš získat kdykoli, dokonce i během zpracování:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Každý výsledek nese batch_request_id svého požadavku. Selhané požadavky se zde objevují se svou zprávou; pomocí SDK je oddělují vlastnosti succeeded a failed každé stránky.
Kontrola metadat požadavku
Chceš-li sledovat stav každého požadavku:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Každá položka uvádí identifikátor požadavku, jeho koncový bod, model, stav a data vytvoření a ukončení. Toto je diagnostický nástroj, když se čítač zasekne, nebo pro ověření toho, co bylo úspěšně přidáno.
Zrušení dávky
Pokud potřebuješ zastavit probíhající zpracování:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Zrušení je konečné: čekající požadavky nebudou zpracovány a do dávky již nelze přidávat další požadavky. Již zpracované požadavky však zůstávají k dispozici ve výsledcích. Zruš dávku, pokud:
- Jsi po odeslání zjistil chybu ve svých požadavcích
- Dávka již není potřebná (změna priority)
- Chceš znovu odeslat opravenou dávku
Pomocí SDK: client.batch.cancel(batch_id=...), což vrátí dávku a její čítače v okamžiku zrušení.
Strategie dotazování (Polling)
V produkčním prostředí čekej na dokončení pomocí periodického dotazování s odstupem a maximálním časovým limitem:
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 několika minut vyhovuje velkým dávkám; dokumentace xAI ve svých příkladech dotazuje každých několik sekund, což pokrývá malé dávky. A protože výsledky jsou k dispozici, jak přicházejí, nic nebrání jejich získání během čekání.
Klíčové poznatky
- Čti dávku podle jejích čítačů (
num_pending,num_success,num_error…); každý požadavek má svůj stav:pending,succeeded,failed,cancelled GET /v1/batches/{id}poskytuje postup,/resultsvýsledky,/requestsdetaily požadavku- Zrušení (
POST /v1/batches/{id}:cancel) je nevratné, ale zachovává již vyprodukované výsledky - Seznamy a výsledky jsou stránkovány pomocí
limitapagination_token - Dotazuj v intervalech několika minut s maximálním časovým limitem a výsledky získej před uplynutím
expire_time