Cache API automatico
In questa pagina
Il cache come leva di riduzione dei costi
Il cache automatico ha l’impatto maggiore sulla tua fattura, nel bene e nel male. Con molti provider, devi dichiararlo esplicitamente nella richiesta, contrassegnare i blocchi da conservare e gestirne la durata. xAI ha adottato un approccio diverso: il cache si applica automaticamente a tutte le richieste, senza parametri né annotazioni. Non devi attivare nulla, ma hai tutto da guadagnare comprendendo cosa lo innesca, perché un prompt mal strutturato non ne beneficia mai e paga il prezzo pieno sull’intero input.
Come funziona il cache
Il cache opera sui token di input e solo su quelli: la generazione della risposta è sempre fatturata alla tariffa standard. Quando l’inizio del tuo prompt riproduce esattamente l’inizio di un prompt elaborato in precedenza, la parte identica viene servita dalla cache alla tariffa ridotta e solo la nuova parte viene addebitata alla tariffa standard.
Tre famiglie di applicazioni ne beneficiano immediatamente. Innanzitutto, una conversazione: il prompt di sistema e tutti i turni precedenti sono rigorosamente identici da una chiamata all’altra; cambia solo l’ultima domanda, quindi la percentuale di cache sale naturalmente man mano che lo scambio si allunga. Successivamente, un prompt con contesto fisso—un contratto, un manuale tecnico, un repository di prodotti seguito da una domanda variabile—vede il suo blocco documentale messo in cache dalla seconda chiamata in poi. Infine, una pipeline RAG mantiene istruzioni di sistema costanti; cambia solo il contesto recuperato e, se lo posizioni dopo le istruzioni, il prefisso rimane cacheabile.
Sulla griglia tariffaria di xAI, il divario è considerevole. Su grok-4.3 e grok-4.20-0309, un milione di token di input in cache costa $0.20 contro $1.25 alla tariffa standard. Su grok-4.5, lo stesso milione arriva a $0.30 invece di $2.00. In altre parole, un prefisso stabile di 5.000 token riutilizzato mille volte al giorno ti costa dalle cinque alle sette volte in meno rispetto a un prompt ricostruito a ogni chiamata, per un risultato strettamente identico.
L’header x-grok-conv-id
Per aiutare l’infrastruttura ad associare le richieste che appartengono allo stesso contesto, l’API accetta un header dedicato:
curl -X POST "https://api.x.ai/v1/chat/completions" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "x-grok-conv-id: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.20",
"messages": [...]
}'
L’header x-grok-conv-id richiede un UUID v4. La regola d’uso è semplice: un identificatore per conversazione o flusso di elaborazione, riutilizzato per tutte le chiamate che ne fanno parte. Questo segnala che queste richieste sono collegate, aumentando la probabilità di riutilizzo della cache. L’errore comune è generare l’UUID al momento della chiamata invece che all’apertura della sessione: ogni turno riceve allora un identificatore diverso e il beneficio scompare. Generane uno solo, memorizzalo con lo stato della conversazione:
import uuid
# Un UUID per conversazione
conv_id = str(uuid.uuid4())
# Usa lo stesso UUID per tutti i turni della conversazione
headers = {
"Authorization": f"Bearer {api_key}",
"x-grok-conv-id": conv_id,
"Content-Type": "application/json"
}
Verifica dell’efficienza del cache
Nulla batte la misurazione. Il campo cached_tokens nell’oggetto usage, trattato nella lezione precedente, ti indica esattamente cosa è stato servito dalla cache:
{
"usage": {
"prompt_tokens": 5000,
"cached_tokens": 4200,
"completion_tokens": 300
}
}
Qui, 4.200 token su 5.000 provengono dalla cache, una percentuale dell’84%; solo 800 token sono stati fatturati alla tariffa standard. Prendi l’abitudine di controllare questo rapporto su un campione di richieste reali dopo ogni deployment: se vedi una percentuale vicina allo zero su un’applicazione conversazionale, qualcosa varia all’inizio del prompt e la prossima lezione ti mostrerà cosa.
Punti chiave
- Il cache è automatico: nessuna configurazione necessaria
- Usa l’header
x-grok-conv-idcon un UUID v4 per raggruppare le richieste collegate - Il campo
cached_tokensnell’oggettousageindica il numero di token serviti dalla cache - L’input in cache costa dalle 5 alle 7 volte in meno: $0.20/M su grok-4.3, $0.30/M su grok-4.5
- Più il tuo prompt è stabile all’inizio della sequenza, più alta sarà la percentuale di cache