Prompt Caching in Claude API: Risparmia il 90% dei Token
Cos’è il Prompt Caching e Perché Cambia Tutto
Se usi Claude API in produzione, probabilmente stai pagando troppo. Non perché Claude sia caro, ma perché stai re-inviando gli stessi token di contesto ad ogni chiamata. Il prompt caching di Anthropic risolve questo problema in modo elegante: i token in cache costano il 90% in meno e vengono serviti 5 volte più velocemente.
In questo articolo vediamo come funziona il caching, quando usarlo, e come strutturare i tuoi prompt per massimizzare il risparmio. Con esempi pratici in Python e TypeScript.
Come Funziona il Cache di Claude
Il prompt caching di Claude opera a livello di prefisso: quando invii un messaggio, Anthropic memorizza in cache la porzione iniziale del prompt per 5 minuti (o 1 ora con TTL esteso). Le chiamate successive che iniziano con lo stesso prefisso non re-processano quei token.
I requisiti minimi per attivare il cache sono:
- claude-3-5-sonnet: almeno 1.024 token nel prefisso
- claude-3-haiku: almeno 2.048 token nel prefisso
- claude-3-opus: almeno 1.024 token nel prefisso
Struttura del Prompt con Cache Control
Per attivare il caching devi aggiungere cache_control ai blocchi di contenuto che vuoi mettere in cache. Ecco la struttura base:
import anthropic
client = anthropic.Anthropic()
# System prompt lungo da cachare (es. documentazione, contesto)
system_context = "Sei un assistente esperto. [... 2000+ parole di contesto invariato ...]"
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
system=[
{
"type": "text",
"text": system_context,
"cache_control": {"type": "ephemeral"} # Marca come cachable
}
],
messages=[
{"role": "user", "content": "Analizza il Q3 2026 di Apple"}
]
)
# Controlla i token usati
usage = response.usage
print(f"Input tokens: {usage.input_tokens}")
print(f"Cache creation: {usage.cache_creation_input_tokens}")
print(f"Cache read: {usage.cache_read_input_tokens}")
Al primo invio vedrai cache_creation_input_tokens popolato: stai pagando per creare la cache. Dalla seconda chiamata in poi, vedrai cache_read_input_tokens: questi token costano il 90% in meno.
Caso d’Uso 1: Chatbot con Documentazione Lunga
Il caso d’uso classico è un chatbot che risponde domande su documentazione interna. La documentazione non cambia tra una domanda e l’altra — perché riprocessarla ogni volta?
import anthropic
from pathlib import Path
client = anthropic.Anthropic()
docs = Path("docs/manuale-prodotto.md").read_text()
def ask_about_docs(question: str) -> str:
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=2048,
system=[
{
"type": "text",
"text": f"Sei un assistente che risponde domande sul manuale:
{docs}",
"cache_control": {"type": "ephemeral"}
}
],
messages=[{"role": "user", "content": question}]
)
return response.content[0].text
# Prima chiamata: crea cache (~$0.03 per 10k token)
answer1 = ask_about_docs("Come si installa il prodotto?")
# Seconda chiamata: legge da cache (~$0.003) — 10x più economico
answer2 = ask_about_docs("Quali sono i requisiti di sistema?")
Caso d’Uso 2: Tool Definitions Statici
Un altro scenario comune è un agente con molti tool. I tool definitions sono spesso 2k-5k token e non cambiano mai tra le chiamate:
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
// Tool definitions statici: marcati per il cache
const tools: Anthropic.Tool[] = [
{
name: "search_docs",
description: "Cerca nella documentazione interna",
input_schema: {
type: "object",
properties: { query: { type: "string" } },
required: ["query"]
}
},
// ... altri 20+ tool definitions
];
async function runAgent(userMessage: string) {
const response = await client.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1024,
tools,
// Aggiungi cache_control all'ultimo tool definition
// (Claude cacia tutto il prefisso fino al marker)
messages: [{ role: "user", content: userMessage }],
// system con cache_control per i tool definitions statici
system: [
{
type: "text",
text: "Sei un agente con accesso a strumenti interni.",
cache_control: { type: "ephemeral" }
}
]
});
return response;
}
Calcolo del Risparmio Reale
Vediamo i numeri concreti. Prendiamo un chatbot con 10.000 token di contesto fisso e 100 chiamate al giorno per 30 giorni:
# Prezzi claude-3-5-sonnet (per milione di token)
PRICE_INPUT_NORMAL = 3.00 # $3.00/M token
PRICE_CACHE_CREATE = 3.75 # $3.75/M token (25% in piu per creare)
PRICE_CACHE_READ = 0.30 # $0.30/M token (90% in meno per leggere)
context_tokens = 10_000
calls_per_day = 100
days = 30
# Senza caching
cost_no_cache = (context_tokens / 1_000_000) * PRICE_INPUT_NORMAL * calls_per_day * days
print(f"Senza caching: ${cost_no_cache:.2f}/mese") # $90.00
# Con caching (1 creazione + 99 letture per giorno)
cache_creates = 1 * days
cache_reads = 99 * days
cost_with_cache = (
(context_tokens / 1_000_000) * PRICE_CACHE_CREATE * cache_creates +
(context_tokens / 1_000_000) * PRICE_CACHE_READ * cache_reads
)
print(f"Con caching: ${cost_with_cache:.2f}/mese") # ~$9.75
print(f"Risparmio: {(1 - cost_with_cache/cost_no_cache)*100:.0f}%") # ~89%
Con 100 chiamate/giorno e 10k token di contesto fisso, il risparmio mensile è di circa $80 — quasi il 90%. In scenari enterprise con milioni di chiamate, il risparmio diventa enorme.
Best Practice e Limitazioni
- Posiziona il contenuto stabile all’inizio: il caching funziona sul prefisso. System prompt, documentazione, esempi sempre prima del messaggio utente
- TTL di 5 minuti (default): se le chiamate sono distanziate di più, la cache scade. Usa warm-up periodici o TTL esteso (1 ora, su richiesta)
- Non più di 4 checkpoint: Claude supporta al massimo 4 marker
cache_controlper request - Il cache è per account: tutti gli utenti del sistema condividono la stessa cache — attenzione ai dati sensibili nel prefisso
FAQ e Domande Frequenti
Il prompt caching funziona con tutti i modelli Claude?
No. Il caching è disponibile su Claude 3.5 Sonnet, Claude 3 Haiku e Claude 3 Opus. Non è disponibile su Claude 3.5 Haiku né sui modelli legacy Claude 2.x. Verifica sempre la documentazione Anthropic per la lista aggiornata dei modelli supportati.
Cosa succede se il contenuto cachato cambia leggermente?
Se cambia anche un solo carattere nel prefisso cachato, la cache non viene riutilizzata e viene creata una nuova voce. È fondamentale separare il contenuto statico da quello dinamico. Anche i tool definitions si prestano bene al caching se rimangono invariati tra le chiamate.
Il caching è compatibile con lo streaming?
Sì, il prompt caching funziona perfettamente con le risposte in streaming. Puoi usare client.messages.stream() normalmente — il caching opera a livello di input token, prima che la risposta venga generata.
Quanto costa creare la cache vs leggerla?
La creazione costa il 25% in più dei token normali (una tantum). La lettura costa il 90% in meno. Il break-even è già dalla seconda chiamata: paghi 1.25x alla prima, poi 0.1x per ogni successiva. Con anche solo 10 chiamate per sessione, risparmi circa l’80% sul contesto fisso.
Conclusione
Il prompt caching di Claude API è una delle ottimizzazioni più impattanti che puoi implementare oggi. Se hai un sistema che invia lo stesso contesto di base ad ogni chiamata — documentazione, system prompt lungo, esempi few-shot — stai bruciando denaro senza caching. L’implementazione richiede 5 minuti: aggiungi cache_control: {"type": "ephemeral"} al blocco giusto e il gioco è fatto.
Per approfondire le altre ottimizzazioni dell’API Claude, leggi la guida su Claude API Tool Use e Agenti e il confronto tra i principali LLM del 2026.
💡 Pro tip: Monitora sempre
cache_read_input_tokensnei log di produzione. Se vedi molticache_creation_input_tokense pochicache_read_input_tokens, la cache scade prima di essere riutilizzata — aumenta la frequenza delle chiamate o usa il TTL esteso.🔧 Tool: Usa l’SDK ufficiale Anthropic per Python e TypeScript — il supporto al caching è built-in senza dipendenze extra.
🎯 Nota: Con Claude 3.5 Sonnet il caching si attiva quando il prefisso supera 1.024 token. Per contesti più piccoli, considera Claude Haiku che è già più economico come base.
