Štvorkrokový pracovný postup
Na tejto strane
Aktualizované 2. novembra 2026 na základe dokumentácie xAI: zľava pre batch je 20 % na spôsobilé textové modely (nie 50 %); príklady využívajú REST API a oficiálny
xai-sdk(client.batch.*; Batch API od xAI sa neriadi formátom OpenAI, takže SDK od OpenAI nie je použiteľné); a API Responses má prednosť pred Chat Completions, čo je v xAI zastaraný koncový bod. Zdroje: Batch API · Referencia REST · Cenník Batch.
Životný cyklus batchu
Každý batch prechádza rovnakým cyklom: vytvorenie, pridanie požiadaviek, spracovanie, získanie výsledkov. Porozumenie tomuto cyklu je nevyhnutné predtým, než prejdeš k implementácii, pretože každý krok má svoje vlastné obmedzenia a osvedčené postupy.
Krok 1: Vytvorenie batchu
Všetko začína volaním POST /v1/batches s jedným povinným poľom: názvom batchu. API vráti jedinečný identifikátor (batch_id), ktorý použiješ pre všetky následné operácie.
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"}'
Odpoveď obsahuje aj dátumy vytvorenia a exspirácie batchu (create_time, expire_time) a objekt state, ktorého počítadlá sú zatiaľ všetky nastavené na nulu.
Krok 2: Pridanie požiadaviek
Existujú dve metódy:
Prostredníctvom API: požiadavky odosielaš pomocou POST /v1/batches/{batch_id}/requests. Každé volanie nesie zoznam požiadaviek a môžeš ich pridávať ďalej, pokiaľ nie je batch zrušený. Toto je cesta pre batche budované prírastkovo.
Prostredníctvom súboru JSONL: pripravíš súbor obsahujúci všetky svoje požiadavky, nahraješ ho cez Files API a následne z tohto súboru vytvoríš batch. Batch je potom uzavretý: ďalšie pridávanie nie je možné. Toto je cesta pre veľké objemy pripravené vopred.
Každá požiadavka nesie v rámci batchu jedinečný identifikátor: batch_request_id v API, custom_id v súbore JSONL. Ak ho v API vynecháš, xAI vygeneruje UUID; namiesto toho uveď vlastný (napríklad ID z databázy): slúži ako kľúč na spárovanie medzi tvojimi dátami a výsledkami a garantuje, že požiadavka bude spracovaná len raz.
Krok 3: Monitorovanie priebehu
Spracovanie začne hneď, ako prídu požiadavky; neexistuje žiadny krok „štart“. Medzitým GET /v1/batches/{batch_id} vracia objekt state a jeho počítadlá: num_requests (celkom), num_pending (čakajúce), num_success (úspešné), num_error (zlyhané) a num_cancelled (zrušené).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Keď num_pending klesne na nulu, všetky požiadavky boli spracované, či už úspešne, alebo nie. Stačí pravidelné dotazovanie (polling): niekoľko sekúnd pre malý testovací batch, niekoľko minút pre veľký batch.
Krok 4: Získanie výsledkov
Výsledky čítaš pomocou GET /v1/batches/{batch_id}/results, bez čakania na dokončenie batchu: každá požiadavka je dostupná hneď, ako je spracovaná. Odpoveď je stránkovaná: limit nastavuje veľkosť stránky (maximálne 1 000) a vrátený pagination_token sa použije na vyžiadanie ďalšej stránky; na poslednej stránke je prázdny.
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: to ti umožňuje rekonštruovať mapovanie medzi tvojimi vstupnými dátami a odpoveďami od Grok.
Pracovný postup v praxi
Vo výrobnom pipeline sa pracovný postup zvyčajne prekladá do dvoch samostatných procesov:
- Proces odoslania, ktorý vytvorí batch, pripraví a pridá požiadavky a následne uloží
batch_id - Proces získavania, ktorý pravidelne kontroluje počítadlá a sťahuje výsledky, ako sa stávajú dostupnými
Toto oddelenie ti umožňuje integrovať Batch API do architektúr riadených udalosťami alebo do existujúcich dátových pipeline (cron jobs, Apache Airflow, fronty).
Spracovanie chýb v pracovnom postupe
Batch nemá globálny stav „úspešný“ alebo „zlyhaný“: čítaš ho prostredníctvom jeho počítadiel. Zlyhaná požiadavka inkrementuje num_error a objaví sa vo výsledkoch so svojou chybovou správou, bez blokovania ostatných. Preto musíš preskúmať každý výsledok a riešiť zlyhania prípad od prípadu.
Dve udalosti ovplyvňujú celý batch. Prvou je zrušenie, či už tebou, alebo xAI, čo potom vysvetlí v poli cancel_by_xai_message. K tomu dochádza najmä vtedy, keď je riadok v súbore JSONL neplatný. Druhou je exspirácia (expire_time), po ktorej už výsledky nie sú dostupné: získaj ich včas.
Kľúčové poznatky
- Pracovný postup nasleduje poradie: vytvoriť (s názvom), pridať, monitorovať, získať
- Identifikátor požiadavky (
batch_request_idalebocustom_idv JSONL) je tvoj kľúč na spárovanie - Priebeh sa číta z počítadiel v
state; všetko je spracované, keď jenum_pendingrovné nule - Výsledky sú stránkované (
limit,pagination_token) a dostupné hneď, ako sú spracované - Chyby sa riešia požiadavku po požiadavke; zrušenie a exspirácia ovplyvňujú celý batch