Salt la conținutul principal
Română— Alege o limbă
Meniu

Antete API și gestionarea depășirilor de capacitate

Lecția 8 din 14 Actualizată 28 iulie 2026 Intermediar
Pe această pagină
  1. Decideți care cereri consumă capacitatea dumneavoastră
  2. Ocoliți voluntar capacitatea dedicată
  3. Rutați o cerere către un pool specific
  4. Ce se întâmplă în caz de depășire a capacității
  5. Traduceți prioritatea în codul aplicației
  6. Puncte cheie

Decideți care cereri consumă capacitatea dumneavoastră

Rezervarea capacității rezolvă doar jumătate din problemă: trebuie totuși să alegeți care cereri beneficiază efectiv de aceasta. Throughput-ul provizionat nu este o achiziție globală făcută o singură dată la începutul lunii; este un mecanism pe care îl controlați cerere cu cerere. xAI expune antete HTTP dedicate în acest scop, care arbitrează, pentru fiecare cerere, între capacitatea dumneavoastră dedicată și pool-ul partajat. O alocare fixă devine astfel o pârghie operațională pe care echipele dumneavoastră o manipulează direct din codul aplicației.

Ocoliți voluntar capacitatea dedicată

Primul antet servește la excluderea unei cereri din alocarea dumneavoastră:

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."}]
  }'

Renunțarea la propria capacitate poate părea contra-intuitivă. Patru situații justifică această abordare în operațiunile zilnice. În primul rând, sarcinile necritice: o analiză batch lansată la ora 22:00 sau un job de procesare amânată nu necesită o garanție de latență, iar ar fi păcat ca acestea să consume alocarea plătită pentru traficul interactiv. În al doilea rând, prezervarea capacității în perioadele de vârf: prin dezactivarea throughput-ului provizionat pentru procesarea secundară, eliberați alocarea exact atunci când cererile prioritare sosesc în volum mare. Antetul servește, de asemenea, pentru testele A/B, când doriți să măsurați decalajul real de performanță dintre capacitatea dedicată și cea partajată pe propria sarcină de lucru, și nu pe baza unei promisiuni a furnizorului. În final, este valoros pentru depanare: forțarea cererii prin pool-ul partajat vă indică imediat dacă anomalia observată provine de la capacitatea provizionată sau din codul dumneavoastră.

Rutați o cerere către un pool specific

Al doilea antet direcționează apelul către un pool de capacitate identificat:

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?"}]
  }'

Acest antet devine indispensabil de îndată ce multiple aplicații din cadrul organizației dumneavoastră apelează Grok. Creează apoi pool-uri separate – un pool-support pentru chatbot-ul de suport clienți, un pool-analysis pentru analiza documentelor, un pool-internal pentru instrumentele de business – iar fiecare operează independent. Segmentarea izolează performanța: campania de analiză a documentelor lansată luni dimineața nu mai degradează timpii de răspuns pentru suport. De asemenea, produce un consum defalcat pe utilizare, oferind astfel o bază factuală pentru refacturare internă sau arbitraj, acolo unde anterior vă bazați pe estimări. Și, inerent, previne ca o singură aplicație să monopolizeze capacitatea în detrimentul celorlalte.

Ce se întâmplă în caz de depășire a capacității

Când traficul depășește capacitatea provizionată, mecanismul de fallback este automat și silențios: cererea este direcționată către pool-ul partajat cu tarifare pay-as-you-go, se aplică tarifele standard ale modelului, iar aceasta este supusă limitelor de rată uzuale. Nu se returnează nicio eroare; aplicația dumneavoastră nu observă nicio schimbare.

Această discreție are două fețe. Din perspectiva disponibilității, vestea este bună: nu veți întâlni niciodată o eroare 429 cauzată de depășirea capacității provizionate. Din perspectiva financiară și a calității serviciului, situația este mai puțin favorabilă. Cererea este facturată la tariful pay-as-you-go, potențial mai ridicat; timpii de răspuns pot varia deoarece procesarea are loc pe infrastructura partajată; și, mai presus de toate, SLA-ul de 99,9% acoperă doar cererile procesate în cadrul throughput-ului provizionat. O depășire nu strică nimic, ci vă face doar să ieșiți discret din aria de acoperire pentru care plătiți. API-ul de Management expune proporția de cereri procesate în mod provizionat față de cele pay-as-you-go: examinați acest raport lunar, exact ca pe o factură. O rată crescută a depășirilor este semnalul că trebuie să măriți alocarea.

Traduceți prioritatea în codul aplicației

În loc să multiplicați funcțiile de apel, cea mai solidă practică constă în calificarea priorității în momentul emiterii cererii:

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()

Parametrul priority devine singura decizie expusă logicii de business, iar politica de rutare rămâne concentrată într-o singură funcție pe care o evoluați fără a atinge restul codului. Revizuiți propriul cod de apel și sortați fiecare punct de intrare într-una dintre cele trei categorii: exercițiul arată regulat că o bună jumătate din trafic nu avea nevoie de capacitate dedicată.

Puncte cheie

  • Antetul x-pt-disable: true ocolește capacitatea provizionată pentru o cerere
  • Antetul x-pt-id rutează către un pool de capacitate specific
  • Depășirile revin automat la tarifarea pay-as-you-go fără a genera erori
  • Segmentarea în pool-uri permite izolarea performanței și urmărirea consumului pe aplicație
  • Monitorizați rata de depășire pentru a ajusta alocarea dacă este necesar