Cache dei prompt
Memorizza nella cache i prefissi dei prompt con cache_control per ridurre costi e latenza, usando la cache automatica o breakpoint espliciti con TTL di 5 minuti o 1 ora.
L’utilizzo varia in base al prodotto
cache_control, al livello superiore o sui blocchi.Il “prompt caching” (cache dei prompt) ottimizza il tuo utilizzo dell’API consentendo all’API di riprendere da prefissi specifici nei tuoi prompt. Questo riduce significativamente i tempi di elaborazione e i costi per attività ripetitive o prompt con elementi costanti.
Esistono due modi per abilitare la cache dei prompt:
- Cache automatica: Aggiungi un singolo campo
cache_controlal livello superiore della tua richiesta. Il sistema applica automaticamente il “cache breakpoint” (punto di interruzione della cache) all’ultimo blocco memorizzabile nella cache e lo sposta in avanti man mano che le conversazioni crescono. Ideale per conversazioni multi-turno in cui la cronologia dei messaggi in crescita deve essere memorizzata automaticamente nella cache. - Cache breakpoint espliciti: Posiziona
cache_controldirettamente su singoli blocchi di contenuto per un controllo granulare su cosa esattamente viene memorizzato nella cache.
Un modo per iniziare è con la cache automatica:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages=[
{
"role": "user",
"content": "Analyze the major themes in 'Pride and Prejudice'.",
}
],
)
print(response.usage.model_dump_json())Con la cache automatica, il sistema memorizza nella cache tutto il contenuto fino all’ultimo blocco memorizzabile incluso. Nelle richieste successive con lo stesso prefisso, il contenuto nella cache viene riutilizzato automaticamente.
Come funziona la cache dei prompt
Quando invii una richiesta con la cache dei prompt abilitata:
- Il sistema verifica se un prefisso del prompt, fino a un breakpoint di cache specificato, è già nella cache da una query recente.
- Se viene trovato, utilizza la versione nella cache, riducendo tempi di elaborazione e costi.
- Altrimenti, elabora il prompt completo e memorizza nella cache il prefisso non appena la risposta inizia.
Questo è particolarmente utile per:
- Prompt con molti esempi
- Grandi quantità di contesto o informazioni di base
- Attività ripetitive con istruzioni costanti
- Lunghe conversazioni multi-turno
Per impostazione predefinita, la cache ha una durata di 5 minuti. La cache viene aggiornata senza costi aggiuntivi ogni volta che il contenuto nella cache viene utilizzato.
La durata viene misurata dall’inizio della richiesta che scrive o legge la voce della cache, non dalla fine della sua risposta. Il tempo impiegato per generare una risposta viene conteggiato nella durata: se una risposta impiega 4 minuti per lo streaming, una richiesta successiva che riutilizza lo stesso prefisso nella cache deve iniziare entro circa 1 minuto dal completamento di quella risposta.
Se 5 minuti sono troppo pochi, puoi usare una durata della cache di 1 ora a un costo aggiuntivo (consulta Prezzi).
La cache dei prompt copre l’intero prefisso: tools, system e messages (in quest’ordine), fino al blocco designato con cache_control incluso.
Prezzi
La cache dei prompt ha i propri prezzi. La seguente tabella mostra il prezzo per milione di token per ciascun modello supportato:
| Modello | Token base | Caching dei prompt | |||
|---|---|---|---|---|---|
| Nome | Input | Output | Scritture 5 min | Scritture cache 1 h | Hit e aggiornamenti |
Claude Fable 5.2For demanding reasoning and long-horizon agentic work | 8 USD / MTok | 40 USD / MTok | 10 USD / MTok | 16 USD / MTok | 0,20 USD / MTok1 |
Claude Opus 5.5For long-running agentic coding and knowledge work | 4 USD / MTok | 20 USD / MTok | 5 USD / MTok | 8 USD / MTok | 0,20 USD / MTok2 |
Claude Sonnet 5.5The best combination of speed and intelligence | 2 USD / MTok | 10 USD / MTok | 2,50 USD / MTok | 4 USD / MTok | 0,10 USD / MTok2 |
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing | 0,10 USD / MTokper prompt fino a 100.000 token | 0,50 USD / MTok | 0,125 USD / MTok | 0,20 USD / MTok | 0,01 USD / MTok |
0,50 USD / MTokper prompt oltre 100.000 token | 2,50 USD / MTok | 0,625 USD / MTok | 1 USD / MTok | 0,05 USD / MTok | |
8 USD / MTok | 40 USD / MTok | 10 USD / MTok | 16 USD / MTok | 0,20 USD / MTok1 | |
10 USD / MTok | 50 USD / MTok | 12,50 USD / MTok | 20 USD / MTok | 0,25 USD / MTok1 | |
10 USD / MTok | 50 USD / MTok | 12,50 USD / MTok | 20 USD / MTok | 0,25 USD / MTok1 | |
10 USD / MTok | 50 USD / MTok | 12,50 USD / MTok | 20 USD / MTok | 1 USD / MTok | |
10 USD / MTok | 50 USD / MTok | 12,50 USD / MTok | 20 USD / MTok | 1 USD / MTok | |
5 USD / MTok | 25 USD / MTok | 6,25 USD / MTok | 10 USD / MTok | 0,50 USD / MTok | |
5 USD / MTok | 25 USD / MTok | 6,25 USD / MTok | 10 USD / MTok | 0,50 USD / MTok | |
5 USD / MTok | 25 USD / MTok | 6,25 USD / MTok | 10 USD / MTok | 0,50 USD / MTok | |
5 USD / MTok | 25 USD / MTok | 6,25 USD / MTok | 10 USD / MTok | 0,50 USD / MTok | |
5 USD / MTok | 25 USD / MTok | 6,25 USD / MTok | 10 USD / MTok | 0,50 USD / MTok | |
Claude Opus 4.1 | 15 USD / MTok | 75 USD / MTok | 18,75 USD / MTok | 30 USD / MTok | 1,50 USD / MTok |
Claude Opus 4 | 15 USD / MTok | 75 USD / MTok | 18,75 USD / MTok | 30 USD / MTok | 1,50 USD / MTok |
2 USD / MTok | 10 USD / MTok | 2,50 USD / MTok | 4 USD / MTok | 0,20 USD / MTok | |
3 USD / MTok | 15 USD / MTok | 3,75 USD / MTok | 6 USD / MTok | 0,30 USD / MTok | |
3 USD / MTok | 15 USD / MTok | 3,75 USD / MTok | 6 USD / MTok | 0,30 USD / MTok | |
Claude Sonnet 4 | 3 USD / MTok | 15 USD / MTok | 3,75 USD / MTok | 6 USD / MTok | 0,30 USD / MTok |
1 USD / MTok | 5 USD / MTok | 1,25 USD / MTok | 2 USD / MTok | 0,10 USD / MTok | |
1 I cache hit e i refresh su Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1 e Claude Mythos 5.1 hanno un prezzo pari a 0,025x il prezzo base di input.
2 I cache hit e i refresh su Claude Opus 5.5 e Claude Sonnet 5.5 hanno un prezzo pari a 0,05x il prezzo base di input.
Tutti gli altri modelli usano il moltiplicatore standard di 0,1x.
Modelli supportati
La cache dei prompt (sia automatica che esplicita) è supportata su tutti i modelli Claude attivi.
Cache automatica
La cache automatica abilita la cache dei prompt con un solo campo. Invece di posizionare cache_control su singoli blocchi di contenuto, aggiungi un singolo campo cache_control al livello superiore del corpo della richiesta. Il sistema applica automaticamente il breakpoint di cache all’ultimo blocco memorizzabile nella cache.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",
messages=[
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{
"role": "assistant",
"content": "Nice to meet you, Alex! How can I help with your ML work today?",
},
{"role": "user", "content": "What did I say I work on?"},
],
)
print(response.usage.model_dump_json())Come funziona la cache automatica nelle conversazioni multi-turno
Con la cache automatica, il punto della cache si sposta in avanti automaticamente man mano che le conversazioni crescono. Ogni nuova richiesta memorizza nella cache tutto fino all’ultimo blocco memorizzabile, e il contenuto precedente viene letto dalla cache.
| Richiesta | Contenuto | Comportamento della cache |
|---|---|---|
| Richiesta 1 | System + User(1) + Asst(1) + User(2) ◀ cache | Tutto scritto nella cache |
| Richiesta 2 | System + User(1) + Asst(1) + User(2) + Asst(2) + User(3) ◀ cache | Da System fino a User(2) letto dalla cache; Asst(2) + User(3) scritti nella cache |
| Richiesta 3 | System + User(1) + Asst(1) + User(2) + Asst(2) + User(3) + Asst(3) + User(4) ◀ cache | Da System fino a User(3) letto dalla cache; Asst(3) + User(4) scritti nella cache |
Il breakpoint di cache si sposta automaticamente all’ultimo blocco memorizzabile in ogni richiesta, quindi non è necessario aggiornare alcun marcatore cache_control man mano che la conversazione cresce.
Supporto TTL
Per impostazione predefinita, la cache automatica utilizza un TTL di 5 minuti. Puoi specificare un TTL di 1 ora al doppio del prezzo base dei token di input:
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }Combinazione con la cache a livello di blocco
La cache automatica è compatibile con i breakpoint di cache espliciti. Quando vengono usati insieme, il breakpoint di cache automatico utilizza uno dei 4 slot di breakpoint disponibili.
Questo ti consente di combinare entrambi gli approcci. Ad esempio, usa un breakpoint esplicito per memorizzare nella cache il tuo prompt di sistema, mentre la cache automatica gestisce la conversazione:
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}Cosa rimane invariato
La cache automatica utilizza la stessa infrastruttura di cache sottostante. Prezzi, soglie minime di token, requisiti di ordinamento del contesto e la finestra di lookback di 20 blocchi si applicano tutti allo stesso modo dei breakpoint espliciti.
Casi limite
- Se l’ultimo blocco ha già un
cache_controlesplicito con lo stesso TTL, la cache automatica non ha effetto. - Se l’ultimo blocco ha un
cache_controlesplicito con un TTL diverso, l’API restituisce un errore 400. - Se esistono già 4 breakpoint espliciti a livello di blocco, l’API restituisce un errore 400 (nessuno slot rimasto per la cache automatica).
- Se l’ultimo blocco non è idoneo come destinazione del breakpoint di cache automatico, il sistema risale silenziosamente all’indietro per trovare il blocco idoneo più vicino. Se non ne trova nessuno, la cache viene saltata.
Cache breakpoint espliciti
Per un maggiore controllo sulla cache, puoi posizionare cache_control direttamente su singoli blocchi di contenuto. Questo è utile quando devi memorizzare nella cache sezioni diverse che cambiano con frequenze diverse, o hai bisogno di un controllo granulare su cosa esattamente viene memorizzato nella cache.
Strutturare il prompt
Posiziona il contenuto statico (definizioni degli strumenti, istruzioni di sistema, contesto, esempi) all’inizio del tuo prompt. Contrassegna la fine del contenuto riutilizzabile per la cache usando il parametro cache_control.
I prefissi della cache vengono creati nel seguente ordine: tools, system, poi messages. Questo ordine forma una gerarchia in cui ogni livello si basa sui precedenti.
Come funziona il controllo automatico dei prefissi
Puoi usare un solo breakpoint di cache alla fine del tuo contenuto statico, e il sistema trova automaticamente il prefisso più lungo che una richiesta precedente ha già scritto nella cache. Comprendere come funziona ti aiuta a ottimizzare la tua strategia di cache.
Tre principi fondamentali:
-
Le scritture nella cache avvengono solo al tuo breakpoint. Contrassegnare un blocco con
cache_controlscrive esattamente una voce nella cache: un hash del prefisso che termina in quel blocco. Il sistema non scrive voci per alcuna posizione precedente. Poiché l’hash è cumulativo e copre tutto fino al breakpoint incluso, modificare qualsiasi blocco nel breakpoint o prima di esso produce un hash diverso nella richiesta successiva. -
Le letture dalla cache cercano all’indietro le voci scritte da richieste precedenti. A ogni richiesta il sistema calcola l’hash del prefisso al tuo breakpoint e verifica se esiste una voce corrispondente nella cache. Se non ne esiste nessuna, risale all’indietro un blocco alla volta, verificando se l’hash del prefisso in ciascuna posizione precedente corrisponde a qualcosa già presente nella cache. Cerca scritture precedenti, non contenuto stabile.
-
La finestra di lookback è di 20 blocchi. Il sistema controlla al massimo 20 posizioni per ciascun breakpoint, contando il breakpoint stesso come la prima. Se il sistema non trova alcuna voce corrispondente in quella finestra, il controllo si interrompe (o riprende dal successivo breakpoint esplicito, se presente). Sulla Claude API, una serie di blocchi
tool_useconsecutivi conta come una posizione, e lo stesso vale per una serie di blocchitool_resultconsecutivi, quindi un turno con molte chiamate di strumenti parallele non spinge da solo la voce della richiesta precedente fuori dalla finestra.
Esempio: lookback in una conversazione in crescita
Aggiungi nuovi blocchi a ogni turno e imposti cache_control sul blocco finale di ogni richiesta:
- Turno 1: 10 blocchi, breakpoint sul blocco 10. Non esistono voci precedenti nella cache. Il sistema scrive una voce al blocco 10.
- Turno 2: 15 blocchi, breakpoint sul blocco 15. Il blocco 15 non ha alcuna voce, quindi il sistema risale al blocco 10 e trova la voce del turno 1. Cache hit al blocco 10. Il sistema elabora ex novo solo i blocchi da 11 a 15 e scrive una nuova voce al blocco 15.
- Turno 3: 35 blocchi, breakpoint sul blocco 35. Il sistema controlla 20 posizioni (blocchi da 35 a 16) e non trova nulla. La voce del turno 2 al blocco 15 si trova una posizione fuori dalla finestra, quindi non c’è cache hit. Aggiungere un secondo breakpoint al blocco 15 avvia lì una seconda finestra di lookback, che trova la voce del turno 2.
Errore comune: breakpoint su contenuto che cambia a ogni richiesta
Il tuo prompt ha un ampio contesto di sistema statico (blocchi da 1 a 5) seguito da un blocco per richiesta contenente un timestamp e il messaggio dell’utente (blocco 6). Imposti cache_control sul blocco 6:
- Richiesta 1: Scrittura nella cache al blocco 6. L’hash include il timestamp.
- Richiesta 2: Il timestamp è diverso, quindi l’hash del prefisso al blocco 6 è diverso. Il lookback percorre i blocchi 5, 4, 3, 2 e 1, ma il sistema non ha mai scritto una voce in nessuna di quelle posizioni. Nessun cache hit. Paghi una nuova scrittura nella cache a ogni richiesta e non ottieni mai una lettura.
Il lookback non trova il contenuto stabile dietro il tuo breakpoint per memorizzarlo nella cache. Trova le voci che richieste precedenti hanno già scritto, e le scritture avvengono solo ai breakpoint. Sposta cache_control al blocco 5, l’ultimo blocco che rimane uguale tra le richieste, e ogni richiesta successiva legge il prefisso dalla cache. La cache automatica ha lo stesso problema: posiziona il breakpoint sull’ultimo blocco memorizzabile, che in questa struttura è quello che cambia a ogni richiesta, quindi usa invece un breakpoint esplicito sul blocco 5.
Punto chiave: Posiziona cache_control sull’ultimo blocco il cui prefisso è identico tra le richieste che vuoi far condividere una cache. In una conversazione in crescita il blocco finale funziona purché ogni turno aggiunga meno di 20 blocchi: il contenuto precedente non cambia mai, quindi il lookback della richiesta successiva trova la scrittura precedente. Per un prompt con un suffisso variabile (timestamp, contesto per richiesta, il messaggio in arrivo), posiziona il breakpoint alla fine del prefisso statico, non sul blocco variabile.
Quando usare più breakpoint
Puoi definire fino a 4 cache breakpoint se vuoi:
- Memorizzare nella cache sezioni diverse che cambiano con frequenze diverse (ad esempio, gli strumenti cambiano raramente, ma il contesto si aggiorna quotidianamente)
- Avere più controllo su cosa esattamente viene memorizzato nella cache
- Garantire un cache hit quando una conversazione in crescita spinge il tuo breakpoint 20 o più blocchi oltre l’ultima scrittura nella cache
Comprendere i costi dei breakpoint di cache
I cache breakpoint di per sé non aggiungono alcun costo. Ti viene addebitato solo per:
- Scritture nella cache: Quando nuovo contenuto viene scritto nella cache (25 percento in più rispetto ai token di input base per il TTL di 5 minuti)
- Letture dalla cache: Quando viene utilizzato contenuto nella cache (10 percento del prezzo base dei token di input, con eccezioni per modello)
- Token di input regolari: Per qualsiasi contenuto non memorizzato nella cache
Aggiungere altri breakpoint cache_control non aumenta i tuoi costi; paghi comunque lo stesso importo in base al contenuto effettivamente memorizzato e letto dalla cache. I breakpoint ti danno il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.
Strategie e considerazioni sulla cache
Limitazioni della cache
Sulla Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Google managed) e Microsoft Foundry, la lunghezza minima del prompt memorizzabile nella cache è:
- 512 token per Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, Claude Mythos 5 e Claude Haiku 5.5
- 2.048 token per Claude Mythos Preview e Claude Opus 4.7
- 4.096 token per Claude Opus 4.6 e Claude Opus 4.5
- 1.024 token per Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 (deprecato), Claude Opus 4.1 (ritirato, tranne su Claude Models on Google Cloud (Google managed) e Bedrock), Claude Opus 4 (ritirato, tranne su Claude Models on Google Cloud (Google managed)) e Claude Sonnet 4 (ritirato, tranne su Claude Models on Google Cloud (Google managed) e Bedrock)
- 4.096 token per Claude Haiku 4.5
Questi minimi si applicano su ciascuna di queste piattaforme in cui il modello è disponibile.
I prompt più brevi non possono essere memorizzati nella cache, anche se contrassegnati con cache_control. Qualsiasi richiesta di memorizzare nella cache un numero di token inferiore a questo viene elaborata senza cache, e non viene restituito alcun errore. Per verificare se un prompt è stato memorizzato nella cache, controlla i campi usage della risposta: se sia cache_creation_input_tokens che cache_read_input_tokens sono 0, il prompt non è stato memorizzato nella cache (probabilmente perché non soddisfaceva il requisito di lunghezza minima).
Se il tuo prompt è appena al di sotto del minimo per il tuo modello e la tua piattaforma, spesso vale la pena espandere il contenuto da memorizzare nella cache per raggiungere la soglia. Le letture dalla cache costano significativamente meno dei token di input non memorizzati, quindi raggiungere il minimo può ridurre i costi per i prompt riutilizzati frequentemente.
Per le richieste simultanee, tieni presente che una voce della cache diventa disponibile solo dopo l’inizio della prima risposta. Se hai bisogno di cache hit per richieste parallele, attendi la prima risposta prima di inviare le richieste successive.
ephemeral è l’unico tipo di cache supportato, che per impostazione predefinita ha una durata di 5 minuti.
Cosa può essere memorizzato nella cache
La maggior parte dei blocchi nella richiesta può essere memorizzata nella cache. Ciò include:
- Strumenti: Definizioni degli strumenti nell’array
tools - Messaggi di sistema: Blocchi di contenuto nell’array
system - Messaggi di testo: Blocchi di contenuto nell’array
messages.content, sia per i turni dell’utente che dell’assistente - Immagini e documenti: Blocchi di contenuto nell’array
messages.content, nei turni dell’utente - Uso degli strumenti e risultati degli strumenti: Blocchi di contenuto nell’array
messages.content, sia nei turni dell’utente che dell’assistente
Ciascuno di questi elementi può essere memorizzato nella cache, automaticamente o contrassegnandolo con cache_control.
Cosa non può essere memorizzato nella cache
Sebbene la maggior parte dei blocchi della richiesta possa essere memorizzata nella cache, ci sono alcune eccezioni:
-
I blocchi di ragionamento non possono essere memorizzati direttamente nella cache con
cache_control. Tuttavia, i blocchi di ragionamento POSSONO essere memorizzati nella cache insieme ad altro contenuto quando compaiono nei turni precedenti dell’assistente. Quando memorizzati in questo modo, CONTANO come token di input quando vengono letti dalla cache. -
I blocchi di sotto-contenuto (come le citazioni) di per sé non possono essere memorizzati direttamente nella cache. Memorizza invece il blocco di livello superiore.
Nel caso delle citazioni, i blocchi di contenuto dei documenti di livello superiore che fungono da materiale sorgente per le citazioni possono essere memorizzati nella cache. Questo ti consente di usare efficacemente la cache dei prompt con le citazioni, memorizzando nella cache i documenti a cui fanno riferimento le citazioni.
-
I blocchi di testo vuoti non possono essere memorizzati nella cache.
Cosa invalida la cache
Le modifiche al contenuto nella cache possono invalidare parte o tutta la cache.
Come descritto in Strutturare il prompt, la cache segue la gerarchia: tools → system → messages. Le modifiche a ciascun livello invalidano quel livello e tutti i livelli successivi.
La seguente tabella mostra quali parti della cache vengono invalidate da diversi tipi di modifiche. ✘ indica che la cache viene invalidata, mentre ✓ indica che la cache rimane valida.
| Cosa cambia | Cache degli strumenti | Cache di sistema | Cache dei messaggi | Impatto |
|---|---|---|---|---|
| Definizioni degli strumenti | ✘ | ✘ | ✘ | Modificare le definizioni degli strumenti (nomi, descrizioni, parametri) invalida l’intera cache |
| Attivazione della ricerca web | ✓ | ✘ | ✘ | Abilitare/disabilitare la ricerca web modifica il prompt di sistema |
| Attivazione delle citazioni | ✓ | ✘ | ✘ | Abilitare/disabilitare le citazioni modifica il prompt di sistema |
| Impostazione della velocità | ✓ | ✘ | ✘ | Passare tra speed: "fast" e la velocità standard invalida le cache di sistema e dei messaggi |
| Scelta dello strumento | ✓ | ✓ | ✘ | Le modifiche al parametro tool_choice influiscono solo sui blocchi dei messaggi |
| Immagini | ✓ | ✓ | ✘ | Aggiungere/rimuovere immagini in qualsiasi punto del prompt influisce sui blocchi dei messaggi |
| Parametri di ragionamento | Specifico del modello | Specifico del modello | ✘ | La configurazione del ragionamento (modalità e budget_tokens in modalità estesa) viene inserita nel prompt, quindi modificarla invalida sempre i blocchi dei messaggi; anche le cache degli strumenti e di sistema vengono invalidate sui modelli che inseriscono la configurazione prima di esse. Consulta Ragionamento e cache dei prompt. |
| Impostazione dell’effort | Specifico del modello | Specifico del modello | ✘ | Modificare il valore di output_config.effort può invalidare i blocchi dei messaggi e, su alcuni modelli, anche le cache degli strumenti e di sistema (consulta Ragionamento e cache dei prompt). Impostare esplicitamente l’effort al valore predefinito del modello equivale a ometterlo e non invalida la cache. Sui modelli che supportano l’effort per messaggio, una modifica dell’effort trasmessa in un messaggio role: "system" all’interno di messages lascia intatto il prefisso nella cache. |
| Risultati non di strumenti passati a richieste con ragionamento | ✓ | ✓ | Specifico del modello | Su Claude Opus 4.5 e i modelli Opus successivi, Claude Sonnet 4.6 e i modelli Sonnet successivi, Claude Haiku 5.5 e ogni modello Claude Fable e Claude Mythos, i blocchi di ragionamento vengono preservati per impostazione predefinita, quindi la cache rimane valida (✓). Sugli altri modelli, tutti i blocchi di ragionamento precedentemente memorizzati nella cache vengono rimossi dal contesto, e tutti i messaggi che seguono quei blocchi di ragionamento vengono rimossi dalla cache (✘). Per maggiori dettagli, consulta Cache con blocchi di ragionamento. |
| Blocchi di ragionamento scartati | ✓ | ✓ | ✘ | Quando l’API scarta un blocco di ragionamento che non è preservato in quella richiesta, il prefisso nella cache cambia dalla posizione di quel blocco in poi in quella richiesta. I blocchi che il modello ricevente può leggere, restituiti invariati, mantengono intatta la cache. |
Sui modelli che supportano le modifiche agli strumenti a metà conversazione, l’header beta inline-tools-2026-09-15 ti consente di aggiungere uno strumento, o modificare la definizione di uno strumento, a metà di una conversazione senza modificare tools. Invia la definizione in un blocco tool_addition in un messaggio di sistema a metà conversazione e lascia tools esattamente come lo hai inviato la prima volta. Il prefisso nella cache corrisponde ancora, quindi solo il messaggio aggiunto viene elaborato come nuovo input. L’unica eccezione è un array tools senza alcuno strumento non differito, in cui il primo strumento definito in questo modo costa un cache miss completo in quella richiesta. Consulta Definire strumenti in un messaggio.
Monitorare le prestazioni della cache
Monitora le prestazioni della cache usando questi campi della risposta dell’API, all’interno di usage nella risposta (o dell’evento message_start in caso di streaming):
cache_creation_input_tokens: Numero di token scritti nella cache durante la creazione di una nuova vocecache_read_input_tokens: Numero di token recuperati dalla cache per questa richiestainput_tokens: Numero di token di input che non sono stati letti dalla cache né usati per creare una cache (ovvero, i token dopo l’ultimo breakpoint di cache)
Cache con blocchi di ragionamento
Quando usi il ragionamento con la cache dei prompt, i blocchi di ragionamento hanno un comportamento speciale:
Cache automatica insieme ad altro contenuto: Sebbene i blocchi di ragionamento non possano essere contrassegnati esplicitamente con cache_control, vengono memorizzati nella cache come parte del contenuto della richiesta quando effettui chiamate API successive con risultati degli strumenti. Questo avviene comunemente durante l’uso degli strumenti quando restituisci i blocchi di ragionamento per continuare la conversazione.
Conteggio dei token di input: Quando i blocchi di ragionamento vengono letti dalla cache, contano come token di input nelle tue metriche di utilizzo. Questo è importante per il calcolo dei costi e la pianificazione del budget di token.
Schemi di invalidazione della cache:
- La cache rimane valida quando vengono forniti solo risultati degli strumenti come messaggi dell’utente.
- Su Claude Opus 4.5 e i modelli Opus successivi, Claude Sonnet 4.6 e i modelli Sonnet successivi, Claude Haiku 5.5 e ogni modello Claude Fable e Claude Mythos, i blocchi di ragionamento vengono preservati per impostazione predefinita anche quando viene aggiunto contenuto utente che non è un risultato di uno strumento, quindi la cache rimane valida.
- Sugli altri modelli, aggiungere contenuto utente che non è un risultato di uno strumento invalida la cache e rimuove dal contesto tutti i blocchi di ragionamento precedenti.
- Questo comportamento della cache si verifica anche senza marcatori
cache_controlespliciti.
Per maggiori dettagli sull’invalidazione della cache, consulta Cosa invalida la cache.
Esempio con uso degli strumenti:
Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]
Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1
Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)Sui modelli che mantengono il ragionamento precedente, i blocchi di ragionamento precedenti rimangono nel contesto per impostazione predefinita e rimangono parte del prefisso nella cache. Sugli altri modelli, tutti i blocchi di ragionamento precedenti vengono rimossi dal contesto a questo punto.
Per informazioni più dettagliate, consulta Ragionamento e cache dei prompt.
Archiviazione e condivisione della cache
La cache dei prompt segue queste regole:
-
Isolamento per organizzazione: Organizzazioni diverse non condividono mai le cache, anche se usano prompt identici.
-
Isolamento per workspace: Sulla Claude API, su Claude Platform on AWS e su Microsoft Foundry, le cache sono inoltre isolate tra i workspace. Su queste piattaforme, ogni workspace crea la propria cache. Su Claude Models on Google Cloud (Google managed) e Amazon Bedrock, le cache sono isolate solo per organizzazione.
-
Corrispondenza esatta: I cache hit richiedono segmenti di prompt identici al 100 percento, inclusi tutto il testo e le immagini fino al blocco contrassegnato con il controllo della cache, incluso.
-
Generazione dei token di output: La cache dei prompt non ha alcun effetto sulla generazione dei token di output. La risposta che ricevi è identica a quella che otterresti se la cache dei prompt non fosse utilizzata.
Best practice per una cache efficace
Per ottimizzare le prestazioni della cache dei prompt:
- Inizia con la cache automatica per le conversazioni multi-turno. Gestisce automaticamente i breakpoint.
- Usa i breakpoint espliciti a livello di blocco quando devi memorizzare nella cache sezioni diverse con frequenze di modifica diverse.
- Memorizza nella cache contenuto stabile e riutilizzabile come istruzioni di sistema, informazioni di base, contesti ampi o definizioni di strumenti frequenti.
- Posiziona il contenuto da memorizzare nella cache all’inizio del prompt per ottenere le migliori prestazioni.
- Usa i cache breakpoint in modo strategico per separare diverse sezioni di prefisso memorizzabili nella cache.
- Posiziona il breakpoint sull’ultimo blocco che rimane identico tra le richieste. Per un prompt con un prefisso statico e un suffisso variabile (timestamp, contesto per richiesta, il messaggio in arrivo), si tratta della fine del prefisso, non del blocco variabile.
- Analizza regolarmente i tassi di cache hit e adegua la tua strategia secondo necessità.
Ottimizzazione per diversi casi d’uso
Adatta la tua strategia di cache dei prompt al tuo scenario:
- Agenti conversazionali: Riduci costi e latenza per conversazioni prolungate, specialmente quelle con istruzioni lunghe o documenti caricati.
- Assistenti di programmazione: Migliora il completamento automatico e le domande e risposte sulla codebase mantenendo nel prompt le sezioni rilevanti o una versione riassunta della codebase.
- Elaborazione di documenti di grandi dimensioni: Incorpora nel tuo prompt materiale completo di lunga durata, incluse immagini, senza aumentare la latenza della risposta.
- Set di istruzioni dettagliati: Condividi elenchi estesi di istruzioni, procedure ed esempi per perfezionare le risposte di Claude. Gli sviluppatori spesso includono uno o due esempi nel prompt, ma con la cache dei prompt puoi ottenere prestazioni ancora migliori includendo più di 20 esempi diversificati di risposte di alta qualità.
- Uso agentico degli strumenti: Migliora le prestazioni per scenari che prevedono più chiamate di strumenti e modifiche iterative al codice, in cui ogni passaggio richiede in genere una nuova chiamata API.
- Libri, articoli, documentazione, trascrizioni di podcast e altri contenuti di lunga durata: Rendi interattiva qualsiasi base di conoscenza incorporando l’intero documento (o documenti) nel prompt e consentendo agli utenti di porgli domande.
Risoluzione dei problemi comuni
Se riscontri un comportamento inatteso:
- Assicurati che le sezioni memorizzate nella cache siano identiche tra le chiamate. Per i breakpoint espliciti, verifica che i marcatori
cache_controlsi trovino nelle stesse posizioni. - Controlla che le chiamate vengano effettuate entro la durata della cache (5 minuti per impostazione predefinita).
- Verifica che
tool_choice, l’uso delle immagini, la configurazione del ragionamento eoutput_config.effortrimangano coerenti tra le chiamate. - Verifica di memorizzare nella cache almeno il numero minimo di token per il tuo modello e la tua piattaforma (consulta Limitazioni della cache).
- Conferma che il tuo breakpoint si trovi su un blocco che rimane identico tra le richieste. Le scritture nella cache avvengono solo al breakpoint, e se quel blocco cambia (timestamp, contesto per richiesta, il messaggio in arrivo), l’hash del prefisso non corrisponde mai. Il lookback non trova il contenuto stabile dietro il breakpoint; trova solo le voci che richieste precedenti hanno scritto ai propri breakpoint.
- Verifica che le chiavi nei tuoi blocchi di contenuto
tool_useabbiano un ordinamento stabile, poiché alcuni linguaggi (ad esempio Swift, Go) rendono casuale l’ordine delle chiavi durante la conversione JSON, compromettendo le cache. - Usa la diagnostica della cache per far confrontare all’API richieste consecutive e segnalare quale parte del prompt è divergente.
Durata della cache di 1 ora
Se ritieni che 5 minuti siano troppo pochi, Anthropic offre anche una durata della cache di 1 ora a un costo aggiuntivo (consulta Prezzi). La durata di 1 ora è disponibile su ogni piattaforma che supporta la cache dei prompt.
Per usare la cache estesa, includi ttl nella definizione di cache_control in questo modo:
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}La risposta include informazioni dettagliate sulla cache come le seguenti:
{
"usage": {
"input_tokens": 2048,
"cache_read_input_tokens": 1800,
"cache_creation_input_tokens": 248,
"output_tokens": 503,
"cache_creation": {
"ephemeral_5m_input_tokens": 148,
"ephemeral_1h_input_tokens": 100
}
}
}Il campo cache_creation_input_tokens è uguale alla somma dei valori nell’oggetto cache_creation.
Se vedi scritture ephemeral_5m_input_tokens che non hai richiesto mentre usi strumenti server come la ricerca web, consulta I risultati degli strumenti server vengono memorizzati automaticamente nella cache.
Quando usare la cache di 1 ora
Se usi un prompt con una cadenza regolare (ad esempio, un prompt di sistema che invii più frequentemente di ogni 5 minuti), continua a usare la cache di 5 minuti, poiché questa continua a essere aggiornata senza costi aggiuntivi.
La cache di 1 ora è più adatta nei seguenti scenari:
- Quando hai prompt che probabilmente vengono usati meno frequentemente di ogni 5 minuti, ma più frequentemente di ogni ora. Ad esempio, quando un agente secondario agentico impiega più di 5 minuti, oppure quando memorizzi una lunga conversazione chat con un utente e in genere prevedi che quell’utente potrebbe non rispondere nei 5 minuti successivi.
- Quando la latenza è importante e i tuoi prompt successivi potrebbero essere inviati oltre i 5 minuti.
- Quando vuoi migliorare l’utilizzo del tuo limite di velocità, poiché i cache hit non vengono detratti dal tuo limite di velocità.
Combinare TTL diversi
Puoi usare sia controlli della cache da 1 ora sia da 5 minuti nella stessa richiesta, ma con un vincolo importante: le voci della cache con TTL più lungo devono apparire prima di quelle con TTL più breve (ovvero, una voce della cache da 1 ora deve apparire prima di qualsiasi voce della cache da 5 minuti).
Quando si combinano TTL diversi, la Claude API determina tre posizioni di fatturazione nel tuo prompt:
- Posizione
A: il conteggio dei token in corrispondenza dell’ultimo cache hit nel tuo prompt (o 0 se non ci sono hit).- Un hit su una voce memorizzata nella cache con un TTL di 5 minuti non viene conteggiato se un blocco
cache_controlcon TTL di 1 ora successivo a essa è un cache miss. - Una richiesta che legge una voce memorizzata nella cache con un TTL di 5 minuti fa ripartire da capo la durata di 5 minuti della voce, anche se questa volta la richiesta imposta
"ttl": "1h".
- Un hit su una voce memorizzata nella cache con un TTL di 5 minuti non viene conteggiato se un blocco
- Posizione
B: il conteggio dei token in corrispondenza dell’ultimo bloccocache_controlda 1 ora dopoA(oppure uguale adAse non ne esistono). - Posizione
C: il conteggio dei token in corrispondenza dell’ultimo bloccocache_control.
Ti vengono addebitati:
- Token di lettura della cache per
A. - Token di scrittura della cache da 1 ora per
(B - A). - Token di scrittura della cache da 5 minuti per
(C - B).
Ecco tre richieste di esempio, ciascuna con “cache hit” (riscontri nella cache) e “cache miss” (mancati riscontri nella cache) diversi. Ciascuna ha un prezzo calcolato diverso, mostrato nei riquadri.
Pre-riscaldamento della cache
Il “cache pre-warming” (pre-riscaldamento della cache) ti consente di caricare il tuo prompt di sistema o le definizioni degli strumenti nella cache dei prompt prima che un utente attivi una richiesta reale. Questo può ridurre la penalità di latenza dovuta al cache miss alla prima interazione dell’utente, abbassando il “time-to-first-token” (tempo al primo token), o TTFT, per le applicazioni sensibili alla latenza.
Come funziona
Imposta max_tokens: 0 nella tua richiesta. L’API legge il tuo prompt nel modello e scrive la cache in corrispondenza di qualsiasi breakpoint cache_control, quindi restituisce immediatamente senza generare alcun output. La risposta ha un array content vuoto, stop_reason: "max_tokens" e un blocco usage completamente popolato.
Posiziona il breakpoint cache_control sull’ultimo blocco condiviso con la richiesta successiva (in genere il tuo prompt di sistema o le definizioni degli strumenti), non sul messaggio utente segnaposto. In caso contrario, la voce della cache viene associata al segnaposto e la richiesta successiva non otterrà un hit. Usa anche la stessa configurazione di ragionamento e lo stesso output_config.effort delle tue richieste successive: questi valori vengono renderizzati nel prompt (consulta Cosa invalida la cache), quindi un pre-riscaldamento con una configurazione diversa può scrivere una voce che il tuo traffico reale non raggiunge mai. Ciò significa usare un breakpoint di cache esplicito anziché la cache automatica, perché la cache automatica posiziona il breakpoint sull’ultimo blocco, che qui è il segnaposto. Il messaggio utente segnaposto può essere qualsiasi stringa con contenuto non composto solo da spazi (gli esempi qui usano "warmup"); il suo contenuto viene letto nel modello ma non riceve mai risposta.
client = anthropic.Anthropic()
# Esegui questa chiamata prima dell'arrivo degli utenti per preriscaldare la cache del prompt di sistema condiviso.
prewarm = client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=[
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason) # "max_tokens"
print(prewarm.content) # []
print(prewarm.usage)L’API restituisce un array content vuoto:
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [],
"model": "claude-opus-5-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 5120,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"iterations": [
{
"input_tokens": 8,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 5120,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"type": "message"
}
],
"output_tokens": 0,
"service_tier": "standard",
"inference_geo": "global"
}
}Schema di utilizzo tipico
Effettua una richiesta di pre-riscaldamento all’avvio della tua applicazione (o a intervalli pianificati), quindi invia le richieste reali degli utenti dopo il completamento del pre-riscaldamento:
client = anthropic.Anthropic()
SYSTEM_PROMPT = [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
]
def prewarm_cache() -> None:
"""Call this at application startup or on a scheduled interval."""
client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "warmup"}],
)
def respond(user_message: str) -> anthropic.types.Message:
"""The real user request; benefits from a warm cache."""
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": user_message}],
)
# Prepara la cache prima che arrivi qualsiasi traffico utente.
prewarm_cache()
# In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già in cache.
response = respond("How do I implement a binary search tree?")
for block in response.content:
if block.type == "text":
print(block.text)Tieni presente che il TTL della cache si applica comunque. Per la cache predefinita da 5 minuti, invia una nuova richiesta di pre-riscaldamento almeno ogni 5 minuti per mantenere la cache calda. Per intervalli più lunghi tra le richieste degli utenti, usa invece la durata della cache di 1 ora.
Limitazioni
Una richiesta con max_tokens: 0 viene rifiutata con un invalid_request_error se è impostato uno qualsiasi dei seguenti elementi, perché ciascuno implica un output che un budget di zero token non può produrre:
stream: true- Ragionamento esteso (
thinking.type: "enabled") - Output strutturati (
output_config.format) tool_choicedi{"type": "tool", ...}o{"type": "any"}
max_tokens: 0 viene rifiutato anche all’interno di una richiesta Message Batches. Il pre-riscaldamento mira al time-to-first-token, che non si applica all’elaborazione batch, e una voce della cache scritta durante l’elaborazione batch probabilmente scadrebbe prima dell’esecuzione della richiesta successiva.
Sostituire l’espediente max_tokens=1
Alcune applicazioni inviano richieste con max_tokens: 1 per riscaldare la cache. Preferisci max_tokens: 0 quando la richiesta lo consente: non viene prodotto alcun output, quindi non c’è una risposta di un singolo token da scartare, non vengono fatturati token di output e l’intento della richiesta è inequivocabile.
Esempi di cache dei prompt
Per aiutarti a iniziare con la cache dei prompt, la ricetta sulla cache dei prompt nel Claude Cookbook fornisce esempi dettagliati e best practice.
I seguenti frammenti di codice mostrano vari schemi di cache dei prompt. Questi esempi dimostrano come implementare la cache in diversi scenari, aiutandoti a comprendere le applicazioni pratiche di questa funzionalità:
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing legal documents.",
},
{
"type": "text",
"text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "What are the key terms and conditions in this agreement?",
}
],
)
print(response.usage.model_dump_json())Questo esempio dimostra l’uso di base della cache dei prompt, memorizzando nella cache il testo completo dell’accordo legale come prefisso e mantenendo l’istruzione dell’utente non memorizzata nella cache.
Per la prima richiesta:
input_tokens: numero di token solo nel messaggio utentecache_creation_input_tokens: numero di token nell’intero messaggio di sistema, incluso il documento legalecache_read_input_tokens: 0 (nessun cache hit alla prima richiesta)
Per le richieste successive entro la durata della cache:
input_tokens: numero di token solo nel messaggio utentecache_creation_input_tokens: 0 (nessuna nuova creazione della cache)cache_read_input_tokens: numero di token nell’intero messaggio di sistema memorizzato nella cache
Le definizioni degli strumenti possono essere memorizzate nella cache posizionando cache_control sull’ultimo strumento nel tuo array tools. Tutti gli strumenti definiti prima di tale strumento, incluso quest’ultimo, vengono memorizzati nella cache come un unico prefisso.
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": { "location": { "type": "string" } },
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": { "timezone": { "type": "string" } },
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}Alla prima richiesta, cache_creation_input_tokens riflette il conteggio dei token di tutte le definizioni degli strumenti. Nelle richieste successive entro la durata della cache, quei token appaiono invece in cache_read_input_tokens.
Per l’interazione dettagliata tra definizioni degli strumenti, defer_loading e invalidazione della cache, consulta Uso degli strumenti con la cache dei prompt.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "...long system prompt",
"cache_control": {"type": "ephemeral"},
}
],
messages=[
# ...lunga conversazione finora
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, can you tell me more about the solar system?",
}
],
},
{
"role": "assistant",
"content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
},
{
"role": "user",
"content": [
{"type": "text", "text": "Good to know."},
{
"type": "text",
"text": "Tell me more about Mars.",
"cache_control": {"type": "ephemeral"},
},
],
},
],
)
print(response.usage.model_dump_json())Questo esempio dimostra come usare la cache dei prompt in una conversazione a più turni.
A ogni turno, il blocco finale dell’ultimo messaggio viene contrassegnato con cache_control in modo che la conversazione possa essere memorizzata nella cache in modo incrementale. Il sistema cerca e usa automaticamente la sequenza di blocchi più lunga precedentemente memorizzata nella cache per i messaggi successivi. I blocchi contrassegnati con cache_control in un turno precedente non vengono contrassegnati di nuovo, ma una richiesta entro 5 minuti li legge comunque dalla cache e ne rinnova la durata.
Il parametro cache_control è presente anche sul messaggio di sistema. Se il messaggio di sistema viene rimosso dalla cache dopo più di 5 minuti senza essere usato, la richiesta successiva lo aggiunge di nuovo.
Questo approccio è utile per mantenere il contesto nelle conversazioni in corso senza elaborare ripetutamente le stesse informazioni.
Se è configurato correttamente, dovresti vedere quanto segue nella risposta di utilizzo di ciascuna richiesta:
input_tokens: numero di token nel nuovo messaggio utente (minimo)cache_creation_input_tokens: numero di token nei nuovi turni dell’assistente e dell’utentecache_read_input_tokens: numero di token nella conversazione fino al turno precedente
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{
"name": "search_documents",
"description": "Search through the knowledge base",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"],
},
},
{
"name": "get_document",
"description": "Retrieve a specific document by ID",
"input_schema": {
"type": "object",
"properties": {
"doc_id": {"type": "string", "description": "Document ID"}
},
"required": ["doc_id"],
},
"cache_control": {"type": "ephemeral"},
},
],
system=[
{
"type": "text",
"text": """You are a helpful research assistant with access to a document knowledge base.
# Instructions
- Always search for relevant documents before answering
- Provide citations for your sources
- Be objective and accurate in your responses
- If multiple documents contain relevant information, synthesize them
- Acknowledge when information is not available in the knowledge base""",
"cache_control": {"type": "ephemeral"},
},
{
"type": "text",
"text": """# Knowledge Base Context
Here are the relevant documents for this conversation:
## Document 1: Solar System Overview
The solar system consists of the Sun and all objects that orbit it...
## Document 2: Planetary Characteristics
Each planet has unique features. Mercury is the smallest planet...
## Document 3: Mars Exploration
Mars has been a target of exploration for decades...
[Additional documents...]""",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Can you search for information about Mars rovers?",
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "tool_1",
"name": "search_documents",
"input": {"query": "Mars rovers"},
}
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "tool_1",
"content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}
],
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
}
],
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "Yes, please tell me about the Perseverance rover specifically.",
"cache_control": {"type": "ephemeral"},
}
],
},
],
)
print(response.usage.model_dump_json())Questo esempio completo dimostra come usare tutti e 4 i breakpoint di cache disponibili per ottimizzare diverse parti del tuo prompt:
-
Cache degli strumenti (breakpoint di cache 1): il parametro
cache_controlsull’ultima definizione di strumento memorizza nella cache tutte le definizioni degli strumenti. -
Cache delle istruzioni riutilizzabili (breakpoint di cache 2): le istruzioni statiche nel prompt di sistema vengono memorizzate nella cache separatamente. Queste istruzioni cambiano raramente tra una richiesta e l’altra.
-
Cache del contesto RAG (breakpoint di cache 3): i documenti della knowledge base vengono memorizzati nella cache in modo indipendente, consentendoti di aggiornare i documenti RAG senza invalidare la cache degli strumenti o delle istruzioni.
-
Cache della cronologia della conversazione (breakpoint di cache 4): l’ultimo messaggio utente è contrassegnato con
cache_controlper abilitare la cache incrementale della conversazione man mano che procede.
Questo approccio offre la massima flessibilità:
- Se aggiungi un nuovo turno alla conversazione senza modificare il contenuto precedente, tutti e quattro i segmenti della cache vengono riutilizzati.
- Se aggiorni i documenti RAG ma mantieni gli stessi strumenti e le stesse istruzioni, i primi due segmenti della cache vengono riutilizzati.
- Se modifichi la conversazione ma mantieni gli stessi strumenti, istruzioni e documenti, i primi tre segmenti vengono riutilizzati.
- Le modifiche in corrispondenza di qualsiasi breakpoint invalidano quel segmento e tutto ciò che segue, mentre i segmenti precedenti memorizzati nella cache restano validi.
Per la prima richiesta:
input_tokens: minimo (token dopo l’ultimo breakpoint di cache, vicino a 0 in questo esempio)cache_creation_input_tokens: token in tutti i segmenti memorizzati nella cache (strumenti + istruzioni + documenti RAG + cronologia della conversazione)cache_read_input_tokens: 0 (nessun cache hit)
Per le richieste successive con solo un nuovo messaggio utente (e il quarto breakpoint spostato su quel nuovo messaggio finale, come nell’esempio):
input_tokens: minimo (token dopo l’ultimo breakpoint di cache, vicino a 0 in questo esempio)cache_creation_input_tokens: token nel nuovo messaggio utente e nel turno precedente dell’assistente (il nuovo segmento di conversazione in fase di memorizzazione nella cache)cache_read_input_tokens: tutti i token precedentemente memorizzati nella cache (strumenti + istruzioni + documenti RAG + conversazione precedente)
Questo schema è particolarmente efficace per:
- Applicazioni RAG con ampi contesti di documenti
- Sistemi di agenti che usano più strumenti
- Conversazioni di lunga durata che devono mantenere il contesto
- Applicazioni che devono ottimizzare diverse parti del prompt in modo indipendente
Conservazione dei dati
La cache dei prompt (sia automatica sia esplicita) è idonea alla ZDR. Anthropic non memorizza il testo grezzo dei tuoi prompt né delle risposte di Claude.
Le rappresentazioni della cache KV (chiave-valore) e gli hash crittografici del contenuto memorizzato nella cache sono conservati solo in memoria e non vengono archiviati in modo persistente. Le voci della cache hanno una durata minima di 5 minuti (standard) o 1 ora (estesa), dopodiché vengono eliminate tempestivamente, anche se non immediatamente.
Le voci della cache sono isolate tra organizzazioni e, su alcune piattaforme, tra i workspace all’interno di un’organizzazione.
Domande frequenti
Nella maggior parte dei casi, un singolo breakpoint di cache alla fine del tuo contenuto statico è sufficiente. Le scritture della cache avvengono solo in corrispondenza del blocco che contrassegni. Posizionalo sull’ultimo blocco che rimane identico tra le richieste, e ogni richiesta successiva leggerà quella stessa voce. Se un blocco successivo varia a ogni richiesta (un timestamp, il messaggio in arrivo), mantieni il breakpoint prima di esso, sull’ultimo blocco stabile.
Hai bisogno di più breakpoint solo se:
- Una conversazione in crescita spinge il tuo breakpoint 20 o più blocchi oltre l’ultima scrittura della cache, collocando la voce precedente al di fuori della finestra di ricerca all’indietro
- Vuoi memorizzare nella cache in modo indipendente sezioni che si aggiornano con frequenze diverse
- Hai bisogno di un controllo esplicito su cosa viene memorizzato nella cache per l’ottimizzazione dei costi
Esempio: se hai istruzioni di sistema (che cambiano raramente) e un contesto RAG (che cambia ogni giorno), potresti usare due breakpoint per memorizzarli nella cache separatamente.
No, i breakpoint di cache di per sé sono gratuiti. Paghi solo per:
- Scrivere contenuto nella cache (il 25 percento in più rispetto ai token di input base per il TTL di 5 minuti)
- Leggere dalla cache (una frazione del prezzo base dei token di input)
- Token di input regolari per il contenuto non memorizzato nella cache
Il numero di breakpoint non influisce sul prezzo; conta solo la quantità di contenuto memorizzato nella cache e letto.
La risposta di utilizzo include tre campi separati per i token di input che insieme rappresentano il tuo input totale:
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokenscache_read_input_tokens: token recuperati dalla cache (tutto ciò che precede i breakpoint di cache ed era stato memorizzato nella cache)cache_creation_input_tokens: nuovi token scritti nella cache (in corrispondenza dei breakpoint di cache)input_tokens: token dopo l’ultimo breakpoint di cache che non sono memorizzati nella cache
Importante: input_tokens NON rappresenta tutti i token di input, ma solo la parte dopo il tuo ultimo breakpoint di cache. Se hai contenuto memorizzato nella cache, input_tokens è in genere molto più piccolo del tuo input totale.
Esempio: con un documento da 200k token memorizzato nella cache e una domanda dell’utente di 50 token:
cache_read_input_tokens: 200.000cache_creation_input_tokens: 0input_tokens: 50- Totale: 200.050 token
Questa suddivisione è fondamentale per comprendere sia i tuoi costi sia l’utilizzo del limite di velocità. Consulta Monitorare le prestazioni della cache per maggiori dettagli.
La durata minima predefinita della cache (TTL) è di 5 minuti. Questa durata viene rinnovata ogni volta che il contenuto memorizzato nella cache viene usato.
Se ritieni che 5 minuti siano troppo pochi, Anthropic offre anche un TTL della cache di 1 ora.
La durata viene misurata dall’inizio della richiesta che scrive o legge la voce della cache, non dalla fine della sua risposta. Il tempo impiegato per generare una risposta viene conteggiato nella durata, quindi la finestra entro cui una richiesta successiva può riutilizzare la cache è pari alla durata meno il tempo di generazione.
Se le tue richieste producono risposte lunghe e la richiesta successiva potrebbe non iniziare prima che la durata sia trascorsa, usa il TTL della cache di 1 ora.
Puoi definire fino a 4 breakpoint di cache (usando i parametri cache_control) nel tuo prompt.
La cache dei prompt è supportata su tutti i modelli Claude attivi.
La modifica dei parametri di ragionamento (cambio di modalità o modifica del budget in modalità estesa) invalida i prefissi dei messaggi memorizzati nella cache e può invalidare anche i prompt di sistema e gli strumenti memorizzati nella cache, perché la configurazione del ragionamento viene renderizzata nel prompt. Modificare il valore output_config.effort può avere lo stesso effetto.
Per maggiori dettagli sull’invalidazione della cache, consulta Cosa invalida la cache.
Per ulteriori informazioni sul ragionamento, inclusa la sua interazione con l’uso degli strumenti e la cache dei prompt, consulta Ragionamento e cache dei prompt.
Il modo più semplice è aggiungere "cache_control": {"type": "ephemeral"} al livello principale del corpo della tua richiesta (cache automatica). In alternativa, includi almeno un breakpoint cache_control su singoli blocchi di contenuto (breakpoint di cache espliciti).
Sì, la cache dei prompt può essere usata insieme ad altre funzionalità dell’API, come l’uso degli strumenti e le capacità di visione. Tuttavia, modificare la presenza di immagini in un prompt o modificare le impostazioni dell’uso degli strumenti invalida la cache.
Per maggiori dettagli sull’invalidazione della cache, consulta Cosa invalida la cache.
La cache dei prompt ha i propri prezzi: le scritture della cache da 5 minuti costano il 25 percento in più rispetto ai token di input base, le scritture della cache da 1 ora costano 2 volte i token di input base e i cache hit costano una frazione del prezzo base dei token di input, con un moltiplicatore per ciascun modello.
Non c’è modo di svuotare manualmente la cache. I prefissi memorizzati nella cache scadono automaticamente dopo un minimo di 5 minuti di inattività.
Puoi monitorare le prestazioni della cache usando i campi cache_creation_input_tokens e cache_read_input_tokens nella risposta dell’API.
Consulta Cosa invalida la cache per maggiori dettagli sull’invalidazione della cache, incluso un elenco delle modifiche che richiedono la creazione di una nuova voce della cache.
La cache dei prompt è progettata con solide misure di privacy e separazione dei dati:
-
Le chiavi della cache vengono generate usando un hash crittografico dei prompt fino al punto di controllo della cache. Ciò significa che solo le richieste con prompt identici possono accedere a una specifica cache.
-
Le cache non vengono mai condivise tra organizzazioni, nemmeno per prompt identici. Su alcune piattaforme, sono inoltre isolate per workspace all’interno di un’organizzazione.
-
Il meccanismo di cache è progettato per mantenere l’integrità e la privacy di ogni conversazione o contesto univoco.
-
È sicuro usare
cache_controlin qualsiasi punto dei tuoi prompt. Affinché la cache produca letture, posiziona il breakpoint alla fine di un prefisso stabile: posizionarlo su un blocco che cambia a ogni richiesta (come un timestamp o l’input arbitrario dell’utente) scrive ogni volta una nuova voce e non ottiene mai un hit.
Queste misure garantiscono che la cache dei prompt mantenga la privacy e la sicurezza dei dati offrendo al contempo vantaggi in termini di prestazioni.
Sì, puoi usare la cache dei prompt con le tue richieste alla Message Batches API. Tuttavia, poiché le richieste batch asincrone possono essere elaborate in modo concorrente e in qualsiasi ordine, i cache hit sono forniti secondo il principio del massimo impegno (best-effort).
La cache da 1 ora può aiutarti a migliorare i tuoi cache hit. Il modo più conveniente per usarla è il seguente:
- Raccogli un insieme di richieste di messaggi che hanno un prefisso condiviso.
- Invia una richiesta batch con una singola richiesta che abbia questo prefisso condiviso e un blocco di cache da 1 ora. Questo scrive il prefisso nella cache da 1 ora.
- Non appena questa è completata, invia il resto delle richieste. Devi monitorare il job per sapere quando viene completato.
In genere questo è meglio che usare la cache da 5 minuti, perché è comune che le richieste batch impieghino tra 5 minuti e 1 ora per essere completate.
Questo errore si verifica in genere quando hai aggiornato il tuo SDK o stai usando esempi di codice obsoleti. La cache dei prompt è disponibile su client.messages, senza il prefisso beta. Invece di:
client.beta.prompt_caching.messages.create(**params)Usa:
client.messages.create(**params)Questo errore si verifica in genere quando hai aggiornato il tuo SDK o stai usando esempi di codice obsoleti. La cache dei prompt è disponibile su client.messages, senza il prefisso beta. Invece di:
client.beta.promptCaching.messages.create(/* ... */);Usa:
client.messages.create(/* ... */);Disponibilità
Claude API
- API
- Messages API
- Managed Agents Beta
- Modelli
- Tutti i modelli
Amazon Bedrock
- API
- Messages API
- Modelli
- Tutti i modelli
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelli
- Tutti i modelli
Claude Platform on AWS
- API
- Messages API
- Managed Agents Beta
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents Beta
- Modelli
- Tutti i modelli
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelli
- Tutti i modelli
Microsoft Foundry
- API
- Messages API
- Modelli
- Tutti i modelli
Gestione dei dati
Panoramica sulla gestione dei datiEndpoint applicabili
/v1/messages
Esclude Modelli coperti
I tuoi prompt e gli output di Claude non vengono archiviati. Le rappresentazioni della cache KV e gli hash crittografici vengono mantenuti in memoria per il TTL della cache ed eliminati tempestivamente dopo la scadenza. Scopri di più
Questa pagina ti è stata utile?