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 il tempo di elaborazione e i costi per attività ripetitive o prompt con elementi costanti.

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-20250514",
    "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 lungo in più chiamate API senza doverlo rielaborare ogni volta. Modificando solo il messaggio dell’utente è possibile porre varie domande sul libro utilizzando il contenuto memorizzato nella cache, ottenendo risposte più rapide e 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 l’intero prompt 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 costanti
• Conversazioni lunghe a più turni

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 ciascun modello supportato:

Nota:

• I token di scrittura nella cache di 5 minuti costano 1,25 volte il prezzo base dei token di input
• I token di scrittura nella cache di 1 ora costano 2 volte il prezzo base dei token di input
• I token di lettura dalla cache costano 0,1 volte il prezzo base dei token di input
• I token di input e output regolari sono prezzati alle tariffe standard

​

Come implementare il caching dei prompt

​

Modelli supportati

Il caching dei prompt è attualmente supportato su:

• Claude Opus 4
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Sonnet 3.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3

​

Strutturazione del prompt

Posiziona il contenuto statico (definizioni di strumenti, istruzioni di sistema, contesto, esempi) all’inizio del 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.

Utilizzando il parametro cache_control, puoi definire fino a 4 punti di interruzione della cache, consentendo di memorizzare nella cache diverse sezioni riutilizzabili separatamente. Per ogni punto di interruzione, il sistema verificherà automaticamente la presenza di corrispondenze nella cache in posizioni precedenti e utilizzerà il prefisso corrispondente più lungo se ne viene trovato uno.

​

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 e Claude Opus 3
• 2048 token per Claude Haiku 3.5 e Claude Haiku 3

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

Per le richieste concorrenti, nota che una voce della cache diventa disponibile solo dopo l’inizio della prima risposta. Se hai bisogno di corrispondenze nella 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.

​

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

Ciascuno 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 altri contenuti quando appaiono nei turni precedenti dell’assistente. Quando memorizzati nella cache in questo modo, vengono conteggiati come token di input quando letti dalla cache.

• I blocchi di sotto-contenuto (come le citazioni) 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 fungono da materiale di origine per le citazioni possono essere memorizzati nella cache. Questo ti consente di utilizzare efficacemente il caching dei prompt con le citazioni memorizzando nella cache i documenti a cui le citazioni faranno riferimento.

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

​

Monitoraggio delle prestazioni della cache

Monitora le prestazioni della cache utilizzando questi campi di risposta API, all’interno di usage nella risposta (o nell’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 dalla cache o utilizzati per creare una cache.

​

Best practice per un caching efficace

Per ottimizzare le prestazioni del caching dei prompt:

• Memorizza nella cache contenuti stabili e riutilizzabili 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 ottenere le migliori prestazioni.
• Utilizza i punti di interruzione della cache in modo strategico per separare diverse sezioni di prefisso 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 caching dei prompt al tuo scenario:

• Agenti conversazionali: Riduci costi e latenza per conversazioni estese, specialmente quelle con lunghe istruzioni 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 durata, incluse immagini, nel tuo prompt senza aumentare la latenza di risposta.
• Set di istruzioni dettagliati: Condividi ampie liste di istruzioni, procedure ed esempi per perfezionare 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 più di 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 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: Dai vita a qualsiasi base di conoscenza incorporando l’intero documento(i) nel prompt e consentendo agli utenti di porgli domande.

​

Risoluzione dei problemi comuni

Se riscontri comportamenti inaspettati:

• Assicurati che le sezioni memorizzate nella cache siano identiche e contrassegnate con cache_control nelle stesse posizioni tra le chiamate
• Verifica che le chiamate siano effettuate entro la durata della cache (5 minuti per impostazione predefinita)
• Verifica che tool_choice e l’utilizzo delle immagini rimangano coerenti tra le chiamate
• Verifica di memorizzare nella cache almeno il numero minimo di token
• Mentre il sistema tenterà di utilizzare il contenuto precedentemente memorizzato nella cache in posizioni precedenti a un punto di interruzione della cache, puoi utilizzare un parametro cache_control aggiuntivo per garantire la ricerca nella cache su porzioni precedenti del prompt, che può essere utile per query con elenchi molto lunghi di blocchi di contenuto

Nota che le modifiche a tool_choice o la presenza/assenza di immagini in qualsiasi punto del prompt invalideranno la cache, richiedendo la creazione di una nuova voce nella cache.

​

Caching con blocchi di pensiero

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

Caching automatico insieme ad altri contenuti: Mentre i blocchi di pensiero non possono essere contrassegnati esplicitamente con cache_control, vengono memorizzati nella cache come parte del contenuto della richiesta quando effettui chiamate API successive con risultati degli strumenti. Questo accade comunemente durante l’utilizzo degli 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, vengono conteggiati 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 degli strumenti come messaggi utente
• La cache viene invalidata quando viene aggiunto contenuto utente non relativo ai risultati degli strumenti, causando la rimozione di tutti i blocchi di pensiero precedenti
• Questo comportamento di caching si verifica anche senza marcatori cache_control espliciti

Esempio con utilizzo di strumenti:

Richiesta 1: Utente: "Che tempo fa a Parigi?"
Risposta: [thinking_block_1] + [tool_use block 1]

Richiesta 2: 
Utente: ["Che tempo fa 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: ["Che tempo fa a Parigi?"], 
Assistente: [thinking_block_1] + [tool_use block 1], 
Utente: [tool_result_1, cache=True], 
Assistente: [thinking_block_2] + [text block 2], 
Utente: [Risposta testuale, cache=True]
# Un blocco utente non relativo ai risultati degli strumenti fa sì che tutti i blocchi di pensiero vengano ignorati
# Questa richiesta viene elaborata come se i blocchi di pensiero non fossero mai stati presenti

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

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

​

Archiviazione e condivisione della cache

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

• Corrispondenza esatta: I successi della cache richiedono segmenti di prompt identici al 100%, inclusi tutti i testi e le immagini fino al blocco contrassegnato con cache control.

• Generazione di token di output: Il caching dei prompt non ha alcun 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 (beta)

Se ritieni che 5 minuti siano troppo brevi, Anthropic offre anche una durata della cache di 1 ora.

Per utilizzare la cache estesa, aggiungi extended-cache-ttl-2025-04-11 come header beta alla tua richiesta, e poi includi ttl nella definizione di cache_control in questo modo:

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

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

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

Nota che il campo cache_creation_input_tokens attuale è uguale alla somma dei valori nell’oggetto cache_creation.

​

Quando utilizzare la cache di 1 ora

Se hai prompt che vengono utilizzati con cadenza regolare (ad esempio, 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 è ideale 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 si memorizza una lunga conversazione con un utente e generalmente ci si aspetta 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 i 5 minuti.
• Quando vuoi migliorare l’utilizzo del limite di frequenza, poiché i successi della cache non vengono detratti dal tuo limite di frequenza.

​

Combinare TTL diversi

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 di quelle con TTL più breve (cioè, una voce della cache di 1 ora deve apparire prima di qualsiasi voce della cache di 5 minuti).

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

1. Posizione A: Il conteggio dei token al successo della cache più alto (o 0 se non ci sono successi).
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.

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, ciascuna delle quali ha diversi successi e mancati della cache. Ognuna ha un prezzo calcolato diverso, mostrato nelle caselle colorate, come risultato.

​

Esempi di caching dei prompt

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

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