Omejitve hitrosti in najboljši postopki
Na tej strani
Posodobljeno 2. novembra 2026. Na podlagi dokumentacije xAI: popust za paketno obdelavo znaša 20 % za ustrezne besedilne modele, primeri sledijo REST API-ju in uradnemu paketu
xai-sdk(client.batch.*; paketni API xAI ne uporablja formata OpenAI, zato paket SDK OpenAI ni primeren), API Responses pa ima prednost pred Chat Completions, ki je zastarela končna točka pri xAI. Viri: Batch API · Referenca REST · Cene paketne obdelave.
Omejitve, ki jih moraš poznati
Paketni API nalaga tehnične omejitve, ki jih moraš upoštevati v svoji arhitekturi. Če jih ignoriraš, pride do zavrnitev, preklicev paketov ali izgube rezultatov. Ta lekcija povzema omejitve, ki jih dokumentira xAI, in najboljše postopke za proizvodno uporabo.
Omejitve hitrosti
| Omejitev | Vrednost | Obseg |
|---|---|---|
| Ustvarjanje paketov | 2 na sekundo | Na ekipo |
| Število paketov | Neomejeno | Na ekipo |
| Klici za dodajanje zahtevkov | 1.000 na 30 sekund | Drseče okno, skupno za vse pakete ekipe |
| Velikost zahtevka | 25 MB | Na posamezen zahtevek |
| Zahtevki na paket | Teoretično neomejeno | Nad 100.000 je obdelava lahko počasnejša |
Ustvarjanje paketov: omejitev 2 ustvarjanj na sekundo redko predstavlja težavo, saj običajno ustvariš en paket na operacijo.
Dodajanje zahtevkov: omejitev velja za klice, pri čemer vsak klic prenese seznam zahtevkov. S paketi po 100 zahtevkov to že omogoča več kot 3.000 zahtevkov na sekundo.
Velikost zahtevka: omejitev 25 MB vpliva predvsem na zahtevke, naložene s slikami, kodiranimi v base64; besedilni zahtevek redko preseže nekaj kilobajtov.
Nasprotno pa paketni zahtevki se ne štejejo v omejitve hitrosti API-ja v realnem času: velik paket ne upočasni tvoje interaktivne aplikacije.
Omejitve datotek JSONL
| Omejitev | Vrednost |
|---|---|
| Zahtevki na datoteko | Največ 50.000 |
| Velikost datoteke | Največ 200 MB |
| Dodajanje po ustvarjanju | Ni mogoče: paket je zaprt |
Če tvoj paket preseže te omejitve, ga razdeli na več datotek in ustvari en paket na datoteko; rezultate nato združiš.
Potek veljavnosti URL-jev
Podpisani URL-ji za rezultate slik in videoposnetkov potečejo po eni uri. To je najbolj kritična omejitev, ki jo je treba obravnavati v proizvodnji: tvoj postopek pridobivanja mora medije prenesti takoj, brez ročnega posredovanja (funkcija telecharger_medias iz lekcije 9). Za paket spremljaj tudi expire_time, po katerem rezultati niso več dostopni.
Najboljši postopki za proizvodnjo
Deterministični ID-ji
Svoje ID-je zahtevkov (batch_request_id ali custom_id v JSONL) izpelji iz vhodnih podatkov. Če moraš paket ponovno predložiti, bodo isti podatki ustvarili iste ID-je, kar olajša deduplikacijo:
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]
Obravnava delnih napak
Tudi popolnoma obdelan paket lahko vsebuje neuspele zahtevke. Vedno preveri vsak rezultat:
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")
Sledenje stroškom
Vsak paket vodi evidenco svojih skupnih stroškov v tikih (desetmilijardinkah dolarja):
batch = client.batch.get(batch_id=batch_id)
print("Total cost: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Prek REST API-ja se strošek vsakega besedilnega zahtevka prikaže v njegovem rezultatu v polju usage.cost_in_usd_ticks.
Dnevniki in sledljivost
Zabeleži vsako operacijo, da lahko diagnosticiraš težave:
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))
Ponovni poskus z eksponentnim zamikom
Za prehodne napake (časovna omejitev, omejitev hitrosti, napaka strežnika) poskusi znova z naraščajočim zamikom:
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)
Kontrolni seznam pred proizvodnjo
Preden pipeline paketnega API-ja uvedeš v proizvodnjo, preveri:
- Model sprejema paketno obdelavo in je na seznamu modelov s popustom, če so stroški pomembni
- ID-ji zahtevkov so edinstveni in deterministični
- Datoteka JSONL je pred nalaganjem validirana (ena neveljavna vrstica prekliče celoten paket)
- Prenos multimedijskih rezultatov je avtomatiziran in opravljen v eni uri
- Delne napake so zaznane in ponovno predložene v novem paketu
- Rezultati so pridobljeni pred
expire_time - Dnevniki pokrivajo vsak korak delovnega toka
- Ključ API-ja je prebran iz spremenljivke okolja, nikoli trdo kodiran
Ključne ugotovitve
- Omejitve: 2 ustvarjanja na sekundo, 1.000 klicev za dodajanje zahtevkov na 30 sekund, 25 MB na zahtevek
- Datoteke JSONL: največ 50.000 zahtevkov in 200 MB, en paket na datoteko
- URL-ji slik in videoposnetkov potečejo v eni uri: takojšnji prenos
- Deterministični ID-ji, preverjanje vsakega rezultata, sledenje stroškom v tikih
- Dnevniki, ponovni poskus z eksponentnim zamikom in največji časovni okvir za proizvodnjo
Preveri svoje znanje
Paketna obdelava: paketni API brez sivih con.
1. Kdaj je paketni API prava izbira?
Odgovor: Za velike količine brez omejitev realnega časa: razvrščanje, obogatitev, evalvacije, množično generiranje. Paketni zahtevki se ne štejejo v omejitve hitrosti, ustrezni besedilni modeli pa prejmejo 20-odstotni popust.
2. Kakšen je štiristopenjski delovni tok?
Odgovor: Ustvari imenovani paket, mu dodaj zahtevke (prek API-ja ali z ustvarjanjem paketa iz naložene datoteke JSONL), spremljaj njegove števce in nato pridobi rezultate, ko prispejo ali na koncu. Obdelava se začne samodejno, brez koraka zagona.
3. Kaj lahko vključiš v paket?
Odgovor: Zahtevke Responses (priporočeno) in Chat Completions (zastarelo), s strežniškimi orodji in klicanjem funkcij, pa tudi generiranje in urejanje slik ter videoposnetkov in razširitve videoposnetkov. Popust velja le za besedilne žetone ustreznih modelov.
4. Kako spremljaš izvajanje?
Odgovor: Prek števcov paketa (num_pending, num_success, num_error …), stanja vsakega zahtevka (pending, succeeded, failed, cancelled) in rezultate s paginacijo, ki ločujejo uspešne od neuspešnih. Paket je v celoti obdelan, ko je num_pending enak nič.
5. Kateri najboljši postopki veljajo za omejitve?
Odgovor: Dodajaj zahtevke v paketih, velike datoteke razdeli na en paket na datoteko, medije prenesi v eni uri, rezultate pridobi pred expire_time in neuspele zahtevke ponovno predloži v novem paketu: paket zasnuj kot robusten pipeline, ne kot slepo množično predložitev.
Pravilno oblikovani paketi, sledeni števci, ponovljeni neuspehi: paketni API spremeni obseg v rutino, po najboljši ceni.