Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Sledovanie, stav a zrušenie

Lekcia 11 z 12 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Správa životného cyklu batchu
  2. Dve úrovne stavu
  3. Kontrola počítadiel
  4. Zoznam tvojich batchov
  5. Získanie výsledkov
  6. Kontrola metadát požiadavky
  7. Zrušenie batchu
  8. Stratégia dotazovania (Polling)
  9. Kľúčové poznatky

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žiadavkyVýznamAkcia
pendingV poradíČakaj
succeededSpracované, výsledok k dispozíciiZískaj výsledok
failedChyba počas spracovaniaPrečítaj správu, zopakuj, ak je to užitočné
cancelledZrušené, napríklad spolu s batchomOpä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, /results výsledky, /requests detaily 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 limit a pagination_token
  • Dotazuj v intervaloch niekoľkých minút s maximálnym oneskorením a získaj výsledky pred expire_time