Sledovanie, stav a zrušenie
Na tejto strane
Aktualizované 2. novembra 2026 na základe dokumentácie xAI: zľava pre batch je 20 % na eligible textové modely (nie 50 %), príklady nasledujú REST API a oficiálny
xai-sdk(client.batch.*; Batch API od xAI nezodpovedá formátu OpenAI, takže SDK od OpenAI nie je použiteľné) a Responses API má prednosť pred Chat Completions, čo je zastaraný koncový bod v xAI. Zdroje: Batch API · REST Reference · Batch Pricing.
Správa životného cyklu batchu
Akonáhle odošleš svoje požiadavky, musíš sledovať priebeh spracovania, čítať stavy a vedieť, kedy a ako zrušiť batch. Táto lekcia pokrýva všetky dostupné operácie správy.
Dve úrovne stavu
xAI sleduje priebeh na dvoch úrovniach. Samotný batch nemá globálny stav ako „dokončené“ alebo „zlyhalé“: nesie počítadlá vo svojom objekte state. Každá požiadavka však má svoj vlastný stav:
| Stav požiadavky | Význam | Akcia |
|---|---|---|
pending | V poradí | Čakaj |
succeeded | Spracované, výsledok k dispozícii | Získaj výsledok |
failed | Chyba počas spracovania | Prečítaj správu, zopakuj, ak je to užitočné |
cancelled | Zrušené, napríklad spolu s batchom | Opätovne odovzdaj, ak je to potrebné |
Batch je úplne spracovaný, keď jeho počítadlo num_pending klesne na nulu. Môže byť tiež zrušený alebo expirovať: po čase expire_time už nie sú jeho výsledky dostupné.
Kontrola počítadiel
Volanie GET /v1/batches/{batch_id} vráti batch a jeho počítadlá:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Odpoveď 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
}
}
Tieto počítadlá sledujú priebeh v reálnom čase bez čakania na dokončenie spracovania. Pomocou SDK ich načítaš v client.batch.get(batch_id=...).state.
Zoznam tvojich batchov
Ak chceš nájsť batch alebo skontrolovať históriu:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Zoznam je stránkovaný pomocou limit a pagination_token. Batche tam zostávajú až do exspirácie. Pomocou SDK vráti client.batch.list(limit=20) zoznam batches, kde každý prvok nesie svoje name, batch_id a state. Konzola xAI ponúka rovnaký pohľad vo vizuálnej forme.
Získanie výsledkov
Výsledky môžeš získať kedykoľvek, dokonca aj počas spracovania:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Každý výsledok nesie batch_request_id svojej požiadavky. Zlyhané požiadavky sa tu zobrazujú so svojou správou; pomocou SDK ich oddeľujú vlastnosti succeeded a failed každej stránky.
Kontrola metadát požiadavky
Na sledovanie stavu každej požiadavky:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Každý záznam poskytuje identifikátor požiadavky, jej koncový bod, model, stav a dátumy vytvorenia a ukončenia. Toto je diagnostický nástroj, keď sa počítadlo zastaví, alebo na overenie toho, čo bolo úspešne pridané.
Zrušenie batchu
Ak potrebuješ zastaviť prebiehajúce spracovanie:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Zrušenie je konečné: čakajúce požiadavky nebudú spracované a do batchu už nemôžeš pridávať ďalšie požiadavky. Už spracované požiadavky však zostávajú dostupné vo výsledkoch. Zrušenie vykonaj, ak:
- Si po odoslaní zistil chybu vo svojich požiadavkách
- Batch už nie je potrebný (zmena priority)
- Chceš odovzdať opravený batch
Pomocou SDK: client.batch.cancel(batch_id=...), čo vráti batch a jeho počítadlá v čase zrušenia.
Stratégia dotazovania (Polling)
V produkcii čakaj na dokončenie s odstupňovaným dotazovaním a maximálnym oneskorením:
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 niekoľkých minút vyhovuje veľkým batchom; dokumentácia xAI v príkladoch dotazuje každých niekoľko sekúnd, čo pokrýva malé batche. A keďže výsledky sú dostupné hneď, ako prichádzajú, nič ti nebráni v ich získavaní počas čakania.
Kľúčové poznatky
- Čítaj batch podľa jeho počítadiel (
num_pending,num_success,num_error…); každá požiadavka má svoj stav:pending,succeeded,failed,cancelled GET /v1/batches/{id}poskytuje priebeh,/resultsvýsledky,/requestsdetaily požiadavky- Zrušenie (
POST /v1/batches/{id}:cancel) je nezvratné, ale zachováva už vyprodukované výsledky - Zoznamy a výsledky sú stránkované pomocou
limitapagination_token - Dotazuj v intervaloch niekoľkých minút s maximálnym oneskorením a získaj výsledky pred
expire_time