Verschil tussen KV-cache en prompt-cache uitgelegd

KV-cache versus prompt-cache: het korte antwoord

De KV-cache en de prompt-cache van een provider delen een woord, maar verder vrijwel niets. De KV-cache is het werkgeheugen per verzoek. Het bevindt zich in het RAM of VRAM van uw server gedurende de volledige levensduur van één verzoek, en het groeit naarmate de contextlengte en het aantal gelijktijdige verzoeken toeneemt. Prompt-caching bij een provider is een functie voor facturering en latentievermindering. Een stabiel voorvoegsel van uw prompt wordt opgeslagen op de servers van de provider en vervolgens tegen een gereduceerd tarief in rekening gebracht wanneer u dit opnieuw verstuurt.

Het een is geheugen dat u als hardware aanschaft. Het ander is geheugen dat iemand anders beheert en waarvoor u huur betaalt.

Het praktische verschil is belangrijker dan de definitie. U kunt een tekort aan KV-cache krijgen; als dat gebeurt, weigert het model te laden of wordt het verzoek afgewezen. U kunt geen tekort aan prompt-cache krijgen. U kunt er alleen niet in slagen om de cache te benutten, waarna u simpelweg de volledige prijs betaalt.

Wat de KV-cache bevat en waarom deze bestaat

Een transformer die token nummer 500 genereert, moet aandacht besteden aan alle 499 voorgaande tokens. Voor elk van die tokens heeft elke laag een key-vector en een value-vector nodig. Het telkens opnieuw berekenen van al deze vectoren voor elk nieuw token zou ervoor zorgen dat de generatietijd kwadratisch toeneemt met de lengte. Daarom bewaart de runtime deze gegevens. Dit opslaggeheugen is de KV-cache (key/value cache).

Dit is een status per verzoek, omdat de cache wordt opgebouwd uit de exacte tokenreeks van dat specifieke verzoek. Twee gebruikers die verschillende prompts versturen, kunnen deze niet delen, tenzij de runtime gebruikmaakt van prefix caching; dit is een afzonderlijke functie die later wordt beschreven.

Het serveren gebeurt in twee fasen. De prefill-fase leest de volledige prompt en vult de cache; deze fase wordt beperkt door rekenkracht. De decode-fase produceert één token per keer en voegt dit toe aan de cache; deze fase wordt beperkt door de geheugenbandbreedte. Deze splitsing is de reden waarom de verwerking van prompts en de generatie van tokens verschillende snelheden rapporteren wanneer u tokens per seconde op uw eigen systeem meet.

Hoeveel geheugen gebruikt de KV-cache?

Zoek niet naar een tabel van de leverancier. De grootte is een rekensom die u voor elk model opnieuw kunt maken:

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

De 2 staat voor de key en de value. Elk ander getal is afkomstig van de config.json van het model, gepubliceerd op de Hugging Face-pagina van het model.

Neem Llama 3.1 8B. De configuratie vermeldt num_hidden_layers 32 en num_key_value_heads 8. De hidden_size van 4096 verdeeld over 32 attention heads geeft een head-dimensie van 128. Bij f16 is elk element 2 bytes:

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

Vermenigvuldig dit met de context waar u om vraagt, en vervolgens met het aantal verzoeken dat u tegelijkertijd uitvoert.

[
  {
    "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
  }
]

Bij 8k context is de cache 1 GiB. Bij 32k is dit 4 GiB, wat in dezelfde orde van grootte ligt als de 4-bit gewichten zelf. Bij de volledige 128k context van het model is dit 16 GiB voor één verzoek, en 64 GiB als vier verzoeken deze elk vullen. De gewichten zijn ongewijzigd gebleven. Alleen de cache is veranderd.

Grouped query attention (GQA) levert een grote bijdrage aan dit getal. Llama 3.1 8B heeft 8 key/value heads die 32 query heads bedienen, waardoor vier query heads één opgeslagen key/value-paar delen. Een model waarvan de num_key_value_heads gelijk is aan de num_attention_heads gebruikt vier keer zoveel cache bij hetzelfde aantal parameters. Controleer dat ene veld voordat u ervan uitgaat dat twee 8B-modellen evenveel kosten om te draaien.

Waarom een model dat op 2k draaide niet wil laden op 32k

Omdat de runtime de KV-cache reserveert op het moment dat het model wordt geladen, gebaseerd op de door u geconfigureerde contextlengte en niet op de prompt die u daadwerkelijk verstuurt. Het standaard contextvenster van Ollama is 4096 tokens. Verhoogt u dit naar 32k, dan vraagt u om 4 GiB aan extra toewijzing voordat er ook maar één token is binnengekomen.

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

Dezelfde instelling per sessie, vanuit de interactieve prompt:

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

De foutmelding ziet er per stack anders uit. vLLM controleert de berekening bij het opstarten en weigert te draaien:

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.

Op een VPS die alleen op CPU draait, vindt deze controle niet plaats, omdat de toewijzing uit het normale systeem-RAM komt. De out-of-memory killer van de kernel beëindigt het proces in plaats daarvan en laat het bewijs achter in de kernel ring buffer:

dmesg -T | grep -i "killed process"

Een regel waarin uw serverproces wordt genoemd, betekent dat de server meer geheugen heeft toegezegd dan beschikbaar was. De oplossing is een kleinere context, niet een groter swap-bestand: een KV-cache die naar schijf wordt geswapt, wordt bij elk gegenereerd token opnieuw gelezen, waardoor de generatiesnelheid vertraagt tot het punt van onbruikbaarheid. Het kiezen van een verstandig getal wordt behandeld in onze handleiding over num_ctx en contextlengte in Ollama.

Wat concurrency doet met het aantal

Elk in-flight verzoek draagt zijn eigen KV cache met zich mee. Dat is de regel die de meeste capaciteitsplannen missen. Vier gebruikers die elk 32k aan context vasthouden, hebben 16 GiB nodig, bovenop de gewichten van het model.

Runtimes verschillen in hoe strikt dit wordt toegepast. Ollama en llama.cpp reserveren de gevraagde context bij het laden van het model; het geheugen wordt dus gecommitteerd, ongeacht of het daadwerkelijk wordt gebruikt. vLLM verdeelt de pool in blokken van vaste grootte en wijst deze toe naarmate elk verzoek groeit, waardoor een verzoek van 500 tokens slechts de ruimte van 500 tokens in beslag neemt. Hoe dan ook is de pool eindig; zodra deze vol is, komen nieuwe verzoeken in de wachtrij in plaats van dat ze worden uitgevoerd. Wat die wachtrij doet met de responstijden, wordt uitgewerkt in hoeveel gelijktijdige gebruikers een zelfgehoste LLM kan bedienen.

Vier manieren om de KV-cache te verkleinen

1. Verlaag de contextlengte. Dit is de meest effectieve methode en meestal de goedkoopste. De meeste chat-workloads komen nooit in de buurt van 32k.
2. Kwantiseer de cache zelf. De OLLAMA_KV_CACHE_TYPE van Ollama staat standaard op f16 en accepteert q8_0, wat ongeveer de helft van het geheugen verbruikt, en q4_0, wat ongeveer een kwart verbruikt. De equivalenten in llama.cpp zijn -ctk q8_0 en -ctv q8_0.
3. Kies een model met minder key/value-heads of minder lagen. Lees config.json voordat u 40 GB aan gewichten downloadt.
4. Verwerk minder verzoeken tegelijk en plaats de rest in de wachtrij.

Bij q4_0 daalt het cijfer voor Llama 3.1 8B van 128 KiB per token naar ongeveer 32 KiB, waardoor 32k aan context ongeveer 1 GiB kost in plaats van 4 GiB. Deze besparing is niet gratis. De keys en values worden met minder precisie opgeslagen, dus vergelijk de uitvoer met uw eigen prompts voordat u deze instelling behoudt.

Wat provider prompt caching daadwerkelijk oplevert

Provider prompt caching is een ander product met een andere rekeneenheid. U markeert een stabiel voorvoegsel, de provider slaat dit op, en latere aanroepen die exact hetzelfde voorvoegsel herhalen, worden tegen een gereduceerd tarief gefactureerd in plaats van tegen de volledige prijs voor invoer.

De gepubliceerde vermenigvuldigers van Anthropic, per augustus 2026: een cache-schrijfactie van 5 minuten kost 1,25 keer de basisprijs per invoertoken. Een schrijfactie van 1 uur kost 2 keer, en een cache-leesactie kost 0,1 keer. Plaats een systeemprompt van 20.000 tokens achter deze cijfers en de aard van de deal wordt duidelijk.

[
  {
    "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"
  }
]

Bekijk het als een rekensom. De premie voor een schrijfactie van 5 minuten bedraagt 5.000 token-equivalenten bij de eerste aanroep: 25,000 tegenover 20,000 voor het ongecached verzenden ervan. Elke latere aanroep binnen het venster factureert 2,000 in plaats van 20,000, een besparing van 18.000. De cache van 5 minuten is dus vanaf de tweede aanroep rendabel.

De cache van 1 uur is een andere gok. Deze factureert 40,000 bij het schrijven, een premie van 20.000 token-equivalenten, dus er zijn twee hits binnen het uur nodig voordat deze rendabel is. Dat is een vraag over uw verkeerspatroon, niet over het model. De volledige berekening, inclusief hoe u het venster kiest, staat in de break-even berekening voor Claude prompt caching.

Twee details bepalen of u de cache überhaupt raakt. Ten eerste wordt een voorvoegsel onder de minimumlengte van het model stilzwijgend niet gecachet: per augustus 2026 is het gedocumenteerde minimum 512 tokens voor Claude Opus 5 en 1.024 tokens voor Claude Sonnet 5, en een korter verzoek wordt normaal verwerkt zonder dat er een foutmelding wordt geretourneerd. Ten tweede wordt de levensduur gemeten vanaf het begin van het verzoek dat het item schrijft of leest, en elke leesactie ververst het zonder extra kosten. Een druk eindpunt houdt een cache van 5 minuten daarom voor onbepaalde tijd in leven. Een eindpunt dat elke tien minuten wordt aangeroepen, betaalt elke keer de schrijfpremie en haalt er nooit voordeel uit.

Controleer het antwoord in plaats van ervan uit te gaan. Het usage-object rapporteert cache_creation_input_tokens en cache_read_input_tokens. Een leestelling van nul bij elke aanroep betekent dat u schrijfacties koopt en niets terugkrijgt.

Waar de twee caches elkaar raken

Een lange systeemprompt is de plek waar ze samenkomen, en deze belast u aan beide kanten tegelijk.

Lokaal beslaat een systeemprompt van 20.000 tokens ongeveer 2,4 GiB aan KV-cache op een Llama 3.1 8B-server bij f16, en dit gebeurt afzonderlijk voor elk gelijktijdig verzoek dat deze bevat. Op afstand kost hetzelfde voorvoegsel één cache-schrijfactie en vervolgens 0,1 keer de invoer bij elke latere aanroep. De lokale kosten schalen mee met uw gebruikers. De kosten op afstand schalen mee met uw verkeer en worden gereset tijdens uw inactiviteit.

Er is een lokale functie die lijkt op prompt-caching van een provider en daar voortdurend mee wordt verward: prefix caching. De documentatie van vLLM beschrijft automatische prefix caching als het cachen van "de KV-cache van bestaande queries, zodat een nieuwe query de KV-cache direct kan hergebruiken als deze hetzelfde voorvoegsel deelt met een van de bestaande queries". De llama.cpp-server houdt standaard een prompt-cache per slot bij, en --cache-reuse N stelt het kleinste blok in dat zal worden geprobeerd te hergebruiken.

Wat prefix caching bespaart, is prefill-rekenkracht. Uw systeemprompt van 20.000 tokens wordt één keer verwerkt in plaats van bij elk verzoek, wat de tijd tot het eerste token aanzienlijk verkort. In vLLM worden de gedeelde blokken hergebruikt in plaats van gedupliceerd, waardoor ook het geheugengebruik verbetert. Wat het nooit doet, is de cache verkleinen die u moet aanhouden voor de tokens die momenteel actief zijn. Het in het geheugen houden van de gewichten tussen verzoeken door is een gerelateerde maar afzonderlijke methode, die wordt behandeld in een Ollama-model geladen houden tussen verzoeken.

Wat u op uw eigen server moet meten

Laad het model in uw doelcontext en lees de werkelijke getallen af in plaats van te vertrouwen op de schatting.

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

ollama ps toont het geladen model met de grootte en of het op de GPU of de CPU draait. Als een model dat volledig op de GPU zou moeten passen een CPU-verdeling rapporteert, betekent dit dat de KV-cache een deel ervan heeft verdrongen, waardoor de generatiesnelheid navenant zal dalen. nvidia-smi geeft het werkelijke VRAM-cijfer weer en free -g doet hetzelfde op een VPS die alleen over een CPU beschikt. Verhoog de context in stappen, herlaad en observeer hoe het getal verandert. Uw berekening en het gerapporteerde cijfer zouden dicht bij elkaar moeten liggen. Wanneer dit niet het geval is, wordt het verschil meestal veroorzaakt door de eigen compute-buffers van de runtime in plaats van door een fout in de formule.

Als deze cijfers u dwingen tot hardware die u liever niet huurt, vindt u de vergelijking met betalen per token in GPU VPS versus API-tokens.

FAQ

Is de KV cache hetzelfde als prompt caching?

Nee. De KV cache is geheugen per request binnen het serving-proces, dat de key- en value-vectoren bevat voor elk token in de huidige context. Dit geheugen bevindt zich in uw RAM of VRAM en wordt vrijgegeven zodra het request is beëindigd. Prompt caching bij een provider is een facturatiefunctie die een stabiel prompt-prefix opslaat op de infrastructuur van de provider en een gereduceerd tarief in rekening brengt wanneer u dit opnieuw verstuurt. Een tekort aan KV cache zorgt ervoor dat een model niet kan laden. Het ontbreken van prompt caching verhoogt enkel uw factuur en de tijd tot het eerste token.

Waarom laadt mijn model wel met 2k context, maar faalt het bij 32k?

Omdat de runtime de volledige KV cache reserveert bij het laden, gebaseerd op de geconfigureerde contextlengte in plaats van de prompt die u verstuurt. Voor Llama 3.1 8B op f16 is de cache 128 KiB per token; 2k context kost dus 0.25 GiB en 32k kost 4 GiB. De gewichten passen in beide gevallen in het geheugen. Het is de reservering die faalt. vLLM rapporteert dit als een ValueError waarin het maximale aantal tokens wordt genoemd dat opgeslagen kon worden, en suggereert om gpu_memory_utilization te verhogen of max_model_len te verlagen. Op een systeem zonder GPU beëindigt de kernel out-of-memory killer het proces, wat u kunt bevestigen met dmesg -T | grep -i "killed process".

Hoe bereken ik de KV cache-grootte voor mijn model?

Vermenigvuldig 2 met het aantal lagen, het aantal key/value-heads, de head-dimensie en het aantal bytes per element. Dit geeft het aantal bytes per token. Vermenigvuldig dit vervolgens met uw contextlengte en het aantal gelijktijdige requests. Lees het aantal lagen en heads af uit de config.json van het model. Gebruik 2 bytes per element voor f16 of bf16. Een q8_0 cache is ongeveer de helft daarvan, en q4_0 ongeveer een kwart.

Vermindert prompt caching het geheugen dat mijn eigen server nodig heeft?

Prompt caching bij een provider doet niets voor uw hardware, omdat de opslag aan de kant van de provider plaatsvindt. Het lokale equivalent is prefix caching, aangeboden door zowel vLLM als de llama.cpp server. Dit hergebruikt reeds berekende key- en value-vectoren voor een gedeeld prefix, wat rekenkracht voor prefill bespaart en de tijd tot het eerste token verkort. In vLLM worden de gedeelde blokken hergebruikt in plaats van gedupliceerd, waardoor ook het geheugengebruik verbetert. Geen van beide functies verkleint de cache die nodig is voor de tokens die op dat moment in behandeling zijn, dus uw berekening voor context en gelijktijdigheid blijft de ondergrens bepalen.

Is het de moeite waard om een prompt te cachen die ik slechts eenmaal verstuur?

Nee. Een cache-schrijfactie kost meer dan standaard invoer; per augustus 2026 is dit 1,25 keer het basistarief voor de optie van 5 minuten. Een prefix die u nooit opnieuw verstuurt binnen het tijdsvenster is dus puur verlies. Caching loont wanneer hetzelfde prefix wordt herhaald, zoals bij een lange system prompt of een document waarover u meerdere vragen zult stellen. Controleer cache_read_input_tokens in de API-respons om te bevestigen dat u hits krijgt in plaats van te betalen voor schrijfacties.