Cache dei prompt

Il cache dei prompt è una funzionalità potente che ottimizza l’utilizzo delle 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 il 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-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Sei un assistente AI incaricato di analizzare opere letterarie. Il tuo obiettivo è fornire commenti perspicaci su temi, personaggi e stile di scrittura.\n"
      },
      {
        "type": "text",
        "text": "<l'intero contenuto di Orgoglio e Pregiudizio>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analizza i temi principali in Orgoglio e Pregiudizio."
      }
    ]
  }'

# Chiama nuovamente il modello con gli stessi input fino al checkpoint della cache
curl https://api.anthropic.com/v1/messages # resto dell'input

JSON

{"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 “Orgoglio e Pregiudizio” viene memorizzato nella cache utilizzando il parametro cache_control. Questo consente il riutilizzo di questo testo di grandi dimensioni attraverso più chiamate API senza riprocessarlo ogni volta. Cambiando solo il messaggio dell’utente ti permette di fare varie domande sul libro utilizzando il contenuto memorizzato nella cache, portando a risposte più veloci e maggiore efficienza.

Come funziona il cache dei prompt

Quando invii una richiesta con il cache dei prompt abilitato:

Il sistema controlla 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 i tempi di elaborazione e i costi.
Altrimenti, elabora l’intero prompt e memorizza nella cache il prefisso una volta che inizia la risposta.

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.

Se trovi che 5 minuti siano troppo pochi, Anthropic offre anche una durata della cache di 1 ora.Per maggiori informazioni, vedi Durata della cache di 1 ora.

Il cache dei prompt memorizza l’intero prefissoIl cache dei prompt fa riferimento all’intero prompt - tools, system e messages (in quest’ordine) fino al blocco designato con cache_control incluso.

Prezzi

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

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output Tokens
Claude Opus 4.1	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
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 (deprecated)	$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 (deprecated)	$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

La tabella sopra riflette i seguenti moltiplicatori di prezzo per il cache dei prompt:

I token di scrittura della cache di 5 minuti costano 1,25 volte il prezzo base dei token di input
I token di scrittura della cache di 1 ora costano 2 volte il prezzo base dei token di input
I token di lettura della cache costano 0,1 volte il prezzo base dei token di input

Come implementare il cache dei prompt

Modelli supportati

Il cache dei prompt è attualmente supportato su:

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

Strutturare il tuo prompt

Posiziona il contenuto statico (definizioni degli strumenti, istruzioni di sistema, contesto, esempi) all’inizio del tuo prompt. Segna la fine del contenuto riutilizzabile per la memorizzazione nella cache utilizzando il parametro cache_control. I prefissi della cache vengono creati nel seguente ordine: tools, system, poi messages. Questo ordine forma una gerarchia dove ogni livello si basa sui precedenti.

Come funziona il controllo automatico dei prefissi

Puoi utilizzare solo un punto di interruzione della cache alla fine del tuo contenuto statico, e il sistema troverà automaticamente il prefisso corrispondente più lungo. Ecco come funziona:

Quando aggiungi un punto di interruzione cache_control, il sistema controlla automaticamente i riscontri della cache a tutti i confini dei blocchi di contenuto precedenti (fino a circa 20 blocchi prima del tuo punto di interruzione esplicito)
Se qualcuna di queste posizioni precedenti corrisponde al contenuto memorizzato nella cache da richieste precedenti, il sistema utilizza il prefisso corrispondente più lungo
Questo significa che non hai bisogno di più punti di interruzione solo per abilitare la memorizzazione nella cache - uno alla fine è sufficiente

Quando utilizzare più punti di interruzione

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

Memorizzare nella cache diverse sezioni 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 la memorizzazione nella cache per contenuti più di 20 blocchi prima del tuo punto di interruzione finale

Limitazione importante: Il controllo automatico dei prefissi guarda indietro solo circa 20 blocchi di contenuto da ogni punto di interruzione esplicito. Se il tuo prompt ha più di 20 blocchi di contenuto prima del tuo punto di interruzione della cache, il contenuto precedente a quello non verrà controllato per i riscontri della cache a meno che tu non aggiunga punti di interruzione aggiuntivi.

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

1024 token per Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (deprecato) e Claude Opus 3 (deprecato)
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 memorizzazione nella cache. Per vedere se un prompt è stato memorizzato nella cache, vedi i campi di utilizzo della risposta. Per le richieste concorrenti, nota che una voce della cache diventa disponibile solo dopo che inizia la prima risposta. Se hai bisogno di riscontri della cache per richieste parallele, aspetta 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.

Comprendere i costi dei punti di interruzione della cache

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

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

Aggiungere più punti di interruzione cache_control non aumenta i tuoi costi - paghi ancora la stessa quantità basata su 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 indipendentemente.

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 degli strumenti nell’array tools
Messaggi di sistema: Blocchi di contenuto nell’array system
Messaggi di testo: Blocchi di contenuto nell’array messages.content, per turni sia 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, in turni sia dell’utente che dell’assistente

Ognuno di questi elementi può essere contrassegnato con cache_control per abilitare la memorizzazione nella cache 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 altro contenuto quando appaiono nei turni precedenti dell’assistente. Quando memorizzati nella cache in questo modo, CONTANO come token di input quando letti dalla cache.
I sotto-blocchi di 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 permette di utilizzare il cache dei prompt con le citazioni efficacemente 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 Strutturare il tuo prompt, la cache segue la gerarchia: tools → system → messages. I cambiamenti a ogni livello invalidano quel livello e tutti i livelli successivi. La seguente tabella mostra quali parti della cache vengono invalidate da diversi tipi di cambiamenti. ✘ indica che la cache viene invalidata, mentre ✓ indica che la cache rimane valida.

Cosa cambia	Cache degli strumenti	Cache del sistema	Cache dei messaggi	Impatto
Definizioni degli strumenti	✘	✘	✘	Modificare le definizioni degli strumenti (nomi, descrizioni, parametri) invalida l’intera cache
Attivazione/disattivazione ricerca web	✓	✘	✘	Abilitare/disabilitare la ricerca web modifica il prompt di sistema
Attivazione/disattivazione citazioni	✓	✘	✘	Abilitare/disabilitare le citazioni modifica il prompt di sistema
Scelta dello strumento	✓	✓	✘	I cambiamenti al parametro `tool_choice` influenzano solo i blocchi dei messaggi
Immagini	✓	✓	✘	Aggiungere/rimuovere immagini ovunque nel prompt influenza i blocchi dei messaggi
Parametri di pensiero	✓	✓	✘	I cambiamenti alle impostazioni di pensiero esteso (abilita/disabilita, budget) influenzano i blocchi dei messaggi
Risultati non-strumento passati alle richieste di pensiero esteso	✓	✓	✘	Quando risultati non-strumento vengono passati nelle richieste mentre il pensiero esteso è abilitato, tutti i blocchi di pensiero precedentemente memorizzati nella cache vengono rimossi dal contesto, e qualsiasi messaggio nel contesto che segue quei blocchi di pensiero viene rimosso dalla cache. Per maggiori dettagli, vedi Memorizzazione nella cache con blocchi di pensiero.

Monitorare le 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 quando si crea 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.

Migliori pratiche per una memorizzazione nella cache efficace

Per ottimizzare le prestazioni del cache dei prompt:

Memorizza nella cache contenuto stabile e riutilizzabile come istruzioni di sistema, informazioni di background, contesti di grandi dimensioni 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 prefissi 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 cache dei prompt 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 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 durata incluse immagini nel tuo prompt senza aumentare la latenza di 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 un esempio o due nel prompt, ma con il cache dei prompt puoi ottenere prestazioni ancora migliori includendo 20+ esempi diversi di risposte di alta qualità.
Uso 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: Porta qualsiasi base di conoscenza in vita incorporando l’intero documento/i nel prompt e lasciando che gli utenti facciano domande.

Risoluzione dei problemi comuni

Se stai sperimentando comportamenti inaspettati:

Assicurati che le sezioni memorizzate nella cache siano identiche e contrassegnate con cache_control nelle stesse posizioni tra le chiamate
Controlla che le chiamate siano fatte entro la durata della cache (5 minuti per impostazione predefinita)
Verifica che tool_choice e l’uso delle immagini rimangano coerenti tra le chiamate
Convalida che stai memorizzando nella cache almeno il numero minimo di token
Il sistema controlla automaticamente i riscontri della cache ai confini dei blocchi di contenuto precedenti (fino a ~20 blocchi prima del tuo punto di interruzione). Per prompt con più di 20 blocchi di contenuto, potresti aver bisogno di parametri cache_control aggiuntivi prima nel prompt per garantire che tutto il contenuto possa essere memorizzato nella cache

I cambiamenti a tool_choice o la presenza/assenza di immagini ovunque nel prompt invalideranno la cache, richiedendo la creazione di una nuova voce della cache. Per maggiori dettagli sull’invalidazione della cache, vedi Cosa invalida la cache.

Memorizzazione nella cache con blocchi di pensiero

Quando utilizzi il pensiero esteso con il cache dei prompt, i blocchi di pensiero hanno un comportamento speciale: Memorizzazione automatica nella cache insieme ad altro contenuto: Mentre i blocchi di pensiero non possono essere esplicitamente contrassegnati con cache_control, vengono memorizzati nella cache come parte del contenuto della richiesta quando fai chiamate API successive con risultati degli strumenti. Questo accade comunemente durante l’uso degli strumenti quando passi i blocchi di pensiero indietro 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-risultato-strumento, 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 maggiori dettagli sull’invalidazione della cache, vedi Cosa invalida la cache. Esempio con uso di strumenti:

Richiesta 1: Utente: "Che tempo fa a Parigi?"
Risposta: [blocco_pensiero_1] + [blocco uso strumento 1]

Richiesta 2: 
Utente: ["Che tempo fa a Parigi?"], 
Assistente: [blocco_pensiero_1] + [blocco uso strumento 1], 
Utente: [risultato_strumento_1, cache=True]
Risposta: [blocco_pensiero_2] + [blocco testo 2]
# La Richiesta 2 memorizza nella cache il suo contenuto di richiesta (non la risposta)
# La cache include: messaggio utente, blocco_pensiero_1, blocco uso strumento 1, e risultato_strumento_1

Richiesta 3:
Utente: ["Che tempo fa a Parigi?"], 
Assistente: [blocco_pensiero_1] + [blocco uso strumento 1], 
Utente: [risultato_strumento_1, cache=True], 
Assistente: [blocco_pensiero_2] + [blocco testo 2], 
Utente: [Risposta di testo, cache=True]
# Il blocco utente non-risultato-strumento causa l'ignoramento di tutti i blocchi di pensiero
# Questa richiesta viene elaborata come se i blocchi di pensiero non fossero mai stati presenti

Quando viene incluso un blocco utente non-risultato-strumento, designa un nuovo ciclo dell’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. Organizzazioni diverse non condividono mai le cache, anche se utilizzano prompt identici.
Corrispondenza esatta: I riscontri della cache richiedono segmenti di prompt identici al 100%, inclusi tutto il testo e le immagini fino al blocco contrassegnato con controllo della cache incluso.
Generazione di token di output: Il cache dei prompt non ha effetto sulla generazione di token di output. La risposta che ricevi sarà identica a quella che otterresti se il cache dei prompt non fosse utilizzato.

Durata della cache di 1 ora

Se trovi che 5 minuti siano troppo pochi, Anthropic offre anche una durata della cache di 1 ora. Per utilizzare la cache estesa, includi ttl nella definizione cache_control così:

"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 l’attuale campo cache_creation_input_tokens è 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é questa continuerà ad 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 quell’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 tuo limite di velocità, poiché i riscontri della cache non vengono detratti dal tuo limite di velocità.

La cache di 5 minuti e quella di 1 ora si comportano allo stesso modo rispetto alla latenza. Generalmente vedrai un miglioramento del tempo-al-primo-token per documenti lunghi.

Mescolare 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 della cache con TTL più lungo devono apparire prima dei TTL più brevi (cioè, una voce della cache di 1 ora deve apparire prima di qualsiasi voce della cache di 5 minuti). Quando mescoli TTL, determiniamo tre posizioni di fatturazione nel tuo prompt:

Posizione A: Il conteggio dei token al riscontro della cache più alto (o 0 se non ci sono riscontri).
Posizione B: Il conteggio dei token al blocco cache_control di 1 ora più alto dopo A (o uguale ad A se non ne esistono).
Posizione C: Il conteggio dei token all’ultimo blocco cache_control.

Se B e/o C sono maggiori di A, saranno necessariamente mancati riscontri della cache, perché A è il riscontro della cache più alto.

Verrai 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 raffigura i token di input di 3 richieste, ognuna delle quali ha diversi riscontri e mancati riscontri della cache. Ognuna ha un prezzo calcolato diverso, mostrato nelle caselle colorate, di conseguenza.

Esempi di cache dei prompt

Per aiutarti a iniziare con il cache dei prompt, abbiamo preparato un cookbook del cache dei prompt con esempi dettagliati e migliori pratiche. Di seguito, abbiamo incluso diversi frammenti di codice che mostrano vari modelli di cache dei prompt. Questi esempi dimostrano come implementare la memorizzazione nella cache in diversi scenari, aiutandoti a comprendere le applicazioni pratiche di questa funzionalità:

Esempio di memorizzazione nella cache di contesto di grandi dimensioni

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "Sei un assistente AI incaricato di analizzare documenti legali."
        },
        {
            "type": "text",
            "text": "Ecco il testo completo di un accordo legale complesso: [Inserisci il testo completo di un accordo legale di 50 pagine qui]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Quali sono i termini e le condizioni chiave in questo accordo?"
        }
    ]
}'

Questo esempio dimostra l’uso base del cache dei prompt, memorizzando nella cache il testo completo dell’accordo legale come prefisso mantenendo l’istruzione dell’utente non memorizzata nella cache.Per la prima richiesta:

input_tokens: Numero di token solo nel messaggio dell’utente
cache_creation_input_tokens: Numero di token nell’intero messaggio di sistema, incluso il documento legale
cache_read_input_tokens: 0 (nessun riscontro della cache alla prima richiesta)

Per le richieste successive entro la durata della cache:

input_tokens: Numero di token solo nel messaggio dell’utente
cache_creation_input_tokens: 0 (nessuna nuova creazione di cache)
cache_read_input_tokens: Numero di token nell’intero messaggio di sistema memorizzato nella cache

Memorizzazione nella cache delle definizioni degli strumenti

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Ottieni il tempo attuale in una determinata località",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La città e lo stato, ad es. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "L'unità di temperatura, celsius o fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # molti altri strumenti
        {
            "name": "get_time",
            "description": "Ottieni l'ora attuale in un determinato fuso orario",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "Il nome del fuso orario IANA, ad es. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Qual è il tempo e l'ora a New York?"
        }
    ]
}'

In questo esempio, dimostriamo la memorizzazione nella cache delle definizioni degli strumenti.Il parametro cache_control è posizionato sull’ultimo strumento (get_time) per designare tutti gli strumenti come parte del prefisso statico.Questo significa che tutte le definizioni degli strumenti, inclusi get_weather e qualsiasi altro strumento definito prima di get_time, verranno memorizzate nella cache come un singolo prefisso.Questo approccio è utile quando hai un set coerente di strumenti che vuoi riutilizzare attraverso più richieste senza riprocessarli ogni volta.Per la prima richiesta:

input_tokens: Numero di token nel messaggio dell’utente
cache_creation_input_tokens: Numero di token in tutte le definizioni degli strumenti e prompt di sistema
cache_read_input_tokens: 0 (nessun riscontro della cache alla prima richiesta)

Per le richieste successive entro la durata della cache:

input_tokens: Numero di token nel messaggio dell’utente
cache_creation_input_tokens: 0 (nessuna nuova creazione di cache)
cache_read_input_tokens: Numero di token in tutte le definizioni degli strumenti memorizzate nella cache e prompt di sistema

Continuare una conversazione multi-turno

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...prompt di sistema lungo",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Ciao, puoi dirmi di più sul sistema solare?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certamente! Il sistema solare è la collezione di corpi celesti che orbitano attorno al nostro Sole. È composto da otto pianeti, numerose lune, asteroidi, comete e altri oggetti. I pianeti, in ordine dal più vicino al più lontano dal Sole, sono: Mercurio, Venere, Terra, Marte, Giove, Saturno, Urano e Nettuno. Ogni pianeta ha le sue caratteristiche e caratteristiche uniche. C'è un aspetto specifico del sistema solare di cui vorresti sapere di più?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Buono a sapersi."
                },
                {
                    "type": "text",
                    "text": "Dimmi di più su Marte.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

In questo esempio, dimostriamo come utilizzare il cache dei prompt in una conversazione multi-turno.Durante ogni turno, contrassegniamo il blocco finale del messaggio finale con cache_control così la conversazione può essere memorizzata nella cache incrementalmente. Il sistema cercherà automaticamente e utilizzerà il prefisso precedentemente memorizzato nella cache più lungo per i messaggi di follow-up. Cioè, i blocchi che erano precedentemente contrassegnati con un blocco cache_control successivamente non sono contrassegnati con questo, ma saranno comunque considerati un riscontro della cache (e anche un aggiornamento della cache!) se vengono colpiti entro 5 minuti.Inoltre, nota che il parametro cache_control è posizionato sul messaggio di sistema. Questo è per garantire che se questo viene rimosso dalla cache (dopo non essere stato utilizzato per più di 5 minuti), verrà aggiunto nuovamente alla cache alla richiesta successiva.Questo approccio è utile per mantenere il contesto nelle conversazioni in corso senza elaborare ripetutamente le stesse informazioni.Quando questo è impostato correttamente, dovresti vedere quanto segue nella risposta di utilizzo di ogni richiesta:

input_tokens: Numero di token nel nuovo messaggio dell’utente (sarà minimo)
cache_creation_input_tokens: Numero di token nei nuovi turni dell’assistente e dell’utente
cache_read_input_tokens: Numero di token nella conversazione fino al turno precedente

Mettere tutto insieme: Più punti di interruzione della cache

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Cerca nella base di conoscenza",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Query di ricerca"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Recupera un documento specifico per ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "ID del documento"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "Sei un assistente di ricerca utile con accesso a una base di conoscenza di documenti.\n\n# Istruzioni\n- Cerca sempre documenti rilevanti prima di rispondere\n- Fornisci citazioni per le tue fonti\n- Sii obiettivo e accurato nelle tue risposte\n- Se più documenti contengono informazioni rilevanti, sintetizzali\n- Riconosci quando le informazioni non sono disponibili nella base di conoscenza",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Contesto della Base di Conoscenza\n\nEcco i documenti rilevanti per questa conversazione:\n\n## Documento 1: Panoramica del Sistema Solare\nIl sistema solare è composto dal Sole e da tutti gli oggetti che lo orbitano...\n\n## Documento 2: Caratteristiche Planetarie\nOgni pianeta ha caratteristiche uniche. Mercurio è il pianeta più piccolo...\n\n## Documento 3: Esplorazione di Marte\nMarte è stato un obiettivo di esplorazione per decenni...\n\n[Documenti aggiuntivi...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Puoi cercare informazioni sui rover di Marte?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "rover di Marte"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Trovati 3 documenti rilevanti: Documento 3 (Esplorazione di Marte), Documento 7 (Tecnologia dei Rover), Documento 9 (Storia delle Missioni)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Ho trovato 3 documenti rilevanti sui rover di Marte. Fammi ottenere più dettagli dal documento di Esplorazione di Marte."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Sì, per favore dimmi del rover Perseverance specificamente.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

Questo esempio completo dimostra come utilizzare tutti i 4 punti di interruzione della cache disponibili per ottimizzare diverse parti del tuo prompt:

Cache degli strumenti (punto di interruzione della cache 1): Il parametro cache_control sull’ultima definizione dello strumento memorizza nella cache tutte le definizioni degli strumenti.
Cache delle istruzioni riutilizzabili (punto di interruzione della cache 2): Le istruzioni statiche nel prompt di sistema vengono memorizzate nella cache separatamente. Queste istruzioni cambiano raramente tra le richieste.
Cache del contesto RAG (punto di interruzione della cache 3): I documenti della base di conoscenza vengono memorizzati nella cache indipendentemente, permettendoti di aggiornare i documenti RAG senza invalidare la cache degli strumenti o delle istruzioni.
Cache della cronologia della conversazione (punto di interruzione della cache 4): La risposta dell’assistente è contrassegnata con cache_control per abilitare la memorizzazione nella cache incrementale della conversazione mentre progredisce.

Questo approccio fornisce la massima flessibilità:

Se aggiorni solo il messaggio finale dell’utente, tutti e quattro i segmenti della cache vengono riutilizzati
Se aggiorni i documenti RAG ma mantieni gli stessi strumenti e istruzioni, i primi due segmenti della cache vengono riutilizzati
Se cambi la conversazione ma mantieni gli stessi strumenti, istruzioni e documenti, i primi tre segmenti vengono riutilizzati
Ogni punto di interruzione della cache può essere invalidato indipendentemente basato su cosa cambia nella tua applicazione

Per la prima richiesta:

input_tokens: Token nel messaggio finale dell’utente
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 riscontro della cache)

Per le richieste successive con solo un nuovo messaggio dell’utente:

input_tokens: Token solo nel nuovo messaggio dell’utente
cache_creation_input_tokens: Qualsiasi nuovo token aggiunto alla cronologia della conversazione
cache_read_input_tokens: Tutti i token precedentemente memorizzati nella cache (strumenti + istruzioni + documenti RAG + conversazione precedente)

Questo modello è particolarmente potente per:

Applicazioni RAG con contesti di documenti di grandi dimensioni
Sistemi di agenti che utilizzano più strumenti
Conversazioni di lunga durata che devono mantenere il contesto
Applicazioni che devono ottimizzare diverse parti del prompt indipendentemente

FAQ

Ho bisogno di più punti di interruzione della cache o uno alla fine è sufficiente?

I punti di interruzione della cache aggiungono costi extra?

Qual è la durata della cache?

Quanti punti di interruzione della cache posso utilizzare?

Il cache dei prompt è disponibile per tutti i modelli?

Come funziona il cache dei prompt con il pensiero esteso?

Come abilito il cache dei prompt?

Posso utilizzare il cache dei prompt con altre funzionalità dell'API?

Come influisce il cache dei prompt sui prezzi?

Posso cancellare manualmente la cache?

Come posso monitorare l'efficacia della mia strategia di memorizzazione nella cache?

Cosa può rompere la cache?

Come gestisce il cache dei prompt la privacy e la separazione dei dati?

Posso utilizzare il cache dei prompt con l'API Batches?

Perché vedo l'errore `AttributeError: 'Beta' object has no attribute 'prompt_caching'` in Python?

Questo errore appare tipicamente quando hai aggiornato il tuo SDK o stai utilizzando esempi di codice obsoleti. Il cache dei prompt è ora generalmente disponibile, quindi non hai più bisogno del prefisso beta. Invece di:

python client.beta.prompt_caching.messages.create(...)

Usa semplicemente:

python client.messages.create(...)

Perché vedo 'TypeError: Cannot read properties of undefined (reading 'messages')'?

TypeScript

client.beta.promptCaching.messages.create(...)

Usa semplicemente:

client.messages.create(...)

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

Come funziona il cache dei prompt

Prezzi

Come implementare il cache dei prompt

Modelli supportati

Strutturare il tuo prompt

Come funziona il controllo automatico dei prefissi

Quando utilizzare più punti di interruzione

Limitazioni della cache

Comprendere i costi dei punti di interruzione della cache

Cosa può essere memorizzato nella cache

Cosa non può essere memorizzato nella cache

Cosa invalida la cache

Monitorare le prestazioni della cache

Migliori pratiche per una memorizzazione nella cache efficace

Ottimizzazione per diversi casi d’uso

Risoluzione dei problemi comuni

Memorizzazione nella cache con blocchi di pensiero

Archiviazione e condivisione della cache

Durata della cache di 1 ora

Quando utilizzare la cache di 1 ora

Mescolare diversi TTL

Esempi di cache dei prompt

FAQ

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

​Come funziona il cache dei prompt

​Prezzi

​Come implementare il cache dei prompt

​Modelli supportati

​Strutturare il tuo prompt

​Come funziona il controllo automatico dei prefissi

​Quando utilizzare più punti di interruzione

​Limitazioni della cache

​Comprendere i costi dei punti di interruzione della cache

​Cosa può essere memorizzato nella cache

​Cosa non può essere memorizzato nella cache

​Cosa invalida la cache

​Monitorare le prestazioni della cache

​Migliori pratiche per una memorizzazione nella cache efficace

​Ottimizzazione per diversi casi d’uso

​Risoluzione dei problemi comuni

​Memorizzazione nella cache con blocchi di pensiero

​Archiviazione e condivisione della cache

​Durata della cache di 1 ora

​Quando utilizzare la cache di 1 ora

​Mescolare diversi TTL

​Esempi di cache dei prompt

​FAQ

Come funziona il cache dei prompt

Prezzi

Come implementare il cache dei prompt

Modelli supportati

Strutturare il tuo prompt

Come funziona il controllo automatico dei prefissi

Quando utilizzare più punti di interruzione

Limitazioni della cache

Comprendere i costi dei punti di interruzione della cache

Cosa può essere memorizzato nella cache

Cosa non può essere memorizzato nella cache

Cosa invalida la cache

Monitorare le prestazioni della cache

Migliori pratiche per una memorizzazione nella cache efficace

Ottimizzazione per diversi casi d’uso

Risoluzione dei problemi comuni

Memorizzazione nella cache con blocchi di pensiero

Archiviazione e condivisione della cache

Durata della cache di 1 ora

Quando utilizzare la cache di 1 ora

Mescolare diversi TTL

Esempi di cache dei prompt

FAQ