Cos'è il prompt caching? Come viene riutilizzato un prompt ripetuto

Il prompt caching significa che l'API ricorda l'inizio della tua richiesta e lo riutilizza la volta successiva in cui invii lo stesso inizio. Invii comunque il testo completo a ogni chiamata, ma il provider può saltare il lavoro di rilettura della parte ripetuta, e alcuni provider fatturano quella parte a una tariffa inferiore. Funziona solo sull'inizio della richiesta, e solo se quell'inizio è identico.

Il bot di supporto che continua a rileggere la stessa pagina#

Immagina di gestire un bot di supporto con 2.000 ticket al giorno. Ogni richiesta inizia con gli stessi 3.000 token: tono di voce, regole sui rimborsi, politica di spedizione. Dopo arriva il messaggio del cliente su una riga, qualcosa come "Dov'è il mio ordine?" (Se i token ti sono ancora poco chiari, inizia da cos'è un token.)

Senza caching, il provider rilegge tutti i 3.000 token di regole per il ticket numero 1, il ticket numero 2 e il ticket numero 2.000. Stessa pagina, letta 2.000 volte. Con il caching, la prima richiesta paga il prezzo pieno della lettura, e le richieste successive che iniziano con lo stesso testo possono riutilizzare il lavoro.

La guida API di DeepSeek (verificata il 24 ottobre 2026) descrive esattamente questo: il context caching è attivo per impostazione predefinita, non richiede modifiche al codice, e una richiesta successiva con un prefisso sovrapposto conta come "cache hit". Viene messo in cache solo l'input. La risposta viene generata da zero ogni volta.

Cosa conta come "lo stesso": la regola del prefisso#

La cache confronta dal primo carattere in poi. Nel momento in cui la tua richiesta differisce da quella in cache, tutto ciò che segue quel punto è nuovo. Ecco perché l'ordine della tua richiesta conta più della sua lunghezza.

Ecco l'errore che uccide silenziosamente il caching. Uno sviluppatore vuole che il bot conosca l'ora e la mette in cima:

Current time: 14:03:22
You are a support assistant for a shop...
(3,000 tokens of rules)

L'ora cambia ogni secondo, quindi la primissima riga differisce a ogni richiesta, e nulla di ciò che segue può corrispondere. La soluzione è spostare alla fine tutto ciò che cambia:

You are a support assistant for a shop...
(3,000 tokens of rules)
Current time: 14:03:22
Customer: Where is my order?

Ora i 3.000 token di regole vengono per primi e restano identici. La stessa logica copre gli altri due casi comuni: una chat lunga reinvia tutta la sua cronologia a ogni turno, quindi i vecchi messaggi sono un inizio ripetuto già pronto (ne parliamo in perché una chat lunga costa di più), e un agente ripete le sue definizioni degli strumenti e le istruzioni a ogni passo.

Il caching è anche best-effort. DeepSeek afferma che la cache impiega qualche secondo per essere costruita, che un hit richiede una corrispondenza completa di un'unità di prefisso già in cache, che non c'è una percentuale di hit garantita, e che le cache inutilizzate vengono cancellate, di solito entro ore o giorni. Quindi una seconda richiesta inviata mezzo secondo dopo la prima potrebbe non fare ancora hit, e l'hit potrebbe coprire meno del tuo intero prefisso.

Come vederlo: i campi della cache in usage#

Non devi indovinare se ha funzionato. Ogni provider lo riporta nella parte usage della risposta, con i propri nomi di campo.

DeepSeek usa due campi:

• prompt_cache_hit_tokens — token di input trovati nella cache
• prompt_cache_miss_tokens — token di input che non lo erano

Supponiamo che il tuo primo ticket di supporto torni con prompt_cache_hit_tokens: 0 e prompt_cache_miss_tokens: 3200, e che un ticket un minuto dopo mostri prompt_cache_hit_tokens: 3000 e prompt_cache_miss_tokens: 200. I 3.000 token di regole sono stati riutilizzati; solo il nuovo messaggio del cliente e pochi token sono stati letti da zero. Se il numero di hit resta a zero a ogni chiamata, guarda l'inizio della tua richiesta: qualcosa lì sta cambiando.

Anthropic funziona diversamente, perché sei tu a marcare cosa mettere in cache. Aggiungi cache_control con tipo ephemeral alla richiesta o a un blocco di contenuto:

{
  "model": "your-model-id",
  "max_tokens": 300,
  "system": [
    {
      "type": "text",
      "text": "You are a support assistant... (long rules)",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "Where is my order?"}]
}

Secondo la documentazione sul prompt caching di Anthropic (verificata il 24 ottobre 2026), la risposta riporta tre numeri: cache_creation_input_tokens (scritti nella cache ora), cache_read_input_tokens (letti dalla cache) e input_tokens (ciò che è venuto dopo l'ultimo cache breakpoint). Supponiamo che la prima chiamata mostri cache_creation_input_tokens: 10000, cache_read_input_tokens: 0; la seconda mostri 0 e 10000. Si tratta di una scrittura in cache seguita da una lettura dalla cache.

C'è una trappola a schermo. I prompt più corti del minimo del modello (512, 1.024 o 4.096 token, a seconda del modello) vengono elaborati senza caching e senza errori. Vedrai zeri in entrambi i campi della cache e nessun avviso. La durata predefinita è di 5 minuti, rinnovata gratuitamente a ogni utilizzo; un ttl opzionale di 1h la mantiene più a lungo.

Cosa fa alla tua bolletta#

Il caching cambia il prezzo della parte ripetuta, quindi vale la pena fare due conti una volta. Anthropic elenca dei moltiplicatori sul prezzo base dell'input: una scrittura in cache con durata di 5 minuti costa 1,25×, una lettura costa 0,1× (0,05× per Opus 5.5 e Sonnet 5.5). Prendi un prefisso di 10.000 token riutilizzato in 20 richieste entro la finestra di 5 minuti, usando la lettura standard a 0,1×:

10.000 × 20 = 200.000 token al prezzo base senza caching

10.000 × 1,25 = 12.500 per la prima richiesta che scrive la cache

19 × 10.000 × 0,1 = 19.000 per le 19 richieste che la leggono

12.500 + 19.000 = 31.500 token-equivalenti con il caching

Quindi la parte ripetuta costa ben meno di un quinto dell'importo senza cache. Il rovescio della medaglia: se i 5 minuti trascorrono tra una richiesta e l'altra, la successiva riscrive la cache a 1,25×, e un prefisso usato raramente può finire per costare più che senza caching.

Ora il bot dell'inizio, come semplice baseline a prezzo pieno. 2.000 richieste al giorno, 3.000 token di input e circa 300 token di output ciascuna:

2.000 × 3.000 = 6.000.000 token di input al giorno

2.000 × 300 = 600.000 token di output al giorno

La tabella prezza il carico di lavoro di quel giorno su ogni modello CheapTokens disponibile accanto a OpenRouter:

DeepSeek-V4-Flash è più economico di OpenRouter in totale, contando insieme input e output, e il carico di lavoro ci sta comodamente: contesto da 380K e fino a 32.768 token di output per risposta. Questo è il costo a prezzo pieno del carico di lavoro: token di input × prezzo per token. Un lungo prefisso stabile è dove quella quota di input è più grande.

Provalo tu stesso in cinque minuti#

Il piano: invia due volte lo stesso lungo system prompt con domande diverse e guarda usage. Metti il tuo testo di regole in support_rules.txt (una o due pagine di testo bastano). L'endpoint è la CheapTokens API compatibile con OpenAI, e puoi prendere la chiave dal tuo account.

from openai import OpenAI

client = OpenAI(base_url='https://api.cheaptokens.dev/v1', api_key='YOUR_API_KEY')

SYSTEM = open('support_rules.txt').read()  # long, never changes

for question in ['Where is my order?', 'Can I change the address?']:
    r = client.chat.completions.create(
        model='deepseek-ai/DeepSeek-V4-Flash-0731',
        messages=[
            {'role': 'system', 'content': SYSTEM},
            {'role': 'user', 'content': question},
        ],
        max_tokens=300,
    )
    print(r.usage)

Cosa controllare nell'output: prompt_tokens ti dice quanto è grande la tua richiesta. Entrambe le richieste portano lo stesso testo SYSTEM, quindi gran parte di quel numero si ripete da una richiesta all'altra — all'incirca la dimensione del tuo file di regole. Quell'inizio ripetuto è la parte che un provider con caching, come l'API DeepSeek o Anthropic qui sopra, può riutilizzare. Ora un esercizio sull'ordine: aggiungi una riga con l'ora corrente (datetime.now()) in cima a SYSTEM ed esegui di nuovo. Le due richieste non condividono più un inizio, perché differiscono dalla primissima riga. Metti la stessa riga alla fine del prompt e l'inizio condiviso torna.

Una breve checklist per i tuoi prompt:

1. Testo stabile per primo: istruzioni, regole, definizioni degli strumenti, esempi.
2. Testo che cambia per ultimo: data, nome utente, ultimo messaggio.
3. Mantieni il prefisso identico byte per byte — conta anche uno spazio in più.
4. Controlla la dimensione minima del provider prima di chiederti perché nulla è in cache.
5. Guarda i campi usage dopo una modifica, non prima.

Per prezzare il tuo carico di lavoro, apri la pagina dei prezzi e inserisci le tue dimensioni di input e output, oppure parti dalla pagina DeepSeek. Una volta che la prima richiesta funziona, la stessa stima richiede un minuto per qualsiasi prompt tu scriva. Per quanto costano i due lati di una richiesta, vedi token di input vs output.