Limity rychlosti a osvědčené postupy
Na této stránce
Aktualizováno 2. listopadu 2026. Na základě dokumentace xAI: sleva pro dávkové zpracování činí 20 % u způsobilých textových modelů, příklady následují rozhraní REST API a oficiální
xai-sdk(client.batch.*; Batch API od xAI nepoužívá formát OpenAI, takže SDK OpenAI není použitelné) a API Responses má přednost před Chat Completions, což je u xAI zastaralý koncový bod. Zdroje: Batch API · Reference REST · Ceník Batch API.
Omezení, která musíš znát
Batch API ukládá technická omezení, která musíš ve své architektuře zohlednit. Jejich ignorování vede k odmítnutím, zrušení dávek nebo ztrátě výsledků. Tato lekce shrnuje omezení zdokumentovaná společností xAI a osvědčené postupy pro nasazení v produkci.
Limity rychlosti
| Omezení | Hodnota | Rozsah |
|---|---|---|
| Vytvoření dávky | 2 za sekundu | Na tým |
| Počet dávek | Neomezeně | Na tým |
| Volání přidání požadavků | 1 000 za 30 sekund | Posuvné okno, sdíleno napříč všemi dávkami týmu |
| Velikost požadavku | 25 MB | Na jednotlivý požadavek |
| Požadavků na dávku | Teoreticky neomezeně | Nad 100 000 může být zpracování pomalejší |
Vytvoření dávky: limit 2 vytvoření za sekundu je zřídka problémem, protože obvykle vytváříš jednu dávku na operaci.
Přidávání požadavků: limit se vztahuje na volání a každé volání nese seznam požadavků. Při blocích po 100 požadavcích to již umožňuje více než 3 000 požadavků za sekundu.
Velikost požadavku: limit 25 MB se týká především požadavků zatížených obrázky kódovanými v base64; textový požadavek zřídka přesáhne několik kilobajtů.
Naopak požadavky v dávce se nezapočítávají do limitů rychlosti API pro reálný čas: velká dávka nezpomaluje tvou interaktivní aplikaci.
Limity souborů JSONL
| Omezení | Hodnota |
|---|---|
| Požadavků na soubor | Maximálně 50 000 |
| Velikost souboru | Maximálně 200 MB |
| Přidání po vytvoření | Není možné: dávka je uzavřena |
Pokud tvoje dávka překročí tyto limity, rozděl ji na několik souborů a vytvoř jednu dávku na soubor; výsledky následně agreguješ.
Expirace URL
Podepsané URL adresy pro výsledky obrázků a videí expirují po jedné hodině. Toto je nejkritičtější omezení, které musíš v produkci řešit: tvůj proces stahování musí média stáhnout okamžitě, bez manuálního zásahu (funkce telecharger_medias z lekce 9). U dávky také sleduj expire_time, po jehož uplynutí nejsou žádné výsledky přístupné.
Osvědčené postupy pro produkci
Deterministická ID
Odvoď ID svých požadavků (batch_request_id nebo custom_id v JSONL) ze vstupních dat. Pokud potřebuješ dávku znovu odeslat, stejná data vygenerují stejná ID, což usnadňuje deduplikaci:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Generuje deterministické ID požadavku."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Zpracování částečných selhání
I plně zpracovaná dávka může obsahovat neúspěšné požadavky. Vždy zkontroluj každý výsledek:
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)} neúspěšných požadavků k opětovnému odeslání v nové dávce")
Sledování nákladů
Každá dávka eviduje své celkové náklady v ticks (desetimiliardtinách dolaru):
batch = client.batch.get(batch_id=batch_id)
print("Celkové náklady: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Prostřednictvím REST API se náklady na každý textový požadavek objevují v jeho výsledku v poli usage.cost_in_usd_ticks.
Logy a sledovatelnost
Loguj každou operaci, abys mohl diagnostikovat problémy:
import logging
logger = logging.getLogger("batch_api")
logger.info("Dávka vytvořena: %s", batch_id)
logger.info("Soubor nahrán: %s, %d požadavků", file_id, len(documents))
logger.info("Výsledky: %d úspěšných, %d neúspěšných", len(reussies), len(echouees))
Opakování s exponenciálním čekáním
U přechodných chyb (časový limit, limit rychlosti, chyba serveru) opakuj akci s rostoucím zpoždění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"Opakování za {attente} s: {e}")
time.sleep(attente)
Kontrolní seznam před nasazením
Před nasazením pipeline Batch API do produkce zkontroluj:
- Model podporuje dávkové zpracování a pokud záleží na nákladech, objevuje se v seznamu modelů se slevou
- ID požadavků jsou jedinečná a deterministická
- Soubor JSONL je před nahráním validován (jeden neplatný řádek zruší celou dávku)
- Stahování multimediálních výsledků je automatizováno a proběhne do jedné hodiny
- Částečná selhání jsou detekována a znovu odeslána v nové dávce
- Výsledky jsou staženy před
expire_time - Logy pokrývají každý krok pracovního postupu
- Klíč API je čten z proměnné prostředí, nikdy není natvrdo zakódován
Klíčové poznatky
- Limity: 2 vytvoření za sekundu, 1 000 volání přidání požadavků za 30 sekund, 25 MB na požadavek
- Soubory JSONL: maximálně 50 000 požadavků a 200 MB, jedna dávka na soubor
- URL obrázků a videí expirují za jednu hodinu: stahuj okamžitě
- Deterministická ID, kontrola každého výsledku, sledování nákladů v ticks
- Logy, opakování s exponenciálním čekáním a maximální časový limit pro produkci
Ověř si své znalosti
Hromadné zpracování: Batch API bez jakýchkoli nejasností.
1. Kdy je Batch API tou správnou volbou?
Odpověď: Pro velké objemy bez požadavků na reálný čas: klasifikace, obohacování, evaluace, hromadná generace. Požadavky v dávce se nezapočítávají do limitů rychlosti a způsobilé textové modely získávají 20% slevu.
2. Jaký je čtyřkrokový pracovní postup?
Odpověď: Vytvoř pojmenovanou dávku, přidej do ní požadavky (prostřednictvím API nebo vytvořením dávky z nahraného souboru JSONL), sleduj její čítače a poté stáhni výsledky, jak přicházejí, nebo na konci. Zpracování začíná samo, není nutný žádný spouštěcí krok.
3. Co můžeš vložit do dávky?
Odpověď: Požadavky Responses (doporučeno) a Chat Completions (zastaralé), včetně serverových nástrojů a volání funkcí, stejně jako generování a úpravy obrázků a videí a rozšíření videí. Slevu získávají pouze textové tokeny u způsobilých modelů.
4. Jak sleduješ provádění?
Odpověď: Prostřednictvím čítačů dávky (num_pending, num_success, num_error…), stavu každého požadavku (pending, succeeded, failed, cancelled) a stránkovaných výsledků, které oddělují úspěchy od selhání. Dávka je plně zpracována, když je num_pending rovno nule.
5. Jaké osvědčené postupy platí pro limity?
Odpověď: Přidávej požadavky v blocích, rozděl velké soubory na jednu dávku na soubor, stahuj média do jedné hodiny, stahuj výsledky před expire_time a neúspěšné požadavky znovu odešli v nové dávce: navrhni dávku jako robustní pipeline, nikoliv jako slepé hromadné odeslání.
Správně vytvořené dávky, sledované čítače, opakovaná selhání: Batch API mění objem v rutinu za nejlepší cenu.