Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Intestazioni API e gestione del sovraccarico

Lezione 8 di 14 Aggiornata il 28 luglio 2026 Intermedio
In questa pagina
  1. Decidi quali richieste consumano la tua capacità
  2. Scavalca volontariamente la capacità dedicata
  3. Instrada una richiesta verso un pool specifico
  4. Cosa succede in caso di sovraccarico
  5. Traduci la priorità nel codice applicativo
  6. Punti chiave

Decidi quali richieste consumano la tua capacità

Prenotare la capacità risolve solo metà del problema: devi ancora scegliere quali richieste ne beneficiano effettivamente. Il throughput prenotato non è un acquisto forfettario da effettuare una volta all’inizio del mese; è un meccanismo che controlli chiamata per chiamata. xAI espone intestazioni HTTP dedicate a questo scopo, che arbitrano, richiesta per richiesta, tra la tua capacità dedicata e il pool condiviso. Un’allocazione fissa diventa così una leva operativa che i tuoi team manipolano direttamente dal codice applicativo.

Scavalca volontariamente la capacità dedicata

La prima intestazione serve a escludere una richiesta dalla tua allocazione:

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

Rinunciare alla propria capacità sembra controintuitivo. Quattro situazioni lo giustificano nelle operazioni quotidiane. Primo, le attività non critiche: un’analisi batch lanciata alle 22:00 o un job di elaborazione differita non necessita di garanzie di latenza, e sarebbe un peccato che consumi l’allocazione pagata per il traffico interattivo. Secondo, preservare la capacità durante i picchi: disabilitando il throughput prenotato sull’elaborazione secondaria, liberi l’allocazione esattamente quando le richieste prioritarie arrivano in grandi volumi. L’intestazione serve anche per i test A/B, quando vuoi misurare il divario reale di prestazioni tra capacità dedicata e condivisa sul tuo carico specifico, piuttosto che basarti su una promessa del fornitore. Infine, è preziosa per il debug: forzare la richiesta attraverso il pool condiviso ti dice immediatamente se l’anomalia osservata proviene dalla capacità prenotata o dal tuo codice.

Instrada una richiesta verso un pool specifico

La seconda intestazione dirige la chiamata verso un pool di capacità identificato:

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

Questa intestazione diventa indispensabile non appena più applicazioni all’interno della tua organizzazione chiamano Grok. Crei allora pool separati: un pool-support per il chatbot di assistenza clienti, un pool-analysis per l’analisi documentale, un pool-internal per gli strumenti aziendali; ognuno opera in modo indipendente. La segmentazione isola le prestazioni: la campagna di analisi documentale lanciata lunedì mattina non degrada più i tempi di risposta del supporto. Produce inoltre un consumo ripartito per utilizzo, fornendo così una base fattuale per l’addebito interno o l’arbitrato, laddove prima ti affidavi a congetture. E impedisce intrinsecamente a una singola applicazione di monopolizzare la capacità a danno delle altre.

Cosa succede in caso di sovraccarico

Quando il traffico supera la capacità prenotata, il fallback è automatico e silenzioso: la richiesta passa al pool condiviso in modalità pay-as-you-go, si applicano le tariffe standard del modello ed è soggetta ai limiti di velocità usuali. Nessun errore viene restituito; la tua applicazione non vede accadere nulla.

Questa discrezione ha due facce. Sul fronte della disponibilità, la notizia è buona: non incontrerai mai un errore 429 causato dal superamento della capacità prenotata. Sul fronte finanziario e della qualità del servizio, è meno buona. La richiesta viene fatturata alla tariffa pay-as-you-go, potenzialmente più alta; i tempi di risposta possono variare poiché l’elaborazione avviene su infrastrutture condivise; e soprattutto, lo SLA del 99,9% copre solo le richieste elaborate entro il throughput prenotato. Un sovraccarico non rompe quindi nulla, ti fa semplicemente scivolare silenziosamente fuori dall’ambito per cui paghi. L’API di Management espone la proporzione di richieste elaborate in modalità prenotata rispetto al pay-as-you-go: esamina questo rapporto ogni mese proprio come una fattura. Un tasso di sovraccarico in aumento è il segnale che devi aumentare l’allocazione.

Traduci la priorità nel codice applicativo

Piuttosto che moltiplicare le funzioni di chiamata, la pratica più solida consiste nel qualificare la priorità al momento dell’emissione della richiesta:

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

Il parametro priority diventa l’unica decisione esposta alla logica di business, e la politica di instradamento rimane concentrata in un’unica funzione che evolvi senza toccare il resto. Rivedi il tuo codice di chiamata e classifica ogni punto di ingresso in una delle tre categorie: l’esercizio mostra regolarmente che una buona metà del traffico non aveva bisogno di capacità dedicata.

Punti chiave

  • L’intestazione x-pt-disable: true scavalca la capacità prenotata per una richiesta
  • L’intestazione x-pt-id instrada verso un pool di capacità specifico
  • I sovraccarichi passano automaticamente al pay-as-you-go senza errori
  • La segmentazione in pool permette di isolare le prestazioni e tracciare il consumo per applicazione
  • Monitora il tasso di sovraccarico per adeguare la tua allocazione se necessario