Le meccaniche della cache, le fasce di prezzo, le durate del TTL e le soglie minime di token cambiano man mano che Anthropic aggiorna la piattaforma. Non fare affidamento su numeri specifici di guide di terze parti. Controlla sempre la documentazione ufficiale sul prompt caching e la pagina Modelli e Prezzi per i valori attuali.
Economia del Prompt Caching
Ogni volta che chiami l'API di Claude, paghi per ogni token di input che invii — incluso il tuo system prompt, le tue definizioni di strumenti e qualsiasi contesto che inietti. Se stai facendo molte chiamate con lo stesso grande prefisso, stai pagando per elaborare quel prefisso da zero ogni singola volta.
Il prompt caching cambia questo. Marchi una porzione stabile del tuo prompt come memorizzabile in cache. La prima chiamata la elabora e la archivia. Le chiamate successive che colpiscono la cache saltano quell'elaborazione — e pagano una frazione della tariffa normale per quei token.
I risparmi non sono cosmetici. Per le applicazioni con system prompt grandi e stabili o con contesto pesante, il caching può cambiare l'economia di una funzionalità da "troppo costosa da mandare in produzione" a "praticamente gratis da far girare".
Il modello mentale: prefisso stabile, suffisso volatile
Pensa a ogni chiamata API come a due parti:
Il prefisso stabile — contenuto che non cambia tra le chiamate. È qui che si applica il caching. Esempi:
- Il tuo system prompt
- Le definizioni di strumenti
- Un grande documento di riferimento o una codebase che inietti a ogni chiamata
- Un lungo blocco di esempi few-shot
Il suffisso volatile — contenuto che cambia a ogni chiamata. È qui che il caching non si applica. Esempi:
- Il messaggio utente corrente
- Dati in tempo reale che inietti per ogni richiesta
- Cronologia della conversazione che cresce a ogni turno
La regola è semplice: struttura i tuoi prompt in modo che il contenuto stabile venga prima e il contenuto che cambia venga per ultimo. I cache breakpoint sono posizionali — tutto ciò che precede il breakpoint marcato è idoneo al caching; tutto ciò che segue no.
Se metti contenuto dinamico prima di contenuto statico, rompi la cache, perché il prefisso cambia a ogni richiesta.
Come funziona il modello di costo
Il prompt caching introduce una suddivisione a tre vie nel modo in cui vengono tariffati i token di input:
| Tipo di token | Quando si verifica | Costo rispetto all'input normale |
|---|---|---|
| Scrittura in cache | Prima chiamata, o dopo la scadenza della cache | Più alto dell'input normale |
| Lettura dalla cache | Chiamate successive che colpiscono la cache | Molto più basso dell'input normale |
| Input regolare | Token dopo l'ultimo cache breakpoint | Tariffa normale |
I moltiplicatori esatti sono sulla pagina ufficiale dei prezzi e fluttuano — controllali direttamente. Ciò che non cambia è la struttura: le scritture costano più del normale, le letture costano molto meno. Il punto di pareggio — quando hai fatto abbastanza chiamate in cache da recuperare l'overhead di scrittura — arriva rapidamente su qualsiasi prompt con contenuto stabile sostanziale.
La latenza segue lo stesso pattern. Le letture dalla cache saltano l'elaborazione completa della porzione in cache, il che riduce in modo significativo il time-to-first-token sulle chiamate con grandi prefissi.
Quando il prompt caching aiuta
Il caching ripaga quando sono vere entrambe le condizioni:
- Hai un prefisso stabile sostanziale (esiste una soglia minima di token al di sotto della quale il caching non è disponibile — controlla la documentazione attuale per il numero esatto per modello).
- Quel prefisso viene riutilizzato abbastanza spesso da colpire la cache più che occasionalmente.
Scenari in cui il caching è una scelta naturale:
- Q&A su documenti — lo stesso grande documento viene iniettato per molte domande utente.
- Assistenti di codice — una grande codebase o un albero di file è incluso in ogni richiesta.
- Cicli agentici — lo stesso system prompt e le stesse definizioni di strumenti vengono inviati a ogni passo di un workflow multi-step.
- Agenti conversazionali con istruzioni lunghe — una persona dettagliata, un set di regole o una base di conoscenza che non cambia mai da una chiamata all'altra.
- Elaborazione batch — molti input vengono eseguiti rispetto allo stesso template.
Quando il prompt caching non aiuta
Il caching non è utile quando:
- I tuoi prompt sono brevi (sotto la soglia minima di token memorizzabili in cache).
- Il tuo prefisso cambia a ogni chiamata — iniettare un timestamp, un contesto specifico per utente o qualsiasi personalizzazione nella parte "stabile" invalida la cache.
- Fai chiamate poco frequenti con lunghi intervalli tra di esse. Il contenuto in cache scade dopo un TTL (una durata che puoi configurare, entro i limiti supportati dall'API). Se il tuo traffico è rado, pagherai per lo più costi di scrittura con poche letture.
- Il tuo prefisso è piccolo rispetto al contenuto dinamico per chiamata. I risparmi scalano con la dimensione di ciò che è in cache.
Strutturare i prompt per essere cache-friendly
L'unico requisito strutturale è l'ordine: il contenuto stabile deve venire prima del contenuto volatile.
In pratica:
[System prompt — istruzioni, persona, regole]
[Definizioni di strumenti — se statiche]
[Grandi documenti o contesto iniettati — se gli stessi tra le chiamate]
--------- cache breakpoint qui ---------
[Contenuto dinamico per chiamata — messaggio utente, frammenti recuperati specifici per questa richiesta]
Marchi il breakpoint con un campo cache_control sull'ultimo blocco che vuoi includere nella cache. Tutto ciò che precede quel marcatore è idoneo al caching; tutto ciò che segue è input regolare.
Puoi collocare fino a quattro breakpoint espliciti in una singola richiesta. Questo è utile quando parti diverse del tuo prompt cambiano a frequenze diverse — ad esempio, le definizioni di strumenti cambiano raramente, la cronologia della conversazione cambia a ogni turno. Ogni sezione può avere il proprio breakpoint.
Regole di invalidazione della cache
La cache è sensibile all'ordine. Qualsiasi modifica a un blocco in cache, o a qualsiasi blocco che lo precede nel prompt, invalida la cache a quel breakpoint e a tutti quelli successivi.
Le modifiche alle definizioni di strumenti invalidano tutte le cache. Le modifiche al system prompt invalidano la cache del system e dei messaggi. Le modifiche a metà conversazione interessano solo la cache dei messaggi.
L'implicazione pratica: se stai iniettando qualcosa che cambia per ogni richiesta, assicurati in modo assoluto che viva dopo l'ultimo cache breakpoint, non prima o al suo interno.
Pre-warming e monitoraggio
Puoi pre-riscaldare la cache prima che arrivi il traffico degli utenti inviando una richiesta con max_tokens: 0 — questo scrive la cache senza generare output. Utile per i job batch o per anticipare il costo di scrittura durante le ore fuori picco.
Il campo usage della risposta dell'API ti dice quanti token sono stati letti dalla cache (cache_read_input_tokens), scritti in cache (cache_creation_input_tokens) e fatturati come input regolare. Monitora questi valori per verificare che il tuo caching stia effettivamente colpendo e per misurare i risparmi che stai realizzando.
Usa il Calcolatore di Costi per modellare i risparmi attesi prima di impegnarti in un'architettura di caching.
In conclusione
Il prompt caching non è una micro-ottimizzazione. Per qualsiasi applicazione che invia ripetutamente lo stesso grande prefisso, è una decisione economica strutturale. Il modello per ragionarci è semplice: il contenuto stabile va prima, il contenuto volatile va per ultimo, metti il breakpoint al confine.
Se stai sviluppando sull'API e non hai ancora guardato al caching, controlla i tuoi prompt attuali per sezioni stabili grandi. Se esistono, abilitare il caching di solito richiede poco sforzo e i risparmi sono reali.