Przejdź do głównej treści
Polski— Wybierz język
Menu

Nagłówki API i zarządzanie przeciążeniem

Lekcja 8 z 14 Zaktualizowano 28 lipca 2026 Średnio zaawansowani
Na tej stronie
  1. Decyduj, które żądania zużywają Twój przydział
  2. Dobrowolne pominięcie dedykowanej przepustowości
  3. Kierowanie żądania do konkretnej puli
  4. Co dzieje się w przypadku przeciążenia
  5. Przełóż priorytet na kod aplikacji
  6. Kluczowe wnioski

Decyduj, które żądania zużywają Twój przydział

Rezerwacja przepustowości rozwiązuje tylko połowę problemu: nadal musisz wybrać, które żądania faktycznie z niej skorzystają. Przepustowość zarezerwowana (provisioned throughput) to nie jednorazowy zakup na początek miesiąca, lecz mechanizm, którym sterujesz przy każdym wywołaniu. xAI udostępnia dedykowane nagłówki HTTP, które arbitrują, żądanie po żądaniu, między Twoją dedykowaną przepustowością a pulą współdzieloną. Stały przydział staje się więc dźwignią operacyjną, którą Twoje zespoły manipulują bezpośrednio z poziomu kodu aplikacji.

Dobrowolne pominięcie dedykowanej przepustowości

Pierwszy nagłówek służy do wykluczenia żądania z Twojego przydziału:

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

Rezygnacja z własnej przepustowości może wydawać się nielogiczna. W codziennych operacjach uzasadniają to cztery sytuacje. Po pierwsze, zadania niekrytyczne: analiza wsadowa uruchamiana o 22:00 lub zadanie przetwarzania odroczonego nie wymagają gwarancji niskiego opóźnienia; szkoda, by zużywały przydział opłacony dla ruchu interaktywnego. Po drugie, ochrona przepustowości w godzinach szczytu: wyłączając przepustowość zarezerwowaną dla przetwarzania drugoplanowego, uwalniasz przydział dokładnie wtedy, gdy napływają liczne żądania o wysokim priorytecie. Nagłówek ten przydaje się też do testów A/B, gdy chcesz zmierzyć rzeczywistą różnicę wydajności między przepustowością dedykowaną a współdzieloną na własnym obciążeniu, a nie na obietnicach dostawcy. Wreszcie, jest cenny przy debugowaniu: wymuszenie przejścia żądania przez pulę współdzieloną natychmiast wskazuje, czy obserwowana anomalia wynika z przepustowości zarezerwowanej, czy z Twojego kodu.

Kierowanie żądania do konkretnej puli

Drugi nagłówek kieruje wywołanie do zidentyfikowanej puli przepustowości:

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

Nagłówek ten staje się niezbędny, gdy wiele aplikacji w Twojej organizacji wywołuje Grok. Tworzysz wtedy oddzielne pule – np. pool-support dla czatbota obsługi klienta, pool-analysis do analizy dokumentów, pool-internal dla narzędzi biznesowych – a każda działa niezależnie. Segmentacja izoluje wydajność: kampania analizy dokumentów uruchomiona w poniedziałek rano nie pogarsza już czasów odpowiedzi wsparcia. Daje też rozbicie zużycia według rodzaju użycia, co stanowi faktyczną podstawę do rozliczeń wewnętrznych lub arbitrażu, tam gdzie wcześniej polegałeś na domysłach. Co więcej, z natury zapobiega sytuacji, w której jedna aplikacja monopolizuje przepustowość kosztem innych.

Co dzieje się w przypadku przeciążenia

Gdy ruch przekroczy przepustowość zarezerwowaną, mechanizm awaryjny działa automatycznie i bezgłośnie: żądanie trafia do puli współdzielonej w modelu płatności za użycie (pay-as-you-go), obowiązują standardowe stawki modelu, a żądanie podlega zwykłym limitom częstotliwości. Nie zwracany jest żaden błąd; Twoja aplikacja nie widzi żadnej zmiany.

Ta dyskrecja ma dwie strony. Pod względem dostępności wiadomość jest dobra: nigdy nie otrzymasz błędu 429 spowodowanego przekroczeniem przepustowości zarezerwowanej. Pod względem finansów i jakości usługi jest gorzej. Żądanie jest rozliczane według stawki pay-as-you-go, potencjalnie wyższej; czasy odpowiedzi mogą się różnić, ponieważ przetwarzanie odbywa się na infrastrukturze współdzielonej; co najważniejsze, SLA na poziomie 99,9% obejmuje wyłącznie żądania przetworzone w ramach przepustowości zarezerwowanej. Przeciążenie niczego nie psuje, po prostu cicho wyprowadza Cię poza zakres, za który płacisz. Interfejs API zarządzania udostępnia odsetek żądań przetworzonych w trybie zarezerwowanym wobec tych w modelu pay-as-you-go: badaj ten stosunek co miesiąc tak jak rachunek. Rosnący wskaźnik przeciążeń to sygnał, że musisz zwiększyć przydział.

Przełóż priorytet na kod aplikacji

Zamiast mnożyć funkcje wywołujące, najsolidniejszą praktyką jest kwalifikowanie priorytetu w momencie wystawienia żądania:

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 staje się jedyną decyzją udostępnioną logice biznesowej, a polityka routingu pozostaje skupiona w jednej funkcji, którą rozwijasz bez dotykania reszty kodu. Przejrzyj swój własny kod wywołań i przyporządkuj każdy punkt wejścia do jednej z trzech kategorii: regularne ćwiczenie często pokazuje, że solidna połowa ruchu nie potrzebowała dedykowanej przepustowości.

Kluczowe wnioski

  • Nagłówek x-pt-disable: true pomija przepustowość zarezerwowaną dla danego żądania
  • Nagłówek x-pt-id kieruje ruch do konkretnej puli przepustowości
  • Przeciążenia automatycznie przechodzą na model pay-as-you-go bez błędów
  • Segmentacja na pule pozwala izolować wydajność i śledzić zużycie według aplikacji
  • Monitoruj wskaźnik przeciążeń, aby w razie potrzeby dostosować swój przydział