Zaglavlja API-ja i upravljanje preopterećenjem
Na ovoj stranici
Odluči koji zahtjevi troše tvoj kapacitet
Rezerviranje kapaciteta rješava samo pola problema: i dalje moraš odabrati koji će zahtjevi od toga stvarno imati koristi. Dodijeljena propusnost (provisioned throughput) nije jednokratna kupnja na početku mjeseca; to je mehanizam kojim upravljaš poziv po poziv. xAI izlaže namjenska HTTP zaglavlja za tu svrhu koja arbitriraju, zahtjev po zahtjev, između tvog namjenskog kapaciteta i zajedničkog bazena. Fiksna alokacija tako postaje operativna poluga kojom tvoji timovi izravno manipuliraju iz koda aplikacije.
Dobrovoljno zaobiđi namjenski kapacitet
Prvo zaglavlje služi za isključivanje zahtjeva iz tvoje alokacije:
curl https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "x-pt-disable: true" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.3",
"messages": [{"role": "user", "content": "Summarize this document."}]
}'
Odricanje od vlastitog kapaciteta može djelovati kontraintuitivno. Četiri situacije to opravdavaju u svakodnevnom radu. Prvo, nekritični zadaci: skupna analiza pokrenuta u 22 sata ili odgođeni posao obrade ne trebaju jamstvo kašnjenja, i bila bi šteta da troše alokaciju plaćenu za interaktivni promet. Drugo, očuvanje kapaciteta tijekom vrhunaca: onemogućavanjem dodijeljene propusnosti na sekundarnoj obradi, oslobađaš alokaciju točno kada prioritetni zahtjevi pristižu u velikom obujmu. Zaglavlje također služi za A/B testiranje, kada želiš izmjeriti stvarni jaz u performansama između namjenskog i zajedničkog kapaciteta na vlastitom opterećenju, a ne na obećanju pružatelja usluge. Konačno, vrijedno je za otklanjanje grešaka: prisiljavanje zahtjeva kroz zajednički bazen odmah ti govori proizlazi li uočena anomalija iz dodijeljenog kapaciteta ili tvog koda.
Usmjeri zahtjev na određeni bazen
Drugo zaglavlje usmjerava poziv na identificirani bazen kapaciteta:
curl https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "x-pt-id: pool-support-client" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.3",
"messages": [{"role": "user", "content": "How can I help you?"}]
}'
Ovo zaglavlje postaje neophodno čim više aplikacija unutar tvoje organizacije poziva Grok. Tada stvaraš odvojene bazene – pool-support za chatbota korisničke podrške, pool-analysis za analizu dokumenata, pool-internal za poslovne alate – i svaki radi neovisno. Segmentacija izolira performanse: kampanja analize dokumenata pokrenuta ponedjeljkom ujutro više ne degradira vremena odgovora podrške. Ona također proizvodi potrošnju raščlanjenu po uporabi, dakle činjeničnu osnovu za interni obračun troškova ili arbitražu, gdje si se ranije oslanjao na nagađanja. I inherentno sprječava da jedna aplikacija monopolizira kapacitet na štetu drugih.
Što se događa u slučaju preopterećenja
Kada promet premaši dodijeljeni kapacitet, povratna opcija (fallback) je automatska i tiha: zahtjev odlazi u zajednički bazen po modelu „plati koliko trošiš“ (pay-as-you-go), primjenjuju se standardne cijene modela i podliježe uobičajenim ograničenjima stope. Nema povratne greške; tvoja aplikacija ne vidi da se išta dogodilo.
Ova diskrecija ima dvije strane. S aspekta dostupnosti, vijest je dobra: nikada nećeš naići na grešku 429 uzrokovanu premašenjem dodijeljenog kapaciteta. S aspekta financija i kvalitete usluge, situacija je manje dobra. Zahtjev se naplaćuje po stopi „plati koliko trošiš“, koja je potencijalno viša; vremena odgovora mogu varirati jer se obrada odvija na zajedničkoj infrastrukturi; i što je najvažnije, SLA od 99,9% pokriva samo zahtjeve obrađene unutar dodijeljene propusnosti. Preopterećenje dakle ništa ne kvari, jednostavno te tiho izvlači iz okvira za koji plaćaš. Upravljački API izlaže udio zahtjeva obrađenih u načinu dodijeljene propusnosti naspram onih po modelu „plati koliko trošiš“: ispituj taj omjer svakog mjeseca baš kao i račun. Rastuća stopa preopterećenja signal je da trebaš povećati alokaciju.
Pretvori prioritet u kod aplikacije
Umjesto umnožavanja funkcija za pozive, najčvršća praksa sastoji se u kvalificiranju prioriteta u trenutku izdavanja zahtjeva:
import httpx
def query_grok(prompt: str, priority: str = "normal"):
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
if priority == "low":
headers["x-pt-disable"] = "true"
elif priority == "high":
headers["x-pt-id"] = "pool-critical"
response = httpx.post(
"https://api.x.ai/v1/chat/completions",
headers=headers,
json={
"model": "grok-4.3",
"messages": [{"role": "user", "content": prompt}],
},
)
return response.json()
Parametar priority postaje jedina odluka izložena poslovnoj logici, a politika usmjeravanja ostaje koncentrirana u jednoj funkciji koju evoluiraš bez diranja ostatka koda. Pregledaj svoj vlastiti kod za pozive i svrstaj svaku ulaznu točku u jednu od tri kategorije: vježba redovito pokazuje da solidna polovica prometa nije trebala namjenski kapacitet.
Ključne točke
- Zaglavlje
x-pt-disable: truezaobilazi dodijeljeni kapacitet za zahtjev - Zaglavlje
x-pt-idusmjerava na određeni bazen kapaciteta - Preopterećenja automatski prelaze na model „plati koliko trošiš“ bez greške
- Segmentacija u bazene omogućuje izolaciju performansi i praćenje potrošnje po aplikaciji
- Prati stopu preopterećenja kako bi prilagodio svoju alokaciju ako je potrebno