Caching dei prompt

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

Come funziona il caching dei prompt

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.

• Prompt con molti esempi
• Grandi quantità di contesto o informazioni di background
• Attività ripetitive con istruzioni coerenti
• Lunghe conversazioni multi-turno

​

Prezzi

​

Come implementare il caching dei prompt

​

Modelli supportati

• 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

​

Come funziona il controllo automatico del prefisso

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

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

​

Quando utilizzare più punti di interruzione

• 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

• 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

​

Comprensione dei costi dei punti di interruzione della cache

• 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

​

Cosa può essere memorizzato nella cache

• 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

​

Cosa non può essere memorizzato nella cache

• 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

​

Tracciamento delle prestazioni della cache

• 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

• 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

• 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

• 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

• 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

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

​

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

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

{
    "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,
        }
    }
}

​

Quando utilizzare la cache di 1 ora

• 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

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.

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

​

Esempi di caching dei prompt

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents."
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Good to know."
                },
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Document ID"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

​

Domande frequenti

python client.beta.prompt_caching.messages.create(...)

python client.messages.create(...)

client.beta.promptCaching.messages.create(...)

client.messages.create(...)