---
title: Cache dei prompt
url: https://platform.claude.com/docs/it/build-with-claude/prompt-caching
description: Memorizza nella cache i prefissi dei prompt con `cache_control` per ridurre costi e latenza, usando la cache automatica o punti di interruzione espliciti con TTL di 5 minuti o 1 ora.
---
Il "prompt caching" (cache dei prompt) ottimizza l'utilizzo dell'API consentendo di riprendere l'elaborazione da prefissi specifici dei tuoi prompt. Questo riduce in modo significativo i tempi di elaborazione e i costi per attività ripetitive o prompt con elementi costanti.
Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
Ci sono due modi per abilitare la cache dei prompt:
* **[Cache automatica](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#automatic-caching)**: aggiungi un singolo campo `cache_control` al livello superiore della richiesta. Il sistema applica automaticamente il "cache breakpoint" (punto di interruzione della cache) all'ultimo blocco memorizzabile nella cache e lo sposta in avanti man mano che la conversazione cresce. È la soluzione migliore per le conversazioni a più turni, in cui la cronologia crescente dei messaggi deve essere memorizzata automaticamente nella cache.
* **[Punti di interruzione espliciti della cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#explicit-cache-breakpoints)**: inserisci `cache_control` direttamente sui singoli blocchi di contenuto per un controllo granulare su cosa viene memorizzato esattamente nella cache.
Il modo più semplice per iniziare è con la cache automatica:
```bash cURL
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-5-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."
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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'."
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
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 =
[
new()
{
Role = Role.User,
Content = "Analyze the major themes in 'Pride and Prejudice'."
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in 'Pride and Prejudice'.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class PromptCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.")
.addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]
],
model: 'claude-opus-5-5',
cacheControl: CacheControlEphemeral::with(),
system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-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'."
}
]
)
puts response.usage
```
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 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 punto di interruzione della cache specificato, è già presente nella cache a seguito di una query recente.
2. Se lo trova, utilizza la versione nella cache, riducendo tempi di elaborazione e costi.
3. Altrimenti, elabora il prompt completo e memorizza il prefisso nella cache non appena inizia la risposta.
Questo è particolarmente utile per:
* Prompt con molti esempi
* Grandi quantità di contesto o informazioni di base
* Attività ripetitive con istruzioni costanti
* Lunghe conversazioni a più turni
Per impostazione predefinita, la cache ha una durata di 5 minuti. La cache viene aggiornata senza costi aggiuntivi ogni volta che il contenuto memorizzato viene utilizzato.
La durata viene misurata dall'inizio della richiesta che scrive o legge la voce della cache, non dalla fine della sua risposta. Il tempo impiegato per generare una risposta viene conteggiato nella durata: se una risposta impiega 4 minuti per lo streaming, una richiesta successiva che riutilizza lo stesso prefisso nella cache deve iniziare entro circa 1 minuto dal completamento di quella risposta.
Se ritieni che 5 minuti siano troppo pochi, Anthropic offre anche una durata della cache di 1 ora [a un costo aggiuntivo](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#pricing).
Per ulteriori informazioni, consulta [Durata della cache di 1 ora](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#1-hour-cache-duration).
**La cache dei prompt memorizza l'intero prefisso**
La cache dei prompt fa riferimento all'intero prompt: `tools`, `system` e `messages` (in quest'ordine), fino al blocco designato con `cache_control` incluso.
***
## Prezzi
La cache dei prompt introduce una nuova struttura dei prezzi. La tabella seguente mostra il prezzo per milione di token per ciascun modello supportato:
| Model | Base input tokens | 5m cache writes | 1h cache writes | Cache hits and refreshes | Output tokens |
| :----------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :-------------- | :-------------- | :----------------------- | :------------ |
| Claude Fable 5.1 | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Fable 5 | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Opus 5.5 | $4 / MTok | $5 / MTok | $8 / MTok | $0.20 / MTok2 | $20 / MTok |
| Claude Opus 5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.8 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| 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 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 5.5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.10 / MTok2 | $10 / MTok |
| Claude Sonnet 5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.20 / MTok | $10 / MTok |
| Claude Sonnet 4.6 | $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 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.10 / MTok | $0.125 / MTok | $0.20 / MTok | $0.01 / MTok | $0.50 / MTok |
| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.50 / MTok | $0.625 / MTok | $1 / MTok | $0.05 / MTok | $2.50 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 ([retired, except on Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)) | $0.80 / MTok | $1 / MTok | $1.60 / MTok | $0.08 / MTok | $4 / MTok |
*1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.*
*2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.*
*All other models use the standard 0.1x multiplier.*
La tabella precedente riflette i seguenti moltiplicatori di prezzo per la cache dei prompt:
* 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 (consulta la nota a piè di tabella per le eccezioni specifiche per modello)
Questi moltiplicatori si sommano ad altri modificatori di prezzo come lo sconto della Batch API, i [prezzi per contesti lunghi](https://platform.claude.com/docs/it/about-claude/pricing#long-context-pricing) e la residenza dei dati. Su un modello con prezzo basato sulla lunghezza del prompt, le letture e le scritture nella cache contano ai fini della lunghezza del prompt di una richiesta. Consulta i [prezzi](https://platform.claude.com/docs/it/about-claude/pricing) per tutti i dettagli.
***
## Modelli supportati
La cache dei prompt (sia automatica che esplicita) è supportata su tutti i [modelli Claude attivi](https://platform.claude.com/docs/it/models/overview).
***
## Cache automatica
La cache automatica è il modo più semplice per abilitare la cache dei prompt. Invece di inserire `cache_control` sui singoli blocchi di contenuto, aggiungi un singolo campo `cache_control` al livello superiore del corpo della richiesta. Il sistema applica automaticamente il punto di interruzione della cache all'ultimo blocco memorizzabile nella cache.
```bash cURL
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-5-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?"}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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?" }
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
System = "You are a helpful assistant that remembers our conversation.",
Messages =
[
new()
{
Role = Role.User,
Content = "My name is Alex. I work on machine learning."
},
new()
{
Role = Role.Assistant,
Content = "Nice to meet you, Alex! How can I help with your ML work today?"
},
new()
{
Role = Role.User,
Content = "What did I say I work on?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are a helpful assistant that remembers our conversation."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("My name is Alex. I work on machine learning.")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("Nice to meet you, Alex! How can I help with your ML work today?")),
anthropic.NewUserMessage(anthropic.NewTextBlock("What did I say I work on?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class AutomaticCachingExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are a helpful assistant that remembers our conversation.")
.addUserMessage("My name is Alex. I work on machine learning.")
.addAssistantMessage("Nice to meet you, Alex! How can I help with your ML work today?")
.addUserMessage("What did I say I work on?")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
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?'],
],
model: 'claude-opus-5-5',
cacheControl: CacheControlEphemeral::with(),
system: 'You are a helpful assistant that remembers our conversation.',
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-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?"}
]
)
puts response.usage
```
### Come funziona la cache automatica nelle conversazioni a più turni
Con la cache automatica, il punto della cache si sposta in avanti automaticamente man mano che la conversazione cresce. Ogni nuova richiesta memorizza nella cache tutto fino all'ultimo blocco memorizzabile, e il contenuto precedente viene letto dalla cache.
| Richiesta | Contenuto | Comportamento della cache |
| ----------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| Richiesta 1 | System
+ User(1) + Asst(1)
+ **User(2)** ◀ cache | Tutto viene scritto nella cache |
| Richiesta 2 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ **User(3)** ◀ cache | Da System a User(2) letto dalla cache;
Asst(2) + User(3) scritti nella cache |
| Richiesta 3 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ **User(4)** ◀ cache | Da System a User(3) letto dalla cache;
Asst(3) + User(4) scritti nella cache |
Il punto di interruzione della cache si sposta automaticamente sull'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" (time-to-live, durata) di 5 minuti. Puoi specificare un TTL di 1 ora a 2 volte il prezzo base dei token di input:
```json
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }
```
### Combinazione con la cache a livello di blocco
La cache automatica è compatibile con i [punti di interruzione espliciti della cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#explicit-cache-breakpoints). Quando vengono usati insieme, il punto di interruzione automatico della cache occupa uno dei 4 slot disponibili per i punti di interruzione.
Questo ti consente di combinare entrambi gli approcci. Ad esempio, usa un punto di interruzione esplicito per memorizzare nella cache il tuo prompt di sistema, mentre la cache automatica gestisce la conversazione:
```json
{
"model": "claude-opus-5-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 cache sottostante. Prezzi, soglie minime di token, requisiti di ordinamento del contesto e la finestra di ricerca a ritroso di 20 blocchi si applicano tutti allo stesso modo dei punti di interruzione 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 punti di interruzione espliciti a livello di blocco, l'API restituisce un errore 400 (non rimangono slot per la cache automatica).
* Se l'ultimo blocco non è idoneo come destinazione di un punto di interruzione automatico della cache, il sistema risale silenziosamente all'indietro per trovare il blocco idoneo più vicino. Se non ne trova nessuno, la cache viene saltata.
La cache automatica è disponibile su tutte le piattaforme tranne l'integrazione legacy [Amazon Bedrock (Opus 4.6 e precedenti)](https://platform.claude.com/docs/it/build-with-claude/claude-on-amazon-bedrock-legacy). Su tale integrazione, l'API restituisce un errore 400 per un campo `cache_control` di livello superiore, quindi usa invece i [punti di interruzione espliciti della cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#explicit-cache-breakpoints).
***
## Punti di interruzione espliciti della cache
Per un maggiore controllo sulla cache, puoi inserire `cache_control` direttamente sui singoli blocchi di contenuto. Questo è utile quando devi memorizzare nella cache sezioni diverse che cambiano con frequenze diverse, o quando hai bisogno di un controllo granulare su cosa viene memorizzato esattamente.
### Strutturare il prompt
Posiziona il contenuto statico (definizioni degli strumenti, istruzioni di sistema, contesto, esempi) all'inizio del prompt. Contrassegna la fine del contenuto riutilizzabile da memorizzare nella 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 dei prefissi
Puoi usare un solo punto di interruzione della cache alla fine del contenuto statico, e il sistema troverà automaticamente il prefisso più lungo che una richiesta precedente ha già scritto nella cache. Capire come funziona ti aiuta a ottimizzare la tua strategia di cache.
**Tre principi fondamentali:**
1. **Le scritture nella cache avvengono solo in corrispondenza del punto di interruzione.** Contrassegnare un blocco con `cache_control` scrive esattamente una voce nella cache: un hash del prefisso che termina in quel blocco. Il sistema non scrive voci per nessuna posizione precedente. Poiché l'hash è cumulativo e copre tutto fino al punto di interruzione incluso, modificare qualsiasi blocco in corrispondenza o prima del punto di interruzione produce un hash diverso nella richiesta successiva.
2. **Le letture dalla cache cercano a ritroso le voci scritte dalle richieste precedenti.** A ogni richiesta il sistema calcola l'hash del prefisso in corrispondenza del punto di interruzione e verifica se esiste una voce corrispondente nella cache. Se non esiste, risale all'indietro un blocco alla volta, verificando se l'hash del prefisso in ciascuna posizione precedente corrisponde a qualcosa già presente nella cache. Cerca scritture precedenti, non contenuto stabile.
3. **La "lookback window" (finestra di ricerca a ritroso) è di 20 blocchi.** Il sistema controlla al massimo 20 posizioni per punto di interruzione, contando il punto di interruzione stesso come prima posizione. Se il sistema non trova alcuna voce corrispondente in quella finestra, il controllo si interrompe (o riprende dal successivo punto di interruzione esplicito, se presente). Sulla Claude API, una sequenza di blocchi `tool_use` consecutivi conta come una sola posizione, così come una sequenza di blocchi `tool_result` consecutivi, quindi un turno con molte chiamate parallele agli strumenti non spinge da solo la voce della richiesta precedente fuori dalla finestra.
**Esempio: ricerca a ritroso 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, punto di interruzione sul blocco 10. Non esistono voci precedenti nella cache. Il sistema scrive una voce al blocco 10.
* **Turno 2:** 15 blocchi, punto di interruzione sul blocco 15. Il blocco 15 non ha alcuna voce, quindi il sistema risale al blocco 10 e trova la voce del turno 1. "Cache hit" (corrispondenza nella cache) al blocco 10; il sistema elabora da zero solo i blocchi da 11 a 15 e scrive una nuova voce al blocco 15.
* **Turno 3:** 35 blocchi, punto di interruzione sul blocco 35. Il sistema controlla 20 posizioni (blocchi da 35 a 16) e non trova nulla. La voce del turno 2 al blocco 15 si trova una posizione fuori dalla finestra, quindi non c'è alcun cache hit. Aggiungere un secondo punto di interruzione al blocco 15 avvia lì una seconda finestra di ricerca a ritroso, che trova la voce del turno 2.
**Errore comune: punto di interruzione su contenuto che cambia a ogni richiesta**
Il tuo prompt ha un ampio contesto di sistema statico (blocchi da 1 a 5) seguito da un blocco specifico per ogni 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. La ricerca a ritroso 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 una nuova scrittura nella cache a ogni richiesta e non ottieni mai una lettura.
La ricerca a ritroso non trova il contenuto stabile dietro il punto di interruzione per memorizzarlo nella cache. Trova le voci che le richieste precedenti hanno già scritto, e le scritture avvengono solo in corrispondenza dei punti di interruzione. Sposta `cache_control` sul blocco 5, l'ultimo blocco che rimane invariato tra le richieste, e ogni richiesta successiva leggerà il prefisso dalla cache. La [cache automatica](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#automatic-caching) cade nella stessa trappola: posiziona il punto di interruzione sull'ultimo blocco memorizzabile, che in questa struttura è quello che cambia a ogni richiesta, quindi usa invece un punto di interruzione esplicito sul blocco 5.
**Punto chiave:** posiziona `cache_control` sull'ultimo blocco il cui prefisso è identico tra le richieste che vuoi far condividere 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 la ricerca a ritroso della richiesta successiva trova la scrittura precedente. Per un prompt con un suffisso variabile (timestamp, contesto specifico per richiesta, il messaggio in arrivo), posiziona il punto di interruzione alla fine del prefisso statico, non sul blocco variabile.
#### Quando usare più punti di interruzione
Puoi definire fino a 4 punti di interruzione della cache se vuoi:
* Memorizzare nella cache sezioni diverse che cambiano con frequenze diverse (ad esempio, gli strumenti cambiano raramente, ma il contesto si aggiorna ogni giorno)
* Avere un maggiore controllo su cosa viene memorizzato esattamente nella cache
* Garantire un cache hit quando una conversazione in crescita sposta il punto di interruzione di 20 o più blocchi oltre l'ultima scrittura nella cache
**Limitazione importante:** la ricerca a ritroso può trovare solo le voci che le richieste precedenti hanno già scritto. Se una conversazione in crescita sposta il punto di interruzione di 20 o più blocchi oltre l'ultima scrittura, la finestra di ricerca a ritroso non la trova. Aggiungi fin dall'inizio un secondo punto di interruzione più vicino a quella posizione, in modo che lì si accumuli una scrittura prima che ti serva.
### Comprendere i costi dei breakpoint della cache
**I breakpoint della cache di per sé non aggiungono alcun costo.** Ti vengono addebitati solo:
* **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 viene utilizzato contenuto nella cache (10% del prezzo base dei token di input, oppure 2,5% su Claude Fable 5.1 e Claude Mythos 5.1, e 5% su Claude Opus 5.5 e Claude Sonnet 5.5)
* **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 e letto dalla cache. 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, su [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai) e [Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry), la lunghezza minima del prompt memorizzabile nella cache è:
* 512 token per Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/it/models/mythos-5-1/overview), Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/it/models/mythos-5/overview) e Claude Haiku 5.5
* 2.048 token per [Claude Mythos Preview](https://anthropic.com/glasswing) 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 ([deprecato](https://platform.claude.com/docs/it/about-claude/model-deprecations)), Claude Opus 4.1 ([ritirato, tranne su Bedrock e Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)), Claude Opus 4 ([ritirato, tranne su Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)) e Claude Sonnet 4 ([ritirato, tranne su Bedrock e Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations))
* 4.096 token per Claude Haiku 4.5
* 2.048 token per Claude Haiku 3.5 ([ritirato, tranne su Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations))
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 di utilizzo della risposta](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#tracking-cache-performance): se sia `cache_creation_input_tokens` che `cache_read_input_tokens` sono 0, il prompt non è stato memorizzato nella cache (probabilmente perché non soddisfaceva il requisito di lunghezza minima).
Se il tuo prompt è appena al di sotto del minimo per il tuo modello e la tua piattaforma, spesso vale la pena espandere il contenuto memorizzato nella cache per raggiungere la soglia. Le letture dalla cache costano significativamente meno dei token di input non memorizzati, quindi raggiungere il minimo può ridurre i costi per i prompt riutilizzati frequentemente.
[Bedrock](https://platform.claude.com/docs/it/build-with-claude/claude-in-amazon-bedrock) è una piattaforma gestita da AWS. Su Bedrock, consulta la [documentazione sulla cache dei prompt di Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) per i minimi per modello, il comportamento in caso di errore e i nomi dei campi di utilizzo applicabili.
Per le richieste simultanee, tieni presente 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 dell'utente che per quelli 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 in quelli dell'assistente
Ciascuno di questi elementi può essere memorizzato nella cache, automaticamente oppure 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 ragionamento non possono essere memorizzati direttamente nella cache con `cache_control`. Tuttavia, i blocchi di ragionamento POSSONO essere memorizzati nella cache insieme ad altro contenuto quando compaiono nei turni precedenti dell'assistente. Quando vengono memorizzati in questo modo, VENGONO conteggiati come token di input quando letti dalla cache.
* I blocchi di sotto-contenuto (come le [citazioni](https://platform.claude.com/docs/it/build-with-claude/citations)) non possono essere memorizzati direttamente nella cache. Memorizza invece 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 efficacemente la cache dei prompt con le citazioni, memorizzando nella cache i documenti a cui le citazioni faranno riferimento.
* I blocchi di testo vuoti non possono essere memorizzati nella cache.
### Cosa invalida la cache
Le modifiche al contenuto memorizzato nella cache possono invalidare parte o tutta la cache.
Come descritto in [Strutturare il prompt](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#structuring-your-prompt), la cache segue la gerarchia: `tools` → `system` → `messages`. Le modifiche a ciascun livello invalidano quel livello e tutti i livelli successivi.
La tabella seguente mostra quali parti della cache vengono invalidate da diversi tipi di modifiche. ✘ indica che la cache viene invalidata, mentre ✓ indica che la cache rimane valida.
| Cosa cambia | Cache degli strumenti | Cache di sistema | Cache dei messaggi | Impatto |
| ------------------------------------------------------------------- | --------------------- | --------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Definizioni degli strumenti** | ✘ | ✘ | ✘ | Modificare le definizioni degli strumenti (nomi, descrizioni, parametri) invalida l'intera cache |
| **Attivazione della ricerca web** | ✓ | ✘ | ✘ | Abilitare/disabilitare la ricerca web modifica il prompt di sistema |
| **Attivazione delle citazioni** | ✓ | ✘ | ✘ | Abilitare/disabilitare le citazioni modifica il prompt di sistema |
| **Impostazione della velocità** | ✓ | ✘ | ✘ | Passare tra [`speed: "fast"` e la velocità standard](https://platform.claude.com/docs/it/build-with-claude/fast-mode) invalida le cache di sistema e dei messaggi |
| **Scelta dello strumento** | ✓ | ✓ | ✘ | Le modifiche al parametro `tool_choice` influiscono solo sui blocchi dei messaggi |
| **Immagini** | ✓ | ✓ | ✘ | Aggiungere/rimuovere immagini in qualsiasi punto del prompt influisce sui blocchi dei messaggi |
| **Parametri di ragionamento** | Specifico per modello | Specifico per modello | ✘ | La configurazione del ragionamento (modalità e `budget_tokens` in modalità estesa) viene inserita nel prompt, quindi modificarla invalida sempre i blocchi dei messaggi; anche le cache degli strumenti e di sistema vengono invalidate sui modelli che inseriscono la configurazione prima di esse. Consulta [Ragionamento e cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-and-prompt-caching). |
| **Impostazione dell'effort** | Specifico per modello | Specifico per modello | ✘ | Modificare il valore di [`output_config.effort`](https://platform.claude.com/docs/it/build-with-claude/effort) invalida sempre i blocchi dei messaggi, con lo stesso effetto specifico per modello dei parametri di ragionamento sulle cache degli strumenti e di sistema. Impostare esplicitamente l'effort sul valore predefinito del modello equivale a ometterlo e non causa invalidazione. Sui modelli che supportano l'[effort per messaggio](https://platform.claude.com/docs/it/build-with-claude/effort#change-effort-mid-conversation-beta), una modifica dell'effort trasmessa in un messaggio `role: "system"` all'interno di `messages` lascia intatto il prefisso nella cache. |
| **Risultati non di strumenti passati a richieste con ragionamento** | ✓ | ✓ | Specifico per modello | Su Opus 4.5+, Sonnet 4.6+ e Haiku 5.5, i blocchi di ragionamento vengono preservati per impostazione predefinita, quindi la cache rimane valida (✓). Sui modelli Opus/Sonnet precedenti e sui modelli Haiku fino a Claude Haiku 4.5, tutti i blocchi di ragionamento precedentemente memorizzati nella cache vengono rimossi dal contesto, e tutti i messaggi che seguono quei blocchi di ragionamento vengono rimossi dalla cache (✘). Per maggiori dettagli, consulta [Cache con blocchi di ragionamento](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#caching-with-thinking-blocks). |
| **Blocchi di ragionamento scartati** | ✓ | ✓ | ✘ | Quando l'API scarta un blocco di ragionamento di Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 o Claude Haiku 5.5 che non è [preservato](https://platform.claude.com/docs/it/build-with-claude/thinking#preserved-thinking) in quella richiesta (ad esempio, uno che ripassi a un modello che non può leggerlo), il prefisso nella cache cambia dalla posizione di quel blocco in poi in quella richiesta. I blocchi che il modello ricevente può leggere, ripassati senza modifiche, mantengono intatta la cache. |
Sui modelli che supportano le [modifiche agli strumenti a metà conversazione](https://platform.claude.com/docs/it/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), l'header beta `inline-tools-2026-09-15` ti consente di aggiungere uno strumento, o modificare la definizione di uno strumento, a metà di una conversazione senza modificare `tools`. Invia la definizione in un blocco `tool_addition` in un messaggio di sistema a metà conversazione e lascia `tools` esattamente come l'hai inviato la prima volta. Il prefisso nella cache corrisponde ancora, quindi solo il messaggio aggiunto viene elaborato come nuovo input. L'unica eccezione è un array `tools` senza alcuno strumento non differito, in cui il primo strumento definito in questo modo costa un cache miss completo in quella richiesta. Consulta [Definire strumenti in un messaggio](https://platform.claude.com/docs/it/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).
Su Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/it/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/it/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5 e Claude Haiku 5.5, puoi aggiungere una nuova istruzione di sistema a metà di una conversazione senza invalidare le cache di sistema o dei messaggi. Aggiungi un messaggio `{"role": "system"}` a `messages` invece di modificare il campo `system` di livello superiore, in modo che il prefisso nella cache rimanga invariato. Questa funzionalità non è disponibile su Claude Sonnet 5. Usa invece il campo `system` di livello superiore. Consulta [Messaggi di sistema a metà conversazione](https://platform.claude.com/docs/it/build-with-claude/mid-conversation-system-messages).
### Monitorare le prestazioni della cache
Monitora le prestazioni della cache usando questi campi della risposta dell'API, all'interno di `usage` nella risposta (o nell'evento `message_start` se usi lo [streaming](https://platform.claude.com/docs/it/build-with-claude/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é usati per crearla (ovvero, i token dopo l'ultimo punto di interruzione della cache).
**Comprendere la suddivisione dei token**
Il campo `input_tokens` rappresenta solo i token che si trovano **dopo l'ultimo punto di interruzione della cache** nella tua richiesta, non tutti i token di input che hai inviato.
Per calcolare il totale dei token di input:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
**Spiegazione spaziale:**
* `cache_read_input_tokens` = token prima del punto di interruzione già presenti nella cache (letture)
* `cache_creation_input_tokens` = token prima del punto di interruzione che vengono memorizzati ora nella cache (scritture)
* `input_tokens` = token dopo l'ultimo punto di interruzione (non idonei per la cache)
**Esempio:** se hai una richiesta con 100.000 token di contenuto nella cache (letti dalla cache), 0 token di nuovo contenuto da memorizzare nella cache e 50 token nel messaggio dell'utente (dopo il punto di interruzione della cache):
* `cache_read_input_tokens`: 100.000
* `cache_creation_input_tokens`: 0
* `input_tokens`: 50
* **Totale dei token di input elaborati:** 100.050 token
Questo è importante per comprendere sia i costi che i limiti di velocità, poiché `input_tokens` sarà in genere molto più piccolo del tuo input totale quando usi la cache in modo efficace.
### Cache con blocchi di ragionamento
Quando usi il [ragionamento](https://platform.claude.com/docs/it/build-with-claude/thinking) con la cache dei prompt, i blocchi di ragionamento hanno un comportamento speciale:
**Cache automatica insieme ad altro contenuto:** Sebbene i blocchi di ragionamento 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 ripassi i blocchi di ragionamento per continuare la conversazione.
**Conteggio dei token di input:** Quando i blocchi di ragionamento vengono letti dalla cache, contano come token di input nelle tue metriche di utilizzo. Questo è importante per il calcolo dei costi e la pianificazione del budget di token.
**Schemi di invalidazione della cache:**
* La cache rimane valida quando vengono forniti solo risultati degli strumenti come messaggi dell'utente
* Su Opus 4.5+, Sonnet 4.6+ e Haiku 5.5, i blocchi di ragionamento vengono preservati per impostazione predefinita anche quando viene aggiunto contenuto utente che non è un risultato di strumento, quindi la cache rimane valida
* Sui modelli Opus/Sonnet precedenti e sui modelli Haiku fino a Claude Haiku 4.5, la cache viene invalidata quando viene aggiunto contenuto utente che non è un risultato di strumento, causando la rimozione dal contesto di tutti i blocchi di ragionamento precedenti
* Questo comportamento della cache si verifica anche senza marcatori `cache_control` espliciti
Per maggiori dettagli sull'invalidazione della cache, consulta [Cosa invalida la cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#what-invalidates-the-cache).
**Esempio con uso degli strumenti:**
```text wrap
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]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)
```
Sui modelli Opus/Sonnet precedenti e sui modelli Haiku fino a Claude Haiku 4.5, tutti i blocchi di ragionamento precedenti vengono rimossi dal contesto a questo punto. Su Opus 4.5+, Sonnet 4.6+ e Haiku 5.5, i blocchi di ragionamento precedenti vengono mantenuti per impostazione predefinita e rimangono parte del prefisso nella cache.
Per informazioni più dettagliate, consulta [Ragionamento e cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-and-prompt-caching).
### Archiviazione e condivisione della cache
La cache dei prompt utilizza l'isolamento a livello di [workspace](https://platform.claude.com/docs/it/manage-claude/workspaces). Le cache sono isolate per workspace, garantendo la separazione dei dati tra i workspace all'interno della stessa organizzazione. Questo si applica alla Claude API, a Claude Platform on AWS e a Microsoft Foundry; Bedrock e Google Cloud mantengono l'isolamento della cache a livello di organizzazione. Se usi più workspace, rivedi la tua strategia di cache per tenere conto di questa differenza.
* **Isolamento per organizzazione e workspace:** le cache sono isolate tra le organizzazioni. Organizzazioni diverse non condividono mai le cache, anche se usano prompt identici. Le cache sono inoltre isolate per workspace all'interno di un'organizzazione sulla Claude API, su Claude Platform on AWS e su Microsoft Foundry; Bedrock e Google Cloud usano solo l'isolamento a livello di organizzazione.
* **Corrispondenza esatta:** i cache hit richiedono segmenti di prompt identici al 100%, inclusi tutto il testo e tutte le immagini fino al blocco contrassegnato con il controllo della cache 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](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#automatic-caching) per le conversazioni a più turni. Gestisce automaticamente i punti di interruzione.
* Usa i [punti di interruzione espliciti a livello di blocco](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#explicit-cache-breakpoints) 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 base, contesti ampi o definizioni di strumenti usate di frequente.
* Posiziona il contenuto da memorizzare nella cache all'inizio del prompt per ottenere le migliori prestazioni.
* Usa i punti di interruzione della cache in modo strategico per separare le diverse sezioni di prefisso memorizzabili.
* Posiziona il punto di interruzione sull'ultimo blocco che rimane identico tra le richieste. Per un prompt con un prefisso statico e un suffisso variabile (timestamp, contesto specifico per richiesta, il messaggio in arrivo), si tratta della fine del prefisso, non del 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 "latency" (latenza) per conversazioni estese, in particolare quelle con istruzioni lunghe o documenti caricati.
* Assistenti di programmazione: migliora il completamento automatico e le domande e risposte sulla codebase mantenendo nel prompt le sezioni rilevanti o una versione riassunta della codebase.
* Elaborazione di documenti di grandi dimensioni: incorpora nel prompt materiale completo di lunga durata, incluse le immagini, senza aumentare la latenza della risposta.
* Set di istruzioni dettagliati: 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 la cache dei prompt puoi ottenere prestazioni ancora migliori includendo più di 20 esempi diversificati di risposte di alta qualità.
* Uso degli strumenti in modalità agentica: migliora le prestazioni per scenari che prevedono più chiamate agli strumenti e modifiche iterative al codice, in cui ogni passaggio richiede in genere una nuova chiamata API.
* Conversare 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 gli interi documenti) nel prompt e consentendo agli utenti di porre domande.
### Risoluzione dei problemi comuni
Se riscontri un comportamento inatteso:
La [diagnostica della cache](https://platform.claude.com/docs/it/build-with-claude/cache-diagnostics) fa sì che l'API confronti richieste consecutive e segnali il punto in cui il prefisso del prompt è divergente, gestendo automaticamente molti dei passaggi di questo elenco.
* Assicurati che le sezioni memorizzate nella cache siano identiche tra le chiamate. Per i punti di interruzione espliciti, verifica che i marcatori `cache_control` si trovino nelle stesse posizioni
* Controlla 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 ragionamento 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](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#cache-limitations))
* Conferma che il punto di interruzione si trovi su un blocco che rimane identico tra le richieste. Le scritture nella cache avvengono solo in corrispondenza del punto di interruzione e, se quel blocco cambia (timestamp, contesto specifico per richiesta, il messaggio in arrivo), l'hash del prefisso non corrisponde mai. La ricerca a ritroso non trova il contenuto stabile dietro il punto di interruzione; trova solo le voci che le richieste precedenti hanno scritto in corrispondenza dei propri punti di interruzione
* Verifica che le chiavi nei blocchi di contenuto `tool_use` abbiano un ordinamento stabile, poiché alcuni linguaggi (ad esempio Swift, Go) rendono casuale l'ordine delle chiavi durante la conversione in JSON, compromettendo le cache
* Usa la [diagnostica della cache](https://platform.claude.com/docs/it/build-with-claude/cache-diagnostics) per far sì che l'API confronti richieste consecutive e segnali quale parte del prompt è divergente
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](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#what-invalidates-the-cache).
***
## 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](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#pricing).
La durata della cache di 1 ora è disponibile sulla Claude API, su [Amazon Bedrock](https://platform.claude.com/docs/it/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (Opus 4.6 e precedenti)](https://platform.claude.com/docs/it/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai) e [Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry).
Per usare la cache estesa, includi `ttl` nella definizione di `cache_control` in questo modo:
```json
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}
```
La risposta include informazioni dettagliate sulla cache come le seguenti:
```json Output
{
"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
}
}
}
```
Tieni presente 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](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically).
### Quando usare la cache di 1 ora
Se hai prompt utilizzati con cadenza regolare (ovvero, prompt di sistema utilizzati più spesso di ogni 5 minuti), continua a usare la cache di 5 minuti, poiché continuerà a essere aggiornata senza costi aggiuntivi.
La cache di 1 ora è più indicata nei seguenti scenari:
* Quando hai prompt che probabilmente vengono utilizzati meno spesso di ogni 5 minuti, ma più spesso di ogni ora. Ad esempio, quando un agente secondario in un flusso agentico impiegherà più di 5 minuti, oppure quando memorizzi una lunga conversazione di chat con un utente e in genere prevedi che quell'utente potrebbe non rispondere nei 5 minuti successivi.
* Quando la latenza è importante e i tuoi prompt successivi potrebbero essere inviati dopo più di 5 minuti.
* Quando vuoi migliorare l'utilizzo del tuo "rate limit" (limite di velocità), poiché i cache hit non vengono detratti dal tuo limite di velocità.
La cache di 5 minuti e quella di 1 ora si comportano allo stesso modo per quanto riguarda la latenza. In genere noterai un miglioramento del tempo al primo token per i documenti lunghi.
### Combinare TTL diversi
Puoi usare sia controlli di cache da 1 ora sia da 5 minuti nella stessa richiesta, ma con un vincolo importante: le voci di cache con TTL più lungo devono comparire prima di quelle con TTL più breve (ovvero, una voce di cache da 1 ora deve comparire prima di qualsiasi voce di cache da 5 minuti).
Quando combini TTL diversi, l'API determina tre posizioni di fatturazione nel tuo prompt:
1. Posizione `A`: il conteggio dei token in corrispondenza del cache hit più alto (o 0 se non ci sono hit).
2. Posizione `B`: il conteggio dei token in corrispondenza del blocco `cache_control` da 1 ora più alto dopo `A` (oppure uguale ad `A` se non ne esistono).
3. Posizione `C`: il conteggio dei token in corrispondenza dell'ultimo blocco `cache_control`.
Se `B` o `C` è maggiore di `A`, si tratta necessariamente di un cache miss, perché `A` è il cache hit più alto.
Ti verranno addebitati:
1. Token di lettura dalla cache per `A`.
2. Token di scrittura nella cache da 1 ora per `(B - A)`.
3. Token di scrittura nella cache da 5 minuti per `(C - B)`.
Ecco tre esempi. L'immagine mostra i token di input di 3 richieste, ciascuna con cache hit e cache miss diversi. Di conseguenza, ciascuna ha un prezzo calcolato diverso, mostrato nei riquadri colorati.
***
## Preriscaldare la cache
Il "cache pre-warming" (preriscaldamento 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 dovuta al cache miss alla prima interazione dell'utente, riducendo il "time-to-first-token" (tempo al primo token), o 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 corrispondenza di qualsiasi breakpoint `cache_control`, quindi restituisce immediatamente una risposta senza generare alcun output. La risposta ha un array `content` vuoto, `stop_reason: "max_tokens"` e un blocco `usage` completamente popolato.
Posiziona il breakpoint `cache_control` sull'ultimo blocco condiviso con la richiesta successiva (in genere 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 colpirà. Usa anche la stessa configurazione del ragionamento e lo stesso `output_config.effort` delle tue richieste successive: questi valori vengono inseriti nel prompt (vedi [Cosa invalida la cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#what-invalidates-the-cache)), quindi un preriscaldamento con una configurazione diversa può scrivere una voce che il tuo traffico reale non colpirà mai. Ciò significa usare un [breakpoint della cache esplicito](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#explicit-cache-breakpoints) anziché la [cache automatica](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#automatic-caching), poiché la cache automatica posiziona il breakpoint sull'ultimo blocco, che in questo caso è il segnaposto. Il messaggio utente segnaposto può essere qualsiasi stringa con contenuto diverso da spazi bianchi (gli esempi qui usano `"warmup"`); il suo contenuto viene letto nel modello ma non riceve mai risposta.
Una richiesta di preriscaldamento comporta un addebito per **scrittura nella cache** se il prefisso non è già in cache, come qualsiasi altra richiesta. Controlla `usage.cache_creation_input_tokens` nella risposta per confermare che sia avvenuta una scrittura. Non vengono fatturati token di output.
```bash cURL
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-5-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"}]
}'
```
```bash CLI
ant messages create \
--transform '{stop_reason,content,usage}' --format yaml <<'YAML'
model: claude-opus-5-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
YAML
```
```python Python
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-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)
```
```typescript TypeScript
const client = new Anthropic();
// Esegui questa chiamata prima dell'arrivo degli utenti per preriscaldare la cache condivisa del prompt di sistema.
const prewarm = await client.messages.create({
model: "claude-opus-5-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" }]
});
console.log(prewarm.stop_reason); // "max_tokens"
console.log(prewarm.content); // []
console.log(prewarm.usage);
```
```csharp C#
AnthropicClient client = new();
var prewarm = await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
]
),
Messages = [new() { Role = Role.User, Content = "warmup" }],
}
);
Console.WriteLine(prewarm.StopReason?.Raw()); // "max_tokens"
Console.WriteLine(prewarm.Content.Count); // 0
Console.WriteLine(prewarm.Usage);
```
```go Go
client := anthropic.NewClient()
prewarm, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
if err != nil {
panic(err)
}
fmt.Println(prewarm.StopReason) // "max_tokens"
fmt.Println(prewarm.Content) // []
fmt.Println(prewarm.Usage.RawJSON())
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message prewarm = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build()))
.addUserMessage("warmup")
.build());
IO.println(prewarm.stopReason()); // Optional[max_tokens]
IO.println(prewarm.content()); // []
IO.println(prewarm.usage());
```
```php PHP
$client = new Client();
$prewarm = $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 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']],
);
echo $prewarm->stopReason, PHP_EOL; // "max_tokens"
echo json_encode($prewarm->content), PHP_EOL; // []
echo json_encode($prewarm->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
prewarm = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_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"}]
)
puts prewarm.stop_reason # :max_tokens
puts prewarm.content # []
puts prewarm.usage
```
L'API restituisce un array `content` vuoto:
```json Output
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [],
"model": "claude-opus-5-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 preriscaldamento all'avvio della tua applicazione (o a intervalli programmati), quindi invia le richieste reali degli utenti dopo il completamento del preriscaldamento:
```bash cURL
# Prepara la cache all'avvio dell'applicazione o a intervalli pianificati.
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-5-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"}]
}'
# In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già nella cache.
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-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "How do I implement a binary search tree?"}]
}'
```
```bash CLI
# Prepara la cache all'avvio dell'applicazione o a intervalli pianificati.
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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
YAML
# In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già in cache.
ant messages create --transform 'content.#(type=="text").text' --raw-output <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: How do I implement a binary search tree?
YAML
```
```python Python
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-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-5",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": user_message}],
)
# Prepara 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)
```
```typescript TypeScript
const client = new Anthropic();
const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
];
// Chiama questa funzione all'avvio dell'applicazione o a intervalli pianificati.
async function prewarmCache(): Promise {
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: "warmup" }]
});
}
// La vera richiesta dell'utente; beneficia di una cache già calda.
async function respond(userMessage: string): Promise {
return client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: userMessage }]
});
}
// Riscalda la cache prima che arrivi traffico dagli utenti.
await prewarmCache();
// In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già in cache.
const response = await respond("How do I implement a binary search tree?");
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
List systemPrompt =
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
];
// Chiama questa funzione all'avvio dell'applicazione o a intervalli pianificati.
async Task PrewarmCache() =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(systemPrompt),
Messages = [new() { Role = Role.User, Content = "warmup" }],
}
);
// La richiesta reale dell'utente; beneficia di una cache già calda.
async Task Respond(string userMessage) =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new(systemPrompt),
Messages = [new() { Role = Role.User, Content = userMessage }],
}
);
// Riscalda la cache prima che arrivi traffico dagli utenti.
await PrewarmCache();
// In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già in cache.
var response = await Respond("How do I implement a binary search tree?");
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
```
```go Go
var client = anthropic.NewClient()
var systemPrompt = []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
}
// Chiama questa funzione all'avvio dell'applicazione o a intervalli pianificati.
func prewarmCache() error {
_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
return err
}
// La vera richiesta dell'utente; beneficia di una cache già calda.
func respond(userMessage string) (*anthropic.Message, error) {
return client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(userMessage)),
},
})
}
func main() {
// Riscalda la cache prima che arrivi traffico dagli utenti.
if err := prewarmCache(); err != nil {
log.Fatal(err)
}
// In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già in cache.
response, err := respond("How do I implement a binary search tree?")
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List systemPrompt = List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build());
// Chiama questa funzione all'avvio dell'applicazione o a intervalli pianificati.
void prewarmCache() {
client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage("warmup")
.build());
}
// La vera richiesta dell'utente; beneficia di una cache già calda.
Message respond(String userMessage) {
return client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage(userMessage)
.build());
}
void main() {
// Riscalda la cache prima che arrivi traffico dagli utenti.
prewarmCache();
// In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già in cache.
Message response = respond("How do I implement a binary search tree?");
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$systemPrompt = [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
];
// Chiama questa funzione all'avvio dell'applicazione o a intervalli pianificati.
$prewarmCache = fn () => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => 'warmup']],
);
// La richiesta reale dell'utente; beneficia di una cache già calda.
$respond = fn (string $userMessage) => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => $userMessage]],
);
// Riscalda la cache prima che arrivi traffico dagli utenti.
$prewarmCache();
// 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?');
foreach ($response->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
SYSTEM_PROMPT = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
]
# Chiama questa funzione all'avvio dell'applicazione o a intervalli pianificati.
def prewarm_cache(client)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: "warmup"}]
)
end
# La vera richiesta dell'utente; beneficia di una cache già calda.
def respond(client, user_message)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: user_message}]
)
end
# Riscalda la cache prima che arrivi traffico dagli utenti.
prewarm_cache(client)
# In seguito, quando l'utente invia un messaggio, il prefisso del prompt di sistema è già in cache.
response = respond(client, "How do I implement a binary search tree?")
response.content.each do |block|
puts block.text if block.type == :text
end
```
Tieni presente che il TTL della cache continua ad applicarsi. Per la cache predefinita da 5 minuti, invia una nuova richiesta di preriscaldamento almeno ogni 5 minuti per mantenere la cache calda. Per intervalli più lunghi tra le richieste degli utenti, usa invece la [durata della cache di 1 ora](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#1-hour-cache-duration).
### Limitazioni
Una richiesta con `max_tokens: 0` viene rifiutata con un `invalid_request_error` se è impostato uno qualsiasi dei seguenti elementi, poiché ciascuno implica un output che un budget di zero token non può produrre:
* `stream: true`
* [Ragionamento esteso](https://platform.claude.com/docs/it/build-with-claude/extended-thinking) (`thinking.type: "enabled"`)
* [Output strutturati](https://platform.claude.com/docs/it/build-with-claude/structured-outputs) (`output_config.format`)
* `tool_choice` con valore `{"type": "tool", ...}` o `{"type": "any"}`
`max_tokens: 0` viene rifiutato anche all'interno di una richiesta [Message Batches](https://platform.claude.com/docs/it/build-with-claude/batch-processing). Il preriscaldamento mira al time-to-first-token, che non si applica all'elaborazione in batch, e una voce della cache scritta durante l'elaborazione in batch probabilmente scadrebbe prima dell'esecuzione della richiesta successiva.
### Sostituire la 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 il "prompt caching" (cache dei prompt), il [cookbook sulla cache dei prompt](https://platform.claude.com/cookbook/misc-prompt-caching) 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à:
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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?"
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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?",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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?"
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "You are an AI assistant tasked with analyzing legal documents.",
},
new TextBlockParam()
{
Text = "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new()
{
Role = Role.User,
Content = "What are the key terms and conditions in this agreement?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing legal documents.",
},
{
Text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What are the key terms and conditions in this agreement?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class LegalDocumentAnalysisExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text("You are an AI assistant tasked with analyzing legal documents.")
.build(),
TextBlockParam.builder()
.text(
"Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("What are the key terms and conditions in this agreement?")
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => 'What are the key terms and conditions in this agreement?'
]
],
model: 'claude-opus-5-5',
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']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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?"
}
]
)
puts message.usage
```
Questo esempio dimostra l'utilizzo di base della cache dei prompt, memorizzando nella cache il testo completo dell'accordo legale come prefisso e lasciando l'istruzione dell'utente fuori dalla cache.
Per la prima richiesta:
* `input_tokens`: numero di token solo nel messaggio dell'utente
* `cache_creation_input_tokens`: numero di token nell'intero messaggio di sistema, incluso il documento legale
* `cache_read_input_tokens`: 0 (nessun cache hit alla prima richiesta)
Per le richieste successive entro la durata della cache:
* `input_tokens`: numero di token solo nel messaggio dell'utente
* `cache_creation_input_tokens`: 0 (nessuna nuova creazione di cache)
* `cache_read_input_tokens`: numero di token nell'intero messaggio di sistema memorizzato nella cache
Le definizioni degli strumenti possono essere memorizzate nella cache posizionando `cache_control` sull'ultimo strumento del tuo array `tools`. Tutti gli strumenti definiti prima di quello strumento, incluso quest'ultimo, vengono memorizzati nella cache come un unico prefisso.
```json
{
"model": "claude-opus-5-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" } },
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": { "timezone": { "type": "string" } },
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}
```
Alla prima richiesta, `cache_creation_input_tokens` riflette il conteggio dei token di tutte le definizioni degli strumenti. Nelle richieste successive entro la durata della cache, quei token compaiono invece in `cache_read_input_tokens`.
Per i dettagli sull'interazione tra definizioni degli strumenti, `defer_loading` e invalidazione della cache, consulta [Uso degli strumenti con la cache dei prompt](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-use-with-prompt-caching).
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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"}
}
]
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "...long system prompt",
"cache_control": {"type": "ephemeral"},
}
],
messages=[
# ...lunga conversazione fin qui
{
"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'd 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"},
},
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "...long system prompt",
cache_control: { type: "ephemeral" }
}
],
messages: [
// ...lunga conversazione fin qui
{
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'd 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" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "...long system prompt",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),
}),
},
new()
{
Role = 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?"
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam("Good to know.")),
new ContentBlockParam(new TextBlockParam()
{
Text = "Tell me more about Mars.",
CacheControl = new CacheControlEphemeral(),
}),
})
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "...long system prompt",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, can you tell me more about the solar system?")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("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: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
anthropic.NewTextBlock("Good to know."),
{OfText: &anthropic.TextBlockParam{
Text: "Tell me more about Mars.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class ConversationWithCacheControlExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Crea un prompt di sistema effimero
TextBlockParam systemPrompt = TextBlockParam.builder()
.text("...long system prompt")
.cacheControl(CacheControlEphemeral.builder().build())
.build();
// Crea i parametri del messaggio
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(List.of(systemPrompt))
// Primo messaggio utente (senza controllo della cache)
.addUserMessage("Hello, can you tell me more about the solar system?")
// Risposta dell'assistente
.addAssistantMessage(
"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?"
)
// Secondo messaggio utente (con controllo della cache)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(TextBlockParam.builder().text("Good to know.").build()),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Tell me more about Mars.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
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']
]
]
]
],
model: 'claude-opus-5-5',
system: [
[
'type' => 'text',
'text' => '...long system prompt',
'cache_control' => ['type' => 'ephemeral']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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" }
}
]
}
]
)
puts message.usage
```
Questo esempio dimostra come usare la cache dei prompt in una conversazione a più turni.
A ogni turno, il blocco finale del messaggio finale viene contrassegnato con `cache_control` in modo che la conversazione possa essere memorizzata nella cache in modo incrementale. Il sistema cerca e usa automaticamente la sequenza di blocchi più lunga precedentemente memorizzata nella cache per i messaggi successivi. In altre parole, i blocchi che in precedenza erano contrassegnati con un blocco `cache_control` in seguito non vengono più contrassegnati, ma verranno comunque considerati un cache hit (e anche un aggiornamento della cache!) se vengono colpiti entro 5 minuti.
Inoltre, nota che il parametro `cache_control` è posizionato sul messaggio di sistema. Questo serve a garantire che, se viene rimosso dalla cache (dopo non essere stato usato per più di 5 minuti), venga aggiunto nuovamente alla cache alla richiesta successiva.
Questo approccio è utile per mantenere il contesto nelle conversazioni in corso senza elaborare ripetutamente le stesse informazioni.
Quando è configurato correttamente, dovresti vedere quanto segue nella risposta di utilizzo di ogni richiesta:
* `input_tokens`: numero di token nel nuovo messaggio dell'utente (sarà minimo)
* `cache_creation_input_tokens`: numero di token nei nuovi turni dell'assistente e dell'utente
* `cache_read_input_tokens`: numero di token nella conversazione fino al turno precedente
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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"}
}
]
}
]
}'
```
```bash CLI
ant messages create --transform usage <<'YAML'
model: claude-opus-5-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.
# Instructions
- Always search for relevant documents before answering
- Provide citations for your sources
- Be objective and accurate in your responses
- If multiple documents contain relevant information, synthesize them
- Acknowledge when information is not available in the knowledge base
cache_control:
type: ephemeral
- type: text
text: |-
# Knowledge Base Context
Here are the relevant documents for this conversation:
## Document 1: Solar System Overview
The solar system consists of the Sun and all objects that orbit it...
## Document 2: Planetary Characteristics
Each planet has unique features. Mercury is the smallest planet...
## Document 3: Mars Exploration
Mars has been a target of exploration for decades...
[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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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"},
}
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools =
[
new ToolUnion(new Tool()
{
Name = "search_documents",
Description = "Search through the knowledge base",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Search query" }),
},
Required = ["query"],
},
}),
new ToolUnion(new Tool()
{
Name = "get_document",
Description = "Retrieve a specific document by ID",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["doc_id"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Document ID" }),
},
Required = ["doc_id"],
},
CacheControl = new CacheControlEphemeral(),
}),
],
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
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",
CacheControl = new CacheControlEphemeral(),
},
new TextBlockParam()
{
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...]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new() { Role = Role.User, Content = "Can you search for information about Mars rovers?" },
new()
{
Role = Role.Assistant,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new ToolUseBlockParam()
{
ID = "tool_1",
Name = "search_documents",
Input = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement("Mars rovers"),
},
}),
}),
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = "tool_1",
Content = "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}),
}),
},
new()
{
Role = Role.Assistant,
Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
},
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = "Yes, please tell me about the Perseverance rover specifically.",
CacheControl = new CacheControlEphemeral(),
}),
}),
},
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "search_documents",
Description: anthropic.String("Search through the knowledge base"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"query": map[string]any{
"type": "string",
"description": "Search query",
},
},
Required: []string{"query"},
},
}},
{OfTool: &anthropic.ToolParam{
Name: "get_document",
Description: anthropic.String("Retrieve a specific document by ID"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"doc_id": map[string]any{
"type": "string",
"description": "Document ID",
},
},
Required: []string{"doc_id"},
},
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
System: []anthropic.TextBlockParam{
{
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",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
{
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...]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),
anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(
"tool_1",
map[string]any{"query": "Mars rovers"},
"search_documents",
)),
anthropic.NewUserMessage(anthropic.NewToolResultBlock(
"tool_1",
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
false,
)),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),
{
Role: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
{OfText: &anthropic.TextBlockParam{
Text: "Yes, please tell me about the Perseverance rover specifically.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
public class MultipleCacheBreakpointsExample {
public static void main(String[] args) {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Schema dello strumento di ricerca
InputSchema searchSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("query", Map.of("type", "string", "description", "Search query"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.build();
// Schema dello strumento per ottenere documenti
InputSchema getDocSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("doc_id", Map.of("type", "string", "description", "Document ID"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("doc_id")))
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
// Strumenti con cache control sull'ultimo
.addTool(
Tool.builder()
.name("search_documents")
.description("Search through the knowledge base")
.inputSchema(searchSchema)
.build()
)
.addTool(
Tool.builder()
.name("get_document")
.description("Retrieve a specific document by ID")
.inputSchema(getDocSchema)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
// Prompt di sistema con cache control separato su istruzioni e contesto
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.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"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build(),
TextBlockParam.builder()
.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...]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
// Cronologia della conversazione
.addUserMessage("Can you search for information about Mars rovers?")
.addAssistantMessageOfBlockParams(
List.of(
ContentBlockParam.ofToolUse(
ToolUseBlockParam.builder()
.id("tool_1")
.name("search_documents")
.input(JsonValue.from(Map.of("query", "Mars rovers")))
.build()
)
)
)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId("tool_1")
.content(
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
)
.build()
)
)
)
.addAssistantMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text(
"I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
)
.build()
)
)
)
.addUserMessageOfBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Yes, please tell me about the Perseverance rover specifically.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
System.out.println(message.usage());
}
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
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']
]
]
]
],
model: 'claude-opus-5-5',
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']
]
],
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']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-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" }
}
]
}
]
)
puts message.usage
```
Questo esempio completo dimostra come usare tutti e 4 i "cache breakpoint" (punti di interruzione della cache) disponibili per ottimizzare diverse parti del tuo prompt:
1. **Cache degli strumenti** (breakpoint della cache 1): il parametro `cache_control` sull'ultima definizione di strumento memorizza nella cache tutte le definizioni degli strumenti.
2. **Cache delle istruzioni riutilizzabili** (breakpoint della cache 2): le istruzioni statiche nel prompt di sistema vengono memorizzate nella cache separatamente. Queste istruzioni cambiano raramente tra una richiesta e l'altra.
3. **Cache del contesto RAG** (breakpoint della cache 3): i documenti della knowledge base vengono memorizzati nella cache in modo indipendente, consentendoti di aggiornare i documenti RAG senza invalidare la cache degli strumenti o delle istruzioni.
4. **Cache della cronologia della conversazione** (breakpoint della cache 4): il messaggio finale dell'utente è contrassegnato con `cache_control` per abilitare la memorizzazione incrementale nella cache della conversazione man mano che procede.
Questo approccio offre la massima flessibilità:
* Se aggiungi un nuovo turno alla conversazione senza modificare il contenuto precedente, tutti e quattro i segmenti della cache vengono riutilizzati
* Se aggiorni i documenti RAG ma mantieni gli stessi strumenti e istruzioni, i primi due segmenti della cache vengono riutilizzati
* Se modifichi la conversazione ma mantieni gli stessi strumenti, istruzioni e documenti, i primi tre segmenti vengono riutilizzati
* Le modifiche in corrispondenza di qualsiasi breakpoint invalidano quel segmento e tutto ciò che segue, mentre i segmenti precedenti memorizzati nella cache restano validi
Per la prima richiesta:
* `input_tokens`: minimo (token dopo l'ultimo breakpoint della cache, vicino a 0 in questo esempio)
* `cache_creation_input_tokens`: token in tutti i segmenti memorizzati nella cache (strumenti + istruzioni + documenti RAG + cronologia della conversazione)
* `cache_read_input_tokens`: 0 (nessun cache hit)
Per le richieste successive con solo un nuovo messaggio dell'utente (e il quarto breakpoint spostato su quel nuovo messaggio finale, come nell'esempio):
* `input_tokens`: minimo (token dopo l'ultimo breakpoint della cache, vicino a 0 in questo esempio)
* `cache_creation_input_tokens`: token nel nuovo messaggio dell'utente e nel turno precedente dell'assistente (il nuovo segmento di conversazione che viene memorizzato nella cache)
* `cache_read_input_tokens`: tutti i token precedentemente memorizzati nella cache (strumenti + istruzioni + documenti RAG + conversazione precedente)
Questo schema è particolarmente efficace per:
* Applicazioni RAG con contesti documentali ampi
* Sistemi di agenti che usano più strumenti
* Conversazioni di lunga durata che devono mantenere il contesto
* Applicazioni che devono ottimizzare diverse parti del prompt in modo indipendente
## Conservazione dei dati
La cache dei prompt (sia automatica sia esplicita) è idonea per ZDR. Anthropic non memorizza il testo grezzo dei tuoi prompt né delle risposte di Claude.
Le rappresentazioni della cache KV (chiave-valore) e gli hash crittografici del contenuto memorizzato nella cache sono conservati solo in memoria e non vengono archiviati in modo persistente. Le voci della cache hanno una durata minima di 5 minuti (standard) o 1 ora (estesa), dopo la quale vengono eliminate tempestivamente, anche se non immediatamente. Le voci della cache sono isolate tra organizzazioni e, sulla Claude API, su Claude Platform on AWS e su Microsoft Foundry, tra i workspace all'interno di un'organizzazione.
Per l'idoneità ZDR di tutte le funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
***
## Domande frequenti
**Nella maggior parte dei casi, è sufficiente un singolo breakpoint della cache alla fine del tuo contenuto statico.** Le scritture nella cache avvengono solo in corrispondenza del blocco che contrassegni. Posizionalo sull'ultimo blocco che rimane identico tra le richieste, e ogni richiesta successiva leggerà quella stessa voce. Se un blocco successivo varia a ogni richiesta (un timestamp, il messaggio in arrivo), mantieni il breakpoint prima di esso, sull'ultimo blocco stabile.
Hai bisogno di più breakpoint solo se:
* Una conversazione in crescita sposta il tuo breakpoint di 20 o più blocchi oltre l'ultima scrittura nella cache, portando la voce precedente fuori dalla finestra di ricerca a ritroso
* Vuoi memorizzare nella cache in modo indipendente sezioni che si aggiornano con frequenze diverse
* Hai bisogno di un controllo esplicito su ciò che viene memorizzato nella cache per ottimizzare i costi
Esempio: se hai istruzioni di sistema (che cambiano raramente) e un contesto RAG (che cambia ogni giorno), potresti usare due breakpoint per memorizzarli nella cache separatamente.
No, i breakpoint della cache in sé sono gratuiti. Paghi solo per:
* La scrittura di contenuti nella cache (25% in più rispetto ai token di input base per il TTL di 5 minuti)
* La lettura dalla cache (una frazione del prezzo base dei token di input, vedi [Prezzi](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#pricing))
* I normali token di input per i contenuti non memorizzati nella cache
Il numero di breakpoint non influisce sui prezzi; conta solo la quantità di contenuto memorizzato nella cache e letto.
La risposta di utilizzo include tre campi separati per i token di input che insieme rappresentano il tuo input totale:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
* `cache_read_input_tokens`: token recuperati dalla cache (tutto ciò che precede i breakpoint della cache ed è stato memorizzato nella cache)
* `cache_creation_input_tokens`: nuovi token scritti nella cache (in corrispondenza dei breakpoint della cache)
* `input_tokens`: token **dopo l'ultimo breakpoint della cache** che non sono memorizzati nella cache
**Importante:** `input_tokens` NON rappresenta tutti i token di input, ma solo la parte successiva al tuo ultimo breakpoint della cache. Se hai contenuti memorizzati nella cache, `input_tokens` sarà in genere molto più piccolo del tuo input totale.
**Esempio:** con un documento da 200k token memorizzato nella cache e una domanda dell'utente da 50 token:
* `cache_read_input_tokens`: 200.000
* `cache_creation_input_tokens`: 0
* `input_tokens`: 50
* **Totale:** 200.050 token
Questa suddivisione è fondamentale per comprendere sia i tuoi costi sia l'utilizzo del "rate limit" (limite di velocità). Consulta [Monitorare le prestazioni della cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#tracking-cache-performance) per maggiori dettagli.
La durata minima predefinita della cache (TTL) è di 5 minuti. Questa durata viene rinnovata ogni volta che il contenuto memorizzato nella cache viene utilizzato.
Se ritieni che 5 minuti siano troppo pochi, Anthropic offre anche un [TTL della cache di 1 ora](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#1-hour-cache-duration).
La durata viene misurata dall'inizio della richiesta che scrive o legge la voce della cache, non dalla fine della sua risposta. Il tempo impiegato per generare una risposta viene conteggiato nella durata, quindi la finestra entro cui una richiesta successiva può riutilizzare la cache è pari alla durata meno il tempo di generazione.
Se le tue richieste producono risposte lunghe e la richiesta successiva potrebbe non iniziare prima che la durata sia trascorsa, usa il [TTL della cache di 1 ora](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#1-hour-cache-duration).
Puoi definire fino a 4 breakpoint della cache (usando i parametri `cache_control`) nel tuo prompt.
La cache dei prompt è supportata su tutti i [modelli Claude attivi](https://platform.claude.com/docs/it/models/overview).
La modifica dei parametri del "thinking" (ragionamento) (cambio di modalità o modifica del budget nella modalità estesa) invalida i prefissi dei messaggi memorizzati nella cache e può invalidare anche i prompt di sistema e gli strumenti memorizzati nella cache, perché la configurazione del ragionamento viene inserita nel prompt. Il valore [`output_config.effort`](https://platform.claude.com/docs/it/build-with-claude/effort) si comporta allo stesso modo.
Per maggiori dettagli sull'invalidazione della cache, consulta [Cosa invalida la cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#what-invalidates-the-cache).
Per saperne di più sul ragionamento, inclusa la sua interazione con l'uso degli strumenti e la cache dei prompt, consulta [Ragionamento e cache dei prompt](https://platform.claude.com/docs/it/build-with-claude/thinking#thinking-and-prompt-caching).
Il modo più semplice è aggiungere `"cache_control": {"type": "ephemeral"}` al livello superiore del corpo della tua richiesta ([cache automatica](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#automatic-caching)). In alternativa, includi almeno un breakpoint `cache_control` su singoli blocchi di contenuto ([breakpoint della cache espliciti](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#explicit-cache-breakpoints)).
Sì, la cache dei prompt può essere usata insieme ad altre funzionalità dell'API come l'uso degli strumenti e le capacità di visione. Tuttavia, modificare la presenza di immagini in un prompt o cambiare le impostazioni dell'uso degli strumenti invaliderà la cache.
Per maggiori dettagli sull'invalidazione della cache, consulta [Cosa invalida la cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#what-invalidates-the-cache).
La cache dei prompt introduce una nuova struttura di prezzi in cui le scritture nella cache da 5 minuti costano il 25% in più rispetto ai token di input base, le scritture nella cache da 1 ora costano 2 volte i token di input base e i cache hit costano una frazione del prezzo base dei token di input (vedi [Prezzi](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#pricing) per il moltiplicatore di ciascun modello).
Attualmente non è possibile svuotare manualmente la cache. I prefissi memorizzati nella cache scadono automaticamente dopo un minimo di 5 minuti di inattività.
Puoi monitorare le prestazioni della cache usando i campi `cache_creation_input_tokens` e `cache_read_input_tokens` nella risposta dell'API.
Consulta [Cosa invalida la cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#what-invalidates-the-cache) per maggiori dettagli sull'invalidazione della cache, incluso un elenco delle modifiche che richiedono la creazione di una nuova voce della cache.
La cache dei prompt è progettata con solide misure di privacy e separazione dei dati:
1. Le chiavi della cache vengono generate usando un hash crittografico dei prompt fino al punto di controllo della cache. Ciò significa che solo le richieste con prompt identici possono accedere a una specifica cache.
2. Sulla Claude API, su Claude Platform on AWS e su Microsoft Foundry, le cache sono isolate per workspace all'interno di un'organizzazione. Su Bedrock e Google Cloud, le cache sono isolate per organizzazione. In ogni caso, le cache non vengono mai condivise tra organizzazioni, nemmeno per prompt identici. Consulta [Archiviazione e condivisione della cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#cache-storage-and-sharing) per i dettagli.
3. Il meccanismo di cache è progettato per mantenere l'integrità e la privacy di ogni conversazione o contesto univoco.
4. È sicuro usare `cache_control` in qualsiasi punto dei tuoi prompt. Affinché la cache produca letture, posiziona il breakpoint alla fine di un prefisso stabile: posizionarlo su un blocco che cambia a ogni richiesta (come un timestamp o l'input arbitrario dell'utente) scrive ogni volta una nuova voce e non produce mai hit.
Queste misure garantiscono che la cache dei prompt mantenga la privacy e la sicurezza dei dati offrendo al contempo vantaggi in termini di prestazioni.
Sì, è possibile usare la cache dei prompt con le tue richieste alla [Batches API](https://platform.claude.com/docs/it/build-with-claude/batch-processing). Tuttavia, poiché le richieste batch asincrone possono essere elaborate in parallelo e in qualsiasi ordine, i cache hit vengono forniti secondo il principio del massimo impegno.
La [cache da 1 ora](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#1-hour-cache-duration) può aiutarti a migliorare i tuoi cache hit. Il modo più conveniente per usarla è il seguente:
* Raccogli un insieme di richieste di messaggi che hanno un prefisso condiviso.
* Invia una richiesta batch con una singola richiesta che contiene questo prefisso condiviso e un blocco di cache da 1 ora. Questo scrive il prefisso nella cache da 1 ora.
* Non appena questa è completata, invia le restanti richieste. Dovrai monitorare il job per sapere quando viene completato.
In genere questo approccio è migliore rispetto all'uso della cache da 5 minuti, perché è comune che le richieste batch impieghino tra 5 minuti e 1 ora per essere completate.
Questo errore compare in genere quando hai aggiornato il tuo SDK o stai usando esempi di codice obsoleti. La cache dei prompt non richiede più il prefisso beta. Invece di:
```python Python
client.beta.prompt_caching.messages.create(**params)
```
Usa:
```python Python
client.messages.create(**params)
```
Questo errore compare in genere quando hai aggiornato il tuo SDK o stai usando esempi di codice obsoleti. La cache dei prompt non richiede più il prefisso beta. Invece di:
```typescript TypeScript
client.beta.promptCaching.messages.create(/* ... */);
```
Usa:
```typescript
client.messages.create(/* ... */);
```