Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Limity rychlosti a osvědčené postupy

Lekce 12 z 12 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Omezení, která musíš znát
  2. Limity rychlosti
  3. Limity souborů JSONL
  4. Expirace URL
  5. Osvědčené postupy pro produkci
  6. Kontrolní seznam před nasazením
  7. Klíčové poznatky
  8. Ověř si své znalosti

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íHodnotaRozsah
Vytvoření dávky2 za sekunduNa tým
Počet dávekNeomezeněNa tým
Volání přidání požadavků1 000 za 30 sekundPosuvné okno, sdíleno napříč všemi dávkami týmu
Velikost požadavku25 MBNa jednotlivý požadavek
Požadavků na dávkuTeoreticky 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 souborMaximálně 50 000
Velikost souboruMaximá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.