Un caso studio su come Claude raggiunge il 92% di cache hit-rate
Ogni volta che un agente AI fa un passo, paga una tassa.
Rilegge tutto da capo.
Le istruzioni di sistema. Le definizioni degli strumenti. Il contesto del progetto che aveva già caricato tre turni fa. Tutto. Ogni singolo turno.
Questa è la tassa sul contesto. E per i flussi di lavoro agentici di lunga durata, è spesso la voce più costosa dell'intera infrastruttura AI.
Ecco i numeri: un prompt di sistema con 20.000 token eseguito per 50 turni significa 1 milione di token di computazione ridondante fatturati a prezzo pieno, che producono zero nuovo valore.
La soluzione è il prompt caching. Ma per usarlo bene, devi capire cosa succede realmente sotto il cofano.
Inizia con Cosa Cambia e Cosa Non Cambia
Prima di poter ottimizzare qualsiasi cosa, devi pensare chiaramente alla struttura del prompt (contesto) di un agente.
Ogni richiesta che il tuo agente invia ha due parti fondamentalmente diverse:
Il prefisso statico: include istruzioni di sistema, definizioni degli strumenti, contesto del progetto, linee guida comportamentali. Questo contenuto è identico in ogni singolo turno di una sessione.
La coda dinamica: messaggi utente, output degli strumenti, osservazioni dal terminale. Questo è unico per ogni richiesta e cresce man mano che la conversazione procede.
Questa distinzione è tutto. Il prefisso statico è la parte costosa che continui a ricalcolare senza motivo. La coda dinamica è l'unica parte che ha effettivamente bisogno di una computazione fresca.
Il prompt caching funziona memorizzando lo stato matematico del prefisso statico, in modo che le richieste future possano saltare completamente il suo ricalcolo. Paghi per elaborare quel prefisso una volta. Ogni turno successivo legge dalla memoria invece.
Perché Funziona: Cosa Fa Realmente un Trasformatore
Per capire davvero perché il caching è così efficace, devi capire cosa succede dentro il modello quando legge il tuo prompt.
Ogni richiesta di inferenza LLM ha due fasi:
Fase 1: Prefill (Prefill)
Qui è dove il modello elabora il tuo prompt di input completo. È vincolato dal calcolo, il che significa che esegue dense moltiplicazioni di matrici su ogni token nel tuo contesto. Il modello legge tutto e costruisce una rappresentazione. Questa è la fase lenta e costosa.
Fase 2: Decode (Decodifica)
Qui è dove il modello genera token di output, uno alla volta. È vincolato dalla memoria piuttosto che dal calcolo, perché il modello passa la maggior parte del tempo a leggere lo stato precedentemente calcolato piuttosto che eseguire calcoli pesanti.
Durante la fase di prefill, il trasformatore costruisce tre vettori per ogni token: una Query, una Key e un Value. Il meccanismo di attenzione li usa per capire come ogni token si relaziona a ogni altro token nella sequenza.
Ecco l'intuizione critica: i vettori Key e Value dipendono solo dai token che li hanno preceduti. Una volta calcolati per un dato prefisso, non devono mai cambiare.
L'illustrazione qui sotto spiega visivamente ciò di cui abbiamo appena parlato:
Senza caching, quei tensori Key-Value vengono buttati via nel momento in cui una richiesta termina. La richiesta successiva ricomincia da capo e li ricalcola per tutti i 20.000 token di nuovo.
Il KV caching risolve questo problema memorizzando quei tensori. L'infrastruttura li tiene sui server di inferenza, indicizzati da un hash crittografico del testo di input. Quando arriva una nuova richiesta con lo stesso prefisso, l'hash corrisponde, i tensori vengono recuperati immediatamente e il modello salta tutta quella computazione.
Questo riduce la complessità computazionale da O(n²) per token generato a O(n). Per un prefisso di 20.000 token ripetuto per 50 turni, è una riduzione enorme.
L'Economia
Capire la struttura dei prezzi è ciò che rende questa decisione architetturale così consequenziale.
Ecco come Anthropic prezza il caching nelle loro famiglie di modelli:
Tre numeri da interiorizzare:
- Le letture dalla cache costano il 10% del prezzo di input base, uno sconto del 90% su ogni token letto dalla cache
- Le scritture nella cache costano il 25% in più rispetto al prezzo di input base, un piccolo premio per memorizzare i tensori KV
- Il caching esteso di 1 ora costa 2 volte il prezzo base
Il calcolo funziona solo se il tuo cache hit-rate rimane alto. Il che ci porta al miglior esempio reale di come appare in pratica.
Claude Code: Un Percorso Guidato di una Sessione di 30 Minuti
Claude Code è costruito interamente attorno a un obiettivo: mantenere la cache calda.
Per capire cosa significa concretamente, esaminiamo come appare una tipica sessione di coding di 30 minuti e tracciamo esattamente cosa viene fatturato e cosa no.
Minuto 0: Inizio Sessione
Claude Code carica il suo prompt di sistema e le definizioni degli strumenti. Legge anche il file CLAUDE.md nella root del tuo progetto, che descrive il codebase e le convenzioni. Questo carico supera regolarmente i 20.000 token.
Questo è il momento più costoso dell'intera sessione. Ogni singolo token è nuovo. Ma paghi questo costo solo una volta.
Minuti da 1 a 5: Primi Comandi
Scrivi la tua prima istruzione, qualcosa come "guarda il modulo di autenticazione e suggerisci miglioramenti."
Claude Code invia un Explore Subagent (Sottoagente di Esplorazione). Naviga attraverso il codebase, apre file, esegue comandi grep e costruisce un'immagine del codice rilevante. Tutto questo viene aggiunto alla coda dinamica.
La fondazione statica di 20.000 token? Già in cache. Viene letta a $0.30/MTok invece di $3.00/MTok. Stai pagando solo per i nuovi output degli strumenti e il tuo messaggio.
Minuti da 6 a 15: Lavoro Profondo
Il Plan Subagent (Sottoagente di Pianificazione) riceve i risultati dall'Explore Subagent. Invece di passare i risultati grezzi alla lettera (che farebbe esplodere inutilmente la coda dinamica), Claude Code passa un riepilogo conciso. Questo mantiene il suffisso gestibile e la cache efficiente.
Il pianificatore produce un piano di implementazione strutturato. Lo esamini, lo approvi e Claude Code inizia ad apportare modifiche. Ogni turno in questo ciclo legge il prefisso di 20.000 token dalla cache. Ogni cache hit resetta il TTL, mantenendo la cache calda per i turni futuri.
Minuti da 16 a 25: Iterazione
Chiedi modifiche. Claude Code rivede il suo approccio. Altre chiamate a strumenti, più output dal terminale. La coda dinamica sta crescendo, ma rappresenta solo il contenuto nuovo e unico di questa sessione.
A questo punto, la sessione ha elaborato centinaia di migliaia di token in totale. Ma la fondazione di 20.000 token è stata letta dalla cache in ogni singolo turno.
Minuto 28: Esecuzione di /cost
Senza caching, una sessione come questa supera facilmente i 2 milioni di token. Alle tariffe di Sonnet 4.5, siamo intorno a $6.00.
Con il caching che funziona ad alta efficienza:
- La stragrande maggioranza dei token viene letta dalla cache a $0.30/MTok
- Solo i nuovi token della coda dinamica vengono calcolati freschi
In pratica, ti aspetteresti una riduzione dei costi superiore all'80% su un singolo compito. Ora moltiplicalo per ogni utente, ogni giorno.
Per riassumere, ecco come appare la disposizione del prompt di sistema mentre la sessione continua:
La Regola che Rompe Tutto
Ecco la cosa più controintuitiva del prompt caching.
1 + 2 = 3. Ma 2 + 1 è un cache miss.
L'infrastruttura esegue l'hash del prompt. L'hash è un identificatore per la crittografia. L'hash cambia se qualcosa in quell'ordine cambia, anche se due elementi sono in un ordine diverso. La cache è vuota. L'intero prefisso viene ricalcolato a prezzo pieno.
Tre regole che seguono da questo:
- Non aggiungere o rimuovere strumenti durante una sessione. Il prefisso memorizzato nella cache include gli strumenti. Cambiare gli strumenti rende inutile tutto ciò che viene dopo.
- Non cambiare mai modello a metà sessione. Le cache sono specifiche per modello. Passare a un modello più economico a metà conversazione richiede la ricostruzione dell'intera cache.
- Non cambiare mai il prefisso per cambiare lo stato. Invece, Claude Code aggiunge un tag al prossimo messaggio utente che ricorda al sistema. Il prefisso non cambia mai.
Cosa Significa per Te
Tutto quanto sopra spiega come Claude Code gestisce il caching. Le stesse regole si applicano se stai creando il tuo agente.
Ecco come strutturare i tuoi prompt:
- All'inizio ci sono le istruzioni di sistema e le regole. Non cambiarle a metà.
- Carica tutti gli strumenti che ti serviranno in anticipo. Non aggiungerli o rimuoverli.
- Il contesto e i documenti recuperati dopo. Statici per la durata.
- In fondo, la cronologia della conversazione e gli output degli strumenti.
Con l'auto-caching attivato, il punto di interruzione si sposta automaticamente in avanti man mano che la conversazione procede.
Claude Code ha il controllo della propria cache. Anthropic ha appena aggiunto l'auto-caching alla sua API, così puoi fare lo stesso per il tuo agente.
Senza auto-caching, dovevi ricordare dove si trovavano i confini dei token. Un confine sbagliato significava non accedere alla cache.
Usa il fork cache-safe per compattare entro il limite di contesto. Usa lo stesso prompt di sistema, strumenti e conversazione, quindi aggiungi la compattazione come un nuovo messaggio.
La chiamata di compattazione sembra quasi identica all'ultima. Il prefisso memorizzato nella cache viene riutilizzato. L'unica cosa fatturata come nuova è l'istruzione di compattazione.
Per vedere se un'API funziona, tieni d'occhio questi tre campi in ogni risposta:
- cache_creation_input_tokens: token messi in memoria
- cache_read_input_tokens: token letti dalla memoria
- input_tokens: token elaborati come al solito
Il tuo punteggio di efficienza della cache è il numero di token letti rispetto al numero di token creati. Tienilo d'occhio come tieni d'occhio il tempo di attività.
Punti Chiave
Il prompt caching non è una funzionalità che attivi. È una disciplina architetturale attorno a cui costruisci.
Claude Code è il miglior esempio di come appare quel campo quando viene fatto su larga scala.
Un cache hit-rate del 92%. Una riduzione dei costi dell'81%.
Questo è il progetto se stai creando agenti. Non puoi ignorare la tassa; esiste. L'unica cosa che conta è se la stai pagando o te ne stai liberando.
