API-otsikot ja ylivuodon hallinta
Tällä sivulla
Päätä, mitkä pyynnöt kuluttavat kapasiteettiasi
Kapasiteetin varaaminen ratkaisee vain puolet ongelmasta: sinun on silti valittava, mitkä pyynnöt todella hyötyvät siitä. Varattu läpimeno ei ole kertaluonteinen hankinta kuukauden alussa, vaan mekanismi, jota ohjaat pyyntö kerrallaan. xAI tarjoaa tätä varten omat HTTP-otsikkonsa, jotka sopivat pyyntö kohtaisesti omistetun kapasiteettisi ja jaetun poolin välillä. Kiinteä kohdistus muuttuu näin operatiiviseksi vivuksi, jota tiimisi käyttävät suoraan sovelluskoodista.
Ohita omistettu kapasiteetti vapaaehtoisesti
Ensimmäinen otsikko sulkee pyynnön pois kohdistuksestasi:
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."}]
}'
Oman kapasiteetin luovuttaminen vaikuttaa vastakkaiselta. Neljä tilannetta oikeuttaa tämän päivittäisessä toiminnassa. Ensinnäkin ei-kriittiset tehtävät: klo 22 käynnistetty eräanalyysi tai viivästetty käsittelytyö ei tarvitse latenssitakuuta, ja olisi sääli, jos se kuluttaisi interaktiivista liikennettä varten maksettua kohdistusta. Toiseksi kapasiteetin säilyttäminen huippukuormituksen aikana: poistamalla varattu läpimeno käytöstä toissijaisessa käsittelyssä vapautat kohdistusta juuri silloin, kun prioriteettipyynnöt saapuvat suurina määrinä. Otsikko soveltuu myös A/B-testaukseen, kun haluat mitata todellista suorituskykyeroa omistetun ja jaetun kapasiteetin välillä omalla kuormallasi eikä toimittajan lupauksilla. Lopuksi se on arvokas vianetsinnässä: pakottamalla pyyntö jaettuun pooliin näet heti, johtuuko havaittu poikkeama varatusta kapasiteetista vai koodistasi.
Reititä pyyntö tiettyyn pooliin
Toinen otsikko ohjaa kutsun tunnistettuun kapasiteettipooliin:
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?"}]
}'
Tästä otsikosta tulee välttämätön, kun organisaatiosi sisällä useat sovellukset kutsuvat Grokia. Luot tällöin erillisiä pooleja: pool-support asiakastukichatbotille, pool-analysis dokumenttianalyysille ja pool-internal liiketoimintatyökaluille, ja kukin toimii itsenäisesti. Segmentointi eristää suorituskyvyn: maanantaiaamuna käynnistetty dokumenttianalyysikampanja ei enää heikennä tuen vasteaikoja. Se tuottaa myös kulutuksen eriteltynä käytön mukaan, mikä luo faktoihin perustuvan pohjan kustannusten kohdistukselle tai arbitraasille, missä aiemmin luotit arvailuun. Lisäksi se estää luontaisesti yhden sovelluksen monopolisoimasta kapasiteettia muiden kustannuksella.
Mitä tapahtuu ylivuodon sattuessa
Kun liikenne ylittää varatun kapasiteetin, varajärjestelmä on automaattinen ja hiljainen: pyyntö siirtyy maksa-käytä-mukaan -pooliin, normaalit mallihinnat tulevat voimaan, ja siihen sovelletaan tavanomaisia nopeusrajoituksia. Virhettä ei palauteta; sovelluksesi ei huomaa mitään tapahtuneen.
Tällä hienovaraisuudella on kaksi puolta. Saatavuuden kannalta uutiset ovat hyviä: et koskaan kohtaa 429-virhettä, joka johtuisi varatun kapasiteetin ylittämisestä. Rahoituksen ja palvelun laadun kannalta tilanne on heikompi. Pyyntö laskutetaan maksa-käytä-mukaan -hinnalla, joka voi olla korkeampi; vasteajat voivat vaihdella, koska käsittely tapahtuu jaetussa infrastruktuurissa; ja ennen kaikkea 99,9 %:n SLA koskee vain varatussa läpimenossa käsiteltyjä pyyntöjä. Ylivuoto ei siis riko mitään, se vain liu’uttaa sinut hiljaa ulos siitä scopesta, josta maksat. Hallinta-API paljastaa varatussa tilassa versus maksa-käytä-mukaan -tilassa käsiteltyjen pyyntöjen osuuden: tarkastele tätä suhdetta joka kuukausi aivan kuin laskua. Nouseva ylivuotoaste on merkki siitä, että sinun on lisättävä kohdistusta.
Käännä prioriteetti sovelluskoodiksi
Kutsufunktioiden määrän lisäämisen sijaan vankin käytäntö on määrittää prioriteetti pyynnön lähetyshetkellä:
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()
priority-parametrista tulee ainoa liiketoimintalogiikalle altistettu päätös, ja reitityskäytäntö pysyy keskittyneenä yhteen funktioon, jota kehität koskematta muuhun koodiin. Käy läpi oma kutsukoodisi ja luokittele jokainen entry point yhteen kolmesta kategoriasta: harjoitus osoittaa usein, että noin puolella liikenteestä ei ollut tarvetta omistetulle kapasiteetille.
Keskeiset asiat
- Otsikko
x-pt-disable: trueohittaa varatun kapasiteetin pyynnön osalta - Otsikko
x-pt-idreitittää pyynnön tiettyyn kapasiteettipooliin - Ylivuodot siirtyvät automaattisesti maksa-käytä-mukaan -malliin ilman virhettä
- Poolittaminen mahdollistaa suorituskyvyn eristämisen ja kulutuksen seurannan sovelluskohtaisesti
- Seuraa ylivuotoastetta säätääksesi kohdistustasi tarvittaessa