Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Omejitve hitrosti in najboljši postopki

Lekcija 12 od 12 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Omejitve, ki jih moraš poznati
  2. Omejitve hitrosti
  3. Omejitve datotek JSONL
  4. Potek veljavnosti URL-jev
  5. Najboljši postopki za proizvodnjo
  6. Kontrolni seznam pred proizvodnjo
  7. Ključne ugotovitve
  8. Preveri svoje znanje

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

OmejitevVrednostObseg
Ustvarjanje paketov2 na sekundoNa ekipo
Število paketovNeomejenoNa ekipo
Klici za dodajanje zahtevkov1.000 na 30 sekundDrseče okno, skupno za vse pakete ekipe
Velikost zahtevka25 MBNa posamezen zahtevek
Zahtevki na paketTeoretično neomejenoNad 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

OmejitevVrednost
Zahtevki na datotekoNajveč 50.000
Velikost datotekeNajveč 200 MB
Dodajanje po ustvarjanjuNi 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.