Négy lépésből álló munkafolyamat
Ezen az oldalon
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-sdkcsomagot 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éncustom_id) a te összerendelő kulcsod - A haladást a
stateszámlálóiból olvashatod ki; minden akkor kerül feldolgozásra, ha anum_pendingnulla - 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