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

Korlátok és bevált gyakorlatok

12. lecke 12 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. Ismerned kellő korlátok
  2. Sebességkorlátok (Rate limits)
  3. JSONL-fájl korlátok
  4. URL-lejárat
  5. Bevált gyakorlatok éles környezetben
  6. Élesítés előtti ellenőrzőlista
  7. Főbb megállapítások
  8. Teszteld a tudásod!

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ékHatókör
Köteg létrehozása2 másodpercenkéntCsapatonként
Kötegek számaKorlátlanCsapatonként
Request-add hívások1000 db 30 másodpercenkéntCsúszó ablak, a csapat összes kötegére közösen vonatkozik
Kérés mérete25 MBEgyedi kérésenként
Kérések kötegenkéntElméletileg korlátlan100 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éntMaximum 50 000
FájlméretMaximum 200 MB
Hozzáadás létrehozás utánNem 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_time elő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.