Loading...
    • Guida per sviluppatori
    • Riferimento API
    • MCP
    • Risorse
    • Note sulla versione
    Search...
    ⌘K
    Primi passi
    Introduzione a ClaudeAvvio rapido
    Modelli e prezzi
    Panoramica dei modelliScelta di un modelloNovità in Claude 4.6Guida alla migrazioneDeprecazioni dei modelliPrezzi
    Crea con Claude
    Panoramica delle funzioniUtilizzo dell'API MessagesGestione dei motivi di arrestoBest practice per i prompt
    Capacità del modello
    Extended thinkingAdaptive thinkingEffortFast mode (anteprima di ricerca)Output strutturatiCitazioniStreaming dei messaggiElaborazione batchSupporto PDFRisultati di ricercaSupporto multilingueEmbeddingsVision
    Strumenti
    PanoramicaCome implementare l'uso degli strumentiStrumento di ricerca webStrumento di recupero webStrumento di esecuzione del codiceStrumento di memoriaStrumento BashStrumento Computer useStrumento editor di testo
    Infrastruttura degli strumenti
    Ricerca strumentiChiamata programmatica degli strumentiStreaming granulare degli strumenti
    Gestione del contesto
    Finestre di contestoCompattazioneModifica del contestoPrompt cachingConteggio dei token
    File e risorse
    API Files
    Agent Skills
    PanoramicaAvvio rapidoBest practiceSkills per l'aziendaUtilizzo di Skills con l'API
    Agent SDK
    PanoramicaAvvio rapidoTypeScript SDKTypeScript V2 (anteprima)Python SDKGuida alla migrazione
    MCP nell'API
    Connettore MCPServer MCP remoti
    Claude su piattaforme di terze parti
    Amazon BedrockMicrosoft FoundryVertex AI
    Prompt engineering
    PanoramicaGeneratore di promptUsa modelli di promptMiglioratore di promptSii chiaro e direttoUsa esempi (multishot prompting)Lascia che Claude pensi (CoT)Usa tag XMLDai a Claude un ruolo (prompt di sistema)Concatena prompt complessiSuggerimenti per il contesto lungoSuggerimenti per extended thinking
    Test e valutazione
    Definisci criteri di successoSviluppa casi di testUtilizzo dello strumento di valutazioneRiduzione della latenza
    Rafforza i guardrail
    Riduci le allucinazioniAumenta la coerenza dell'outputMitiga i jailbreakStreaming dei rifiutiRiduci la perdita di promptMantieni Claude nel personaggio
    Amministrazione e monitoraggio
    Panoramica dell'API AdminResidenza dei datiWorkspaceAPI di utilizzo e costiAPI Claude Code AnalyticsZero Data Retention
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    Gestione del contesto

    Prompt caching

    Ottimizza l'utilizzo dell'API memorizzando nella cache i prefissi dei prompt per ridurre i costi e la latenza.

    Was this page helpful?

    • Come funziona il prompt caching
    • Prezzi
    • Modelli supportati
    • Caching automatico
    • Come funziona il caching automatico nelle conversazioni multi-turno
    • Supporto TTL
    • Combinazione con il caching a livello di blocco
    • Cosa rimane invariato
    • Casi limite
    • Breakpoint espliciti della cache
    • Strutturare il tuo prompt
    • Comprendere i costi dei breakpoint della cache
    • Strategie e considerazioni sul caching
    • Limitazioni della cache
    • Cosa può essere memorizzato nella cache
    • Cosa non può essere memorizzato nella cache
    • Cosa invalida la cache
    • Monitoraggio delle prestazioni della cache
    • Caching con blocchi di thinking
    • Archiviazione e condivisione della cache
    • Best practice per un caching efficace
    • Ottimizzazione per diversi casi d'uso
    • Risoluzione dei problemi comuni
    • Durata della cache di 1 ora
    • Quando usare la cache di 1 ora
    • Combinazione di TTL diversi
    • Esempi di prompt caching
    • Conservazione dei dati
    • FAQ

    Il prompt caching ottimizza l'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 costanti.

    This feature qualifies for Zero Data Retention (ZDR) with limited technical retention. See the Data retention section for details on what is retained and why.

    Esistono due modi per abilitare il prompt caching:

    • Caching automatico: 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 deve essere memorizzata automaticamente nella cache.
    • Breakpoint espliciti della cache: Posiziona cache_control direttamente su singoli blocchi di contenuto per un controllo granulare su esattamente ciò che viene memorizzato nella cache.

    Il modo più semplice per iniziare è con il caching automatico:

    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-6",
        "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."
          }
        ]
      }'

    Con il caching automatico, 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 il prompt caching

    Quando invii una richiesta con il prompt caching abilitato:

    1. Il sistema verifica se un prefisso del prompt, fino a un breakpoint della cache specificato, è già memorizzato nella cache da una query recente.
    2. Se trovato, utilizza la versione memorizzata nella cache, riducendo i tempi di elaborazione e i costi.
    3. Altrimenti, elabora 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 costanti
    • 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 viene utilizzato.

    Se trovi che 5 minuti sono troppo brevi, Anthropic offre anche una durata della cache di 1 ora a costo aggiuntivo.

    Per ulteriori informazioni, consulta Durata della cache di 1 ora.

    Il prompt caching memorizza nella cache il prefisso completo

    Il prompt caching fa riferimento all'intero prompt - tools, system e messages (in quest'ordine) fino al blocco designato con cache_control incluso.


    Prezzi

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

    ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
    Claude Opus 4.6$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
    Claude Opus 4.5$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
    Claude Opus 4.1$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
    Claude Opus 4$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
    Claude Sonnet 4.6

    La tabella sopra riflette i seguenti moltiplicatori di prezzo per il prompt caching:

    • I token di scrittura nella cache a 5 minuti costano 1,25 volte il prezzo base dei token di input
    • I token di scrittura nella cache a 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

    Questi moltiplicatori si sommano ad altri modificatori di prezzo come lo sconto dell'API Batch, i prezzi per contesti lunghi e la residenza dei dati. Consulta i prezzi per tutti i dettagli.


    Modelli supportati

    Il prompt caching (sia automatico che esplicito) è attualmente supportato su:

    • Claude Opus 4.6
    • Claude Opus 4.5
    • Claude Opus 4.1
    • Claude Opus 4
    • Claude Sonnet 4.6
    • Claude Sonnet 4.5
    • Claude Sonnet 4
    • Claude Sonnet 3.7 (deprecato)
    • Claude Haiku 4.5
    • Claude Haiku 3.5 (deprecato)
    • Claude Haiku 3

    Caching automatico

    Il caching automatico è il modo più semplice per abilitare il prompt caching. Invece di posizionare cache_control su 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.

    Come funziona il caching automatico nelle conversazioni multi-turno

    Con il caching automatico, il punto della 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.

    RichiestaContenutoComportamento della cache
    Richiesta 1System
    + User(1) + Asst(1)
    + User(2) ◀ cache
    Tutto scritto nella cache
    Richiesta 2System
    + User(1) + Asst(1)
    + User(2) + Asst(2)
    + User(3) ◀ cache
    System fino a User(2) letto dalla cache;
    Asst(2) + User(3) scritti nella cache
    Richiesta 3System
    + User(1) + Asst(1)
    + User(2) + Asst(2)
    + User(3) + Asst(3)
    + User(4) ◀ cache
    System fino a User(3) letto dalla cache;
    Asst(3) + User(4) scritti nella 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, il caching automatico utilizza un TTL di 5 minuti. Puoi specificare un TTL di 1 ora al doppio del prezzo base del token di input:

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

    Combinazione con il caching a livello di blocco

    Il caching automatico è compatibile con i breakpoint espliciti della cache. Quando utilizzati insieme, il breakpoint della cache automatico utilizza uno dei 4 slot di breakpoint disponibili.

    Questo ti consente di combinare entrambi gli approcci. Ad esempio, usa breakpoint espliciti per memorizzare nella cache il tuo system prompt e gli strumenti in modo indipendente, mentre il caching automatico gestisce la conversazione:

    {
      "model": "claude-opus-4-6",
      "max_tokens": 1024,
      "cache_control": {"type": "ephemeral"},
      "system": [
        {
          "type": "text",
          "text": "You are a helpful assistant.",
          "cache_control": {"type": "ephemeral"}
        }
      ],
      "messages": [...]
    }

    Cosa rimane invariato

    Il caching automatico 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 allo stesso modo dei breakpoint espliciti.

    Casi limite

    • Se l'ultimo blocco ha già un cache_control esplicito con lo stesso TTL, il caching automatico è un no-op.
    • 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 il caching automatico).
    • Se l'ultimo blocco non è idoneo come destinazione del breakpoint della cache automatica, il sistema torna silenziosamente indietro per trovare il blocco idoneo più vicino. Se non ne viene trovato nessuno, il caching viene saltato.

    Il caching automatico è disponibile sull'API Claude e su Azure AI Foundry (anteprima). Il supporto per Amazon Bedrock e Google Vertex AI arriverà in seguito.


    Breakpoint espliciti della cache

    Per un maggiore controllo sul caching, puoi posizionare cache_control direttamente su singoli blocchi di contenuto. Questo è utile quando hai bisogno di memorizzare nella cache sezioni diverse che cambiano a frequenze diverse, o quando hai bisogno di un controllo granulare su esattamente ciò che viene 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 il caching 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 su quelli precedenti.

    Come funziona il controllo automatico dei prefissi

    Puoi usare un solo breakpoint della cache alla fine del tuo contenuto statico, e il sistema troverà automaticamente la sequenza più lunga di blocchi memorizzati nella cache corrispondenti. Capire come funziona ti 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 a ritroso: Il sistema verifica i cache hit lavorando a ritroso dal tuo breakpoint esplicito, controllando ogni blocco precedente in ordine inverso. Questo garantisce di ottenere il cache hit più lungo possibile.

    3. Finestra di lookback di 20 blocchi: Il sistema controlla solo fino a 20 blocchi prima di ogni breakpoint cache_control esplicito. Dopo aver controllato 20 blocchi senza una corrispondenza, smette di controllare e passa al successivo breakpoint esplicito (se presente).

    Esempio: Comprendere la 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 cache hit al blocco 30, e solo il blocco 31 deve essere elaborato.

    • Se modifichi il blocco 25 e invii il blocco 31: Il sistema controlla a ritroso dal blocco 30 → 29 → 28... → 25 (nessuna corrispondenza) → 24 (corrispondenza!). Poiché il blocco 24 non è cambiato, ottieni un cache hit al blocco 24, e solo i blocchi 25-30 devono essere rielaborati.

    • Se modifichi il blocco 5 e invii il blocco 31: Il sistema controlla a ritroso dal blocco 30 → 29 → 28... → 11 (controllo n. 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 cache hit e tutti i blocchi devono essere rielaborati. Tuttavia, se avessi impostato un breakpoint cache_control esplicito sul blocco 5, il sistema continuerebbe a controllare da quel breakpoint: blocco 5 (nessuna corrispondenza) → blocco 4 (corrispondenza!). Ciò consente un cache hit al blocco 4, dimostrando perché dovresti posizionare i breakpoint prima del contenuto modificabile.

    Conclusione chiave: Imposta sempre un breakpoint esplicito della cache alla fine della tua conversazione per massimizzare le possibilità di cache hit. Inoltre, imposta i breakpoint appena prima dei blocchi di contenuto che potrebbero essere modificabili per garantire che quelle sezioni possano essere memorizzate nella cache in modo indipendente.

    Quando usare più breakpoint

    Puoi definire fino a 4 breakpoint della cache se vuoi:

    • Memorizzare nella cache sezioni diverse che cambiano a frequenze diverse (ad esempio, gli strumenti cambiano raramente, ma il contesto si aggiorna quotidianamente)
    • Avere un maggiore controllo su esattamente ciò che viene memorizzato nella cache
    • Garantire il caching per contenuti a più di 20 blocchi prima del tuo breakpoint finale
    • Posizionare breakpoint prima del contenuto modificabile per garantire cache hit anche quando si verificano modifiche oltre la finestra di 20 blocchi

    Limitazione importante: Se il tuo prompt ha più di 20 blocchi di contenuto prima del tuo breakpoint della cache e modifichi contenuto precedente a quei 20 blocchi, non otterrai un cache hit a meno che non aggiunga breakpoint espliciti aggiuntivi più vicini a quel contenuto.

    Comprendere i costi dei breakpoint della cache

    I breakpoint della cache stessi non aggiungono alcun costo. Vengono addebitati solo:

    • Scritture nella cache: Quando nuovo contenuto viene scritto nella cache (25% in più rispetto ai token di input base per TTL di 5 minuti)
    • Letture dalla cache: Quando il contenuto memorizzato nella cache viene utilizzato (10% del prezzo base del 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 al contenuto effettivamente memorizzato nella cache e letto. I breakpoint ti danno semplicemente il controllo su quali sezioni possono essere memorizzate nella cache in modo indipendente.


    Strategie e considerazioni sul caching

    Limitazioni della cache

    La lunghezza minima del prompt memorizzabile nella cache è:

    • 4096 token per Claude Opus 4.6, Claude Opus 4.5
    • 2048 token per Claude Sonnet 4.6
    • 1024 token per Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4 e Claude Sonnet 3.7 (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, 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 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 utente che assistente
    • Immagini e documenti: Blocchi di contenuto nell'array messages.content, nei turni utente
    • Uso degli strumenti e risultati degli strumenti: Blocchi di contenuto nell'array messages.content, sia nei turni utente che assistente

    Ciascuno 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 di richiesta possa essere memorizzata nella cache, ci sono alcune eccezioni:

    • I blocchi di thinking non possono essere memorizzati direttamente nella cache con cache_control. Tuttavia, i blocchi di thinking POSSONO essere memorizzati nella cache insieme ad altri contenuti quando appaiono nei turni precedenti dell'assistente. Quando memorizzati nella cache in questo modo, CONTANO come token di input quando vengono letti dalla cache.

    • I sotto-blocchi di contenuto (come le citazioni) non possono essere memorizzati direttamente nella cache. 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 sorgente per le citazioni possono essere memorizzati nella cache. Questo ti consente di utilizzare il 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 è invalidata, mentre ✓ indica che la cache rimane valida.

    Cosa cambiaCache toolsCache systemCache messagesImpatto
    Definizioni degli strumenti✘✘✘La modifica delle definizioni degli strumenti (nomi, descrizioni, parametri) invalida l'intera cache
    Toggle ricerca web✓✘✘Abilitare/disabilitare la ricerca web modifica il system prompt
    Toggle citazioni✓✘✘Abilitare/disabilitare le citazioni modifica il system prompt
    Impostazione velocità✓✘✘Il passaggio tra speed: "fast" e velocità standard invalida le cache di sistema e messaggi

    Monitoraggio delle prestazioni della cache

    Monitora le prestazioni della cache usando questi campi di risposta dell'API, all'interno di usage nella risposta (o nell'evento message_start se in 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 creare una cache (ovvero, token dopo l'ultimo breakpoint della cache).

    Comprendere la suddivisione dei token

    Il campo input_tokens rappresenta solo i token che si trovano dopo l'ultimo breakpoint della cache nella tua richiesta - non tutti i token di input che hai inviato.

    Per calcolare il totale dei token di input:

    total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

    Spiegazione spaziale:

    • cache_read_input_tokens = token prima del breakpoint già memorizzati nella cache (letture)
    • cache_creation_input_tokens = token prima del breakpoint che vengono memorizzati nella cache ora (scritture)
    • input_tokens = token dopo il tuo ultimo breakpoint (non idonei per la cache)

    Esempio: Se hai una richiesta con 100.000 token di contenuto memorizzato nella cache (letto dalla cache), 0 token di nuovo contenuto da memorizzare nella cache e 50 token nel tuo messaggio utente (dopo il breakpoint della cache):

    • cache_read_input_tokens: 100.000
    • : 0

    Caching con blocchi di thinking

    Quando si utilizza il thinking esteso con il prompt caching, i blocchi di thinking hanno un comportamento speciale:

    Caching automatico insieme ad altri contenuti: Sebbene i blocchi di thinking non possano essere esplicitamente contrassegnati 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 thinking per continuare la conversazione.

    Conteggio dei token di input: Quando i blocchi di thinking 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.

    Pattern 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-tool-result, causando la rimozione di tutti i blocchi di thinking precedenti
    • 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]
    # Non-tool-result user block causes all thinking blocks to be ignored
    # This request is processed as if thinking blocks were never present

    Quando viene incluso un blocco utente non-tool-result, designa un nuovo ciclo dell'assistente e tutti i blocchi di thinking precedenti vengono rimossi dal contesto.

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

    Archiviazione e condivisione della cache

    A partire dal 5 febbraio 2026, il prompt caching utilizzerà l'isolamento a livello di workspace invece dell'isolamento a livello di organizzazione. Le cache saranno isolate per workspace, garantendo la separazione dei dati tra workspace all'interno della stessa organizzazione. Questa modifica si applica all'API Claude e ad Azure AI Foundry (anteprima); Amazon Bedrock e Google Vertex AI manterranno l'isolamento della cache a livello di organizzazione. Se utilizzi più workspace, rivedi la tua strategia di caching per tenere conto di questa modifica.

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

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

    • Generazione dei token di output: Il prompt caching non ha effetto sulla generazione dei token di output. La risposta che ricevi sarà identica a quella che otterresti se il prompt caching non fosse utilizzato.

    Best practice per un caching efficace

    Per ottimizzare le prestazioni del prompt caching:

    • Inizia con il caching automatico per le conversazioni multi-turno. Gestisce automaticamente la gestione dei breakpoint.
    • Usa i breakpoint espliciti a livello di blocco quando hai bisogno di 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 della cache in modo strategico per separare diverse sezioni di prefisso memorizzabili nella cache.
    • Imposta i breakpoint della cache alla fine delle conversazioni e appena prima del contenuto modificabile per massimizzare i tassi di cache hit, specialmente quando si lavora con prompt che hanno più di 20 blocchi di contenuto.
    • 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 prompt caching al tuo scenario:

    • Agenti conversazionali: Riduci costi e latenza per conversazioni estese, specialmente quelle con istruzioni lunghe o documenti caricati.
    • Assistenti di codice: Migliora il completamento automatico e le domande e risposte sulla codebase mantenendo sezioni rilevanti o una versione riassunta della codebase nel prompt.
    • Elaborazione di documenti di grandi dimensioni: Incorpora materiale completo in formato lungo 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 perfezionare le risposte di Claude. Gli sviluppatori spesso includono uno o due esempi nel prompt, ma con il prompt caching puoi ottenere prestazioni ancora migliori includendo 20+ esempi diversi di risposte di alta qualità.
    • Uso agentivo degli strumenti: Migliora le prestazioni per scenari che coinvolgono più chiamate agli strumenti e modifiche iterative al codice, dove ogni passaggio richiede tipicamente una nuova chiamata API.
    • Parla con libri, articoli, 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 lasciando che gli utenti facciano domande.

    Risoluzione dei problemi comuni

    Se si verificano comportamenti imprevisti:

    • Assicurati che le sezioni memorizzate nella cache siano identiche tra le chiamate. Per i breakpoint espliciti, verifica che i marcatori cache_control si trovino nelle stesse posizioni
    • 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 rimangano coerenti tra le chiamate
    • Verifica di memorizzare nella cache almeno il numero minimo di token
    • Il sistema controlla automaticamente i cache hit ai confini dei blocchi di contenuto precedenti (fino a ~20 blocchi prima del tuo breakpoint). Per i prompt con più di 20 blocchi di contenuto, potrebbe essere necessario aggiungere 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 ordinamento stabile poiché alcuni linguaggi (ad esempio, Swift, Go) randomizzano l'ordine delle chiavi durante la conversione JSON, rompendo le cache

    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 della cache. Per maggiori dettagli sull'invalidazione della cache, consulta Cosa invalida la cache.


    Durata della cache di 1 ora

    Se trovi che 5 minuti sono troppo brevi, 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 in questo modo:

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

    La risposta includerà 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": 456,
          "ephemeral_1h_input_tokens": 100
        }
      }
    }

    Nota che il campo cache_creation_input_tokens corrente è uguale alla somma dei valori nell'oggetto cache_creation.

    Quando usare la cache di 1 ora

    Se hai prompt che vengono utilizzati a cadenza regolare (ovvero, system prompt 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 è 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 sotto-agente agentivo impiegherà più di 5 minuti, o quando si memorizza una lunga conversazione in chat con un utente e generalmente ci si aspetta che quell'utente potrebbe non rispondere nei prossimi 5 minuti.
    • Quando la latenza è importante e i tuoi prompt di follow-up potrebbero essere inviati oltre i 5 minuti.
    • Quando vuoi migliorare l'utilizzo del limite di frequenza, poiché i cache hit non vengono detratti dal tuo limite di frequenza.

    La cache di 5 minuti e quella di 1 ora si comportano allo stesso modo rispetto alla latenza. In genere vedrai un miglioramento del time-to-first-token per i documenti lunghi.

    Combinazione di TTL diversi

    Puoi usare sia i 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 quelle con TTL più breve (ovvero, 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 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.

    Se B e/o C sono maggiori di A, saranno necessariamente cache miss, perché A è il cache hit più alto.

    Ti verrà addebitato:

    1. Token di lettura dalla cache per A.
    2. Token di scrittura nella cache di 1 ora per (B - A).
    3. Token di scrittura nella cache di 5 minuti per (C - B).

    Ecco 3 esempi. Questo mostra i token di input di 3 richieste, ognuna delle quali ha diversi cache hit e cache miss. Ognuna ha un calcolo dei prezzi diverso, mostrato nelle caselle colorate, come risultato. Diagramma di combinazione TTL


    Esempi di prompt caching

    Per aiutarti a iniziare con il prompt caching, abbiamo preparato un cookbook sul prompt caching con esempi dettagliati e best practice.

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

    Conservazione dei dati

    Il prompt caching memorizza le rappresentazioni della cache KV (chiave-valore) e gli hash crittografici del contenuto memorizzato nella cache, ma non memorizza il testo grezzo dei prompt o delle risposte. Le voci memorizzate nella cache hanno una durata minima di 5 minuti (standard) o 60 minuti (estesa). Le voci della cache sono isolate tra le organizzazioni. Poiché Anthropic non memorizza il testo grezzo dei prompt o delle risposte, questa funzionalità potrebbe essere adatta ai clienti che richiedono impegni di conservazione dei dati di tipo ZDR.

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


    FAQ

    $3 / MTok
    $3.75 / MTok
    $6 / MTok
    $0.30 / MTok
    $15 / MTok
    Claude Sonnet 4.5$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Sonnet 3.7 (deprecated)$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Haiku 4.5$1 / MTok$1.25 / MTok$2 / MTok$0.10 / MTok$5 / MTok
    Claude Haiku 3.5$0.80 / MTok$1 / MTok$1.6 / MTok$0.08 / MTok$4 / MTok
    Claude Opus 3 (deprecated)$15 / MTok$18.75 / MTok$30 / MTok$1.50 / MTok$75 / MTok
    Claude Haiku 3$0.25 / MTok$0.30 / MTok$0.50 / MTok$0.03 / MTok$1.25 / MTok
    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-6",
        "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?"}
        ]
      }'
    Scelta dello strumento✓✓✘Le modifiche al parametro tool_choice influenzano solo i blocchi dei messaggi
    Immagini✓✓✘L'aggiunta/rimozione di immagini in qualsiasi punto del prompt influenza i blocchi dei messaggi
    Parametri di thinking✓✓✘Le modifiche alle impostazioni del thinking esteso (abilita/disabilita, budget) influenzano i blocchi dei messaggi
    Risultati non-tool passati a richieste di thinking esteso✓✓✘Quando risultati non-tool vengono passati in richieste mentre il thinking esteso è abilitato, tutti i blocchi di thinking precedentemente memorizzati nella cache vengono rimossi dal contesto, e tutti i messaggi nel contesto che seguono quei blocchi di thinking vengono rimossi dalla cache. Per maggiori dettagli, consulta Caching con blocchi di thinking.
    cache_creation_input_tokens
  1. input_tokens: 50
  2. Totale token di input elaborati: 100.050 token
  3. Questo è importante per comprendere sia i costi che i limiti di frequenza, poiché input_tokens sarà tipicamente molto più piccolo del tuo input totale quando si utilizza il caching in modo efficace.