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

Pracovní postup ve čtyřech krocích

Lekce 2 z 12 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Životní cyklus dávky
  2. Krok 1: Vytvoření dávky
  3. Krok 2: Přidání požadavků
  4. Krok 3: Sledování průběhu
  5. Krok 4: Získání výsledků
  6. Pracovní postup v praxi
  7. Zpracování chyb v pracovním postupu
  8. 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 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_id nebo custom_id v JSONL) je tvým spárovacím klíčem
  • Průběh se čte z čítačů state; vše je zpracováno, když je num_pending rovno 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