Cache dei prompt

La "prompt caching" (cache dei prompt) ottimizza il tuo utilizzo dell'API consentendo di riprendere da prefissi specifici nei tuoi prompt. Questo riduce significativamente i tempi di elaborazione e i costi per attività ripetitive o prompt con elementi coerenti.

Ci sono due modi per abilitare la cache dei prompt:

• Cache automatica: Aggiungi un singolo campo cache_control al livello superiore della tua richiesta. Il sistema applica automaticamente il breakpoint della cache all'ultimo blocco memorizzabile nella cache e lo sposta in avanti man mano che le conversazioni crescono. Ideale per conversazioni multi-turno in cui la cronologia dei messaggi in crescita dovrebbe essere memorizzata nella cache automaticamente.
• Breakpoint di cache espliciti: Posiziona cache_control direttamente sui singoli blocchi di contenuto per un controllo granulare su cosa viene esattamente memorizzato nella cache.

Il modo più semplice per iniziare è con la cache automatica:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

Con la cache automatica, il sistema memorizza nella cache tutto il contenuto fino all'ultimo blocco memorizzabile incluso. Nelle richieste successive con lo stesso prefisso, il contenuto memorizzato nella cache viene riutilizzato automaticamente.



Come funziona la cache dei prompt

Quando invii una richiesta con la cache dei prompt abilitata:

1. Il sistema verifica se un prefisso del prompt, fino a un breakpoint di 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 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

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



Modelli supportati

La cache dei prompt (sia automatica che esplicita) è supportata su tutti i modelli Claude attivi.



Cache automatica

La cache automatica è il modo più semplice per abilitare la cache dei prompt. Invece di posizionare cache_control sui singoli blocchi di contenuto, aggiungi un singolo campo cache_control al livello superiore del corpo della tua richiesta. Il sistema applica automaticamente il breakpoint della cache all'ultimo blocco memorizzabile nella cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())



Come funziona la cache automatica nelle conversazioni multi-turno

Con la cache automatica, il punto di cache si sposta in avanti automaticamente man mano che le conversazioni crescono. Ogni nuova richiesta memorizza nella cache tutto fino all'ultimo blocco memorizzabile, e il contenuto precedente viene letto dalla cache.

Il breakpoint della cache si sposta automaticamente all'ultimo blocco memorizzabile in ogni richiesta, quindi non è necessario aggiornare alcun marcatore cache_control man mano che la conversazione cresce.



Supporto TTL

Per impostazione predefinita, la cache automatica utilizza un TTL di 5 minuti. Puoi specificare un TTL di 1 ora a 2 volte il prezzo base dei token di input:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }



Combinazione con la cache a livello di blocco

La cache automatica è compatibile con i breakpoint di cache espliciti. Quando usati insieme, il breakpoint di cache automatico utilizza uno dei 4 slot di breakpoint disponibili.

Questo ti consente di combinare entrambi gli approcci. Ad esempio, usa un breakpoint esplicito per memorizzare nella cache il tuo prompt di sistema, mentre la cache automatica gestisce la conversazione:

{
  "model": "claude-opus-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}



Cosa rimane invariato

La cache automatica utilizza la stessa infrastruttura di caching sottostante. I prezzi, le soglie minime di token, i requisiti di ordinamento del contesto e la finestra di lookback di 20 blocchi si applicano tutti allo stesso modo dei breakpoint espliciti.



Casi limite

• Se l'ultimo blocco ha già un cache_control esplicito con lo stesso TTL, la cache automatica non ha alcun effetto.
• Se l'ultimo blocco ha un cache_control esplicito con un TTL diverso, l'API restituisce un errore 400.
• Se esistono già 4 breakpoint espliciti a livello di blocco, l'API restituisce un errore 400 (nessuno slot rimasto per la cache automatica).
• Se l'ultimo blocco non è idoneo come destinazione del breakpoint di cache automatico, il sistema procede silenziosamente all'indietro per trovare il blocco idoneo più vicino. Se non ne viene trovato nessuno, la cache viene saltata.



Breakpoint di cache espliciti

Per un maggiore controllo sulla cache, puoi posizionare cache_control direttamente sui singoli blocchi di contenuto. Questo è utile quando devi memorizzare nella cache sezioni diverse che cambiano con frequenze diverse, o hai bisogno di un controllo granulare su cosa viene esattamente memorizzato nella cache.



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 la cache usando il parametro cache_control.

I prefissi della cache vengono creati nel seguente ordine: tools, system, poi messages. Questo ordine forma una gerarchia in cui ogni livello si basa sui precedenti.



Come funziona il controllo automatico del prefisso

Puoi usare un solo breakpoint di cache alla fine del tuo contenuto statico, e il sistema troverà automaticamente il prefisso più lungo che una richiesta precedente ha già scritto nella cache. Comprendere come funziona ti aiuta a ottimizzare la tua strategia di caching.

Tre principi fondamentali:

1. Le scritture nella cache avvengono solo al tuo breakpoint. Contrassegnare un blocco con cache_control scrive esattamente una voce di cache: un hash del prefisso che termina in quel blocco. Il sistema non scrive voci per nessuna posizione precedente. Poiché l'hash è cumulativo, coprendo tutto fino al breakpoint incluso, modificare qualsiasi blocco al breakpoint o prima di esso produce un hash diverso nella richiesta successiva.

2. Le letture della cache cercano all'indietro le voci che le richieste precedenti hanno scritto. A ogni richiesta il sistema calcola l'hash del prefisso al tuo breakpoint e verifica la presenza di una voce di cache corrispondente. Se non ne esiste nessuna, procede all'indietro un blocco alla volta, verificando se l'hash del prefisso in ogni posizione precedente corrisponde a qualcosa già presente nella cache. Sta cercando scritture precedenti, non contenuto stabile.

3. La finestra di lookback è di 20 blocchi. Il sistema verifica al massimo 20 posizioni per breakpoint, contando il breakpoint stesso come la prima. Se il sistema non trova alcuna voce corrispondente in quella finestra, la verifica si interrompe (o riprende dal successivo breakpoint esplicito, se presente).

Esempio: Lookback in una conversazione in crescita

Aggiungi nuovi blocchi a ogni turno e imposti cache_control sul blocco finale di ogni richiesta:

• Turno 1: 10 blocchi, breakpoint sul blocco 10. Non esistono voci di cache precedenti. Il sistema scrive una voce al blocco 10.
• Turno 2: 15 blocchi, breakpoint sul blocco 15. Il blocco 15 non ha alcuna voce, quindi il sistema torna indietro al blocco 10 e trova la voce del turno 1. Cache hit al blocco 10; il sistema elabora solo i blocchi da 11 a 15 da zero e scrive una nuova voce al blocco 15.
• Turno 3: 35 blocchi, breakpoint sul blocco 35. Il sistema verifica 20 posizioni (blocchi da 35 a 16) e non trova nulla. La voce del turno 2 al blocco 15 è una posizione fuori dalla finestra, quindi non c'è alcun cache hit. Aggiungere un secondo breakpoint al blocco 15 avvia una seconda finestra di lookback lì, che trova la voce del turno 2.

Errore comune: Breakpoint su contenuto che cambia a ogni richiesta

Il tuo prompt ha un grande contesto di sistema statico (blocchi da 1 a 5) seguito da un blocco per richiesta contenente un timestamp e il messaggio dell'utente (blocco 6). Imposti cache_control sul blocco 6:

• Richiesta 1: Scrittura nella cache al blocco 6. L'hash include il timestamp.
• Richiesta 2: Il timestamp è diverso, quindi l'hash del prefisso al blocco 6 è diverso. Il lookback attraversa i blocchi 5, 4, 3, 2 e 1, ma il sistema non ha mai scritto una voce in nessuna di quelle posizioni. Nessun cache hit. Paghi per una nuova scrittura nella cache a ogni richiesta e non ottieni mai una lettura.

Il lookback non trova il contenuto stabile dietro il tuo breakpoint per memorizzarlo nella cache. Trova le voci che le richieste precedenti hanno già scritto, e le scritture avvengono solo ai breakpoint. Sposta cache_control al blocco 5, l'ultimo blocco che rimane invariato tra le richieste, e ogni richiesta successiva legge il prefisso memorizzato nella cache. La cache automatica incorre nella stessa trappola: posiziona il breakpoint sull'ultimo blocco memorizzabile, che in questa struttura è quello che cambia a ogni richiesta, quindi usa invece un breakpoint esplicito sul blocco 5.

Punto chiave: Posiziona cache_control sull'ultimo blocco il cui prefisso è identico tra le richieste che vuoi che condividano una cache. In una conversazione in crescita il blocco finale funziona purché ogni turno aggiunga meno di 20 blocchi: il contenuto precedente non cambia mai, quindi il lookback della richiesta successiva trova la scrittura precedente. Per un prompt con un suffisso variabile (timestamp, contesto per richiesta, il messaggio in arrivo), posiziona il breakpoint alla fine del prefisso statico, non sul blocco variabile.



Quando usare più breakpoint

Puoi definire fino a 4 breakpoint di cache se vuoi:

• Memorizzare nella cache sezioni diverse che cambiano con frequenze diverse (ad esempio, gli strumenti cambiano raramente, ma il contesto si aggiorna quotidianamente)
• Avere più controllo su cosa viene esattamente memorizzato nella cache
• Garantire un cache hit quando una conversazione in crescita spinge il tuo breakpoint 20 o più blocchi oltre l'ultima scrittura nella cache



Comprendere i costi dei breakpoint di cache

I breakpoint di cache di per sé non aggiungono alcun costo. Ti viene addebitato solo per:

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

Aggiungere più breakpoint cache_control non aumenta i tuoi costi - paghi comunque lo stesso importo in base a quale contenuto viene effettivamente memorizzato nella cache e letto. I breakpoint ti danno il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.



Strategie e considerazioni sulla cache



Limitazioni della cache

Sulla Claude API, Claude Platform on AWS, Google Cloud e Microsoft Foundry, la lunghezza minima del prompt memorizzabile nella cache è:

• 512 token per Claude Opus 5, Claude Fable 5 e Claude Mythos 5
• 2.048 token per Claude Mythos Preview e Claude Opus 4.7
• 4.096 token per Claude Opus 4.6 e Claude Opus 4.5
• 1.024 token per Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1 (deprecato), Claude Opus 4 (ritirato, eccetto su Google Cloud) e Claude Sonnet 4 (ritirato, eccetto su Bedrock e Google Cloud)
• 4.096 token per Claude Haiku 4.5
• 2.048 token per Claude Haiku 3.5 (ritirato, eccetto su Google Cloud)

Questi minimi si applicano su ogni piattaforma in cui ciascun modello è disponibile.

I prompt più brevi non possono essere memorizzati nella cache, anche se contrassegnati con cache_control. Qualsiasi richiesta di memorizzare nella cache un numero di token inferiore a questo verrà elaborata senza cache, e non viene restituito alcun errore. Per verificare se un prompt è stato memorizzato nella cache, controlla i campi usage della risposta: se sia cache_creation_input_tokens che cache_read_input_tokens sono 0, il prompt non è stato memorizzato nella cache (probabilmente perché non ha soddisfatto il requisito di lunghezza minima).

Se il tuo prompt è appena al di sotto del minimo per il tuo modello e la tua piattaforma, espandere il contenuto memorizzato nella cache per raggiungere la soglia è spesso conveniente. Le letture dalla cache costano significativamente meno dei token di input non memorizzati nella cache, quindi raggiungere il minimo può ridurre i costi per i prompt riutilizzati frequentemente.

Per le richieste concorrenti, nota che una voce di cache diventa disponibile solo dopo che la prima risposta inizia. Se hai bisogno di cache hit 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 memorizzata nella cache. 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, sia per i turni 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, sia nei turni dell'utente che dell'assistente

Ognuno di questi elementi può essere memorizzato nella cache, automaticamente o contrassegnandolo con cache_control.



Cosa non può essere memorizzato nella cache

Sebbene la maggior parte dei blocchi della 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 precedenti dell'assistente. Quando memorizzati nella cache in questo modo, VENGONO conteggiati come token di input quando letti dalla cache.

• I sotto-blocchi di 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 usare la cache 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 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 seguente tabella 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.



Monitorare le prestazioni della cache

Monitora le prestazioni della cache usando questi campi della risposta API, all'interno di usage nella risposta (o nell'evento message_start se usi lo 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 né utilizzati per crearne una (cioè, i token dopo l'ultimo breakpoint di cache).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens



Cache con blocchi di pensiero

Quando usi il pensiero con la cache dei prompt, i blocchi di pensiero hanno un comportamento speciale:

Cache automatica insieme ad altro contenuto: Sebbene i blocchi di pensiero non possano 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'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, 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 solo i risultati degli strumenti vengono forniti come messaggi utente
• Su Opus 4.5+ e Sonnet 4.6+, i blocchi di pensiero vengono preservati per impostazione predefinita anche quando viene aggiunto contenuto utente non di tipo tool_result, quindi la cache rimane valida
• Sui modelli Opus/Sonnet precedenti e su tutti i modelli Haiku, la cache viene invalidata quando viene aggiunto contenuto utente non di tipo tool_result, causando la rimozione di tutti i blocchi di pensiero precedenti dal contesto
• Questo comportamento di caching si verifica anche senza marcatori cache_control espliciti

Per maggiori dettagli sull'invalidazione della cache, consulta Cosa invalida la cache.

Esempio con uso degli strumenti:

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

Sui modelli Opus/Sonnet precedenti e su tutti i modelli Haiku, tutti i blocchi di pensiero precedenti vengono rimossi dal contesto a questo punto. Su Opus 4.5+ e Sonnet 4.6+, i blocchi di pensiero precedenti vengono mantenuti per impostazione predefinita e rimangono parte del prefisso memorizzato nella cache.

Per informazioni più dettagliate, consulta Pensiero e cache dei prompt.



Archiviazione e condivisione della cache

• Isolamento di organizzazione e workspace: Le cache sono isolate tra le organizzazioni. Organizzazioni diverse non condividono mai le cache, anche se usano prompt identici. A partire dal 5 febbraio 2026, le cache sono anche isolate per workspace all'interno di un'organizzazione sulla Claude API, Claude Platform on AWS e Microsoft Foundry; Bedrock e Google Cloud continuano a usare solo l'isolamento a livello di organizzazione.

• Corrispondenza esatta: I cache hit richiedono segmenti di prompt identici al 100%, inclusi tutto il testo e le immagini fino al blocco contrassegnato con cache control incluso.

• Generazione dei token di output: La cache dei prompt non ha alcun effetto sulla generazione dei token di output. La risposta che ricevi è identica a quella che otterresti se la cache dei prompt non fosse utilizzata.



Best practice per una cache efficace

Per ottimizzare le prestazioni della cache dei prompt:

• Inizia con la cache automatica per le conversazioni multi-turno. Gestisce automaticamente i breakpoint.
• Usa i breakpoint espliciti a livello di blocco quando devi memorizzare nella cache sezioni diverse con frequenze di modifica diverse.
• Memorizza nella cache 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.
• Usa i breakpoint di cache in modo strategico per separare diverse sezioni di prefisso memorizzabili nella cache.
• Posiziona il breakpoint sull'ultimo blocco che rimane identico tra le richieste. Per un prompt con un prefisso statico e un suffisso variabile (timestamp, contesto per richiesta, il messaggio in arrivo), questo è la fine del prefisso, non il blocco variabile.
• Analizza regolarmente i tassi di cache hit 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 codebase mantenendo le sezioni rilevanti o una versione riassunta della codebase nel prompt.
• Elaborazione di documenti di grandi dimensioni: Incorpora materiale completo di lunga durata, incluse le immagini, nel tuo prompt senza aumentare la latenza della risposta.
• Set di istruzioni dettagliate: Condividi elenchi estesi di istruzioni, procedure ed esempi per affinare le risposte di Claude. Gli sviluppatori spesso includono uno o due esempi nel prompt, ma con la cache dei prompt puoi ottenere prestazioni ancora migliori includendo più di 20 esempi diversificati di risposte di alta qualità.
• Uso degli strumenti agentico: 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.
• Dialoga con libri, articoli, documentazione, trascrizioni di podcast e altri contenuti di lunga durata: Dai vita a qualsiasi base di conoscenza incorporando l'intero documento (o i documenti) nel prompt e lasciando che gli utenti facciano domande.



Risoluzione dei problemi comuni

Se riscontri comportamenti inattesi:

• Assicurati che le sezioni memorizzate nella cache siano identiche tra le chiamate. Per i breakpoint espliciti, verifica che i marcatori cache_control siano nelle stesse posizioni
• Verifica che le chiamate vengano effettuate entro la durata della cache (5 minuti per impostazione predefinita)
• Verifica che tool_choice, l'uso delle immagini, la configurazione del pensiero e output_config.effort rimangano coerenti tra le chiamate
• Verifica di memorizzare nella cache almeno il numero minimo di token per il tuo modello e la tua piattaforma (consulta Limitazioni della cache)
• Conferma che il tuo breakpoint sia su un blocco che rimane identico tra le richieste. Le scritture nella cache avvengono solo al breakpoint, e se quel blocco cambia (timestamp, contesto per richiesta, il messaggio in arrivo), l'hash del prefisso non corrisponde mai. Il lookback non trova il contenuto stabile dietro il breakpoint; trova solo le voci che le richieste precedenti hanno scritto ai loro breakpoint
• Verifica che le chiavi nei tuoi blocchi di contenuto tool_use abbiano un ordinamento stabile, poiché alcuni linguaggi (ad esempio, Swift, Go) randomizzano l'ordine delle chiavi durante la conversione JSON, rompendo le cache
• Usa la diagnostica della cache per far sì che l'API confronti richieste consecutive e riporti quale parte del prompt è divergente



Durata della cache di 1 ora

Se ritieni che 5 minuti siano troppo pochi, Anthropic offre anche una durata della cache di 1 ora a un costo aggiuntivo.

Per usare la cache estesa, includi ttl nella definizione di cache_control in questo modo:

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

La risposta include informazioni dettagliate sulla cache come le seguenti:

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Nota che l'attuale campo cache_creation_input_tokens è uguale alla somma dei valori nell'oggetto cache_creation.

Se vedi scritture ephemeral_5m_input_tokens che non hai richiesto mentre usi strumenti server come la ricerca web, consulta Uso degli strumenti con la cache dei prompt.



Quando usare la cache di 1 ora

Se hai prompt che vengono utilizzati con una cadenza regolare (cioè, prompt di sistema che vengono utilizzati più frequentemente di ogni 5 minuti), continua a usare la cache di 5 minuti, perché questa continuerà a essere aggiornata senza costi aggiuntivi.

La cache di 1 ora è più adatta 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 secondario agentico impiegherà più di 5 minuti, o quando memorizzi una lunga conversazione chat con un utente e in genere ti aspetti che quell'utente potrebbe non rispondere nei prossimi 5 minuti.
• Quando la latenza è importante e i tuoi prompt successivi potrebbero essere inviati oltre i 5 minuti.
• Quando vuoi migliorare l'utilizzo del tuo limite di velocità, perché i cache hit non vengono detratti dal tuo limite di velocità.



Combinare TTL diversi

Puoi usare sia i controlli di cache di 1 ora che quelli di 5 minuti nella stessa richiesta, ma con un vincolo importante: le voci di cache con TTL più lungo devono apparire prima di quelle con TTL più breve (cioè, una voce di cache di 1 ora deve apparire prima di qualsiasi voce di cache di 5 minuti).

Quando combini i TTL, l'API determina tre posizioni di fatturazione nel tuo prompt:

1. Posizione A: Il conteggio dei token al cache hit più alto (o 0 se non ci sono hit).
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 tre esempi. Questo rappresenta i token di input di 3 richieste, ognuna delle quali ha cache hit e cache miss diversi. Ognuna ha un prezzo calcolato diverso, mostrato nei riquadri colorati, come risultato.



Pre-riscaldamento della cache

Il pre-riscaldamento della cache ti consente di caricare il tuo prompt di sistema o le definizioni degli strumenti nella cache dei prompt prima che un utente attivi una richiesta reale. Questo elimina la penalità di latenza del cache miss alla prima interazione dell'utente, riducendo il time-to-first-token (TTFT) per le applicazioni sensibili alla latenza.



Come funziona

Imposta max_tokens: 0 nella tua richiesta. L'API legge il tuo prompt nel modello e scrive la cache in qualsiasi punto di interruzione cache_control, quindi restituisce immediatamente senza generare alcun output. La risposta ha un array content vuoto, stop_reason: "max_tokens" e un blocco usage completamente popolato.

Posiziona il punto di interruzione cache_control sull'ultimo blocco condiviso con la richiesta successiva (tipicamente il tuo prompt di sistema o le definizioni degli strumenti), non sul messaggio utente segnaposto. Altrimenti la voce della cache viene associata al segnaposto e la richiesta successiva non la troverà. Usa anche la stessa configurazione di pensiero e lo stesso output_config.effort delle tue richieste successive: quei valori vengono renderizzati nel prompt (vedi Cosa invalida la cache), quindi un pre-riscaldamento con una configurazione diversa può scrivere una voce che il tuo traffico reale non raggiungerà mai. Questo significa usare un punto di interruzione della cache esplicito piuttosto che la cache automatica, poiché la cache automatica posiziona il punto di interruzione sull'ultimo blocco, che in questo caso è il segnaposto. Il messaggio utente segnaposto può essere qualsiasi stringa con contenuto non vuoto (gli esempi qui usano "warmup"); il suo contenuto viene letto nel modello ma non riceve mai risposta.

client = anthropic.Anthropic()

# Esegui questa chiamata prima dell'arrivo degli utenti per preriscaldare la cache condivisa del prompt di sistema.
prewarm = client.messages.create(
    model="claude-opus-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

L'API restituisce un array content vuoto:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}



Schema di utilizzo tipico

Invia una richiesta di pre-riscaldamento all'avvio della tua applicazione (o a intervalli programmati), quindi invia le richieste reali degli utenti dopo che il pre-riscaldamento è stato completato:

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Riscalda la cache prima che arrivi il traffico degli utenti.
prewarm_cache()

# In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già in cache.
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

Tieni presente che il TTL della cache si applica comunque. Per la cache predefinita di 5 minuti, invia una nuova richiesta di pre-riscaldamento almeno ogni 5 minuti per mantenere la cache attiva. Per intervalli più lunghi tra le richieste degli utenti, usa invece la durata della cache di 1 ora.



Limitazioni

Una richiesta con max_tokens: 0 viene rifiutata con un errore invalid_request_error se è impostata una qualsiasi delle seguenti opzioni, poiché ciascuna implica un output che un budget di zero token non può produrre:

• stream: true
• Pensiero esteso (thinking.type: "enabled")
• Output strutturati (output_config.format)
• tool_choice di tipo {"type": "tool", ...} o {"type": "any"}

max_tokens: 0 viene rifiutato anche all'interno di una richiesta Message Batches. Il pre-riscaldamento mira al tempo fino al primo token, che non si applica all'elaborazione batch, e una voce della cache scritta durante l'elaborazione batch probabilmente scadrebbe prima dell'esecuzione della richiesta successiva.



Sostituzione della soluzione alternativa max_tokens=1

Prima che max_tokens: 0 fosse disponibile, alcune applicazioni usavano chiamate di riscaldamento con max_tokens: 1 per ottenere lo stesso effetto. L'approccio con max_tokens: 0 è preferibile: non viene prodotto alcun output, quindi non c'è una risposta di un singolo token da scartare, non vengono fatturati token di output e l'intento della richiesta è inequivocabile.



Esempi di cache dei prompt

Per aiutarti a iniziare con la cache dei prompt, il cookbook sulla cache dei prompt fornisce esempi dettagliati e best practice.

I seguenti frammenti di codice mostrano vari schemi di cache dei prompt. Questi esempi dimostrano come implementare la cache in diversi scenari, aiutandoti a comprendere le applicazioni pratiche di questa funzionalità:



Conservazione dei dati

La cache dei prompt (sia automatica che esplicita) è idonea per ZDR. Anthropic non memorizza il testo grezzo dei tuoi prompt o delle risposte di Claude.

Le rappresentazioni della cache KV (key-value) e gli hash crittografici del contenuto memorizzato nella cache sono conservati solo in memoria e non vengono archiviati a riposo. Le voci della cache hanno una durata minima di 5 minuti (standard) o 1 ora (estesa), dopo la quale vengono eliminate prontamente, anche se non immediatamente. Le voci della cache sono isolate tra le organizzazioni e, sulla Claude API, su Claude Platform su AWS e su Microsoft Foundry, tra i workspace all'interno di un'organizzazione.

Per l'idoneità ZDR di tutte le funzionalità, vedi API e conservazione dei dati.



FAQ