Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Négy lépésből álló munkafolyamat

2. lecke 12 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. A köteg életciklusa
  2. 1. lépés: Köteg létrehozása
  3. 2. lépés: Kérések hozzáadása
  4. 3. lépés: Haladás figyelése
  5. 4. lépés: Eredmények lekérése
  6. A munkafolyamat a gyakorlatban
  7. Hibakezelés a munkafolyamatban
  8. Főbb megállapítások

Frissítve: 2026. november 2. az xAI dokumentációja alapján: a kötegelt kedvezmény 20% a jogosult szöveges modelleken (nem 50%); a példák a REST API-t és a hivatalos xai-sdk csomagot használják (client.batch.*; az xAI Batch API-ja nem követi az OpenAI formátumát, így az OpenAI SDK nem alkalmazható); a Responses API pedig elsőbbséget élvez a Chat Completionshez képest, amely az xAI-nál már elavult végpont. Források: Batch API · REST referenciák · Batch árazás.

A köteg életciklusa

Minden köteg ugyanazon a cikluson megy keresztül: létrehozás, kérések hozzáadása, feldolgozás, eredmények lekérése. Mielőtt rátérnél a megvalósításra, elengedhetetlen e ciklus megértése, mivel minden lépésnek megvannak a saját korlátai és bevált gyakorlatai.

1. lépés: Köteg létrehozása

Minden egy POST /v1/batches hívással kezdődik, amelynek egyetlen kötelező mezője van: a köteg neve. Az API egy egyedi azonosítót (batch_id) ad vissza, amelyet minden további művelethez használnod kell.

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"}'

A válasz tartalmazza a köteg létrehozásának és lejáratának időpontját is (create_time, expire_time), valamint egy state objektumot, amelynek számlálói még mind nullán állnak.

2. lépés: Kérések hozzáadása

Két módszer létezik:

Az API-n keresztül: a kéréseket a POST /v1/batches/{batch_id}/requests végpontra küldöd. Minden hívás egy kéréslistát tartalmaz, és addig folytathatod a hozzáadást, amíg a köteget nem mondják le. Ez az út azoknak a kötegeknek való, amelyek fokozatosan épülnek fel.

JSONL-fájlon keresztül: előkészítesz egy fájlt, amely az összes kérésedet tartalmazza, feltöltöd azt a Files API-n keresztül, majd ebből a fájlból hozod létre a köteget. A köteg ezután lezárásra kerül: további hozzáadásokra nincs lehetőség. Ez a módszer nagy, előre előkészített mennyiségek esetén javasolt.

Minden kérés rendelkezik egy egyedi azonosítóval a kötegen belül: az API-ban ez a batch_request_id, a JSONL-fájlban pedig a custom_id. Ha az API-ban kihagyod, az xAI generál egy UUID-t; érdemes azonban sajátot megadnod (például egy adatbázis-azonosítót): ez szolgál kulcsként az adataid és az eredmények összerendeléséhez, valamint garantálja, hogy egy kérés csak egyszer kerüljön feldolgozásra.

3. lépés: Haladás figyelése

A feldolgozás automatikusan elindul, amint kérések érkeznek; nincs külön „indítás“ lépés. Eközben a GET /v1/batches/{batch_id} hívás visszaadja a state objektumot és annak számlálóit: num_requests (összesen), num_pending (függőben lévő), num_success (sikeres), num_error (sikertelen) és num_cancelled (megszakított).

curl https://api.x.ai/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $XAI_API_KEY"

Amikor a num_pending értéke nullára csökken, az összes kérés feldolgozásra került, sikerrel vagy kudarc nélkül. A periódusos lekérdezés (polling) elegendő: kis teszt-kötegeknél néhány másodperc, nagy kötegeknél néhány perc.

4. lépés: Eredmények lekérése

Az eredményeket a GET /v1/batches/{batch_id}/results végponttal olvashatod be, anélkül, hogy megvárnád a köteg teljes befejezését: minden kérés eredménye azonnal elérhető, amint a feldolgozása megtörtént. A válasz lapozható: a limit határozza meg az oldalméretet (maximum 1000), a visszaadott pagination_token pedig a következő oldal lekérésére szolgál; az utolsó oldalon ez üres.

curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Minden eredmény tartalmazza a hozzá tartozó kérés batch_request_id azonosítóját: ez lehetővé teszi, hogy helyreállítsd a hozzárendelést a bemeneti adataid és a Grok válaszai között.

A munkafolyamat a gyakorlatban

Egy éles környezetben futó pipeline-ban a munkafolyamat általában két külön folyamatra bomlik:

  • Egy beküldési folyamat, amely létrehozza a köteget, előkészíti és hozzáadja a kéréseket, majd eltárolja a batch_id-t.
  • Egy lekérési folyamat, amely periódikusan ellenőrzi a számlálókat, és letölti az eredményeket, ahogy azok elérhetővé válnak.

Ez a szétválasztás lehetővé teszi, hogy a Batch API-t eseményvezérelt architektúrákba vagy meglévő adatfolyamatokba (cron feladatok, Apache Airflow, sorok) integráld.

Hibakezelés a munkafolyamatban

Egy kötegnek nincs globális „sikeres“ vagy „sikertelen“ állapota: ezt a számlálókon keresztül olvashatod le. Egy sikertelen kérés növeli a num_error értékét, és hibaüzenetével együtt megjelenik az eredmények között anélkül, hogy blokkolná a többit. Ezért minden egyes eredményt meg kell vizsgálnod, és eseti alapon kell kezelned a hibákat.

Két esemény érinti az egész köteget. Az első a megszakítás, amelyet te vagy az xAI kezdeményez; utóbbi esetben a cancel_by_xai_message mező tartalmazza a magyarázatot. Ez különösen akkor fordul elő, ha egy JSONL-fájlban egy sor érvénytelen. A másik esemény a lejárat (expire_time), amely után az eredmények már nem elérhetők: ezért időben mentsd le őket.

Főbb megállapítások

  • A munkafolyamat sorrendje: létrehozás (névvel), hozzáadás, figyelés, lekérés
  • A kérés azonosítója (batch_request_id, vagy JSONL esetén custom_id) a te összerendelő kulcsod
  • A haladást a state számlálóiból olvashatod ki; minden akkor kerül feldolgozásra, ha a num_pending nulla
  • Az eredmények lapozhatók (limit, pagination_token), és a feldolgozásuk során válnak elérhetővé
  • A hibákat kérésenként kell kezelni; a megszakítás és a lejárat az egész köteget érinti