Caching dei prompt Claude — tariffe, oggetto usage e perché la percentuale di hit diminuisce dietro un gateway

La memorizzazione nella cache dei prompt è la singola leva più importante sul costo di un agente e quella che più probabilmente non funziona senza che tu te ne accorga. Se contrassegnata correttamente, la parte ripetuta della richiesta viene fatturata a un decimo della tariffa di input. Se contrassegnata in modo errato — o instradata attraverso qualcosa che riscrive il prefisso — viene fatturata più della tariffa normale, perché paghi per scrivere voci della cache che nessuno legge.

Il meccanismo è ben documentato altrove. Ciò che non è documentato da nessuna parte è cosa cambia quando la richiesta passa attraverso un gateway, situazione che riguarda la maggior parte delle persone che leggono questo testo. Entrambi gli aspetti sono riportati di seguito.

Il meccanismo, in breve

Contrassegni un prefisso stabile — un prompt di sistema, uno schema di strumenti, un documento — e il provider ne memorizza la forma elaborata. La richiesta successiva il cui prefisso corrisponde esattamente lo legge invece di rielaborarlo.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "..." }]
}

Due proprietà fanno tutto il lavoro e causano tutti i problemi. La corrispondenza avviene su un prefisso, quindi qualsiasi modifica iniziale invalida tutto ciò che segue. Inoltre una voce ha una durata, quindi una conversazione con intervalli lunghi tra i turni ricostruisce la cache invece di leggerla.

Quanto costa

La terza colonna è il rapporto standard: una lettura costa un decimo dell’input. Anche la quarta è standard: una scrittura nella cache costa 1,25× l’input, il moltiplicatore indicato da Anthropic per una voce di cinque minuti; poiché entrambi i rapporti si applicano al prezzo di input di Kunavo, ciascuno mantiene lo stesso sconto rispetto al listino Anthropic dell’input del modello. Kunavo si discosta da Anthropic per la voce di un’ora: Anthropic indica quella scrittura a 2× l’input, mentre Kunavo la fattura allo stesso 1,25×. Questo è importante soprattutto per i carichi di lavoro che ricostruiscono spesso la cache — agenti di lunga durata, conversazioni lente, qualsiasi situazione in cui il prefisso cambia frequentemente — perché sono i carichi in cui le scritture, non le letture, dominano la voce cache della fattura.

Entrambi i valori vengono letti dal catalogo al momento del rendering, la stessa fonte letta dalla tabella dei prezzi e dal calcolatore Claude: in questa pagina non ci sono tariffe inserite manualmente.

Leggere l’oggetto usage

Non dedurre il comportamento della cache dalla fattura: ogni risposta lo indica direttamente e i tre conteggi dei token costituiscono l’intera diagnosi.

// The four numbers that tell you whether caching is working.
// Read them from every response before you tune anything.
"usage": {
  "input_tokens": 312,                     // billed at the input rate
  "cache_creation_input_tokens": 0,        // billed at the write rate
  "cache_read_input_tokens": 24106,        // billed at the read rate
  "output_tokens": 890
}

// A healthy cached agent turn looks like the above: a small
// input_tokens, a large cache_read, and a zero creation.
// If cache_creation is large on EVERY turn, the cache is being
// rebuilt each time and you are paying more, not less.

Perché le percentuali di hit diminuiscono dietro un gateway

Una cache risiede nell’upstream che l’ha creata e la corrispondenza del prefisso è esatta. Questi due fatti insieme producono tre modalità di errore che non si verificano mai quando chiami direttamente un solo provider:

L’instradamento è cambiato. Se richieste consecutive arrivano su upstream diversi, la seconda non trova alcuna cache: la voce scritta dalla prima non è visibile dal punto in cui è stata eseguita la seconda. Questo è invisibile nei tuoi log e compare solo come un conteggio di creazione della cache che avrebbe dovuto essere una lettura. È la causa più comune e spiega perché un gateway che reindirizza liberamente tra upstream può costare meno per token e di più per sessione.

Qualcosa è stato inserito prima del prefisso. Un livello che riscrive il messaggio di sistema, normalizza le definizioni degli strumenti o riordina i campi produce un prefisso diverso, e un prefisso diverso è un mancato riscontro. Non si verifica alcun errore; aumenta semplicemente la fattura.

L’intervallo ha superato la durata della voce. Un agente che riflette per diversi minuti tra un turno e l’altro può ricostruire la cache ogni volta. Questo dipende dal carico di lavoro, non dal gateway, ma interagisce male con il primo caso: una ricostruzione è anche un’opportunità di reindirizzamento.

La diagnosi per tutti e tre è la stessa: osserva cache_creation_input_tokens durante una sessione. Un valore piatto e elevato significa che stai ricostruendo. Un valore elevato una sola volta e zero dopo significa che funziona. Su Kunavo, il costo a livello di richiesta e i conteggi dei token memorizzati nella cache sono nella vista usage, mentre la documentazione di riferimento sulla cache contiene i dettagli a livello di endpoint.

Cosa fare

Mantieni il prefisso memorizzato nella cache realmente stabile: inserisci qualsiasi elemento che cambia per richiesta dopo il blocco contrassegnato, mai prima. Raggruppa i turni dell’agente più ravvicinati quando possibile, perché il tempo di inattività è nemico delle voci di breve durata. Misura inoltre una sessione dall’inizio alla fine, non una singola richiesta: la memorizzazione nella cache è una proprietà di una sequenza e una stima per richiesta non può rilevarla. Il calcolatore del costo dei token di Claude include un campo per i token memorizzati nella cache proprio per questo motivo: impostalo sulla frazione del prompt che viene realmente ripetuta e il valore mensile smette di essere fittizio.

Domande frequenti