Prompt caching

Prompt caching è una potente funzionalità 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 prompt caching 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 fare varie domande sul libro mentre utilizzi il contenuto memorizzato nella cache, portando a risposte più veloci e a una migliore efficienza.

Come funziona il prompt caching

Quando invii una richiesta con prompt caching 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 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

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

Come implementare prompt caching

Modelli supportati

Prompt caching è 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 (deprecato)
• Claude Haiku 4.5
• Claude Haiku 3.5 (deprecato)
• Claude Haiku 3
• Claude Opus 3 (deprecato)

Strutturare il 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 aiuta a ottimizzare la tua strategia di caching.

Tre principi fondamentali:

1. Le chiavi della cache sono cumulative: Quando memorizzi esplicitamente un blocco nella cache 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 risultati della cache lavorando all'indietro dal tuo punto di interruzione esplicito, controllando ogni blocco precedente in ordine inverso. Ciò garantisce che tu ottenga il risultato della cache più lungo possibile.

3. Finestra di lookback di 20 blocchi: Il sistema verifica 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 verifica il blocco 30 (corrispondenza!). Ottieni un risultato 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 verifica all'indietro dal blocco 30 → 29 → 28... → 25 (nessuna corrispondenza) → 24 (corrispondenza!). Poiché il blocco 24 non è stato modificato, ottieni un risultato 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 verifica all'indietro dal blocco 30 → 29 → 28... → 11 (controllo #20). Dopo 20 controlli senza trovare una corrispondenza, smette di cercare. Poiché il blocco 5 è al di là della finestra di 20 blocchi, non si verifica alcun risultato 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 risultato della cache al blocco 4, dimostrando perché dovresti posizionare i punti di interruzione prima del contenuto modificabile.

Conclusione chiave: Imposta sempre un punto di interruzione della cache esplicito alla fine della tua conversazione per massimizzare le tue possibilità di risultati 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 risultati della cache anche quando si verificano modifiche oltre la finestra di 20 blocchi

Limitazioni della cache

La lunghezza minima del prompt memorizzabile nella cache è:

• 4096 token per Claude Opus 4.5
• 1024 token per 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 (deprecato) 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, vedi 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 risultati 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. Sei 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 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 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 appaiono 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 prompt caching 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 Strutturare il 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.

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

Per ottimizzare le prestazioni del prompt caching:

• Memorizza nella cache il 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 risultati della cache, specialmente quando si lavora con prompt che hanno più di 20 blocchi di contenuto.
• Analizza regolarmente i tassi di risultati della cache e regola la tua strategia secondo le necessità.

Ottimizzazione per diversi casi d'uso

Personalizza la tua strategia di prompt caching al tuo scenario:

• Agenti conversazionali: Riduci il costo e la 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 le 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 prompt caching puoi ottenere prestazioni ancora migliori includendo 20+ diversi esempi 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 tipicamente richiede una nuova chiamata API.
• Parla con libri, articoli, documentazione, trascrizioni di podcast e altro contenuto di lunga forma: Dai vita a qualsiasi base di conoscenza incorporando l'intero documento(i) nel prompt e lasciando che gli utenti facciano domande.

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 verifica automaticamente i risultati 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, potrebbe essere necessario 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 esempio Swift, Go) randomizzano l'ordine delle chiavi durante la conversione JSON, interrompendo le cache

Caching con blocchi di pensiero

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

Caching automatico 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 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 budgeting dei token.

Modelli di invalidazione della cache:

• La cache rimane valida quando vengono forniti solo risultati di strumenti come messaggi dell'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 caching si verifica anche senza marcatori cache_control espliciti

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

Esempio con utilizzo di strumenti:

Richiesta 1: Utente: "Qual è il meteo a Parigi?"
Risposta: [thinking_block_1] + [tool_use block 1]

Richiesta 2:
Utente: ["Qual è il meteo a Parigi?"],
Assistente: [thinking_block_1] + [tool_use block 1],
Utente: [tool_result_1, cache=True]
Risposta: [thinking_block_2] + [text block 2]
# La richiesta 2 memorizza nella cache il suo contenuto di richiesta (non la risposta)
# La cache include: messaggio utente, thinking_block_1, tool_use block 1 e tool_result_1

Richiesta 3:
Utente: ["Qual è il meteo a Parigi?"],
Assistente: [thinking_block_1] + [tool_use block 1],
Utente: [tool_result_1, cache=True],
Assistente: [thinking_block_2] + [text block 2],
Utente: [Text response, cache=True]
# Il blocco utente non di risultati di strumenti causa l'ignoranza 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 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, vedi la documentazione di pensiero esteso.

Archiviazione e condivisione della cache

• 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 risultati della cache richiedono segmenti di prompt identici al 100%, incluso tutto il testo e le immagini fino a e includendo il blocco contrassegnato con controllo della cache.

• Generazione di token di output: Prompt caching non ha alcun effetto sulla generazione di token di output. La risposta che ricevi sarà identica a quella che otterresti se 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 come questo:

"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 una 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à a essere aggiornata senza costi aggiuntivi.

La cache di 1 ora è meglio utilizzata nei seguenti scenari:

• Quando hai prompt che è probabile vengano 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 5 minuti.
• Quando desideri migliorare l'utilizzo del tuo limite di velocità, poiché i risultati della cache non vengono detratti dal tuo limite di velocità.

Miscelazione di diversi TTL

Puoi utilizzare sia controlli della 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 di TTL più brevi (cioè, una voce della cache di 1 ora deve apparire prima di qualsiasi voce della 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 risultato della cache più alto (o 0 se nessun risultato).
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 rappresenta i token di input di 3 richieste, ognuna delle quali ha diversi risultati della cache e mancati della cache. Ognuno ha una fatturazione calcolata diversa, mostrata 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