Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Sledování, stav a zrušení

Lekce 11 z 12 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Správa životního cyklu dávky
  2. Dvě úrovně stavu
  3. Kontrola čítačů
  4. Výčet dávek
  5. Načítání výsledků
  6. Kontrola metadat požadavku
  7. Zrušení dávky
  8. Strategie dotazování (Polling)
  9. Klíčové poznatky

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žadavkuVýznamAkce
pendingVe frontěČekej
succeededZpracováno, výsledek k dispoziciZískej výsledek
failedChyba během zpracováníPřečti zprávu, případně zkus znovu
cancelledZrušeno, například spolu s dávkouV 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, /results výsledky, /requests detaily 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í limit a pagination_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