Ograničenja stope i najbolje prakse
Na ovoj stranici
Ažurirano 2. studenoga 2026. Na temelju xAI dokumentacije: popust za skupne obrade iznosi 20 % na kvalificirane tekstualne modele, primjeri slijede REST API i službeni
xai-sdk(client.batch.*; xAI-jev Batch API ne koristi OpenAI format, pa se OpenAI SDK ne primjenjuje), a Responses API ima prednost nad Chat Completions, koji je zastarjela krajnja točka kod xAI-ja. Izvori: Batch API · REST referenca · Cijene za skupne obrade.
Ograničenja koja moraš znati
Batch API nameće tehnička ograničenja koja moraš uzeti u obzir pri projektiranju svoje arhitekture. Njihovo ignoriranje dovodi do odbijanja zahtjeva, otkazivanja skupnih obrada ili gubitka rezultata. Ova lekcija sažima ograničenja koja je dokumentirao xAI te najbolje prakse za produkcijsku upotrebu.
Ograničenja stope (Rate limits)
| Ograničenje | Vrijednost | Opseg |
|---|---|---|
| Stvaranje skupne obrade | 2 u sekundi | Po timu |
| Broj skupnih obrada | Neograničeno | Po timu |
| Pozivi za dodavanje zahtjeva | 1.000 svakih 30 sekundi | Klizni prozor, dijeli se između svih skupnih obrada tima |
| Veličina zahtjeva | 25 MB | Po pojedinačnom zahtjevu |
| Zahtjeva po skupnoj obradi | Teoretski neograničeno | Iznad 100.000 obrada može biti sporija |
Stvaranje skupne obrade: ograničenje od 2 stvaranja u sekundi rijetko predstavlja problem jer obično stvaraš jednu skupnu obradu po operaciji.
Dodavanje zahtjeva: ograničenje se odnosi na pozive, a svaki poziv nosi popis zahtjeva. S blokovima od 100 zahtjeva, to već omogućuje više od 3.000 zahtjeva u sekundi.
Veličina zahtjeva: ograničenje od 25 MB uglavnom utječe na zahtjeve opterećene slikama kodiranim u base64; tekstualni zahtjev rijetko prelazi nekoliko kilobajta.
S druge strane, zahtjevi za skupnu obradu ne ulaze u ograničenja stope real-time API-ja: velika skupna obrada ne usporava tvoju interaktivnu aplikaciju.
Ograničenja JSONL datoteka
| Ograničenje | Vrijednost |
|---|---|
| Zahtjeva po datoteci | Najviše 50.000 |
| Veličina datoteke | Najviše 200 MB |
| Dodavanja nakon stvaranja | Nije moguće: skupna obrada je zapečaćena |
Ako tvoja skupna obrada premašuje ova ograničenja, podijeli je na više datoteka i stvori jednu skupnu obradu po datoteci; rezultate ćeš naknadno agregirati.
Istek URL-ova
Potpisani URL-ovi za rezultate slika i videa istječu nakon jednog sata. To je najkritičnije ograničenje koje moraš riješiti u produkciji: tvoj proces preuzimanja mora odmah preuzeti medije, bez ručne intervencije (funkcija telecharger_medias iz lekcije 9). Za skupnu obradu također prati expire_time, nakon kojeg rezultati više nisu dostupni.
Najbolje prakse za produkciju
Deterministički ID-jevi
Izvedi ID-jeve svojih zahtjeva (batch_request_id ili custom_id u JSONL-u) iz ulaznih podataka. Ako moraš ponovno poslati skupnu obradu, isti podaci generirat će iste ID-jeve, što olakšava deduplikaciju:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Generira deterministički ID zahtjeva."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Rukovanje djelomičnim neuspjesima
Potpuno obrađena skupna obrada ipak može sadržavati neuspjele zahtjeve. Uvijek provjeri svaki 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)} neuspjelih zahtjeva za ponovno slanje u novoj skupnoj obradi")
Praćenje troškova
Svaka skupna obrada prati ukupni trošak u tickovima (deset-milijarditih dijelova dolara):
batch = client.batch.get(batch_id=batch_id)
print("Ukupni trošak: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Kroz REST API, trošak svakog tekstualnog zahtjeva pojavljuje se u njegovom rezultatu, u polju usage.cost_in_usd_ticks.
Zapisivanje i sljedivost
Bilježi svaku operaciju kako bi mogao dijagnosticirati probleme:
import logging
logger = logging.getLogger("batch_api")
logger.info("Skupna obrada stvorena: %s", batch_id)
logger.info("Datoteka učitana: %s, %d zahtjeva", file_id, len(documents))
logger.info("Rezultati: %d uspjelih, %d neuspjelih", len(reussies), len(echouees))
Ponovni pokušaji s eksponencijalnim kašnjenjem (Backoff)
Za prolazne pogreške (istek vremena, ograničenje stope, pogreška poslužitelja) ponovi pokušaj s povećanim kašnjenjem:
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"Ponovni pokušaj za {attente} s: {e}")
time.sleep(attente)
Kontrolni popis prije produkcije
Prije raspoređivanja cjevovoda Batch API-ja u produkciju, provjeri:
- Model prihvaća skupnu obradu i pojavljuje se na popisu modela s popustom ako su troškovi bitni
- ID-jevi zahtjeva su jedinstveni i deterministički
- JSONL datoteka je validirana prije učitavanja (jedan neispravan redak otkazuje cijelu skupnu obradu)
- Preuzimanje multimodalnih rezultata je automatizirano i odvija se unutar jednog sata
- Djelomični neuspjesi su otkriveni i ponovno poslani u novoj skupnoj obradi
- Rezultati su preuzeti prije
expire_time - Zapisi pokrivaju svaki korak radnog tijeka
- API ključ se čita iz varijable okruženja, nikada nije hardkodiran
Ključne točke
- Ograničenja: 2 stvaranja u sekundi, 1.000 poziva za dodavanje zahtjeva svakih 30 sekundi, 25 MB po zahtjevu
- JSONL datoteke: najviše 50.000 zahtjeva i 200 MB, jedna skupna obrada po datoteci
- URL-ovi slika i videa istječu za jedan sat: odmah ih preuzmi
- Deterministički ID-jevi, provjera svakog rezultata, praćenje troškova u tickovima
- Zapisi, ponovni pokušaji s kašnjenjem i maksimalno vrijeme čekanja za produkciju
Provjeri svoje znanje
Masovna obrada: Batch API bez nedoumica.
1. Kada je Batch API pravi izbor?
Odgovor: Za velike količine podataka bez potrebe za obradom u stvarnom vremenu: klasifikacija, obogaćivanje, evaluacije, masovno generiranje. Zahtjevi za skupnu obradu ne ulaze u ograničenja stope, a kvalificirani tekstualni modeli imaju popust od 20 %.
2. Koji je četverostupanjski radni tijek?
Odgovor: Stvori imenovanu skupnu obradu, dodaj joj zahtjeve (kroz API ili stvaranjem skupne obrade iz učitane JSONL datoteke), prati njezine brojače, a zatim preuzmi rezultate, kako pristižu ili na kraju. Obrada započinje sama od sebe, bez koraka pokretanja.
3. Što možeš staviti u skupnu obradu?
Odgovor: Requests za Responses API (preporučeno) i Chat Completions (zastarjelo), sa serverskim alatima i pozivanjem funkcija, kao i generiranje i uređivanje slika i videa te proširenja videa. Popust vrijedi samo za tekstualne tokene na kvalificiranim modelima.
4. Kako pratiš izvršavanje?
Odgovor: Kroz brojače skupne obrade (num_pending, num_success, num_error…), status svakog zahtjeva (pending, succeeded, failed, cancelled) i paginirane rezultate koji odvajaju uspjehe od neuspjeha. Skupna obrada je u potpunosti obrađena kada je num_pending jednak nuli.
5. Koje se najbolje prakse primjenjuju na ograničenja?
Odgovor: Dodaj zahtjeve u blokovima, podijeli velike datoteke na jednu skupnu obradu po datoteci, preuzmi medije unutar jednog sata, preuzmi rezultate prije expire_time i ponovno pošalji neuspjehe u novoj skupnoj obradi: dizajniraj skupnu obradu kao robustan cjevovod, a ne kao slijepo masovno slanje.
Ispravno formirane skupne obrade, praćeni brojači, ponovljeni neuspjesi: Batch API pretvara volumen u rutinu, uz najbolji trošak.