Pracovní postup ve čtyřech krocích
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 využívají REST API a oficiální
xai-sdk(client.batch.*; Batch API od xAI se neřídí formátem OpenAI, takže SDK od OpenAI zde nefunguje); a API Responses má přednost před Chat Completions, což je u xAI zastaralý koncový bod. Zdroje: Batch API · Reference REST · Ceník Batch API.
Životní cyklus dávky
Každá dávka prochází stejným cyklem: vytvoření, přidání požadavků, zpracování a získání výsledků. Porozumění tomuto cyklu je před přechodem k implementaci zásadní, protože každý krok má svá vlastní omezení a osvědčené postupy.
Krok 1: Vytvoření dávky
Všechno začíná voláním POST /v1/batches s jedním povinným polem: názvem dávky. API vrátí jedinečný identifikátor (batch_id), který použiješ pro všechny následné operace.
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
Odpověď také obsahuje datum vytvoření a datum vypršení platnosti dávky (create_time, expire_time) a objekt state, jehož čítače jsou zatím všechny nastaveny na nulu.
Krok 2: Přidání požadavků
Existují dvě metody:
Prostřednictvím API: požadavky odešleš pomocí POST /v1/batches/{batch_id}/requests. Každé volání nese seznam požadavků a můžeš je přidávat tak dlouho, dokud není dávka zrušena. Toto je cesta pro dávky budované postupně.
Prostřednictvím souboru JSONL: připravíš soubor obsahující všechny své požadavky, nahraješ jej přes Files API a následně z tohoto souboru vytvoříš dávku. Dávka je poté uzavřena: další přidávání již není možné. Toto je cesta pro velké objemy připravené předem.
Každý požadavek nese v rámci dávky jedinečný identifikátor: batch_request_id v API nebo custom_id v souboru JSONL. Pokud jej v API vynecháš, xAI vygeneruje UUID; místo toho zadej vlastní (například ID z databáze): slouží jako klíč pro spárování tvých dat s výsledky a zaručuje, že požadavek bude zpracován pouze jednou.
Krok 3: Sledování průběhu
Zpracování začíná okamžitě po doručení požadavků; neexistuje žádný krok „spuštění“. Mezitím GET /v1/batches/{batch_id} vrací objekt state a jeho čítače: num_requests (celkem), num_pending (čekající), num_success (úspěšné), num_error (neúspěšné) a num_cancelled (zrušené).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Když num_pending klesne na nulu, všechny požadavky byly zpracovány, ať už úspěšně, či nikoli. Pro malé testovací dávky stačí periodické dotazování každých několik sekund, pro velké dávky každých několik minut.
Krok 4: Získání výsledků
Výsledky čteš pomocí GET /v1/batches/{batch_id}/results, aniž bys čekal na dokončení celé dávky: každý požadavek je k dispozici hned, jak je zpracován. Odpověď je stránkovaná: limit určuje velikost stránky (maximálně 1 000) a vrácený pagination_token slouží k vyžádání další stránky; na poslední stránce je prázdný.
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: to ti umožňuje rekonstruovat mapování mezi tvými vstupními daty a odpověďmi modelu Grok.
Pracovní postup v praxi
V produkčním pipeline se pracovní postup obvykle převádí do dvou samostatných procesů:
- Proces odesílání, který vytvoří dávku, připraví a přidá požadavky a poté uloží
batch_id - Proces získávání, který pravidelně kontroluje čítače a stahuje výsledky, jakmile jsou k dispozici
Toto oddělení ti umožňuje integrovat Batch API do architektur řízených událostmi nebo do stávajících datových pipeline (cron jobs, Apache Airflow, fronty).
Zpracování chyb v pracovním postupu
Dávka nemá žádný globální stav „úspěch“ nebo „neúspěch“: čteš jej prostřednictvím svých čítačů. Neúspěšný požadavek inkrementuje num_error a objeví se ve výsledcích se svou chybovou zprávou, aniž by blokoval ostatní. Proto musíš prozkoumat každý výsledek a řešit selhání případ od případu.
Dvě události ovlivňují celou dávku. První je zrušení, ať už tebou nebo xAI, což je následně vysvětleno v poli cancel_by_xai_message. K tomu dochází zejména tehdy, když je řádek v souboru JSONL neplatný. Druhou je vypršení platnosti (expire_time), po kterém již výsledky nejsou přístupné: stáhni je proto včas.
Klíčové poznatky
- Pracovní postup sleduje pořadí: vytvořit (s názvem), přidat, sledovat, získat
- Identifikátor požadavku (
batch_request_idnebocustom_idv JSONL) je tvým spárovacím klíčem - Průběh se čte z čítačů
state; vše je zpracováno, když jenum_pendingrovno nule - Výsledky jsou stránkované (
limit,pagination_token) a dostupné průběžně během zpracování - Chyby se řeší požadavek po požadavku; zrušení a vypršení platnosti ovlivňují celou dávku