Memorizzazione nella cache dei prompt

La memorizzazione nella cache dei prompt è una funzionalità potente che ottimizza l'utilizzo dell'API consentendo di riprendere da prefissi specifici nei tuoi prompt. Questo approccio riduce significativamente i tempi di elaborazione e i costi per attività ripetitive o prompt con elementi coerenti.

Ecco un esempio di come implementare la memorizzazione nella cache dei prompt con l'API Messages utilizzando un blocco cache_control:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

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 di grandi dimensioni su più chiamate API senza rielaborarlo ogni volta. Modificando solo il messaggio dell'utente, puoi porre varie domande sul libro mentre utilizzi il contenuto memorizzato nella cache, portando a risposte più veloci e a una maggiore efficienza.

Come funziona la memorizzazione nella cache dei prompt

Quando invii una richiesta con la memorizzazione nella cache dei prompt abilitata:

1. 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.
2. Se trovato, utilizza la versione memorizzata nella cache, riducendo i tempi di elaborazione e i costi.
3. In caso contrario, elabora il prompt completo 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 coerenti
• 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 memorizzato nella cache viene utilizzato.

Prezzi

La memorizzazione nella cache dei prompt introduce una nuova struttura di prezzi. La tabella seguente mostra il prezzo per milione di token per ogni modello supportato:

Come implementare la memorizzazione nella cache dei prompt

La memorizzazione nella cache dei prompt è una funzionalità potente che ottimizza l'utilizzo dell'API consentendo di riprendere da prefissi specifici nei tuoi prompt. Questo approccio riduce significativamente i tempi di elaborazione e i costi per attività ripetitive o prompt con elementi coerenti.

Ecco un esempio di come implementare la memorizzazione nella cache dei prompt con l'API Messages utilizzando un blocco cache_control:

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

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 di grandi dimensioni su più chiamate API senza rielaborarlo ogni volta. Modificando solo il messaggio dell'utente, puoi porre varie domande sul libro mentre utilizzi il contenuto memorizzato nella cache, portando a risposte più veloci e a una maggiore efficienza.

Come funziona la memorizzazione nella cache dei prompt

Quando invii una richiesta con la memorizzazione nella cache dei prompt abilitata:

1. 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.
2. Se trovato, utilizza la versione memorizzata nella cache, riducendo i tempi di elaborazione e i costi.
3. In caso contrario, elabora il prompt completo 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 coerenti
• 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 memorizzato nella cache viene utilizzato.

Prezzi

La memorizzazione nella cache dei prompt introduce una nuova struttura di prezzi. La tabella seguente mostra il prezzo per milione di token per ogni modello supportato:

Come implementare la memorizzazione nella cache dei prompt

Modelli supportati

La memorizzazione nella cache dei prompt è attualmente supportata su:

• Claude Opus 4.5
• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Haiku 4.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (deprecato)

Il caching dei prompt è una funzionalità potente che ottimizza l'utilizzo dell'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 coerenti.

Ecco un esempio di come implementare il caching dei prompt con l'API Messages utilizzando un blocco cache_control:

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

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 di grandi dimensioni su più chiamate API senza rielaborarlo ogni volta. Modificando solo il messaggio dell'utente, puoi porre varie domande sul libro mentre utilizzi il contenuto memorizzato nella cache, portando a risposte più veloci e a una maggiore efficienza.

Come funziona il caching dei prompt

Quando invii una richiesta con il caching dei prompt abilitato:

1. 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.
2. Se trovato, utilizza la versione memorizzata nella cache, riducendo il tempo di elaborazione e i costi.
3. In caso contrario, elabora il prompt completo 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 coerenti
• 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 memorizzato nella cache viene utilizzato.

Prezzi

Il caching dei prompt introduce una nuova struttura di prezzi. La tabella seguente mostra il prezzo per milione di token per ogni modello supportato:

Come implementare il caching dei prompt

Modelli supportati

Il caching dei prompt è attualmente supportato su:

• Claude Opus 4.5
• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Haiku 4.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (deprecato)

Strutturazione del tuo prompt

Posiziona il contenuto statico (definizioni di strumenti, istruzioni di sistema, contesto, esempi) all'inizio del tuo 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. Questo ordine forma una gerarchia in cui ogni livello si basa su quelli precedenti.

Come funziona il controllo automatico del prefisso

Puoi utilizzare un solo punto di interruzione della cache alla fine del tuo contenuto statico, e il sistema troverà automaticamente la sequenza più lunga di blocchi memorizzati nella cache corrispondenti. Comprendere come funziona questo ti aiuta a ottimizzare la tua strategia di caching.

Tre principi fondamentali:

1. Le chiavi della cache sono cumulative: Quando memorizzi esplicitamente nella cache un blocco con cache_control, la chiave hash della cache viene generata eseguendo l'hash di tutti i blocchi precedenti nella conversazione in sequenza. Ciò significa che la cache per ogni blocco dipende da tutto il contenuto che lo precede.

2. Controllo sequenziale all'indietro: Il sistema verifica i hit della cache lavorando all'indietro dal tuo punto di interruzione esplicito, controllando ogni blocco precedente in ordine inverso. Ciò garantisce che tu ottenga il hit della cache più lungo possibile.

3. Finestra di lookback di 20 blocchi: Il sistema controlla solo fino a 20 blocchi prima di ogni punto di interruzione cache_control esplicito. Dopo aver controllato 20 blocchi senza una corrispondenza, smette di controllare e passa al punto di interruzione esplicito successivo (se presente).

Esempio: Comprensione della finestra di lookback

Considera una conversazione con 30 blocchi di contenuto in cui imposti cache_control solo sul blocco 30:

• Se invii il blocco 31 senza modifiche ai blocchi precedenti: Il sistema controlla il blocco 30 (corrispondenza!). Ottieni un hit della cache al blocco 30 e solo il blocco 31 necessita di elaborazione.

• Se modifichi il blocco 25 e invii il blocco 31: Il sistema controlla all'indietro dal blocco 30 → 29 → 28... → 25 (nessuna corrispondenza) → 24 (corrispondenza!). Poiché il blocco 24 non è cambiato, ottieni un hit della cache al blocco 24 e solo i blocchi 25-30 necessitano di rielaborazione.

• Se modifichi il blocco 5 e invii il blocco 31: Il sistema controlla all'indietro dal blocco 30 → 29 → 28... → 11 (controllo #20). Dopo 20 controlli senza trovare una corrispondenza, smette di cercare. Poiché il blocco 5 è oltre la finestra di 20 blocchi, non si verifica alcun hit della cache e tutti i blocchi necessitano di rielaborazione. Tuttavia, se avessi impostato un punto di interruzione cache_control esplicito sul blocco 5, il sistema continuerebbe a controllare da quel punto di interruzione: blocco 5 (nessuna corrispondenza) → blocco 4 (corrispondenza!). Ciò consente un hit della cache al blocco 4, dimostrando perché dovresti posizionare i punti di interruzione prima del contenuto modificabile.

Punto chiave: Imposta sempre un punto di interruzione della cache esplicito alla fine della tua conversazione per massimizzare le tue possibilità di hit della cache. Inoltre, imposta i punti di interruzione appena prima dei blocchi di contenuto che potrebbero essere modificabili per garantire che quelle sezioni possano essere memorizzate nella cache in modo indipendente.

Quando utilizzare più punti di interruzione

Puoi definire fino a 4 punti di interruzione della cache se desideri:

• Memorizzare nella cache sezioni diverse che cambiano a frequenze diverse (ad esempio, gli strumenti cambiano raramente, ma il contesto si aggiorna quotidianamente)
• Avere più controllo su esattamente cosa viene memorizzato nella cache
• Garantire il caching per il contenuto più di 20 blocchi prima del tuo punto di interruzione finale
• Posizionare i punti di interruzione prima del contenuto modificabile per garantire hit della cache anche quando si verificano modifiche oltre la finestra di 20 blocchi

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

• 1024 token per Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (deprecato) e Claude Opus 3 (deprecato)
• 4096 token per Claude Haiku 4.5
• 2048 token per Claude Haiku 3.5 e Claude Haiku 3

I 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 simultanee, nota che una voce della cache diventa disponibile solo dopo l'inizio della prima risposta. Se hai bisogno di hit della 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.

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

• 1024 token per Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (deprecato) e Claude Opus 3 (deprecato)
• 4096 token per Claude Haiku 4.5
• 2048 token per Claude Haiku 3.5 e Claude Haiku 3

I 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 simultanee, nota che una voce della cache diventa disponibile solo dopo l'inizio della prima risposta. Se hai bisogno di hit della 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.

Comprensione dei costi dei punti di interruzione della cache

I punti di interruzione della cache stessi non aggiungono alcun costo. Ti viene addebitato solo per:

• Scritture della cache: Quando il nuovo contenuto viene scritto nella cache (25% in più rispetto ai token di input di base per TTL di 5 minuti)
• Letture della cache: Quando il contenuto memorizzato nella cache viene utilizzato (10% del prezzo dei token di input di base)
• Token di input regolari: Per qualsiasi contenuto non memorizzato nella cache

L'aggiunta di più punti di interruzione cache_control non aumenta i tuoi costi - paghi comunque lo stesso importo in base a quale contenuto viene effettivamente memorizzato nella cache e letto. I punti di interruzione ti danno semplicemente il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

• 1024 token per Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (deprecato) e Claude Opus 3 (deprecato)
• 4096 token per Claude Haiku 4.5
• 2048 token per Claude Haiku 3.5 e Claude Haiku 3

I 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 simultanee, nota che una voce della cache diventa disponibile solo dopo l'inizio della prima risposta. Se hai bisogno di hit della 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.

Comprensione dei costi dei punti di interruzione della cache

I punti di interruzione della cache stessi non aggiungono alcun costo. Ti viene addebitato solo per:

• Scritture della cache: Quando il nuovo contenuto viene scritto nella cache (25% in più rispetto ai token di input di base per TTL di 5 minuti)
• Letture della cache: Quando il contenuto memorizzato nella cache viene utilizzato (10% del prezzo dei token di input di base)
• Token di input regolari: Per qualsiasi contenuto non memorizzato nella cache

L'aggiunta di più punti di interruzione cache_control non aumenta i tuoi costi - paghi comunque lo stesso importo in base a quale contenuto viene effettivamente memorizzato nella cache e letto. I punti di interruzione ti danno semplicemente il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.

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 di strumenti: Blocchi di contenuto nell'array messages.content, sia per i turni dell'utente che dell'assistente

Ognuno di questi elementi può essere contrassegnato con cache_control per abilitare il caching per quella parte della richiesta.

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

• 1024 token per Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (deprecato) e Claude Opus 3 (deprecato)
• 4096 token per Claude Haiku 4.5
• 2048 token per Claude Haiku 3.5 e Claude Haiku 3

I 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 simultanee, nota che una voce della cache diventa disponibile solo dopo l'inizio della prima risposta. Se hai bisogno di hit della 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.

Comprensione dei costi dei punti di interruzione della cache

I punti di interruzione della cache stessi non aggiungono alcun costo. Ti viene addebitato solo per:

• Scritture della cache: Quando il nuovo contenuto viene scritto nella cache (25% in più rispetto ai token di input di base per TTL di 5 minuti)
• Letture della cache: Quando il contenuto memorizzato nella cache viene utilizzato (10% del prezzo dei token di input di base)
• Token di input regolari: Per qualsiasi contenuto non memorizzato nella cache

L'aggiunta di più punti di interruzione cache_control non aumenta i tuoi costi - paghi comunque lo stesso importo in base a quale contenuto viene effettivamente memorizzato nella cache e letto. I punti di interruzione ti danno semplicemente il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.

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 di strumenti: Blocchi di contenuto nell'array messages.content, sia per i turni dell'utente che dell'assistente

Ognuno di questi elementi può essere contrassegnato con cache_control per abilitare il caching per quella parte della richiesta.

Cosa non può essere memorizzato nella cache

Sebbene la maggior parte dei blocchi di richiesta possa 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 altro contenuto quando compaiono nei turni dell'assistente precedenti. Quando memorizzati nella cache in questo modo, CONTANO come token di input quando letti dalla cache.

• I blocchi di sub-contenuto (come citazioni) stessi 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 servono come materiale di origine per le citazioni possono essere memorizzati nella cache. Ciò ti consente di utilizzare il caching dei prompt con le citazioni in modo efficace memorizzando nella cache i documenti a cui le citazioni faranno riferimento.

• I blocchi di testo vuoti non possono essere memorizzati nella cache.

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

• 1024 token per Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (deprecato) e Claude Opus 3 (deprecato)
• 4096 token per Claude Haiku 4.5
• 2048 token per Claude Haiku 3.5 e Claude Haiku 3

I 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 simultanee, nota che una voce della cache diventa disponibile solo dopo l'inizio della prima risposta. Se hai bisogno di hit della 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.

Comprensione dei costi dei punti di interruzione della cache

I punti di interruzione della cache stessi non aggiungono alcun costo. Ti viene addebitato solo per:

• Scritture della cache: Quando il nuovo contenuto viene scritto nella cache (25% in più rispetto ai token di input di base per TTL di 5 minuti)
• Letture della cache: Quando il contenuto memorizzato nella cache viene utilizzato (10% del prezzo dei token di input di base)
• Token di input regolari: Per qualsiasi contenuto non memorizzato nella cache

L'aggiunta di più punti di interruzione cache_control non aumenta i tuoi costi - paghi comunque lo stesso importo in base a quale contenuto viene effettivamente memorizzato nella cache e letto. I punti di interruzione ti danno semplicemente il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.

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 di strumenti: Blocchi di contenuto nell'array messages.content, sia per i turni dell'utente che dell'assistente

Ognuno di questi elementi può essere contrassegnato con cache_control per abilitare il caching per quella parte della richiesta.

Cosa non può essere memorizzato nella cache

Sebbene la maggior parte dei blocchi di richiesta possa 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 altro contenuto quando compaiono nei turni dell'assistente precedenti. Quando memorizzati nella cache in questo modo, CONTANO come token di input quando letti dalla cache.

• I blocchi di sub-contenuto (come citazioni) stessi 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 servono come materiale di origine per le citazioni possono essere memorizzati nella cache. Ciò ti consente di utilizzare il caching dei prompt con le citazioni in modo efficace memorizzando nella cache i documenti a cui le citazioni faranno riferimento.

• I blocchi di testo vuoti non possono essere memorizzati nella cache.

Cosa invalida la cache

Le modifiche al contenuto memorizzato nella cache possono invalidare parte o tutta la cache.

Come descritto in Strutturazione del tuo prompt, la cache segue la gerarchia: tools → system → messages. Le modifiche a ogni livello invalidano quel livello e tutti i livelli successivi.

La tabella seguente 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.

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

• 1024 token per Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (deprecato) e Claude Opus 3 (deprecato)
• 4096 token per Claude Haiku 4.5
• 2048 token per Claude Haiku 3.5 e Claude Haiku 3

I 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 simultanee, nota che una voce della cache diventa disponibile solo dopo l'inizio della prima risposta. Se hai bisogno di hit della 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.

Comprensione dei costi dei punti di interruzione della cache

I punti di interruzione della cache stessi non aggiungono alcun costo. Ti viene addebitato solo per:

• Scritture della cache: Quando il nuovo contenuto viene scritto nella cache (25% in più rispetto ai token di input di base per TTL di 5 minuti)
• Letture della cache: Quando il contenuto memorizzato nella cache viene utilizzato (10% del prezzo dei token di input di base)
• Token di input regolari: Per qualsiasi contenuto non memorizzato nella cache

L'aggiunta di più punti di interruzione cache_control non aumenta i tuoi costi - paghi comunque lo stesso importo in base a quale contenuto viene effettivamente memorizzato nella cache e letto. I punti di interruzione ti danno semplicemente il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.

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 di strumenti: Blocchi di contenuto nell'array messages.content, sia per i turni dell'utente che dell'assistente

Ognuno di questi elementi può essere contrassegnato con cache_control per abilitare il caching per quella parte della richiesta.

Cosa non può essere memorizzato nella cache

Sebbene la maggior parte dei blocchi di richiesta possa 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 altro contenuto quando compaiono nei turni dell'assistente precedenti. Quando memorizzati nella cache in questo modo, CONTANO come token di input quando letti dalla cache.

• I blocchi di sub-contenuto (come citazioni) stessi 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 servono come materiale di origine per le citazioni possono essere memorizzati nella cache. Ciò ti consente di utilizzare il caching dei prompt con le citazioni in modo efficace memorizzando nella cache i documenti a cui le citazioni faranno riferimento.

• I blocchi di testo vuoti non possono essere memorizzati nella cache.

Cosa invalida la cache

Le modifiche al contenuto memorizzato nella cache possono invalidare parte o tutta la cache.

Come descritto in Strutturazione del tuo prompt, la cache segue la gerarchia: tools → system → messages. Le modifiche a ogni livello invalidano quel livello e tutti i livelli successivi.

La tabella seguente 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.

Monitoraggio delle prestazioni della cache

Monitora le prestazioni della cache utilizzando questi campi di risposta dell'API, all'interno di usage nella risposta (o 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 da o utilizzati per creare una cache (cioè, token dopo l'ultimo punto di interruzione della cache).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Limitazioni della cache

La lunghezza minima della cache è:

• 1024 token per Claude Opus 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (deprecato) e Claude Opus 3 (deprecato)
• 4096 token per Claude Haiku 4.5
• 2048 token per Claude Haiku 3.5 e Claude Haiku 3

I prompt più brevi non possono essere memorizzati nella cache, anche se contrassegnati con cache_control. Qualsiasi richiesta di memorizzazione nella cache di meno di questo numero di token verrà elaborata senza cache. Per verificare se un prompt è stato memorizzato nella cache, consulta i campi di utilizzo della risposta.

Per le richieste simultanee, tieni presente che una voce della cache diventa disponibile solo dopo l'inizio della prima risposta. Se hai bisogno di hit della 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.

Comprensione dei costi dei punti di interruzione della cache

I punti di interruzione della cache stessi non aggiungono alcun costo. Ti viene addebitato solo per:

• Scritture nella cache: Quando nuovo contenuto viene scritto nella cache (25% in più rispetto ai token di input di base per TTL di 5 minuti)
• Letture dalla cache: Quando il contenuto memorizzato nella cache viene utilizzato (10% del prezzo del token di input di base)
• Token di input regolari: Per qualsiasi contenuto non memorizzato nella cache

L'aggiunta di più punti di interruzione cache_control non aumenta i tuoi costi - paghi comunque lo stesso importo in base al contenuto effettivamente memorizzato nella cache e letto. I punti di interruzione ti danno semplicemente il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.

Cosa può essere memorizzato nella cache

La maggior parte dei blocchi nella richiesta può essere designata per la memorizzazione nella cache 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 di strumenti: Blocchi di contenuto nell'array messages.content, sia per i turni dell'utente che dell'assistente

Ognuno di questi elementi può essere contrassegnato con cache_control per abilitare la memorizzazione nella cache per quella parte della richiesta.

Cosa non può essere memorizzato nella cache

Sebbene la maggior parte dei blocchi di richiesta possa 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 altro contenuto quando compaiono nei turni precedenti dell'assistente. Se memorizzati in questo modo, CONTANO come token di input quando letti dalla cache.

• I blocchi di sotto-contenuto (come le citazioni) stessi 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 servono come materiale di origine per le citazioni possono essere memorizzati nella cache. Questo ti consente di utilizzare la memorizzazione nella cache del prompt con le citazioni in modo efficace memorizzando nella cache i documenti a cui le citazioni faranno riferimento.

• I blocchi di testo vuoti non possono essere memorizzati nella cache.

Cosa invalida la cache

Le modifiche al contenuto memorizzato nella cache possono invalidare parte o tutta la cache.

Come descritto in Strutturazione del prompt, la cache segue la gerarchia: tools → system → messages. Le modifiche a ogni livello invalidano quel livello e tutti i livelli successivi.

La tabella seguente 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.

Tracciamento delle prestazioni della cache

Monitora le prestazioni della cache utilizzando questi campi di risposta dell'API, all'interno di usage nella risposta (o 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 da o utilizzati per creare una cache (cioè token dopo l'ultimo punto di interruzione della cache).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

Migliori pratiche per una memorizzazione nella cache efficace

Per ottimizzare le prestazioni della memorizzazione nella cache del prompt:

• Memorizza nella cache contenuto stabile e riutilizzabile 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 le migliori prestazioni.
• Utilizza i punti di interruzione della cache strategicamente per separare diverse sezioni di prefisso memorizzabili nella cache.
• Imposta i punti di interruzione della cache alla fine delle conversazioni e appena prima del contenuto modificabile per massimizzare i tassi di hit della cache, soprattutto quando si lavora con prompt che hanno più di 20 blocchi di contenuto.
• Analizza regolarmente i tassi di hit della cache e regola la tua strategia secondo le necessità.

Ottimizzazione per diversi casi d'uso

Personalizza la tua strategia di memorizzazione nella cache del prompt al tuo scenario:

• Agenti conversazionali: Riduci il costo e la latenza per conversazioni estese, soprattutto quelle con istruzioni lunghe o documenti caricati.
• Assistenti di codifica: Migliora l'autocompletamento e le domande e risposte 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 forma incluse immagini nel tuo prompt senza aumentare la latenza della risposta.
• Set di istruzioni dettagliati: Condividi elenchi estesi di istruzioni, procedure ed esempi per mettere a punto le risposte di Claude. Gli sviluppatori spesso includono uno o due esempi nel prompt, ma con la memorizzazione nella cache del prompt puoi ottenere prestazioni ancora migliori includendo 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 di codice iterative, dove ogni passaggio in genere richiede una nuova chiamata API.
• Parla con libri, articoli, documentazione, trascrizioni di podcast e altri contenuti di lunga forma: Dai vita a qualsiasi base di conoscenza incorporando l'intero documento(i) nel prompt e lasciando che gli utenti gli facciano domande.

Ottimizzazione per diversi casi d'uso

Personalizza la tua strategia di memorizzazione nella cache del prompt al tuo scenario:

• Agenti conversazionali: Riduci il costo e la latenza per conversazioni estese, soprattutto quelle con istruzioni lunghe o documenti caricati.
• Assistenti di codifica: Migliora l'autocompletamento e le domande e risposte 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 forma incluse immagini nel tuo prompt senza aumentare la latenza della risposta.
• Set di istruzioni dettagliati: Condividi elenchi estesi di istruzioni, procedure ed esempi per mettere a punto le risposte di Claude. Gli sviluppatori spesso includono uno o due esempi nel prompt, ma con la memorizzazione nella cache del prompt puoi ottenere prestazioni ancora migliori includendo 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 di codice iterative, dove ogni passaggio in genere richiede una nuova chiamata API.
• Parla con libri, articoli, documentazione, trascrizioni di podcast e altri contenuti di lunga forma: Dai vita a qualsiasi base di conoscenza incorporando l'intero documento(i) nel prompt e lasciando che gli utenti gli facciano domande.

Risoluzione dei problemi comuni

Se riscontri comportamenti imprevisti:

• Assicurati che le sezioni memorizzate nella cache siano identiche e contrassegnate con cache_control negli stessi luoghi tra le chiamate
• Verifica che le chiamate vengano effettuate entro la durata della cache (5 minuti per impostazione predefinita)
• Verifica che tool_choice e l'utilizzo delle immagini rimangono coerenti tra le chiamate
• Convalida che stai memorizzando nella cache almeno il numero minimo di token
• Il sistema controlla automaticamente i hit della cache ai confini dei blocchi di contenuto precedenti (fino a ~20 blocchi prima del tuo punto di interruzione). Per i prompt con più di 20 blocchi di contenuto, potrebbe essere necessario aggiungere parametri cache_control aggiuntivi all'inizio del prompt per garantire che tutto il contenuto possa essere memorizzato nella cache
• Verifica che le chiavi nei tuoi blocchi di contenuto tool_use abbiano un ordine stabile poiché alcuni linguaggi (ad es. Swift, Go) randomizzano l'ordine delle chiavi durante la conversione JSON, interrompendo le cache

Memorizzazione nella cache con blocchi di pensiero

Quando si utilizza il pensiero esteso con la memorizzazione nella cache del prompt, i blocchi di pensiero hanno un comportamento speciale:

Memorizzazione nella cache automatica insieme ad altro contenuto: Sebbene i blocchi di pensiero non possono essere esplicitamente contrassegnati con cache_control, vengono memorizzati nella cache come parte del contenuto della richiesta quando effettui successive chiamate API con risultati di strumenti. Questo accade comunemente durante l'utilizzo di 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, contano 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 solo i risultati di strumenti vengono forniti come messaggi utente
• La cache viene invalidata quando viene aggiunto contenuto utente non di risultati di strumenti, causando la rimozione di tutti i blocchi di pensiero precedenti
• Questo comportamento di memorizzazione nella cache si verifica anche senza marcatori cache_control espliciti

Per ulteriori dettagli sull'invalidazione della cache, consulta Cosa invalida la cache.

Esempio con utilizzo di 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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Quando viene incluso un blocco utente non di risultati di strumenti, designa un nuovo ciclo dell'assistente e tutti i blocchi di pensiero precedenti vengono rimossi dal contesto.

Per informazioni più dettagliate, consulta la documentazione del pensiero esteso.

Memorizzazione nella cache e condivisione

• Isolamento dell'organizzazione: Le cache sono isolate tra le organizzazioni. Diverse organizzazioni non condividono mai le cache, anche se utilizzano prompt identici.

• Corrispondenza esatta: I hit della cache richiedono segmenti di prompt identici al 100%, incluso tutto il testo e le immagini fino a e incluso il blocco contrassegnato con controllo della cache.

• Generazione di token di output: La memorizzazione nella cache del prompt non ha effetto sulla generazione di token di output. La risposta che ricevi sarà identica a quella che otterresti se la memorizzazione nella cache del prompt non fosse utilizzata.

Ottimizzazione per diversi casi d'uso

Personalizza la tua strategia di memorizzazione nella cache del prompt al tuo scenario:

• Agenti conversazionali: Riduci il costo e la latenza per conversazioni estese, soprattutto quelle con istruzioni lunghe o documenti caricati.
• Assistenti di codifica: Migliora l'autocompletamento e le domande e risposte 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 forma incluse immagini nel tuo prompt senza aumentare la latenza della risposta.
• Set di istruzioni dettagliati: Condividi elenchi estesi di istruzioni, procedure ed esempi per mettere a punto le risposte di Claude. Gli sviluppatori spesso includono uno o due esempi nel prompt, ma con la memorizzazione nella cache del prompt puoi ottenere prestazioni ancora migliori includendo 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 di codice iterative, dove ogni passaggio in genere richiede una nuova chiamata API.
• Parla con libri, articoli, documentazione, trascrizioni di podcast e altri contenuti di lunga forma: Dai vita a qualsiasi base di conoscenza incorporando l'intero documento(i) nel prompt e lasciando che gli utenti gli facciano domande.

Risoluzione dei problemi comuni

Se riscontri comportamenti imprevisti:

• Assicurati che le sezioni memorizzate nella cache siano identiche e contrassegnate con cache_control negli stessi luoghi tra le chiamate
• Verifica che le chiamate vengano effettuate entro la durata della cache (5 minuti per impostazione predefinita)
• Verifica che tool_choice e l'utilizzo delle immagini rimangono coerenti tra le chiamate
• Convalida che stai memorizzando nella cache almeno il numero minimo di token
• Il sistema controlla automaticamente i hit della cache ai confini dei blocchi di contenuto precedenti (fino a ~20 blocchi prima del tuo punto di interruzione). Per i prompt con più di 20 blocchi di contenuto, potrebbe essere necessario aggiungere parametri cache_control aggiuntivi all'inizio del prompt per garantire che tutto il contenuto possa essere memorizzato nella cache
• Verifica che le chiavi nei tuoi blocchi di contenuto tool_use abbiano un ordine stabile poiché alcuni linguaggi (ad es. Swift, Go) randomizzano l'ordine delle chiavi durante la conversione JSON, interrompendo le cache

Memorizzazione nella cache con blocchi di pensiero

Quando si utilizza il pensiero esteso con la memorizzazione nella cache del prompt, i blocchi di pensiero hanno un comportamento speciale:

Memorizzazione nella cache automatica insieme ad altro contenuto: Sebbene i blocchi di pensiero non possono essere esplicitamente contrassegnati con cache_control, vengono memorizzati nella cache come parte del contenuto della richiesta quando effettui successive chiamate API con risultati di strumenti. Questo accade comunemente durante l'utilizzo di 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, contano 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 solo i risultati di strumenti vengono forniti come messaggi utente
• La cache viene invalidata quando viene aggiunto contenuto utente non di risultati di strumenti, causando la rimozione di tutti i blocchi di pensiero precedenti
• Questo comportamento di memorizzazione nella cache si verifica anche senza marcatori cache_control espliciti

Per ulteriori dettagli sull'invalidazione della cache, consulta Cosa invalida la cache.

Esempio con utilizzo di 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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Quando viene incluso un blocco utente non di risultati di strumenti, designa un nuovo ciclo dell'assistente e tutti i blocchi di pensiero precedenti vengono rimossi dal contesto.

Per informazioni più dettagliate, consulta la documentazione del pensiero esteso.

Memorizzazione nella cache e condivisione

• Isolamento dell'organizzazione: Le cache sono isolate tra le organizzazioni. Diverse organizzazioni non condividono mai le cache, anche se utilizzano prompt identici.

• Corrispondenza esatta: I hit della cache richiedono segmenti di prompt identici al 100%, incluso tutto il testo e le immagini fino a e incluso il blocco contrassegnato con controllo della cache.

• Generazione di token di output: La memorizzazione nella cache del prompt non ha effetto sulla generazione di token di output. La risposta che ricevi sarà identica a quella che otterresti se la memorizzazione nella cache del prompt non fosse utilizzata.

Durata della cache di 1 ora

Se ritieni che 5 minuti sia troppo breve, Anthropic offre anche una durata della cache di 1 ora a costo aggiuntivo.

Per utilizzare la cache estesa, includi ttl nella definizione di cache_control in questo modo:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

La risposta includerà informazioni dettagliate sulla cache come la seguente:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,

        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

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 a cadenza regolare (cioè prompt di sistema che vengono utilizzati più frequentemente di ogni 5 minuti), continua a utilizzare la cache di 5 minuti, poiché continuerà a essere aggiornata senza costi aggiuntivi.

La cache di 1 ora è meglio utilizzata 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 agentivo impiegherà più di 5 minuti, o quando memorizzi una lunga conversazione di chat con un utente e generalmente ti aspetti 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 5 minuti.
• Quando desideri migliorare l'utilizzo del tuo limite di velocità, poiché i hit della cache non vengono detratti dal tuo limite di velocità.

Ottimizzazione per diversi casi d'uso

Personalizza la tua strategia di prompt caching al tuo scenario:

• Agenti conversazionali: Riduci costi e latenza per conversazioni estese, specialmente quelle con istruzioni lunghe 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 forma incluse immagini nel tuo prompt senza aumentare la latenza di risposta.
• Set di istruzioni dettagliati: Condividi estesi elenchi di istruzioni, procedure ed esempi per ottimizzare le risposte di Claude. Gli sviluppatori spesso includono uno o due esempi nel prompt, ma con il prompt caching puoi ottenere prestazioni ancora migliori includendo 20+ esempi diversi di risposte di alta qualità.
• Uso di strumenti agentic: Migliora le prestazioni per scenari che coinvolgono più chiamate di strumenti e modifiche di codice iterative, dove ogni passaggio tipicamente richiede una nuova chiamata API.
• Parla con libri, articoli, documentazione, trascrizioni di podcast e altri contenuti di lunga forma: Dai vita a qualsiasi base di conoscenza incorporando l'intero documento(i) nel prompt e lasciando che gli utenti facciano domande al riguardo.

Risoluzione dei problemi comuni

Se riscontri comportamenti inaspettati:

• Assicurati che le sezioni memorizzate nella cache siano identiche e contrassegnate con cache_control negli stessi luoghi tra le chiamate
• Verifica che le chiamate vengano effettuate entro la durata della cache (5 minuti per impostazione predefinita)
• Verifica che tool_choice e l'utilizzo delle immagini rimangono coerenti tra le chiamate
• Convalida che stai memorizzando nella cache almeno il numero minimo di token
• Il sistema controlla automaticamente i cache hit ai confini dei blocchi di contenuto precedenti (fino a ~20 blocchi prima del tuo punto di interruzione). Per i prompt con più di 20 blocchi di contenuto, potrebbe essere necessario aggiungere parametri cache_control aggiuntivi prima nel prompt per garantire che tutto il contenuto possa essere memorizzato nella cache
• Verifica che le chiavi nei tuoi blocchi di contenuto tool_use abbiano un ordine stabile poiché alcuni linguaggi (ad es. Swift, Go) randomizzano l'ordine delle chiavi durante la conversione JSON, interrompendo le cache

Caching con blocchi di pensiero

Quando si utilizza il pensiero esteso con il prompt caching, i blocchi di pensiero hanno un comportamento speciale:

Caching automatico insieme ad altri contenuti: Sebbene i blocchi di pensiero non possono essere esplicitamente contrassegnati con cache_control, vengono memorizzati nella cache come parte del contenuto della richiesta quando effettui successive chiamate API con risultati di strumenti. Questo accade comunemente durante l'uso di 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, contano 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 solo i risultati degli strumenti vengono forniti come messaggi dell'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

Per ulteriori dettagli sull'invalidazione della cache, vedi Cosa invalida la cache.

Esempio con uso di 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]
# Non-tool-result user block causes all thinking blocks to be ignored
# This request is processed as if thinking blocks were never present

Quando un blocco utente non relativo ai risultati degli strumenti è incluso, designa un nuovo ciclo di assistente e tutti i blocchi di pensiero precedenti vengono rimossi dal contesto.

Per informazioni più dettagliate, vedi la documentazione del pensiero esteso.

Archiviazione e condivisione della cache

• Isolamento dell'organizzazione: Le cache sono isolate tra le organizzazioni. Diverse organizzazioni non condividono mai cache, anche se utilizzano prompt identici.

• Corrispondenza esatta: I cache hit richiedono segmenti di prompt identici al 100%, incluso tutto il testo e le immagini fino a e incluso il blocco contrassegnato con il controllo della cache.

• Generazione di token di output: Il prompt caching non ha alcun effetto sulla generazione di token di output. La risposta che ricevi sarà identica a quella che otterresti se il prompt caching non fosse utilizzato.

Durata della cache di 1 ora

Se ritieni che 5 minuti sia troppo breve, Anthropic offre anche una durata della cache di 1 ora a costo aggiuntivo.

Per utilizzare la cache estesa, includi ttl nella definizione di cache_control in questo modo:

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

La risposta includerà informazioni dettagliate sulla cache come le seguenti:

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,

        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

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 a cadenza regolare (ad es. prompt di sistema che vengono utilizzati più frequentemente di ogni 5 minuti), continua a utilizzare la cache di 5 minuti, poiché continuerà a essere aggiornata senza costi aggiuntivi.

La cache di 1 ora è meglio utilizzata 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 agentic impiegherà più di 5 minuti, o quando memorizzi una lunga conversazione di chat con un utente e generalmente ti aspetti 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 5 minuti.
• Quando desideri migliorare l'utilizzo del tuo limite di velocità, poiché i cache hit non vengono detratti dal tuo limite di velocità.

Miscelazione di diversi TTL

Puoi utilizzare sia controlli di cache di 1 ora che di 5 minuti nella stessa richiesta, ma con un vincolo importante: Le voci di cache con TTL più lungo devono apparire prima di TTL più brevi (ad es. una voce di cache di 1 ora deve apparire prima di qualsiasi voce di cache di 5 minuti).

Quando si mescolano i TTL, determiniamo tre posizioni di fatturazione nel tuo prompt:

1. Posizione A: Il conteggio dei token al cache hit più alto (o 0 se nessun hit).
2. Posizione B: Il conteggio dei token al blocco cache_control di 1 ora più alto dopo A (o uguale a A se nessuno esiste).
3. Posizione C: Il conteggio dei token all'ultimo blocco cache_control.

Ti verrà addebitato per:

1. Token di lettura della cache per A.
2. Token di scrittura della cache di 1 ora per (B - A).
3. Token di scrittura della cache di 5 minuti per (C - B).

Ecco 3 esempi. Questo raffigura i token di input di 3 richieste, ognuna delle quali ha diversi cache hit e cache miss. Ognuna ha un prezzo calcolato diverso, mostrato nelle caselle colorate, di conseguenza.

Esempi di prompt caching

Per aiutarti a iniziare con il prompt caching, abbiamo preparato un prompt caching cookbook con esempi dettagliati e best practice.

Di seguito, abbiamo incluso diversi frammenti di codice che mostrano vari modelli di prompt caching. Questi esempi dimostrano come implementare il caching in diversi scenari, aiutandoti a comprendere le applicazioni pratiche di questa funzionalità:

FAQ

Questo è importante per comprendere sia i costi che i limiti di velocità, poiché input_tokens sarà tipicamente molto più piccolo del tuo input totale quando utilizzi il caching in modo efficace.

Questo è importante per comprendere sia i costi che i limiti di velocità, poiché input_tokens sarà in genere molto più piccolo del tuo input totale quando utilizzi la memorizzazione nella cache in modo efficace.