Limity rýchlosti a osvedčené postupy
Na tejto strane
Aktualizované 2. novembra 2026. Na základe dokumentácie xAI: zľava pre batchové spracovanie je 20 % na spôsobilé textové modely, príklady nasledujú REST API a oficiálny
xai-sdk(client.batch.*; Batch API od xAI nepoužíva formát OpenAI, takže SDK od OpenAI nie je použiteľné) a API Responses má prednosť pred Chat Completions, čo je zastaraný koncový bod v xAI. Zdroje: Batch API · Referencia REST · Cenník batchov.
Obmedzenia, ktoré musíš poznať
Batch API ukladá technické limity, ktoré musíš zohľadniť vo svojej architektúre. Ich ignorovanie vedie k odmietnutiam, zrušeným batchom alebo stratenej výstupnej hodnote. Táto lekcia zhrňuje obmedzenia zdokumentované spoločnosťou xAI a osvedčené postupy pre nasadenie do produkcie.
Limity rýchlosti (Rate limits)
| Obmedzenie | Hodnota | Rozsah |
|---|---|---|
| Vytvorenie batchu | 2 za sekundu | Na tím |
| Počet batchov | Neobmedzený | Na tím |
| Volania pridania požiadaviek | 1 000 za 30 sekúnd | Posuvné okno, zdieľané medzi všetkými batchmi tímu |
| Veľkosť požiadavky | 25 MB | Na jednotlivú požiadavku |
| Požiadaviek na batch | Teoreticky neobmedzené | Nad 100 000 môže byť spracovanie pomalšie |
Vytvorenie batchu: limit 2 vytvorení za sekundu je zriedka problémom, keďže zvyčajne vytváraš jeden batch na operáciu.
Pridávanie požiadaviek: limit sa vzťahuje na volania a každé volanie nesie zoznam požiadaviek. Pri chunkoch po 100 požiadavkách to už umožňuje viac ako 3 000 požiadaviek za sekundu.
Veľkosť požiadavky: limit 25 MB ovplyvňuje najmä požiadavky načítané s obrázkami kódovanými v base64; textová požiadavka zriedka presiahne niekoľko kilobajtov.
Naopak, batchové požiadavky sa nepočítajú do limitov rýchlosti real-time API: veľký batch nezspomalí tvoju interaktívnu aplikáciu.
Limity súborov JSONL
| Obmedzenie | Hodnota |
|---|---|
| Požiadaviek na súbor | Maximálne 50 000 |
| Veľkosť súboru | Maximálne 200 MB |
| Pridania po vytvorení | Nie je možné: batch je uzavretý |
Ak tvoj batch presiahne tieto limity, rozdeľ ho na niekoľko súborov a vytvor jeden batch na súbor; výsledky následne agreguješ.
Expirácia URL adries
Podpísané URL adresy pre výsledky obrázkov a videí expirujú po jednej hodine. Toto je najkritickejšie obmedzenie, ktoré musíš v produkcii ošetriť: tvoj proces získavania musí stiahnuť médiá okamžite, bez manuálneho zásahu (funkcia telecharger_medias z lekcie 9). Pre batch tiež monitoruj expire_time, po ktorom už nie sú dostupné žiadne výsledky.
Osvedčené postupy pre produkciu
Deterministické ID
Odvodzuj ID svojich požiadaviek (batch_request_id alebo custom_id v JSONL) zo vstupných dát. Ak potrebuješ batch odoslať znova, rovnaké dáta vygenerujú rovnaké ID, čo uľahčuje deduplikáciu:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Generuje deterministické ID požiadavky."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Spracovanie čiastočných zlyhaní
Úplne spracovaný batch môže stále obsahovať zlyhané požiadavky. Vždy skontroluj každý výsledok:
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)} zlyhaných požiadaviek na opätovné odoslanie v novom batchi")
Sledovanie nákladov
Každý batch si vedie záznam o celkových nákladoch v tickoch (desaťmiliardtinách dolára):
batch = client.batch.get(batch_id=batch_id)
print("Celkové náklady: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Prostredníctvom REST API sa náklady na každú textovú požiadavku zobrazujú v jej výsledku v poli usage.cost_in_usd_ticks.
Logy a sledovateľnosť
Loguj každú operáciu, aby si mohol diagnostikovať problémy:
import logging
logger = logging.getLogger("batch_api")
logger.info("Batch vytvorený: %s", batch_id)
logger.info("Súbor nahraný: %s, %d požiadaviek", file_id, len(documents))
logger.info("Výsledky: %d úspešných, %d zlyhaných", len(reussies), len(echouees))
Opakovanie s exponenciálnym oneskorením (Backoff)
Pre prechodné chyby (časový limit, limit rýchlosti, chyba servera) opakuj pokus so zvyšujúcim sa oneskorením:
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"Opakovanie za {attente} s: {e}")
time.sleep(attente)
Kontrolný zoznam pred nasadením do produkcie
Pred nasadením pipeline Batch API do produkcie skontroluj:
- Model akceptuje batchové spracovanie a objavuje sa v zozname modelov so zľavou, ak záleží na nákladoch
- ID požiadaviek sú jedinečné a deterministické
- Súbor JSONL je pred nahraním validovaný (jeden neplatný riadok zruší celý batch)
- Sťahovanie multimediálnych výsledkov je automatizované a prebehne do jednej hodiny
- Čiastočné zlyhania sú detegované a opätovne odoslané v novom batchi
- Výsledky sú získané pred
expire_time - Logy pokrývajú každý krok workflow
- API kľúč sa číta z premennej prostredia, nikdy nie je hardcoded
Kľúčové poznatky
- Limity: 2 vytvorenia za sekundu, 1 000 volaní na pridanie požiadaviek za 30 sekúnd, 25 MB na požiadavku
- Súbory JSONL: maximálne 50 000 požiadaviek a 200 MB, jeden batch na súbor
- URL adresy obrázkov a videí expirujú za jednu hodinu: stiahni ich okamžite
- Deterministické ID, kontrola každého výsledku, sledovanie nákladov v tickoch
- Logy, opakovanie s backoffom a maximálny časový limit pre produkciu
Otestuj si svoje vedomosti
Hromadné spracovanie: Batch API bez nejasností.
1. Kedy je Batch API tou správnou voľbou?
Odpoveď: Pre veľké objemy bez požiadavky na real-time odozvu: klasifikácia, obohacovanie, evaluácie, hromadná generácia. Batchové požiadavky sa nepočítajú do limitov rýchlosti a spôsobilé textové modely získavajú 20 % zľavu.
2. Aký je štvorkrokový workflow?
Odpoveď: Vytvor pomenovaný batch, pridaj doň požiadavky (cez API alebo vytvorením batchu z nahraného súboru JSONL), sleduj jeho počítadlá a následne získaj výsledky, buď priebežne, alebo na konci. Spracovanie sa spustí samo, bez kroku na spustenie.
3. Čo môžeš vložiť do batchu?
Odpoveď: Požiadavky Responses (odporúčané) a Chat Completions (zastarané), so serverovými nástrojmi a volaním funkcií, ako aj generovanie a úpravy obrázkov a videí a rozšírenia videí. Zľavu získavajú iba textové tokeny pre spôsobilé modely.
4. Ako sleduješ vykonávanie?
Odpoveď: Prostredníctvom počítadiel batchu (num_pending, num_success, num_error…), stavu každej požiadavky (pending, succeeded, failed, cancelled) a stránkovaných výsledkov, ktoré oddeľujú úspechy od zlyhaní. Batch je úplne spracovaný, keď je num_pending rovné nule.
5. Aké osvedčené postupy platia pre limity?
Odpoveď: Pridávaj požiadavky v chunkoch, rozdeľ veľké súbory na jeden batch na súbor, stiahni médiá do jednej hodiny, získaj výsledky pred expire_time a zlyhania opätovne odosielaj v novom batchi: navrhni batch ako robustný pipeline, nie ako slepé hromadné odoslanie.
Dobre vytvorené batche, sledované počítadlá, opakované zlyhania: Batch API mení objem na rutinu za najlepšiu cenu.