Caching dei prompt

Il caching dei prompt è una funzione 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:

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    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'."}],
)
print(response.usage.model_dump_json())

# Call the model again with the same inputs up to the cache checkpoint
response = client.messages.create(.....)
print(response.usage.model_dump_json())

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.messages.create({
  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'."
    }
  ]
});
console.log(response.usage);

// Call the model again with the same inputs up to the cache checkpoint
const new_response = await client.messages.create(...)
console.log(new_response.usage);

import java.util.List;

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.CacheControlEphemeral;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.TextBlockParam;

public class PromptCachingExample {

    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_4_20250514)
                .maxTokens(1024)
                .systemOfTextBlockParams(List.of(
                        TextBlockParam.builder()
 .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")
 .build(),
                        TextBlockParam.builder()
 .text("<the entire contents of 'Pride and Prejudice'>")
 .cacheControl(CacheControlEphemeral.builder().build())
 .build()
                ))
                .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
                .build();

        Message message = client.messages().create(params);
        System.out.println(message.usage());
    }
}

{"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 in più chiamate API senza rielaborarlo ogni volta. Cambiando 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 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.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 il prefisso corrispondente più lungo. Comprendere come funziona 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. Questo assicura di ottenere 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 prossimo punto di interruzione esplicito (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 ha bisogno 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 hanno bisogno 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 hanno bisogno 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!). Questo consente un hit 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 possibilità di hit della cache. Inoltre, imposta i punti di interruzione appena prima dei blocchi di contenuto che potrebbero essere modificabili per assicurare 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 es., gli strumenti cambiano raramente, ma il contesto si aggiorna quotidianamente)
• Avere più controllo su esattamente cosa viene memorizzato nella cache
• Assicurare 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.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 verificare 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 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 a quale 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

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 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. Questo 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.

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.

Migliori pratiche per il caching efficace

Per ottimizzare le prestazioni del caching dei prompt:

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

Ottimizzazione per diversi casi d'uso

Personalizza la tua strategia di caching dei prompt 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 immagini nel tuo prompt senza aumentare la latenza della risposta.
• Set di istruzioni dettagliati: Condividi lunghi elenchi 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 il caching dei 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, in cui 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 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 controlla automaticamente i hit della cache ai limiti 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 parametri cache_control aggiuntivi più all'inizio del prompt per assicurare 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 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 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 vengono forniti solo risultati di strumenti come messaggi dell'utente
• La cache viene invalidata quando viene aggiunto contenuto dell'utente non risultato 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, consulta 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 dell'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 dell'utente non risultato 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 dell'utente non risultato 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.

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

• 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 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 (ad es., 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 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à.

Miscelazione di diversi TTL

Puoi utilizzare sia il controllo 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 (ad es., 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 hit della cache 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 rappresenta i token di input di 3 richieste, ognuna delle quali ha diversi hit della cache e cache miss. Ognuna ha una fatturazione calcolata diversa, mostrata nelle caselle colorate, come risultato.

Esempi di caching dei prompt

Per aiutarti a iniziare con il caching dei prompt, abbiamo preparato un cookbook di 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 funzione:

Domande frequenti