SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Cache KV e prompt cache: differenze e costi

La cache KV occupa RAM o VRAM a ogni richiesta e può impedire il caricamento del modello. La prompt cache riduce costi e latenza, ma non evita errori di memoria.

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.

GraficoLlama 3.1 8B KV cache at f16, in GiB
I dati alla base di questo grafico
[
  {
    "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 dimensione dipende dalla lunghezza del contesto configurata, non dal prompt effettivamente inviato. Il valore predefinito di Ollama non è più un numero unico. A ottobre 2026, la documentazione sulla lunghezza del contesto la imposta in base alla VRAM: 4k sulle macchine con meno di 24 GiB, 32k tra 24 e 48 GiB e 256k con almeno 48 GiB; i modelli cloud usano invece per impostazione predefinita il valore massimo. Un VPS con solo CPU o una GPU di piccole dimensioni parte da 4k. Portare il valore a 32k significa richiedere 4 GiB di allocazione aggiuntiva prima che arrivi un solo token. Su una scheda da 24 GiB, 32k è già il valore predefinito, quindi la riserva viene effettuata indipendentemente dalla richiesta esplicita.

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

La stessa impostazione per sessione, dal prompt interattivo:

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

Il fallimento varia in base allo stack. vLLM verifica i calcoli all'avvio e rifiuta di eseguire il modello:

ValueError: To serve at least one request with the model's max seq len (131072), (16.0 GiB KV cache is needed, which is larger than the available KV cache memory (9.56 GiB). Based on the available memory, the estimated maximum model length is 78336. Try increasing `gpu_memory_utilization` (which also controls CPU memory on the CPU backend) or decreasing `max_model_len` when initializing the engine. See https://docs.vllm.ai/en/latest/configuration/conserving_memory/ for more details.

Su un VPS con solo CPU che esegue Ollama o llama.cpp, l'allocazione usa la normale RAM di sistema e la memoria insufficiente potrebbe non essere rilevata all'avvio. 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 identifica il processo di serving indica 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 appropriato è descritta 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 prompt caching del provider

Il prompt caching 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, a ottobre 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, mentre la lettura della cache costa 0.1 volte sulla maggior parte dei modelli. I modelli più recenti applicano un costo di lettura ancora più basso: 0.05 volte su Claude Opus 5.5 e Sonnet 5.5, e 0.025 volte su Claude Fable 5.1 e Mythos 5.1. Se si inserisce un prompt di sistema di 20,000 token dietro i valori standard, il vantaggio diventa evidente.

GraficoCost of a 20,000 token prefix, in base input token equivalents
I dati alla base di questo grafico
[
  {
    "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"
  }
]

Consideriamo il calcolo. Il sovrapprezzo per la scrittura della cache di 5 minuti equivale a 5,000 token alla prima chiamata: 25,000 contro 20,000 per l'invio senza cache. Ogni chiamata successiva entro la finestra viene addebitata come 2,000 invece di 20,000, con un risparmio di 18,000 token. La cache di 5 minuti è quindi già conveniente a partire dalla seconda chiamata.

La cache di 1 ora segue una logica diversa. La scrittura viene addebitata come 40,000, con un sovrapprezzo di 20,000 token equivalenti. Servono quindi due letture entro l'ora per ottenere un risparmio. Dipende dal modello di traffico, non dal modello AI. Il calcolo completo, compreso il modo per scegliere la finestra, è disponibile in il calcolo del punto di pareggio per il prompt caching di Claude.

Due dettagli determinano se la cache viene utilizzata. Primo, un prefisso più corto della lunghezza minima del modello non viene memorizzato senza alcun avviso: a ottobre 2026 il minimo documentato è di 512 token per Claude Opus 5, Opus 5.5 e Sonnet 5.5, e di 1,024 token per Claude Sonnet 5. Una richiesta più breve 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 può quindi mantenere attiva una cache di 5 minuti indefinitamente. Un endpoint chiamato una volta ogni dieci minuti paga il sovrapprezzo di scrittura a ogni chiamata e non ottiene mai un risparmio.

Controlla la risposta invece di dare per scontato che la cache venga utilizzata. L'oggetto usage restituisce cache_creation_input_tokens e cache_read_input_tokens. Un conteggio delle letture pari a zero a ogni chiamata indica che stai pagando le scritture senza ottenere alcun vantaggio.

Quando le due cache entrano in contatto

Un system prompt lungo è il punto in cui entrano in contatto e incide contemporaneamente su entrambi i lati.

Localmente, un system prompt 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 concorrente che lo include. Da remoto, lo stesso prefisso richiede una scrittura nella cache e poi costa 0.1 volte l'input a ogni chiamata successiva, o anche meno sui modelli più recenti. 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 viene spesso confusa con esso: il prefix caching. La documentazione di vLLM descrive l'automatic prefix caching come la memorizzazione nella cache «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». Le versioni attuali di vLLM lo attivano per impostazione predefinita. 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 proverà a riutilizzare.

Il prefix caching riduce il calcolo di prefill. Il system prompt 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'uso della memoria. Non riduce mai, però, la cache che è necessario mantenere per i token attualmente attivi. Mantenere i pesi residenti tra una richiesta e l'altra è un meccanismo correlato ma separato, descritto in mantenere un modello Ollama caricato tra le richieste.

Cosa misurare sul proprio server

Caricare il modello con il contesto di destinazione e leggere i 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, il contesto con cui è stato caricato e indica se è in esecuzione sulla GPU o sulla CPU. Controllare prima la colonna del contesto, perché il valore predefinito ora dipende dalla VRAM disponibile. Se un modello che dovrebbe risiedere interamente sulla GPU indica una suddivisione sulla CPU, significa che la cache KV ne ha spostato una parte sulla CPU e la velocità di generazione diminuirà di conseguenza. nvidia-smi mostra il valore effettivo della VRAM, mentre free -g svolge la stessa funzione su un VPS che usa soltanto la CPU. Aumentare il contesto per incrementi, ricaricare il modello e osservare come cambia il valore. Il calcolo manuale e il valore riportato dovrebbero essere molto vicini. Quando non lo sono, la differenza è solitamente dovuta ai buffer di calcolo interni del runtime, non a un errore nella formula.

Se questi valori fanno preferire hardware che non si vorrebbe noleggiare, il confronto con il pagamento per token è illustrato in GPU VPS rispetto ai token API.

FAQ

La cache KV è la stessa cosa del prompt caching?

No. La cache KV è 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 funzionalità 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 cache KV impedisce il caricamento del modello. La mancata disponibilità della prompt cache aumenta soltanto la fattura e il time to first token.

Perché il mio modello si carica con un contesto di 2k ma non con uno di 32k?

Perché il runtime alloca l'intera cache KV al caricamento, dimensionandola in base alla lunghezza del contesto configurata e non al prompt inviato. Per Llama 3.1 8B a f16, la cache richiede 128 KiB per token: un contesto di 2k richiede 0.25 GiB, mentre uno di 32k richiede 4 GiB. I pesi rientrano nella memoria disponibile in entrambi i casi. Il problema riguarda la prenotazione della cache. vLLM lo segnala con un ValueError che indica quanta memoria richiede la cache KV rispetto a quella disponibile, insieme alla lunghezza massima stimata del modello, e suggerisce di aumentare gpu_memory_utilization o ridurre max_model_len. Su un sistema solo CPU che esegue Ollama o il server llama.cpp, il kernel può terminare il processo tramite l'oom killer. Puoi confermarlo con dmesg -T | grep -i "killed process".

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

Moltiplica 2 per il numero di layer, il numero di teste key/value, la dimensione della testa e il numero di byte per elemento. Il risultato è il numero di byte per token. Moltiplicalo quindi per la lunghezza del contesto e per il numero di richieste concorrenti. Leggi il numero di layer e di teste dal config.json del modello. Usa 2 byte per elemento per f16 o bf16. Una cache q8_0 richiede circa la metà, mentre una q4_0 ne richiede circa un quarto.

Il prompt caching riduce la memoria necessaria sul mio server?

Il prompt caching del provider non ha alcun effetto sull'hardware locale, perché i dati sono memorizzati sul lato del provider. L'equivalente locale è il prefix caching, disponibile sia in vLLM sia nel server llama.cpp. Questa funzionalità 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 anche l'uso della memoria migliora. Nessuna delle due funzionalità riduce la cache necessaria per i token attualmente in elaborazione. Il dimensionamento basato su contesto e concorrenza continua quindi a definire il limite minimo.

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

No. Una scrittura nella cache costa più di un input normale: per l'opzione di 5 minuti, a ottobre 2026 la tariffa è 1.25 volte quella di base. Un prefisso che non viene mai reinviato durante la finestra di validità produce quindi solo una perdita. Il caching è utile quando lo stesso prefisso viene ripetuto, ad esempio per un prompt di sistema lungo o per un documento sul quale vuoi porre diverse domande. Controlla cache_read_input_tokens nella risposta API per verificare che vengano registrati degli hit anziché addebiti per le scritture.

Questo articolo ti è stato utile?