Hlavičky API a správa přetečení
Na této stránce
Rozhodni, které požadavky spotřebují tvou kapacitu
Rezervace kapacity řeší jen polovinu problému: stále si musíš vybrat, které požadavky z ní skutečně benefited. Nasazená propustnost (provisioned throughput) není jednorázový nákup na začátku měsíce; je to mechanismus, který ovládáš volání po volání. xAI pro tento účel poskytuje vyhrazené HTTP hlavičky, které pro každý požadavek rozhodují mezi tvou vyhrazenou kapacitou a sdíleným poolem. Pevná alokace se tak stává operační pákou, kterou tvoje týmy přímo ovládají z aplikačního kódu.
Dobrovolné obejití vyhrazené kapacity
První hlavička slouží k vyloučení požadavku z tvé alokace:
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."}]
}'
Vzdát se vlastní kapacity se může zdát nelogické. V běžném provozu to však ospravedlňují čtyři situace. Zaprvé, nekritické úlohy: dávková analýza spuštěná ve 22:00 nebo odložená zpracovatelská úloha nepotřebuje garanci latence a byla by škoda, aby spotřebovávala alokaci placenou pro interaktivní provoz. Zadruhé, zachování kapacity během špiček: vypnutím nasazené propustnosti pro sekundární zpracování uvolníš alokaci přesně ve chvíli, kdy ve velkém objemu přicházejí prioritní požadavky. Hlavička se také hodí pro A/B testování, když chceš změřit skutečný výkonový rozdíl mezi vyhrazenou a sdílenou kapacitou na vlastní zátěži, nikoliv na základě slibů dodavatele. Nakonec je cenná pro ladění: vynucení průchodu požadavku přes sdílený pool ti okamžitě řekne, zda pozorovaná anomálie pochází z nasazené kapacity, nebo z tvého kódu.
Směrování požadavku do konkrétního poolu
Druhá hlavička směruje volání do identifikovaného poolu kapacity:
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?"}]
}'
Tato hlavička se stane nepostradatelnou, jakmile Grok volá více aplikací v rámci tvé organizace. Vytvoříš si pak oddělené pooly – pool-support pro chatbota zákaznické podpory, pool-analysis pro analýzu dokumentů, pool-internal pro business nástroje – a každý funguje nezávisle. Segmentace izoluje výkon: kampaň analýzy dokumentů spuštěná v pondělí ráno již nezhoršuje doby odezvy podpory. Zároveň produkuje spotřebu rozdělenou podle využití, což poskytuje faktický základ pro interní vyúčtování nebo arbitráž, kde jsi dříve spoléhal na odhady. A inherentně zabraňuje tomu, aby jedna aplikace monopolizovala kapacitu na úkor ostatních.
Co se stane v případě přetečení
Když provoz překročí nasazenou kapacitu, záložní řešení je automatické a tiché: požadavek přejde do sdíleného poolu na bázi pay-as-you-go, platí standardní sazby modelu a podléhá obvyklým limitům rychlosti. Nevrací se žádná chyba; tvá aplikace nic nezaznamená.
Tato diskrétnost má dvě stránky. Na straně dostupnosti jsou zprávy dobré: nikdy se nesetkáš s chybou 429 způsobenou překročením nasazené kapacity. Na straně financí a kvality služby je to horší. Požadavek je fakturován sazbou pay-as-you-go, která může být vyšší; doby odezvy se mohou lišit, protože zpracování probíhá na sdílené infrastruktuře; a především SLA 99,9 % pokrývá pouze požadavky zpracované v rámci nasazené propustnosti. Přetečení tedy nic nerozbije, pouze tě tiše vyvede z rozsahu, za který platíš. Management API zpřístupňuje poměr požadavků zpracovaných v režimu provisioned oproti pay-as-you-go: tento poměr zkoumej každý měsíc stejně jako fakturu. Rostoucí míra přetečení je signálem, že potřebuješ zvýšit alokaci.
Převeď priority do aplikačního kódu
Místo násobení funkcí pro volání spočívá nejpevnější praxe v kvalifikaci priority v okamžiku vydání požadavku:
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()
Parametr priority se stane jediným rozhodnutím vystaveným business logice a směrovací politika zůstává soustředěna v jediné funkci, kterou vyvíjíš, aniž bys musel sahat na zbytek kódu. Zkontroluj svůj vlastní volací kód a seřiď každý vstupní bod do jedné ze tří kategorií: pravidelné cvičení často ukáže, že solidní polovina provozu vyhrazenou kapacitu vůbec nepotřebovala.
Klíčové poznatky
- Hlavička
x-pt-disable: trueobchází pro daný požadavek nasazenou kapacitu - Hlavička
x-pt-idsměruje požadavek do konkrétního poolu kapacity - Přetečení automaticky přepne na režim pay-as-you-go bez chyby
- Segmentace do poolů umožňuje izolovat výkon a sledovat spotřebu podle aplikace
- Sleduj míru přetečení a v případě potřeby uprav svou alokaci