Caching dei prompt

Il caching dei prompt è una funzionalità potente che ottimizza l’utilizzo delle API consentendo di riprendere da prefissi specifici nei tuoi prompt. Questo approccio riduce significativamente i tempi 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:

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

{"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. Cambiare solo il messaggio dell’utente ti permette di porre varie domande sul libro utilizzando il contenuto memorizzato nella cache, portando a risposte più veloci e maggiore efficienza.

​

Come funziona il caching dei prompt

Quando invii una richiesta con il caching dei prompt abilitato:

1. 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.
2. Se trovato, utilizza la versione memorizzata nella cache, riducendo i tempi di elaborazione e i costi.
3. Altrimenti, elabora l’intero prompt e memorizza il prefisso nella cache 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.

​

Prezzi

Il caching dei prompt introduce una nuova struttura di prezzi. La tabella sottostante 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.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. 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, 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 in 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 il caching - 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 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 contenuti più di 20 blocchi prima del tuo punto di interruzione finale

​

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

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

I prompt più corti 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, 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 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 della cache: Quando nuovo contenuto viene scritto nella cache (25% in più rispetto ai token di input base per TTL di 5 minuti)
• Letture della 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 è effettivamente memorizzato nella cache e letto. I punti di interruzione ti danno semplicemente 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 il caching 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 il caching per quella porzione della richiesta.

​

Cosa non può essere memorizzato nella cache

Mentre la maggior parte dei blocchi di richiesta può essere memorizzata nella cache, ci sono alcune eccezioni:

• I blocchi di pensiero non possono essere memorizzati nella cache direttamente con cache_control. Tuttavia, i blocchi di pensiero POSSONO essere memorizzati nella cache insieme ad 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 sorgente per le citazioni possono essere memorizzati nella cache. Questo ti permette di utilizzare il caching 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.

​

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 un caching efficace

Per ottimizzare le prestazioni del caching dei prompt:

• Memorizza nella cache contenuto stabile e riutilizzabile come istruzioni di sistema, informazioni di background, contesti di grandi dimensioni o definizioni frequenti degli strumenti.
• 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 riscontro della cache e adatta la tua strategia secondo necessità.

​

Ottimizzazione per diversi casi d’uso

Adatta la tua strategia di caching dei prompt al tuo scenario:

• Agenti conversazionali: Riduci costi e latenza per conversazioni estese, specialmente quelle con 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 caching dei prompt puoi ottenere prestazioni ancora migliori includendo 20+ esempi diversi di risposte di alta qualità.
• Uso agentico degli strumenti: Migliora le prestazioni per scenari che coinvolgono più chiamate agli 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

​

Caching con blocchi di pensiero

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

Caching automatico 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.

Mo delli 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 caching si verifica anche senza marcatori cache_control espliciti

Per maggiori dettagli sull’invalidazione della cache, vedi Cosa invalida la cache.

Esempio con uso degli 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 caching dei prompt non ha effetto sulla generazione di token di output. La risposta che ricevi sarà identica a quella che otterresti se il caching dei prompt non fosse utilizzato.

​

Durata della cache di 1 ora

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 il campo attuale 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 agentico 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à.

​

Mescolare diversi TTL

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

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

1. Posizione A: Il conteggio dei token al riscontro della cache più alto (o 0 se non ci sono riscontri).
2. 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).
3. Posizione C: Il conteggio dei token all’ultimo blocco cache_control.

Verrai 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 riscontri e mancati riscontri della cache. Ognuna ha un prezzo calcolato diverso, mostrato nelle caselle colorate, di conseguenza.

​

Esempi di caching dei prompt

Per aiutarti a iniziare con il caching dei prompt, abbiamo preparato un cookbook del caching dei prompt con esempi dettagliati e migliori pratiche.

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

​

FAQ