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

Nyomon követés, állapot és megszakítás

11. lecke 12 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. A köteg életciklusának kezelése
  2. Két szintű állapot
  3. Számlálók ellenőrzése
  4. Kötegek listázása
  5. Eredmények lekérése
  6. Kérés metaadatainak ellenőrzése
  7. Köteg megszakítása
  8. Lekérdezési (polling) stratégia
  9. 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 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 állapotaJelentésTeendő
pendingSorba állítvaVárakozás
succeededFeldolgozva, az eredmény elérhetőEredmény lekérése
failedHiba történt a feldolgozás soránÜzenet olvasása, újrapróbálkozás, ha érdemes
cancelledMegszakí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 /results az eredményeket, a /requests pedig 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 a pagination_token segí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_time előtt kérd le az adatokat