Prompt caching: ridurre i costi delle API Claude

Se sviluppi sopra le API di Claude e rimandi lo stesso, lungo blocco di testo a ogni chiamata — un system prompt corposo, un manuale da consultare, l’elenco dei tuoi tool — stai pagando quel testo ogni volta. Il prompt caching serve esattamente a questo: dici all’API quali parti del prompt sono stabili, lei le mette in cache e dalla seconda chiamata in poi le rilegge a una frazione del prezzo. In questa guida spiego cos’è il prompt caching, quando conviene davvero e come si attiva, con i numeri ufficiali Anthropic alla mano.

Cos’è il prompt caching e quando conviene

Ogni richiesta che mandi a Claude viene elaborata daccapo: il modello legge tutto l’input, dal primo token all’ultimo, e solo dopo genera la risposta. Il prompt caching spezza questa abitudine. Marchi un prefisso del prompt come cacheabile, l’API lo memorizza, e nelle chiamate successive che iniziano con lo stesso prefisso quel pezzo non viene rielaborato: viene ripreso dalla cache.

La condizione che rende tutto utile è il prefisso identico. La cache funziona per prefissi: vale finché i token cacheati sono uguali, byte per byte, e nello stesso ordine. Per questo conviene quando hai una parte fissa e ripetuta, e una variabile alla fine. Casi tipici:

• System prompt lunghi. Istruzioni, regole, esempi few-shot che resti uguali a ogni turno.
• Documenti di contesto. Un manuale, una base di conoscenza, un file di codice su cui poni più domande di fila.
• Definizioni dei tool. L’array tools di un agente, spesso pesante e quasi sempre stabile fra una chiamata e l’altra.
• Conversazioni multi-turno. Lo storico che cresce ma il cui inizio non cambia mai.

Se invece ogni richiesta è breve e diversa dalla precedente, la cache non ha nulla di stabile da riusare e l’accortezza non paga.

Quanto si risparmia: i numeri ufficiali

Qui i conti contano, quindi uso solo cifre dalla documentazione Anthropic. Il prezzo dei token cacheati è espresso come moltiplicatore del prezzo base dei token di input:

• Lettura dalla cache (cache hit): 0,1x il prezzo base di input. Cioè il 10%: rileggere un blocco già in cache costa un decimo rispetto a rielaborarlo.
• Scrittura in cache (TTL 5 minuti): 1,25x il prezzo base. La prima volta che metti qualcosa in cache paghi un 25% in più del normale.
• Scrittura in cache (TTL 1 ora): 2x il prezzo base, se scegli la durata estesa.

Il meccanismo si ripaga in fretta. Con la cache da 5 minuti spendi 1,25x la prima volta, poi 0,1x a ogni riuso: già al secondo passaggio sei in attivo. Anthropic, nell’annuncio ufficiale della funzione, indica risparmi fino al 90% sui costi e fino all’85% sulla latenza per i prompt lunghi. Nell’esempio della chat su un documento da 100.000 token, il caso misurato passa da 11,5 a 2,4 secondi (-79% di latenza) con un -90% di costo. Sono cifre legate a quello scenario specifico, non una garanzia universale, ma rendono l’idea dell’ordine di grandezza.

Come si attiva con cache_control

L’attivazione è un singolo campo, cache_control, che aggiungi al blocco di contenuto fino a cui vuoi cachare. Tutto ciò che precede quel marcatore, in ordine, diventa il prefisso messo in cache. Puoi applicarlo all’array tools, ai blocchi del campo system e ai blocchi dentro messages.

{
  "model": "claude-...",
  "system": [
    {
      "type": "text",
      "text": "Sei un assistente. Ecco il manuale completo: ...testo lungo..."
      ,
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "Domanda che cambia a ogni chiamata" }
  ]
}

Da questo momento il blocco system viene cachato: la prima chiamata lo scrive (1,25x), le successive con lo stesso testo lo leggono (0,1x). Due dettagli pratici dalla documentazione:

• Fino a 4 cache breakpoint. Puoi marcare più punti di taglio, ad esempio uno dopo i tool e uno dopo il system prompt, per gestire parti che cambiano con frequenze diverse.
• Ordine di invalidazione: tools → system → messages. Se modifichi un livello, quel livello e tutti i successivi vengono invalidati. Tradotto: tieni in cima ciò che cambia di meno (i tool), in fondo ciò che varia (il messaggio dell’utente).

Durata della cache (TTL) e soglie minime

La cache ha una durata, il TTL. Le opzioni ufficiali sono due:

• 5 minuti di default. Importante: la documentazione precisa che la cache viene rinfrescata senza costo aggiuntivo a ogni uso. Finché continui a leggerla entro la finestra, il timer riparte. Adatta a sessioni attive, in cui le chiamate sono più ravvicinate di cinque minuti.
• 1 ora come opzione estesa, al costo di scrittura 2x. Conviene quando i riusi sono più diradati e non vuoi che il prefisso scada tra una richiesta e l’altra.

C’è poi una soglia minima: il prefisso deve raggiungere una lunghezza minima per essere cacheabile, e varia per modello. La documentazione indica 1.024 token per modelli come Sonnet 4.5 e gli Opus 4.x precedenti, e 4.096 token per i più recenti come Opus 4.5 e Haiku 4.5. Sotto quella soglia la richiesta funziona ugualmente, ma il blocco non viene messo in cache. È un altro motivo per cui il prompt caching brilla sui prompt lunghi: i blocchi brevi non superano la soglia.

Best practice

Qualche regola che semplifica il lavoro e massimizza i cache hit:

• Metti il fisso prima, il variabile dopo. System prompt, documenti e tool in testa; la domanda dell’utente in coda. È la struttura che produce prefissi riusabili.
• Non toccare il contenuto cachato. Anche una virgola in più nel prefisso lo rende diverso e fa decadere l’hit. Stabilizza il testo prima di cacharlo.
• Scegli il TTL in base al ritmo. Sessioni fitte: 5 minuti, che si rinnovano da soli. Riusi sparsi nell’arco di un’ora: valuta il TTL esteso, facendo il conto del 2x in scrittura contro il numero di riusi attesi.
• Cacha le definizioni dei tool. Negli agenti l’array tools è grosso e quasi immutabile: è uno dei candidati migliori. Se costruisci agenti, vedi anche come funzionano i subagent in Claude Code e il Model Context Protocol.
• Misura prima di ottimizzare. La risposta dell’API riporta i token scritti e letti dalla cache: usali per verificare che i cache hit avvengano davvero, invece di darli per scontati.

In sintesi

Il prompt caching è una delle leve più semplici per abbassare la spesa sulle API Claude: marchi le parti stabili del prompt con cache_control, le paghi una volta in scrittura (1,25x per 5 minuti, 2x per un’ora) e poi le rileggi a 0,1x, cioè a un decimo del prezzo. Conviene quando hai prefissi lunghi e ripetuti — system prompt, documenti, tool — sopra la soglia minima del modello. Il risparmio dichiarato arriva fino al 90% sui costi e all’85% sulla latenza per i prompt lunghi. Tieni il fisso davanti, il variabile dietro, non toccare ciò che è in cache, e controlla i token di cache nella risposta. È poco codice per un effetto concreto sulla bolletta.

Fausto Pitzalis

Blogger dal 2001, Nativo Digitale, Developer.
Da 15 anni mi occupo di IT per una grande Azienda.
Lavoro per abbattere il Digital Divide.
Visita i miei altri progetti
sardiniamobility.com
www.cyberness.it