Prompt caching su Claude: come tagliare i costi dell'API fino al 90%

Se hai un'app che chiama Claude su un prompt lungo e ripetuto – un assistente legale che lavora su un manuale, un copilot di codice che vede sempre la stessa repo, un tutor scolastico che ragiona sullo stesso libro – stai pagando per token di input tutte le volte, anche quando il modello potrebbe riconoscere che e' la stessa roba di prima. Il prompt caching di Anthropic risolve esattamente questo problema: marchiamo un pezzo del prompt come "cacheabile", lo paghiamo una volta a un prezzo leggermente piu' alto del normale, e nelle chiamate successive entro la finestra di TTL paghiamo solo il 10% del costo di lettura. Su carichi reali, il risparmio puo' arrivare al 90%.

Questa guida e' pensata per sviluppatori italiani che vogliono mettere il caching in produzione su Claude Sonnet/Opus oggi, con esempi Python e curl che funzionano davvero.

A chi serve davvero il prompt caching

Il caching brilla in tre scenari precisi:

• RAG con un corpus stabile: hai una base documentale di 20-200 mila token (manuali, contratti, regolamenti) che viene riusata su molte query.
• Agente di coding: stesso codebase, prompt di sistema e tool definition lunghi, ad ogni step.
• Few-shot con esempi pesanti: 10-50 esempi di input/output che servono in ogni chiamata, ma cambiano la sola query utente.

Non serve, invece, se ogni prompt e' diverso (sintesi una-shot di articoli sempre nuovi) o se la parte stabile e' sotto i 1024 token (Sonnet) o 2048 (Haiku) – cioe' la soglia minima sotto cui Anthropic non scrive nulla in cache.

Modelli, costi e finestre temporali

Il caching e' supportato sui modelli attuali della famiglia Claude: Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 4.5. Le finestre temporali disponibili sono due.

• 5 minuti (standard): TTL breve, ideale per sessioni interattive (chat, agente che fa molte chiamate ravvicinate).
• 1 ora (extended): TTL lungo, utile per batch e per agenti che lavorano su task lunghi.

Sui prezzi, la regola pratica e': scrivere in cache costa il 125% di un token di input normale; leggere dalla cache costa il 10%. Quindi conviene se il numero di letture e' superiore a una.

Anatomia di una richiesta con cache_control

Il caching si attiva mettendo il campo cache_control dentro un blocco di contenuto del prompt. Tutto cio' che sta fino a quel blocco compreso – tools, system, messages – viene cacheato. Puoi mettere fino a quattro breakpoint per separare sezioni cacheate diversamente.

Ecco un esempio minimo in curl con un manuale di prodotto fisso, che il modello deve consultare per rispondere a domande dei clienti.

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-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Sei l assistente clienti di Acme. Rispondi solo in base al manuale."
      },
      {
        "type": "text",
        "text": "",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "Come si resetta il dispositivo X-200?"}
    ]
  }'

Il blocco del manuale ha cache_control impostato a ephemeral (la default a 5 minuti). La prima chiamata costa di piu', le successive 60 con la stessa parte cacheata costano un decimo per la parte di sistema.

Stessa cosa in Python: l'esempio completo

In Python l'SDK ufficiale e' anthropic. Installazione:

pip install anthropic

Codice:

import anthropic

client = anthropic.Anthropic()

MANUALE = open("manuale_acme.txt").read()

def chiedi(domanda: str):
    risposta = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        system=[
            {"type": "text", "text": "Sei l assistente clienti di Acme. Rispondi solo in base al manuale."},
            {
                "type": "text",
                "text": MANUALE,
                "cache_control": {"type": "ephemeral"}
            },
        ],
        messages=[{"role": "user", "content": domanda}],
    )
    uso = risposta.usage
    print(f"create={uso.cache_creation_input_tokens}, read={uso.cache_read_input_tokens}, normali={uso.input_tokens}")
    return risposta.content[0].text

print(chiedi("Come si resetta l X-200?"))
print(chiedi("Quanto dura la batteria del Y-100?"))
print(chiedi("Qual e la garanzia?"))

Aprendo i log noterai che, dalla seconda chiamata, cache_creation_input_tokens e' 0 e cache_read_input_tokens contiene il numero di token serviti dalla cache.

Dove mettere il breakpoint: regole pratiche

Il punto piu' delicato e': fino a dove faccio finire il caching? La regola di base e' "tutto cio' che cambia raramente prima del breakpoint, tutto cio' che cambia spesso dopo". Ordina sempre cosi':

1. Tools: definizioni stabili di funzioni che il modello puo' chiamare.
2. System: istruzioni generali e contesto lungo (manuale, codebase).
3. Few-shot examples nel messages: esempi pesanti che ricorrono.
4. Query utente: la sola parte che cambia ogni volta.

Per il caso classico RAG + cronologia chat e' utile mettere due breakpoint: uno alla fine del system (manuale stabile), uno alla fine della cronologia (per cacheare anche i turni precedenti durante una conversazione lunga).

Misurare il risparmio: cosa controllare nei log

Ogni risposta dell'API contiene un oggetto usage con campi cruciali. Loggali tutti.

• input_tokens: token di input non cacheati.
• cache_creation_input_tokens: token scritti in cache in questa chiamata (pagati 125%).
• cache_read_input_tokens: token letti dalla cache (pagati 10%).
• output_tokens: token generati.

Una regola operativa: se sommi 100 chiamate e cache_read_input_tokens / (cache_read_input_tokens + input_tokens) e' > 70%, sei dove vuoi.

Varianti utili

• Cache extended a 1 ora: aggiungi l'header anthropic-beta: extended-cache-ttl-2025-04-11 e usa cache_control: {"type": "ephemeral", "ttl": "1h"}. Utile in batch.
• Cache di tools pesanti: se hai 30 funzioni con schemi JSON lunghi, metti cache_control all'ultimo tool nell'array. Il modello cachera' tutta la sezione tools.
• RAG con piu' documenti: spezza in blocchi separati e metti cache_control solo sui blocchi che riusi spesso, lasciando quelli rari fuori dalla cache.

Errori comuni e come risolverli

• cache_creation e cache_read entrambi a zero: il blocco e' sotto la soglia minima (1024 token su Sonnet/Opus). Soluzione: accorpa contenuti, o non cachare.
• La cache "non si attiva" dopo qualche minuto: hai superato i 5 minuti di TTL. Soluzione: usa extended (1h) o tieni in piedi un "ping" periodico.
• Errore "too many cache breakpoints": stai usando piu' di 4 breakpoint. Riduci.
• Costo medio aumentato: stai cacheando una sezione che cambia ad ogni richiesta. Sposta il breakpoint piu' indietro.

Alternative e quando NON usare il caching

Il caching ha senso quando la parte stabile e' grande e riusata. Se invece il tuo carico e' fatto di prompt corti e unici (es. classificazione di tweet), il caching non aiuta: ogni chiamata e' una cache miss. In quei casi conviene piuttosto:

• Andare su Claude Haiku 4.5, piu' economico e adatto a chiamate brevi.
• Usare la Batch API, che taglia il 50% sui task non urgenti.
• Far girare modelli open in locale con Ollama o vLLM per i carichi ad altissimo volume.

Per chi sviluppa applicazioni AI native su Claude, comunque, il prompt caching e' oggi la singola ottimizzazione con il miglior rapporto sforzo/risparmio. Aggiungere quattro righe di codice e dimezzare la bolletta mensile e' tutto cio' che chiede.

Come proseguire

Per andare oltre, ti consiglio tre passi: leggere la documentazione ufficiale aggiornata su platform.claude.com; clonare il notebook del cookbook Anthropic e farlo girare sui tuoi dati; misurare a 7 giorni la riduzione di spesa nel console di Anthropic, sezione Usage. In molti workload reali la curva di costo scende del 70-90% gia' dal secondo giorno.