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

Štvorkrokový pracovný postup

Lekcia 2 z 12 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Životný cyklus batchu
  2. Krok 1: Vytvorenie batchu
  3. Krok 2: Pridanie požiadaviek
  4. Krok 3: Monitorovanie priebehu
  5. Krok 4: Získanie výsledkov
  6. Pracovný postup v praxi
  7. Spracovanie chýb v pracovnom postupe
  8. Kľúčové poznatky

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_id alebo custom_id v JSONL) je tvoj kľúč na spárovanie
  • Priebeh sa číta z počítadiel v state; všetko je spracované, keď je num_pending rovné 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