Prompt caching: 8 buone pratiche per Claude, OpenAI e Gemini

Che cosa conserva il prompt caching?

Un modello linguistico non ricorda nulla tra una richiesta e l’altra. Se invii cento volte le stesse istruzioni di sistema, lo stesso documento o lo stesso contesto di codice, vengono elaborati cento volte e pagati cento volte. Il prompt caching (cache dei prompt) cambia le cose: il provider elabora una sola volta la parte iniziale della richiesta che non cambia e la conserva; le richieste successive che cominciano allo stesso modo la leggono dalla cache.

Ciò che viene conservato non è il testo in sé, ma gli stati intermedi che il modello calcola mentre elabora quel testo; la prossima sezione lo spiega. Per questo la corrispondenza deve essere esatta: se il prefisso non è identico byte per byte, non si può leggere dalla cache.

Tre concetti si confondono spesso:

Fonte: documentazione di OpenAI, Anthropic, vLLM e GPTCache, 15 ottobre 2026.

Per noi è lavoro di tutti i giorni: quando diffox esamina una pull request, molti agenti specializzati leggono lo stesso contesto in chiamate separate (come funziona lo spieghiamo in un altro articolo).

Come funziona la cache

Prima di cominciare a generare la risposta, un modello linguistico legge tutto l’input; questa fase si chiama prefill. Intanto il modello calcola per ogni token degli stati intermedi chiamati chiave (key) e valore (value). La documentazione di OpenAI li chiama stati KV: mentre genera la risposta, il modello usa questi stati per tornare ai token precedenti. È questo che il prompt caching conserva: non il testo, ma i tensori che il modello calcola elaborandolo.

Il vantaggio nasce da qui. Se il prefisso è in cache, il modello salta il calcolo di quella parte ed elabora solo i token nuovi. La documentazione di vLLM spiega anche dove finisce il guadagno: la cache accorcia l’elaborazione dell’input, non la generazione dei token nuovi. Per questo a guadagnare di più dalla cache sono i lavori con un prefisso lungo e una risposta breve. L’articolo Prompt Cache ha misurato un tempo al primo token ridotto fino a 8 volte su GPU e fino a 60 volte su CPU.

La stessa struttura spiega perché il prefisso deve essere identico byte per byte. Il documento di design di vLLM identifica ogni blocco in cache con due cose: i token del blocco stesso e i token del prefisso che lo precede. Quindi la stessa frase, se davanti ha un testo diverso, è un blocco diverso. Basta una data aggiunta all’inizio perché tutti i blocchi successivi diventino nuovi; la cache serve solo fino al punto in cui c’è la modifica.

E questi stati non sono piccoli. L’articolo su PagedAttention scrive che la memoria della KV cache di ogni richiesta è enorme e cresce e si riduce nel corso della richiesta. È per questo che i provider limitano la cache a pochi minuti: secondo la documentazione di Google Cloud la cache in memoria è limitata e le voci vengono eliminate quando serve spazio. Anche Anthropic dice che questi stati restano solo in memoria e non vengono conservate in modo permanente.

Come si attiva il prompt caching con quattro provider e quanto si risparmia

Tutti e quattro i provider supportano la cache, ma cambiano il modo di attivarla, il prefisso minimo e il prezzo. I dati della tabella vengono dalla documentazione di ciascun provider, consultata il 15 ottobre 2026.

Fonte: documentazione dei provider, 15 ottobre 2026. I moltiplicatori si riferiscono al prezzo dell’input senza cache. La riga di Google Cloud vale per Gemini 2.5 e successivi.

Su Anthropic e sui modelli OpenAI da GPT-5.6 in poi, scrivere in cache costa più che inviare gli stessi token senza cache, mentre leggere costa molto meno. Per questo una cache che scrive a 1,25× si ripaga alla prima lettura, e la cache da 1 ora di Anthropic, che scrive a 2×, alla seconda. Nella cache esplicita di Gemini la scrittura ha il prezzo standard, ma si paga l’archiviazione per ogni ora in cui la cache resta attiva; la convenienza dipende da quante letture si fanno e da quanto a lungo si tiene la cache.

Con la Claude API, quando molte chiamate leggono lo stesso contesto, metti il marcatore sul blocco comune e l’istruzione specifica di ogni chiamata dopo. ephemeral è per ora l’unico tipo di cache supportato; il nome del modello è quello dell’esempio della documentazione:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<contesto comune: lo stesso testo in ogni chiamata>",
      "cache_control": {"type": "ephemeral"}
    },
    {
      "type": "text",
      "text": "<istruzione specifica di questa chiamata>"
    }
  ],
  "messages": [
    {"role": "user", "content": "<la domanda di questa chiamata>"}
  ]
}

Per quanto tempo la cache resta calda?

Una voce in cache non resta per sempre. La documentazione di Claude Code descrive lo stato con due parole: finché la voce è entro la sua durata (il TTL, time to live) la cache è calda (warm), quando è scaduta è fredda (cold). Con la cache calda la richiesta successiva legge il prefisso a basso costo; con la cache fredda lo elabora da capo e paga la scrittura.

Fonte: documentazione dei provider, 15 ottobre 2026. La durata della cache implicita di Gemini non è nella documentazione; su Google Cloud è al massimo 24 ore e la maggior parte delle voci viene eliminata prima.

La durata funziona come un timer, con due dettagli importanti. Su Anthropic il timer parte dall’inizio della richiesta, non dalla fine della risposta: se lo streaming della risposta è durato 4 minuti, la richiesta successiva sullo stesso prefisso deve partire entro circa 1 minuto. Su Anthropic, OpenAI e Bedrock, poi, ogni cache hit fa ripartire il timer da capo; un traffico regolare tiene la cache calda da solo.

Nella maggior parte dei provider non esiste un endpoint che dica se la cache è ancora calda. L’eccezione è la cache esplicita di Gemini: cachedContents.get restituisce sempre l’ora di scadenza (expireTime), non il contenuto. Su Anthropic, OpenAI e Bedrock lo capisci solo dalla risposta successiva: se il numero di token letti dalla cache scende a zero, o il prefisso è cambiato o la voce si è raffreddata. Lo strumento cache diagnostics di Anthropic distingue i due casi: se le richieste sono identiche e la lettura è zero, la voce è scaduta.

In Claude Code la durata dipende da come paghi. Secondo la documentazione, con un abbonamento Claude la conversazione principale usa una cache di 1 ora, finché resti entro l’uso incluso nel tuo piano. Quando passi ai crediti di utilizzo, usi una chiave API o un provider cloud, la cache è di 5 minuti. I subagenti hanno 5 minuti anche con l’abbonamento. Puoi cambiare la durata con l’impostazione promptCacheTtl o con la variabile CLAUDE_CODE_PROMPT_CACHE_TTL.

Lo stato lo vedi in tre punti. /usage dice se la cache è calda o fredda, insieme alla durata in vigore. Nel JSON che arriva alla status line (la riga di stato), l’oggetto prompt_cache contiene i campi warm, ttl ed expires_at; l’ultimo indica quando la cache si raffredderà. Anche l’orologio della cache nell’estensione per VS Code fa il conto alla rovescia da una durata di 5 minuti o di 1 ora e mostra i minuti rimanenti; con la cache di 1 ora parte da 60 minuti.

Tre cose a cui fare attenzione:

• L’intervallo tra le richieste deve restare sotto la durata. Ogni richiesta che arriva più di 5 minuti dopo la precedente riscrive il prefisso. Anthropic consiglia di restare sulla cache di 5 minuti se il prefisso viene usato più spesso di una volta ogni 5 minuti, perché il rinnovo è gratuito.
• Una durata lunga non è gratis. Su Anthropic la scrittura con la cache di 1 ora costa il doppio e non si ripaga finché il prefisso non viene letto due volte; nella cache esplicita di Gemini si paga l’archiviazione per ogni ora.
• La prima richiesta dopo una lunga pausa costa cara. Con la cache fredda la prima richiesta scrive tutto il prefisso. Puoi riscaldare la cache prima che arrivi la richiesta vera: su Anthropic con max_tokens: 0, sui modelli OpenAI da GPT-5.6 in poi con prompt_cache_options.prewarm.

In un esempio con dieci chiamate il prefisso costa il 78,5% in meno

I numeri sono tondi e ipotetici; mostrano solo i moltiplicatori della documentazione. Supponiamo che dieci chiamate leggano un prefisso comune di 50.000 token. L’unità è un token pagato al prezzo base dell’input; la scrittura vale 1,25×, la lettura 0,1×. Usano questi moltiplicatori la cache di 5 minuti di Anthropic e la maggior parte dei modelli OpenAI da GPT-5.6 in poi.

senza cache    10 × 50.000 × 1      = 500.000

con cache       1 × 50.000 × 1,25   =  62.500   la prima chiamata scrive
              + 9 × 50.000 × 0,1    =  45.000   nove chiamate leggono
                                    = 107.500

Dieci chiamate avviate una dopo l’altra pagano per il prefisso l’equivalente di 107.500 token: il 78,5% in meno dei 500.000 senza cache. Con un modello che ha un moltiplicatore di lettura di 0,05× il totale scende a 85.000. Con la cache di 1 ora la scrittura sale a 100.000 e il totale arriva a 145.000.

La terza barra mostra il caso peggiore: le stesse dieci chiamate partono tutte insieme. Nessuna può leggere ciò che ha scritto un’altra e, se scrivono tutte il prefisso, il totale arriva a 625.000. Costa il 25% in più che non attivare affatto la cache. Il perché è più sotto, nella sezione sulle chiamate in parallelo.

Le 8 regole per un alto tasso di cache hit

La documentazione dei quattro provider dice le stesse cose sui cache hit. Ognuna delle regole qui sotto compare nella documentazione di almeno due provider.

La seconda è quella che si salta più spesso. Una riga nelle note di rilascio di Claude Code lo mostra: togliere la data dal prompt di sistema ha alzato il tasso di cache hit. La data cambia ogni giorno, e se sta all’inizio del prefisso la prima richiesta di ogni nuovo giorno riscrive tutto il prefisso.

Due regole valgono per un solo provider. Sui modelli OpenAI precedenti a GPT-5.6, alle richieste che condividono lo stesso prefisso si dà un prompt_cache_key fisso. Questa chiave aiuta a instradarle verso la stessa cache, e la documentazione consiglia circa 15 richieste al minuto per chiave. Anthropic invece chiede che l’ordine delle chiavi JSON nelle chiamate agli strumenti sia stabile. Secondo la documentazione alcuni linguaggi, come Swift e Go, ordinano le chiavi a caso, e lo stesso contenuto parte con byte diversi.

Che cosa invalida la cache

Su Anthropic e su Bedrock la cache segue una gerarchia: tools, system, messages. Una modifica a un livello invalida quel livello e tutti quelli che vengono dopo. Ecco sei casi tra quelli che elenca la documentazione di Anthropic:

Attivare o disattivare le citazioni ha lo stesso effetto della ricerca web; aggiungere o togliere un’immagine dal prompt, lo stesso effetto di tool_choice. Il caso che la documentazione chiama «errore comune» è la quarta scheda: se il breakpoint sta su un blocco che contiene un timestamp o il messaggio dell’utente, ogni richiesta scrive una voce nuova e nessuna richiesta può leggere. Il sistema cerca all’indietro al massimo 20 blocchi; ma quello che cerca non è il contenuto rimasto uguale, è una voce scritta da una richiesta precedente. La scrittura avviene solo sul breakpoint. Per questo il marcatore va sull’ultimo blocco che resta identico da una richiesta all’altra.

La cache con le chiamate in parallelo

Avviare insieme le chiamate che leggono lo stesso prefisso sembra naturale. La documentazione di Anthropic è chiara: con richieste simultanee, una voce di cache diventa disponibile solo dopo l’inizio della prima risposta; se vuoi che le richieste in parallelo leggano dalla cache, aspetta la prima risposta prima di inviare le altre. Anche OpenAI scrive che la cache sta su singole macchine e che oltre 15 richieste al minuto possono finire su altre macchine.

Non serve che la prima risposta finisca, basta che cominci. La documentazione indica tre strade:

• Invia la prima chiamata da sola. Claude Code lo fa da sé quando, in un workflow, avvia insieme agenti che condividono lo stesso prefisso: trattiene tutti tranne il primo finché non comincia la risposta del primo agente; per impostazione predefinita l’attesa è al massimo di 5.000 millisecondi.
• Riscalda la cache in anticipo. Una richiesta inviata con max_tokens: 0 scrive in cache sul breakpoint e torna senza generare output; i token di output non si pagano. Il marcatore deve stare sul blocco comune, e l’impostazione di thinking e il valore di output_config.effort devono essere uguali a quelli delle chiamate vere. Viene rifiutata insieme a impostazioni che richiedono un output (per esempio stream: true).
• Nei lavori in batch usa la cache di 1 ora. Nella Batch API le richieste vengono elaborate in un ordine qualsiasi e la lettura non è garantita. La documentazione consiglia di inviare prima, con la cache di 1 ora, una sola richiesta che porta il prefisso comune, e le altre quando questa è completata.

Come misurare i cache hit

Non dare per scontato che la cache funzioni: controllalo nella risposta. Tutti e quattro i provider riportano i token letti dalla cache in un campo a parte, nei dati di utilizzo della risposta:

Fonte: documentazione dei provider, 15 ottobre 2026.

Il tasso di cache hit è la quota di token letti dalla cache sul totale dell’input; OpenAI lo definisce così e consiglia di aggregarlo per utente, per workspace o per giorno. Il totale dell’input va calcolato bene: su Anthropic e su Bedrock il campo dell’input non conta i token letti o scritti in cache, e il totale è la somma dei tre campi; su Gemini promptTokenCount include già i token letti dalla cache.

L’input totale è la somma dei tre campi. input_tokens da solo non mostra tutto l’input: conta solo ciò che viene dopo l’ultimo breakpoint. Se tutto funziona, alla prima chiamata il campo di scrittura vale quanto la lunghezza del prefisso, e nelle successive lo stesso numero passa al campo di lettura. Se sono a zero tutti e due, il prompt non è finito in cache; la causa più probabile è un prefisso sotto la soglia minima. Se il campo di scrittura resta alto a ogni chiamata, qualcosa nel prefisso sta cambiando.

Noi registriamo separatamente i tre campi di ogni chiamata. Una chiamata senza dati di utilizzo per noi non vale zero, vale «non misurata»: un vuoto scritto come zero si legge come una chiamata gratuita.

Quando la cache non conviene

La cache non conviene con ogni carico di lavoro. Prima di attivarla, controlla quattro casi:

• Se il prefisso viene letto una sola volta. Se la scrittura costa 1,25 volte e nessuna seconda chiamata legge il prefisso, paghi il 25% in più.
• Se l’intervallo tra le chiamate supera la durata. Ogni volta la cache è fredda e il prefisso viene riscritto.
• Se il prefisso è sotto la lunghezza minima. La richiesta funziona, la cache no; e non arriva nessun errore.
• Se il prefisso cambia a ogni richiesta. Una data all’inizio costringe ogni richiesta a riscrivere la cache.

Il guadagno non è solo sul prezzo: con i prefissi lunghi si accorcia anche il tempo al primo token. Sul rate limit i provider si dividono: secondo Anthropic e Bedrock, su Claude i token letti dalla cache non vengono scalati dal rate limit; su OpenAI invece contano nel limite di token al minuto.

In diffox gli agenti specializzati di una review leggono lo stesso contesto comune: il diff della modifica e il contesto dei file. Questo contesto sta all’inizio della richiesta, in un unico blocco, ed è lui a portare il marcatore della cache; la prima chiamata parte da sola, le altre partono subito dopo in parallelo. I token che ogni chiamata scrive e legge vengono registrati separatamente.