Korlátok és bevált gyakorlatok
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 modelleknél, a példák a REST API-t és a hivatalos
xai-sdk-t (client.batch.*) követik (az xAI Batch API-ja nem az OpenAI formátumát használja, így az OpenAI SDK nem alkalmazható), és a Responses API elsőbbséget élvez a Chat Completions-szel szemben, amely az xAI-nál már elavult végpont. Források: Batch API · REST hivatkozás · Batch árazás.
Ismerned kellő korlátok
A Batch API technikai korlátokat szab meg, amelyeket figyelembe kell venned az architektúrádban. Ha figyelmen kívül hagyod őket, az elutasított kérésekhez, megszakított kötegekhez vagy elveszett eredményekhez vezet. Ez a lecke összefoglalja az xAI által dokumentált korlátokat és a éles környezetben alkalmazandó bevált gyakorlatokat.
Sebességkorlátok (Rate limits)
| Korlát | Érték | Hatókör |
|---|---|---|
| Köteg létrehozása | 2 másodpercenként | Csapatonként |
| Kötegek száma | Korlátlan | Csapatonként |
| Request-add hívások | 1000 db 30 másodpercenként | Csúszó ablak, a csapat összes kötegére közösen vonatkozik |
| Kérés mérete | 25 MB | Egyedi kérésenként |
| Kérések kötegenként | Elméletileg korlátlan | 100 000 felett a feldolgozás lassulhat |
Köteg létrehozása: a másodpercenkénti 2 létrehozási korlát ritkán jelent problémát, mivel általában műveletenként csak egy köteget hozol létre.
Kérések hozzáadása: a korlát a hívásokra vonatkozik, és minden hívás egy kéréslistát tartalmaz. 100 kérésből álló csomagok esetén ez már másodpercenként több mint 3000 kérést tesz lehetővé.
Kérés mérete: a 25 MB-os korlát főként a base64-kódolt képeket tartalmazó kéréseket érinti; egy szöveges kérés ritkán haladja meg a néhány kilobájtot.
Ezzel szemben a kötegelt kérések nem számítanak bele a valós idejű API sebességkorlátaiba: egy nagy köteg nem lassítja le az interaktív alkalmazásodat.
JSONL-fájl korlátok
| Korlát | Érték |
|---|---|
| Kérések fájlonként | Maximum 50 000 |
| Fájlméret | Maximum 200 MB |
| Hozzáadás létrehozás után | Nem lehetséges: a köteg lezárásra kerül |
Ha a köteged túllépi ezeket a korlátokat, oszd fel több fájlra, és hozz létre egy köteget fájlonként; az eredményeket utólag egyesíted.
URL-lejárat
A kép- és videoeredményekhez tartozó aláírt URL-ek egy óra múlva lejárnak. Ez a legkritikusabb korlát, amit éles környezetben kezelned kell: a lekérési folyamatodnak azonnal le kell töltenie a médiát, emberi beavatkozás nélkül (lásd a 9. lecke telecharger_medias függvényét). A köteg esetében figyeld az expire_time értéket is, amely után már egyetlen eredmény sem érhető el.
Bevált gyakorlatok éles környezetben
Determinisztikus azonosítók
A kérésazonosítóidat (batch_request_id, vagy custom_id a JSONL-ben) a bemeneti adataidból vezesd le. Ha újra be kell nyújtanod egy köteget, ugyanaz az adat ugyanazokat az azonosítókat generálja, ami megkönnyíti a duplikációk kiszűrését:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Generates a deterministic request ID."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Részleges hibák kezelése
Egy teljesen feldolgozott kötegben is lehetnek sikertelen kérések. Mindig ellenőrizd az összes eredményt:
reussies, echouees = [], []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch_id, limit=1000, pagination_token=jeton
)
reussies.extend(page.succeeded)
echouees.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
if echouees:
print(f"{len(echouees)} failed requests to resubmit in a new batch")
Költségkövetés
Minden köteg nyomon követi a teljes költségét tick-ekben (a dollár tízmilliárdod része):
batch = client.batch.get(batch_id=batch_id)
print("Total cost: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
A REST API-n keresztül minden szöveges kérés költsége megjelenik az eredményében, a usage.cost_in_usd_ticks mezőben.
Naplózás és nyomon követhetőség
Naplózz minden műveletet, hogy diagnosztizálni tudd a problémákat:
import logging
logger = logging.getLogger("batch_api")
logger.info("Batch created: %s", batch_id)
logger.info("File uploaded: %s, %d requests", file_id, len(documents))
logger.info("Results: %d succeeded, %d failed", len(reussies), len(echouees))
Újrapróbálkozás exponenciális várakozással (Backoff)
Átmeneti hibák (időtúllépés, sebességkorlát, szerverhiba) esetén próbáld újra a műveletet növekvő várakozási idővel:
import time
def appel_avec_retry(fonction, max_essais=3):
for essai in range(max_essais):
try:
return fonction()
except Exception as e:
if essai == max_essais - 1:
raise
attente = 2 ** essai
print(f"Retrying in {attente} s: {e}")
time.sleep(attente)
Élesítés előtti ellenőrzőlista
Mielőtt egy Batch API folyamatot éles környezetbe telepítenél, ellenőrizd az alábbiakat:
- A modell támogatja a kötegelt feldolgozást, és szerepel a kedvezményes modellek listáján, ha a költség számít
- A kérésazonosítók egyediek és determinisztikusak
- A JSONL-fájlt feltöltés előtt validálod (egy érvénytelen sor is megszakítja a teljes köteget)
- A multimédiás eredmények letöltése automatizált, és egy órán belül megtörténik
- A részleges hibák észlelésre kerülnek, és egy új kötegben újra beküldik őket
- Az eredményeket az
expire_timeelőtt lekérdezed - A naplók a munkafolyamat minden lépését lefedik
- Az API-kulcsot környezeti változóból olvasod be, soha nem kódolod be keményen
Főbb megállapítások
- Korlátok: másodpercenként 2 létrehozás, 30 másodpercenként 1000 request-add hívás, kérésenként 25 MB
- JSONL-fájlok: maximum 50 000 kérés és 200 MB, fájlonként egy köteg
- A kép- és videó URL-ek egy óra alatt lejárnak: azonnal töltsd le őket
- Determinisztikus azonosítók, minden eredmény ellenőrzése, költségkövetés tick-ekben
- Naplózás, exponenciális várakozással történő újrapróbálkozás és maximális időtúllépés beállítása éles környezethez
Teszteld a tudásod!
Tömeges feldolgozás: a Batch API szürke zónák nélkül.
1. Mikor a Batch API a helyes választás?
Válasz: Nagy mennyiségű adat esetén, ahol nincs szükség valós idejű válaszra: osztályozás, dúsítás, értékelések, tömeges generálás. A kötegelt kérések nem számítanak bele a sebességkorlátokba, és a jogosult szöveges modellek 20% kedvezményt kapnak.
2. Mi a négy lépésből álló munkafolyamat?
Válasz: Hozz létre egy elnevezett köteget, adj hozzá kéréseket (az API-n keresztül, vagy egy feltöltött JSONL-fájlból létrehozva a köteget), kövesd nyomon a számlálóit, majd kérdezd le az eredményeket, ahogy azok beérkeznek, vagy a végén. A feldolgozás magától elindul, nincs külön indítási lépés.
3. Mit tehetsz egy kötegbe?
Válasz: Responses kéréseket (ajánlott) és Chat Completions kéréseket (elavult), szerveres eszközökkel és függvényhívásokkal, valamint kép- és videógenerálást és -szerkesztést, illetve videó-bővítést. Csak a jogosult modellek szöveges tokenjei után jár a kedvezmény.
4. Hogyan követed nyomon a végrehajtást?
Válasz: A köteg számlálóin keresztül (num_pending, num_success, num_error…), az egyes kérések állapotán (pending, succeeded, failed, cancelled), valamint a lapozott eredményeken, amelyek szétválasztják a sikereseket a sikertelenektől. A köteg akkor teljesen feldolgozott, ha a num_pending értéke nulla.
5. Milyen bevált gyakorlatok vonatkoznak a korlátokra?
Válasz: Add hozzá a kéréseket csomagokban, oszd fel a nagy fájlokat úgy, hogy fájlonként egy köteg legyen, töltsd le a médiát egy órán belül, kérdezd le az eredményeket az expire_time előtt, és a hibákat küldd be újra egy új kötegben: a köteget robust folyamatként tervezd meg, nem pedig vak tömeges beküldésként.
Jól felépített kötegek, nyomon követett számlálók, újrapróbált hibák: a Batch API a nagy mennyiséget rutinná teszi, a legjobb költséghatékonysággal.