Caching dei prompt
Il caching dei prompt è una funzionalità potente che ottimizza l’utilizzo delle API consentendo di riprendere da prefissi specifici nei tuoi prompt. Questo approccio riduce significativamente il tempo di elaborazione e i costi per attività ripetitive o prompt con elementi costanti.
Ecco un esempio di come implementare il caching dei prompt con l’API Messages utilizzando un blocco cache_control
:
In questo esempio, l’intero testo di “Pride and Prejudice” viene memorizzato nella cache utilizzando il parametro cache_control
. Questo consente il riutilizzo di questo testo lungo in più chiamate API senza doverlo rielaborare ogni volta. Modificando solo il messaggio dell’utente è possibile porre varie domande sul libro utilizzando il contenuto memorizzato nella cache, ottenendo risposte più rapide e una maggiore efficienza.
Come funziona il caching dei prompt
Quando invii una richiesta con il caching dei prompt abilitato:
- Il sistema verifica se un prefisso del prompt, fino a un punto di interruzione della cache specificato, è già memorizzato nella cache da una query recente.
- Se trovato, utilizza la versione memorizzata nella cache, riducendo il tempo di elaborazione e i costi.
- In caso contrario, elabora l’intero prompt e memorizza nella cache il prefisso una volta che la risposta inizia.
Questo è particolarmente utile per:
- Prompt con molti esempi
- Grandi quantità di contesto o informazioni di background
- Attività ripetitive con istruzioni costanti
- Conversazioni lunghe a più turni
Per impostazione predefinita, la cache ha una durata di 5 minuti. La cache viene aggiornata senza costi aggiuntivi ogni volta che il contenuto memorizzato nella cache viene utilizzato.
Il caching dei prompt memorizza l’intero prefisso
Il caching dei prompt fa riferimento all’intero prompt - tools
, system
e messages
(in quest’ordine) fino a includere il blocco designato con cache_control
.
Prezzi
Il caching dei prompt introduce una nuova struttura di prezzi. La tabella seguente mostra il prezzo per milione di token per ciascun modello supportato:
Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
---|---|---|---|---|---|
Claude Opus 4 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Sonnet 4 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.7 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Sonnet 3.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
Claude Haiku 3.5 | $0.80 / MTok | $1 / MTok | $1.6 / MTok | $0.08 / MTok | $4 / MTok |
Claude Opus 3 | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
Claude Haiku 3 | $0.25 / MTok | $0.30 / MTok | $0.50 / MTok | $0.03 / MTok | $1.25 / MTok |
Nota:
- I token di scrittura nella cache di 5 minuti costano 1,25 volte il prezzo base dei token di input
- I token di scrittura nella cache di 1 ora costano 2 volte il prezzo base dei token di input
- I token di lettura dalla cache costano 0,1 volte il prezzo base dei token di input
- I token di input e output regolari sono prezzati alle tariffe standard
Come implementare il caching dei prompt
Modelli supportati
Il caching dei prompt è attualmente supportato su:
- Claude Opus 4
- Claude Sonnet 4
- Claude Sonnet 3.7
- Claude Sonnet 3.5
- Claude Haiku 3.5
- Claude Haiku 3
- Claude Opus 3
Strutturazione del prompt
Posiziona il contenuto statico (definizioni di strumenti, istruzioni di sistema, contesto, esempi) all’inizio del prompt. Contrassegna la fine del contenuto riutilizzabile per il caching utilizzando il parametro cache_control
.
I prefissi della cache vengono creati nel seguente ordine: tools
, system
, quindi messages
.
Utilizzando il parametro cache_control
, puoi definire fino a 4 punti di interruzione della cache, consentendo di memorizzare nella cache diverse sezioni riutilizzabili separatamente. Per ogni punto di interruzione, il sistema verificherà automaticamente la presenza di corrispondenze nella cache in posizioni precedenti e utilizzerà il prefisso corrispondente più lungo se ne viene trovato uno.
Limitazioni della cache
La lunghezza minima del prompt memorizzabile nella cache è:
- 1024 token per Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 e Claude Opus 3
- 2048 token per Claude Haiku 3.5 e Claude Haiku 3
Prompt più brevi non possono essere memorizzati nella cache, anche se contrassegnati con cache_control
. Qualsiasi richiesta di memorizzare nella cache meno di questo numero di token verrà elaborata senza caching. Per vedere se un prompt è stato memorizzato nella cache, consulta i campi di utilizzo della risposta.
Per le richieste concorrenti, nota che una voce della cache diventa disponibile solo dopo l’inizio della prima risposta. Se hai bisogno di corrispondenze nella cache per richieste parallele, attendi la prima risposta prima di inviare le richieste successive.
Attualmente, “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 designata per il caching con cache_control
. Questo include:
- Strumenti: Definizioni di 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 - Utilizzo di 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 contrassegnato con cache_control
per abilitare il caching per quella porzione della richiesta.
Cosa non può essere memorizzato nella cache
Mentre la maggior parte dei blocchi di richiesta può essere memorizzata nella cache, ci sono alcune eccezioni:
-
I blocchi di pensiero non possono essere memorizzati nella cache direttamente con
cache_control
. Tuttavia, i blocchi di pensiero POSSONO essere memorizzati nella cache insieme ad altri contenuti quando appaiono nei turni precedenti dell’assistente. Quando memorizzati nella cache in questo modo, vengono conteggiati come token di input quando letti dalla cache. -
I blocchi di sotto-contenuto (come le citazioni) non possono essere memorizzati nella cache direttamente. Invece, memorizza nella cache il blocco di livello superiore.
Nel caso delle citazioni, i blocchi di contenuto del documento di livello superiore che fungono da materiale di origine per le citazioni possono essere memorizzati nella cache. Questo ti consente di utilizzare efficacemente il caching dei prompt con le citazioni memorizzando nella cache i documenti a cui le citazioni faranno riferimento.
-
I blocchi di testo vuoti non possono essere memorizzati nella cache.
Monitoraggio delle prestazioni della cache
Monitora le prestazioni della cache utilizzando questi campi di risposta API, all’interno di usage
nella risposta (o nell’evento message_start
se streaming):
cache_creation_input_tokens
: Numero di token scritti nella cache durante la creazione di una nuova voce.cache_read_input_tokens
: Numero di token recuperati dalla cache per questa richiesta.input_tokens
: Numero di token di input che non sono stati letti dalla cache o utilizzati per creare una cache.
Best practice per un caching efficace
Per ottimizzare le prestazioni del caching dei prompt:
- Memorizza nella cache contenuti stabili e riutilizzabili come istruzioni di sistema, informazioni di background, contesti ampi o definizioni di strumenti frequenti.
- Posiziona il contenuto memorizzato nella cache all’inizio del prompt per ottenere le migliori prestazioni.
- Utilizza i punti di interruzione della cache in modo strategico per separare diverse sezioni di prefisso memorizzabili nella cache.
- Analizza regolarmente i tassi di successo della cache e adatta la tua strategia secondo necessità.
Ottimizzazione per diversi casi d’uso
Adatta la tua strategia di caching dei prompt al tuo scenario:
- Agenti conversazionali: Riduci costi e latenza per conversazioni estese, specialmente quelle con lunghe istruzioni o documenti caricati.
- Assistenti di codifica: Migliora l’autocompletamento e le domande sulla base di codice mantenendo sezioni rilevanti o una versione riassunta della base di codice nel prompt.
- Elaborazione di documenti di grandi dimensioni: Incorpora materiale completo di lunga durata, incluse immagini, nel tuo prompt senza aumentare la latenza di risposta.
- Set di istruzioni dettagliati: Condividi ampie liste di istruzioni, procedure ed esempi per perfezionare le risposte di Claude. Gli sviluppatori spesso includono uno o due esempi nel prompt, ma con il caching dei prompt puoi ottenere prestazioni ancora migliori includendo più di 20 esempi diversi di risposte di alta qualità.
- Utilizzo di strumenti agentici: Migliora le prestazioni per scenari che coinvolgono più chiamate di strumenti e modifiche iterative del codice, dove ogni passaggio richiede tipicamente una nuova chiamata API.
- Parla con libri, documenti, documentazione, trascrizioni di podcast e altri contenuti di lunga durata: Dai vita a qualsiasi base di conoscenza incorporando l’intero documento(i) nel prompt e consentendo agli utenti di porgli domande.
Risoluzione dei problemi comuni
Se riscontri comportamenti inaspettati:
- Assicurati che le sezioni memorizzate nella cache siano identiche e contrassegnate con cache_control nelle stesse posizioni tra le chiamate
- Verifica che le chiamate siano effettuate entro la durata della cache (5 minuti per impostazione predefinita)
- Verifica che
tool_choice
e l’utilizzo delle immagini rimangano coerenti tra le chiamate - Verifica di memorizzare nella cache almeno il numero minimo di token
- Mentre il sistema tenterà di utilizzare il contenuto precedentemente memorizzato nella cache in posizioni precedenti a un punto di interruzione della cache, puoi utilizzare un parametro
cache_control
aggiuntivo per garantire la ricerca nella cache su porzioni precedenti del prompt, che può essere utile per query con elenchi molto lunghi di blocchi di contenuto
Nota che le modifiche a tool_choice
o la presenza/assenza di immagini in qualsiasi punto del prompt invalideranno la cache, richiedendo la creazione di una nuova voce nella cache.
Caching con blocchi di pensiero
Quando utilizzi pensiero esteso con il caching dei prompt, i blocchi di pensiero hanno un comportamento speciale:
Caching automatico insieme ad altri contenuti: Mentre i blocchi di pensiero non possono 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 accade comunemente durante l’utilizzo degli strumenti quando passi i blocchi di pensiero per continuare la conversazione.
Conteggio dei token di input: Quando i blocchi di pensiero vengono letti dalla cache, vengono conteggiati come token di input nelle tue metriche di utilizzo. Questo è importante per il calcolo dei costi e il budget dei token.
Modelli di invalidazione della cache:
- La cache rimane valida quando vengono forniti solo risultati degli strumenti come messaggi utente
- La cache viene invalidata quando viene aggiunto contenuto utente non relativo ai risultati degli strumenti, causando la rimozione di tutti i blocchi di pensiero precedenti
- Questo comportamento di caching si verifica anche senza marcatori
cache_control
espliciti
Esempio con utilizzo di strumenti:
Quando viene incluso un blocco utente non relativo ai risultati degli strumenti, questo designa un nuovo ciclo dell’assistente e tutti i blocchi di pensiero precedenti vengono rimossi dal contesto.
Per informazioni più dettagliate, consulta la documentazione sul pensiero esteso.
Archiviazione e condivisione della cache
-
Isolamento dell’organizzazione: Le cache sono isolate tra le organizzazioni. Organizzazioni diverse non condividono mai cache, anche se utilizzano prompt identici.
-
Corrispondenza esatta: I successi della cache richiedono segmenti di prompt identici al 100%, inclusi tutti i testi e le immagini fino al blocco contrassegnato con cache control.
-
Generazione di token di output: Il caching dei prompt non ha alcun effetto sulla generazione di token di output. La risposta che ricevi sarà identica a quella che otterresti se il caching dei prompt non fosse utilizzato.
Durata della cache di 1 ora (beta)
Se ritieni che 5 minuti siano troppo brevi, Anthropic offre anche una durata della cache di 1 ora.
Per utilizzare la cache estesa, aggiungi extended-cache-ttl-2025-04-11
come header beta alla tua richiesta, e poi includi ttl
nella definizione di cache_control
in questo modo:
La risposta includerà informazioni dettagliate sulla cache come le seguenti:
Nota che il campo cache_creation_input_tokens
attuale è uguale alla somma dei valori nell’oggetto cache_creation
.
Quando utilizzare la cache di 1 ora
Se hai prompt che vengono utilizzati con cadenza regolare (ad esempio, prompt di sistema che vengono utilizzati più frequentemente di ogni 5 minuti), continua a utilizzare la cache di 5 minuti, poiché questa continuerà a essere aggiornata senza costi aggiuntivi.
La cache di 1 ora è ideale nei seguenti scenari:
- Quando hai prompt che probabilmente vengono utilizzati meno frequentemente di 5 minuti, ma più frequentemente di ogni ora. Ad esempio, quando un agente laterale agentico impiegherà più di 5 minuti, o quando si memorizza una lunga conversazione con un utente e generalmente ci si aspetta che l’utente potrebbe non rispondere nei prossimi 5 minuti.
- Quando la latenza è importante e i tuoi prompt di follow-up potrebbero essere inviati oltre i 5 minuti.
- Quando vuoi migliorare l’utilizzo del limite di frequenza, poiché i successi della cache non vengono detratti dal tuo limite di frequenza.
La cache di 5 minuti e quella di 1 ora si comportano allo stesso modo rispetto alla latenza. In generale, vedrai un miglioramento del tempo al primo token per documenti lunghi.
Combinare TTL diversi
Puoi utilizzare controlli di cache sia di 1 ora che di 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 (cioè, una voce della cache di 1 ora deve apparire prima di qualsiasi voce della cache di 5 minuti).
Quando si combinano TTL, determiniamo tre posizioni di fatturazione nel tuo prompt:
- Posizione
A
: Il conteggio dei token al successo della cache più alto (o 0 se non ci sono successi). - Posizione
B
: Il conteggio dei token al bloccocache_control
di 1 ora più alto dopoA
(o uguale adA
se non ne esistono). - Posizione
C
: Il conteggio dei token all’ultimo bloccocache_control
.
Se B
e/o C
sono maggiori di A
, saranno necessariamente mancati dalla cache, perché A
è il successo della cache più alto.
Ti verrà addebitato per:
- Token di lettura della cache per
A
. - Token di scrittura della cache di 1 ora per
(B - A)
. - Token di scrittura della cache di 5 minuti per
(C - B)
.
Ecco 3 esempi. Questo rappresenta i token di input di 3 richieste, ciascuna delle quali ha diversi successi e mancati della cache. Ognuna ha un prezzo calcolato diverso, mostrato nelle caselle colorate, come risultato.
Esempi di caching dei prompt
Per aiutarti a iniziare con il caching dei prompt, abbiamo preparato un ricettario di caching dei prompt con esempi dettagliati e best practice.
Di seguito, abbiamo incluso diversi frammenti di codice che mostrano vari modelli di caching dei prompt. Questi esempi dimostrano come implementare il caching in diversi scenari, aiutandoti a comprendere le applicazioni pratiche di questa funzionalità: