Cache KV e prompt cache: differenze e costi

Cache KV e prompt cache: la risposta breve

La cache KV e la prompt cache di un provider condividono una parola, ma quasi nient’altro. La cache KV è memoria di lavoro per singola richiesta. Risiede nella RAM o nella VRAM del server per tutta la durata di una richiesta e cresce con la lunghezza del contesto e con il numero di richieste eseguite contemporaneamente. Il prompt caching del provider è una funzione di fatturazione e latenza. Un prefisso stabile del prompt viene memorizzato sui server del provider e, quando lo invii di nuovo, ti viene addebitato a una tariffa ridotta.

La prima è memoria acquistata come hardware. La seconda è memoria gestita da un altro soggetto, che te ne addebita l’utilizzo.

La differenza pratica è più importante della definizione. Puoi esaurire la cache KV e, in tal caso, il modello non viene caricato oppure la richiesta viene rifiutata. Non puoi esaurire la prompt cache. Puoi solo non ottenere un hit della cache e, in quel caso, pagare silenziosamente il prezzo pieno.

Contenuto della cache KV e motivo della sua esistenza

Un modello transformer che genera il token numero 500 deve eseguire l’attenzione su tutti i 499 token precedenti. Per ciascuno di questi token, ogni layer richiede un vettore key e un vettore value. Ricalcolare tutti questi vettori per ogni nuovo token farebbe crescere il costo della generazione con il quadrato della lunghezza della sequenza. Per questo motivo, il runtime li conserva. Questa struttura è la cache KV (cache key/value).

La cache KV contiene lo stato della singola richiesta, perché viene costruita a partire dalla sequenza esatta di token di quella richiesta. Due utenti che inviano prompt diversi non possono condividerla, a meno che il runtime non supporti il prefix caching, una funzionalità separata descritta più avanti.

Il serving avviene in 2 fasi. Il prefill legge l’intero prompt e riempie la cache; questa fase è limitata dalla capacità di calcolo. Il decode genera un token alla volta e lo aggiunge alla cache; questa fase è limitata dalla larghezza di banda della memoria. Per questo motivo, l’elaborazione del prompt e la generazione dei token riportano velocità diverse quando misuri i token al secondo sul tuo server.

Quanta memoria utilizza la cache KV?

Non cercare una tabella del vendor. La dimensione si calcola con un'operazione aritmetica che puoi ripetere per qualsiasi modello:

bytes per token = 2 * layers * kv_heads * head_dim * bytes per element

Il 2 rappresenta la chiave e il valore. Tutti gli altri numeri derivano da config.json del modello, pubblicato nella pagina del modello su Hugging Face.

Prendi Llama 3.1 8B. La relativa configurazione indica num_hidden_layers 32 e num_key_value_heads 8. Il hidden_size pari a 4096, distribuito su 32 teste di attenzione, produce una dimensione della testa pari a 128. Con f16 ogni elemento occupa 2 byte:

2 * 32 * 8 * 128 * 2 = 131072 bytes = 128 KiB per token

Moltiplica questo valore per il contesto richiesto, quindi per il numero di richieste eseguite contemporaneamente.

[
  {
    "label": "2k context",
    "one_request_gib": 0.25,
    "four_requests_gib": 1
  },
  {
    "label": "8k context",
    "one_request_gib": 1,
    "four_requests_gib": 4
  },
  {
    "label": "32k context",
    "one_request_gib": 4,
    "four_requests_gib": 16
  },
  {
    "label": "128k context",
    "one_request_gib": 16,
    "four_requests_gib": 64
  }
]

Con un contesto di 8k, la cache è pari a 1 GiB per una richiesta. A 32k è pari a 4 GiB, un valore confrontabile con quello dei pesi a 4 bit. Al contesto massimo di 128k del modello, una richiesta utilizza 16 GiB, mentre quattro richieste che lo riempiono ciascuna utilizzano 64 GiB. I pesi non sono cambiati. È cambiata soltanto la cache.

La grouped query attention (GQA) incide molto su questo valore. Llama 3.1 8B ha 8 teste key/value che servono 32 teste query, quindi ogni coppia key/value memorizzata è condivisa da quattro teste query. Un modello in cui num_key_value_heads è uguale a num_attention_heads utilizza una cache quattro volte più grande a parità di numero di parametri. Controlla questo campo prima di presumere che due modelli 8B abbiano lo stesso costo di esecuzione.

Perché un modello che funzionava a 2k rifiuta di caricarsi a 32k

Il runtime riserva la KV cache quando carica il modello. La dimensiona in base alla lunghezza del contesto configurata, non in base al prompt che si invia effettivamente. La finestra di contesto predefinita di Ollama è di 4096 token. Se la si aumenta a 32k, si richiede un'allocazione aggiuntiva di 4 GiB prima che arrivi un solo token.

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

La stessa impostazione per sessione, dal prompt interattivo:

ollama run llama3.1:8b
/set parameter num_ctx 32768

L'errore varia a seconda dello stack. vLLM verifica i calcoli all'avvio e rifiuta di eseguire il modello:

ValueError: The model's max seq len (131072) is larger than the maximum number of tokens that can be stored in KV cache (78336). Try increasing `gpu_memory_utilization` or decreasing `max_model_len` when initializing the engine.

Su un VPS con sola CPU questo controllo non esiste, perché l'allocazione usa la normale RAM di sistema. Interviene invece l'out-of-memory killer del kernel, che termina il processo e lascia le prove nel ring buffer del kernel:

dmesg -T | grep -i "killed process"

Una riga che indica il processo di serving significa che il server ha richiesto più memoria di quella disponibile. La soluzione è usare un contesto più piccolo, non un file di swap più grande: una KV cache paginata su disco viene letta a ogni token generato, quindi la generazione rallenta fino a diventare inutilizzabile. La scelta di un valore adeguato è spiegata nella nostra guida a num_ctx e alla lunghezza del contesto in Ollama.

In che modo la concorrenza influisce sul numero

Ogni richiesta in corso utilizza una propria KV cache. È questo l’aspetto che spesso manca nei piani di capacità. Quattro utenti, ciascuno con un contesto di 32k, richiedono complessivamente 16 GiB, oltre allo spazio occupato dai pesi.

I runtime differiscono nel modo in cui gestiscono questo requisito. Ollama e llama.cpp riservano all’avvio del modello il contesto richiesto, quindi la memoria viene allocata anche se nessuno la utilizza. vLLM suddivide il pool in blocchi di dimensione fissa e li assegna man mano che la richiesta cresce, quindi una richiesta di 500 token utilizza soltanto lo spazio corrispondente a 500 token. In ogni caso, il pool è finito. Quando si esaurisce, le nuove richieste vengono accodate invece di essere eseguite. Gli effetti dell’accodamento sui tempi di risposta sono descritti in quanti utenti simultanei può gestire un LLM self-hosted.

Quattro modi per ridurre le dimensioni della cache KV

1. Ridurre la lunghezza del contesto. È l’intervento più efficace e, in genere, il meno costoso. La maggior parte dei carichi di lavoro di chat non si avvicina mai a 32k.
2. Quantizzare direttamente la cache. Il OLLAMA_KV_CACHE_TYPE di Ollama usa per impostazione predefinita f16 e accetta q8_0, che utilizza circa la metà della memoria, e q4_0, che ne utilizza circa un quarto. Gli equivalenti in llama.cpp sono -ctk q8_0 e -ctv q8_0.
3. Scegliere un modello con meno teste key/value o meno layer. Consultare config.json prima di scaricare 40 GB di pesi.
4. Gestire meno richieste contemporaneamente e accodare le rimanenti.

Con q4_0, il valore per Llama 3.1 8B scende da 128 KiB per token a circa 32 KiB. Di conseguenza, un contesto di 32k richiede circa 1 GiB invece di 4 GiB. Questo risparmio non è gratuito. Le chiavi e i valori vengono memorizzati con una precisione inferiore. Confrontare quindi l'output usando i propri prompt prima di adottare questa impostazione.

Cosa offre realmente il caching dei prompt del provider

Il caching dei prompt del provider è un prodotto diverso, con un'unità di addebito diversa. Si contrassegna un prefisso stabile, il provider lo memorizza e le chiamate successive che ripetono esattamente lo stesso prefisso vengono addebitate a una tariffa ridotta invece che al prezzo pieno dell'input.

I moltiplicatori pubblicati da Anthropic, ad agosto 2026, sono i seguenti: la scrittura di una cache di 5 minuti costa 1.25 volte il prezzo base dei token di input. La scrittura di una cache di 1 ora costa 2 volte tale prezzo, mentre la lettura dalla cache costa 0.1 volte. Applicando questi valori a un prompt di sistema di 20,000 token, il vantaggio diventa evidente.

[
  {
    "label": "No caching, every call",
    "billed_token_equivalents": "20,000"
  },
  {
    "label": "First call, 5 minute cache write",
    "billed_token_equivalents": "25,000"
  },
  {
    "label": "First call, 1 hour cache write",
    "billed_token_equivalents": "40,000"
  },
  {
    "label": "Every later call, cache hit",
    "billed_token_equivalents": "2,000"
  }
]

Leggetelo come un calcolo aritmetico. Il sovrapprezzo della scrittura di 5 minuti equivale a 5,000 token nella prima chiamata: 25,000 rispetto a 20,000 per l'invio senza caching. Ogni chiamata successiva entro la finestra viene addebitata per 2,000 invece di 20,000, con un risparmio di 18,000 token. La cache di 5 minuti è quindi in vantaggio a partire dalla seconda chiamata.

La cache di 1 ora comporta una scelta diversa. La scrittura viene addebitata per 40,000, con un sovrapprezzo di 20,000 token equivalenti. Servono quindi due letture entro l'ora per andare in vantaggio. Questo dipende dal modello di traffico, non dal modello linguistico. Il calcolo completo, compreso il metodo per scegliere la finestra, è disponibile in il calcolo del punto di pareggio per il caching dei prompt di Claude.

Due dettagli determinano se la cache viene utilizzata. Primo, un prefisso più corto della lunghezza minima del modello non viene memorizzato nella cache senza alcun messaggio: ad agosto 2026, il minimo documentato è di 512 token per Claude Opus 5 e 1,024 token per Claude Sonnet 5. Una richiesta più corta viene elaborata normalmente e non restituisce errori. Secondo, la durata viene calcolata dall'inizio della richiesta che scrive o legge la voce, e ogni lettura la rinnova senza costi aggiuntivi. Un endpoint utilizzato frequentemente mantiene quindi attiva una cache di 5 minuti a tempo indefinito. Un endpoint chiamato una volta ogni dieci minuti paga il sovrapprezzo di scrittura a ogni chiamata e non ottiene mai alcun risparmio.

Controllate la risposta invece di dare per scontato il comportamento. L'oggetto usage restituisce cache_creation_input_tokens e cache_read_input_tokens. Un conteggio delle letture pari a zero in ogni chiamata indica che state pagando le scritture senza ottenere alcun vantaggio.

Dove si incontrano le due cache

Un prompt di sistema lungo è il punto in cui si incontrano e il costo viene addebitato contemporaneamente su entrambi i fronti.

Localmente, un prompt di sistema di 20,000 token occupa circa 2.4 GiB di cache KV su un server Llama 3.1 8B a f16, separatamente per ogni richiesta simultanea che lo include. In remoto, lo stesso prefisso richiede una scrittura nella cache, quindi costa 0.1 volte l’input a ogni chiamata successiva. Il costo locale cresce con il numero di utenti. Il costo remoto cresce con il traffico e si azzera durante i periodi di inattività.

Esiste una funzionalità locale che assomiglia al prompt caching del provider e che viene spesso confusa con esso: il prefix caching. La documentazione di vLLM descrive l’automatic prefix caching come il caching “della cache KV delle query esistenti, in modo che una nuova query possa riutilizzare direttamente la cache KV se condivide lo stesso prefisso con una delle query esistenti”. Il server llama.cpp mantiene per impostazione predefinita una prompt cache per ogni slot e --cache-reuse N imposta la dimensione minima del blocco che tenterà di riutilizzare.

Il prefix caching riduce il calcolo di prefill. Il prompt di sistema di 20,000 token viene elaborato una sola volta invece che a ogni richiesta, riducendo nettamente il tempo al primo token. In vLLM i blocchi condivisi vengono riutilizzati invece di essere duplicati, quindi migliora anche l’utilizzo della memoria. Non riduce però mai la cache necessaria per i token attualmente attivi. Mantenere i pesi residenti tra le richieste è un meccanismo correlato ma distinto, descritto in mantenere un modello Ollama caricato tra le richieste.

Cosa misurare sul proprio server

Caricare il modello con il context desiderato, quindi leggere valori reali invece di affidarsi alla stima.

ollama ps
nvidia-smi --query-gpu=memory.used,memory.total --format=csv
free -g

ollama ps elenca il modello caricato, la relativa dimensione e indica se è in esecuzione sulla GPU o sulla CPU. Se un modello che dovrebbe risiedere interamente sulla GPU riporta una parte sulla CPU, significa che la KV cache ha spostato parte del modello fuori dalla GPU e la velocità di generazione diminuirà di conseguenza. nvidia-smi restituisce il valore effettivo della VRAM, mentre free -g svolge la stessa funzione su un VPS che usa soltanto la CPU. Aumentare il context per gradi, ricaricare il modello e osservare come cambia il valore. Il calcolo e il valore riportato dovrebbero essere molto vicini. Quando non lo sono, la differenza dipende generalmente dai buffer di calcolo interni del runtime, non da un errore nella formula.

Se questi valori orientano la scelta verso hardware che si preferirebbe non noleggiare, il confronto con il pagamento a consumo per token è illustrato in Confronto tra GPU VPS e token API.

FAQ

La KV cache è la stessa cosa del prompt caching?

No. La KV cache è memoria per singola richiesta all'interno del processo di serving e contiene i vettori key e value di ogni token nel contesto corrente. Si trova nella RAM o nella VRAM e viene rilasciata al termine della richiesta. Il prompt caching del provider è una funzione di fatturazione che memorizza un prefisso stabile del prompt sull'infrastruttura del provider e applica una tariffa ridotta quando lo si invia di nuovo. L'esaurimento della KV cache impedisce il caricamento del modello. La mancata presenza del prompt cache aumenta soltanto la fattura e il time to first token.

Perché il modello viene caricato con un contesto di 2k, ma non con 32k?

Perché il runtime alloca l'intera KV cache al momento del caricamento, dimensionandola in base alla lunghezza del contesto configurata e non al prompt inviato. Per Llama 3.1 8B in f16, la cache occupa 128 KiB per token: un contesto di 2k richiede 0.25 GiB, mentre 32k richiede 4 GiB. I pesi rientrano nella memoria disponibile in entrambi i casi. A fallire è la riserva di memoria. vLLM lo segnala con ValueError, che indica il numero massimo di token memorizzabili, e suggerisce di aumentare gpu_memory_utilization o ridurre max_model_len. Su un host con solo CPU, il processo viene terminato dall'out-of-memory killer del kernel. Puoi confermarlo con dmesg -T | grep -i "killed process".

Come si calcola la dimensione della KV cache per il mio modello?

Moltiplica 2 per il numero di layer, il numero di attention head key/value, la dimensione della head e il numero di byte per elemento. Il risultato è il numero di byte per token. Moltiplica quindi questo valore per la lunghezza del contesto e per il numero di richieste simultanee. Leggi il numero di layer e di head dal config.json del modello. Usa 2 byte per elemento per f16 o bf16. Una cache q8_0 occupa circa la metà, mentre q4_0 occupa circa un quarto.

Il prompt caching riduce la memoria necessaria sul mio server?

Il prompt caching del provider non influisce sull'hardware locale, perché i dati vengono memorizzati sul lato del provider. L'equivalente locale è il prefix caching, disponibile sia in vLLM sia nel server llama.cpp. Riutilizza i vettori key e value già calcolati per un prefisso condiviso, riducendo il calcolo di prefill e il time to first token. In vLLM i blocchi condivisi vengono riutilizzati anziché duplicati, quindi migliora anche l'utilizzo della memoria. Nessuna delle due funzioni riduce la cache necessaria per i token attualmente in elaborazione. Il limite minimo resta quindi determinato dal calcolo relativo a contesto e concorrenza.

Conviene memorizzare nella cache un prompt che invio una sola volta?

No. La scrittura nella cache costa più del normale input: per l'opzione di 5 minuti, ad agosto 2026 la tariffa è pari a 1.25 volte la tariffa base. Un prefisso che non viene mai inviato di nuovo durante la finestra di validità rappresenta quindi una perdita netta. Il caching conviene quando lo stesso prefisso viene ripetuto, ad esempio per un prompt di sistema lungo o per un documento su cui vuoi porre diverse domande. Controlla cache_read_input_tokens nella risposta dell'API per verificare che vengano registrati degli hit, invece di pagare per le scritture.