Nyomon követés, állapot és megszakítás
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 modellekre (nem 50%), a példák a REST API-t és a hivatalos
xai-sdk-t (client.batch.*) követik (az xAI Batch API-ja nem egyezik az OpenAI formátumával, így az OpenAI SDK nem alkalmazható), és a Responses API elsőbbséget élvez a Chat Completions felett, amely az xAI-nál már elavult végpont. Források: Batch API · REST Referencia · Batch Árazás.
A köteg életciklusának kezelése
Miután beküldted a kéréseidet, nyomon kell követned a feldolgozás előrehaladását, le kell olvasnod az állapotokat, és tudnod kell, mikor és hogyan szakítsd meg a köteget. Ez a lecke minden elérhető kezelési műveletet lefed.
Két szintű állapot
Az xAI két szinten követi nyomon az előrehaladást. Maga a köteg nem rendelkezik olyan globális állapottal, mint a „befejezett“ vagy „sikertelen“: a state objektumában számlálókat tartalmaz. Minden egyes kérésnek azonban megvan a saját állapota:
| Kérés állapota | Jelentés | Teendő |
|---|---|---|
pending | Sorba állítva | Várakozás |
succeeded | Feldolgozva, az eredmény elérhető | Eredmény lekérése |
failed | Hiba történt a feldolgozás során | Üzenet olvasása, újrapróbálkozás, ha érdemes |
cancelled | Megszakítva, például a kötegével együtt | Újrabeküldés, ha szükséges |
A köteg akkor teljes egészében feldolgozott, amikor a num_pending számlálója nullára csökken. A köteg megszakítható vagy lejárhat is: az expire_time után az eredményei már nem érhetők el.
Számlálók ellenőrzése
A GET /v1/batches/{batch_id} hívás visszaadja a köteget és annak számlálóit:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
A válasz tartalmazza:
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "analyse_avis_clients",
"state": {
"num_requests": 500,
"num_pending": 155,
"num_success": 342,
"num_error": 3,
"num_cancelled": 0
}
}
Ezek a számlálók valós időben követik nyomon az előrehaladást anélkül, hogy meg kellene várnod a feldolgozás befejezését. Az SDK használatával a client.batch.get(batch_id=...).state útvonalon olvashatod le őket.
Kötegek listázása
Egy köteg megtalálásához vagy az előzmények ellenőrzéséhez:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
A lista a limit és a pagination_token alapján van lapozva. A kötegek a lejáratukig itt maradnak. Az SDK-val a client.batch.list(limit=20) egy batches listát ad vissza, ahol minden elem tartalmazza a name, batch_id és state adatokat. Az xAI konzol ugyanezt a nézetet kínálja vizuális formában.
Eredmények lekérése
Az eredményeket bármikor lekérheted, még feldolgozás közben is:
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. A sikertelen kérések is megjelennek itt a hibaüzenetükkel; az SDK esetén minden oldal succeeded és failed tulajdonságai választják el ezeket.
Kérés metaadatainak ellenőrzése
Az egyes kérések állapotának nyomon követéséhez:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Minden bejegyzés megadja a kérés azonosítóját, a végpontot, a modellt, az állapotot, valamint a létrehozás és befejezés dátumát. Ez a diagnosztikai eszköz akkor hasznos, ha egy számláló beragad, vagy ellenőrizni szeretnéd, mi került sikeresen hozzáadásra.
Köteg megszakítása
Ha meg kell szakítanod a folyamatban lévő feldolgozást:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
A megszakítás végleges: a függőben lévő kérések nem kerülnek feldolgozásra, és többé nem adhatsz hozzá kéréseket a köteghez. A már feldolgozott kérések azonban továbbra is elérhetők maradnak az eredmények között. Akkor szakítsd meg, ha:
- Beküldés után hibát észleltél a kéréseidben
- A kötegre már nincs szükség (prioritásváltás)
- Egy javított köteget szeretnél újra beküldeni
Az SDK-val: client.batch.cancel(batch_id=...), amely visszaadja a köteget és annak számlálóit a megszakítás pillanatában.
Lekérdezési (polling) stratégia
Éles környezetben várj a befejezésre időzített lekérdezésekkel és egy maximális időkorláttal:
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Wait until all requests in the batch are processed."""
debut = time.monotonic()
while time.monotonic() - debut < delai_max:
batch = client.batch.get(batch_id=batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Canceled by xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
return batch
print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
f"{etat.num_pending} pending out of {etat.num_requests}")
time.sleep(intervalle)
raise TimeoutError(f"Batch not finished after {delai_max} s")
Nagy kötegeknél néhány perces időköz illik; az xAI dokumentációja példái néhány másodpercenkénti lekérdezést mutatnak, amelyek kis kötegeket fednek le. Mivel az eredmények érkezésükkor elérhetők, semmi akadálya annak, hogy a várakozás alatt is lekérd őket.
Főbb megállapítások
- A köteget a számlálói alapján olvasd (
num_pending,num_success,num_error…); minden egyes kérésnek megvan a saját állapota:pending,succeeded,failed,cancelled - A
GET /v1/batches/{id}az előrehaladást adja meg, a/resultsaz eredményeket, a/requestspedig a kérések részleteit - A megszakítás (
POST /v1/batches/{id}:cancel) visszafordíthatatlan, de megtartja a már előállított eredményeket - A listák és az eredmények lapozása a
limités apagination_tokensegítségével történik - Lekérdezést végezz néhány perces időközönként, maximális időkorláttal, és az
expire_timeelőtt kérd le az adatokat