Interactieve KV-Cache Geheugen-Calculator

Door Ivo Donker — samengesteld met AI-ondersteuning · Laatst bijgewerkt: 7 augustus 2026

Welkom bij deze interactieve rekentool binnen module 5 van het leerpad op llmnet.nl. Deze module richt zich volledig op het thema "Onder de motorkap — architectuur & efficiëntie". Als bouwer, indie developer of homelab-beheerder krijg je bij het lokaal of op eigen infrastructuur draaien van Large Language Models (LLM's) direct te maken met de fysieke grenzen van grafisch geheugen (VRAM). De modelgewichten vormen daarbij slechts één deel van de totale geheugenbehoefte; zodra een model tekst genereert of verwerkt, eist de dynamische Key-Value (KV) cache een substantieel en snelgroeiend gedeelte van het geheugen op.

Deze calculator vult het praktische oefen-gat op het platform op als tweede interactieve hulpmiddel, naast de bestaande visualiser. Het doel van deze tool is het exact berekenen van de theoretische geheugenomvang van deze cache onder uiteenlopende instellingen. De opbouw van de KV-cache zelf wordt op deze pagina niet opnieuw van de grond af uitgelegd; die inhoudelijke onderbouwing staat uitvoerig beschreven op de pagina over de opbouw van KV-caching. Deze specifieke pagina rekent puur aan de parameters en helpt je vooraf nauwkeurig in te schatten hoeveel VRAM de cache in beslag zal nemen.

De KV-Cache Geheugen-Calculator

Vul hieronder de technische parameters in van het model dat je wilt analyseren. De waarden worden direct verwerkt in de berekening zonder dat er gegevens naar een server worden verstuurd.

Handleiding voor het invoeren van de waarden

Om correcte resultaten uit de calculator te krijgen, heb je de exacte architectuurparameters van het gekozen model nodig. Deze gegevens zijn doorgaans eenvoudig te achterhalen via de volgende bronnen:

• Het config.json bestand: In de opslag-repository van Hugging Face vind je het configuratiebestand van het model. Zoek naar velden zoals num_hidden_layers (lagen), hidden_size (hidden size), num_attention_heads (heads), en num_key_value_heads (KV-heads).
• De modelkaart (Model Card): Veel ontwikkelaars vermelden de netwerkdimensies direct in de technische specificaties op de introductiepagina van het model.
• GQA-verhouding bepalen: Indien het veld num_key_value_heads niet expliciet vermeld staat, maakt het model waarschijnlijk gebruik van klassieke Multi-Head Attention (MHA). Vul in dat geval voor de KV-heads exact hetzelfde getal in als bij het aantal attention heads.

Als je twijfelt over specifieke parameters van een lokale quantisatie of een aangepast model, vul de waarden dan conservatief in. Het instellen van een hogere precisie (zoals 16-bit) geeft je een veiligheidsmarge bij de voorbereiding van je hardware-capaciteit.

Wat de uitkomst betekent

De uitkomst van de calculator laat zien hoe drastisch de geheugenvereisten opschalen naarmate verzoeken langer worden of wanneer meerdere gebruikers tegelijkertijd bediend worden. Elke token die door het model verwerkt wordt — zowel in de initiële verwerkingsfase (prompt/prefill) als in de opeenvolgende gegenereerde stappen (decoding) — vereist het opslaan van twee vectoren (de Key en de Value) in elke laag van de transformer. Om te achterhalen hoeveel tokens een specifieke Nederlandse tekst oplevert, kun je de tokenizer visualiser tool gebruiken om de exacte token-dichtheid van je invoer te analyseren.

Omdat de autoregressieve generatie stap voor stap plaatsvindt, moeten al deze opgeslagen vectoren in het VRAM blijven staan totdat het gehele gesprek of de taak is afgerond. Gedurende de volledige duur van de generatie blijft dit geheugen gereserveerd. Een gedetailleerde uiteenzetting over hoe en wanneer deze cachegeheugens vrijkomen in de levenscyclus van een verzoek vindt u in het artikel over het verloop van de inference-fase. Het direct vasthouden van deze gegevens verklaart waarom het uitbreiden van een contextvenster van bijvoorbeeld 4.096 naar 32.768 tokens niet alleen meer rekentijd vraagt, maar de geheugenafdruk van de KV-cache evenredig met een factor acht vergroot.

Wanneer je op lokale hardware werkt met een vastgestelde hoeveelheid VRAM (zoals een grafische kaart met 16 GiB of 24 GiB), vormt de KV-cache de variabele factor die bepaalt of een verzoek slaagt of dat de software crasht met een 'Out of Memory' (OOM) foutmelding. Terwijl de modelgewichten een statische hoeveelheid geheugen innemen, groeit de KV-cache lineair met de contextlengte en de batch size. Lees op de gids-site meer over hoe je de contextlengte instelt en optimaliseert op lokale hardware om deze grenzen binnen je eigen systeemsturing strak te beheren.

Waarom GQA de rekening verkleint

Grouped-Query Attention (GQA) is een architecturale aanpassing waarbij meerdere query-heads een gezamenlijke Key- en Value-head delen. Zonder in te zoomen op de exacte wiskundige matrixoperaties van de attention-lagen, is het directe praktische effect dat de dimensie van de opgeslagen KV-vectoren drastisch afneemt. In de calculator zie je dit direct terug via het veld KV-heads. Als een model 32 query-heads heeft maar slechts 8 KV-heads (een verhouding van 4:1), wordt er per token en per laag vier keer minder data opgeslagen in vergelijking met traditionele Multi-Head Attention. Een volledige toelichting over de werking van deze techniek lees je op de pagina over Grouped-Query Attention.

Precisie als tweede knop

Naast het aanpassen van de netwerkarchitectuur (zoals bij GQA) is de precisie van de opgeslagen getallen de tweede belangrijke knop om het geheugenverbruik van de KV-cache te beïnvloeden. Standaard worden de Key- en Value-vectoren opgeslagen in FP16 of BF16 (16-bit float), wat 2 bytes per getal kost. Moderne inference-engines bieden echter de mogelijkheid om de KV-cache los van de modelgewichten te kwantiseren naar 8-bit (1 byte per getal) of zelfs 4-bit (0,5 byte per getal).

Het verlagen van de KV-cache precisie halveert (bij 8-bit) of kwartiert (bij 4-bit) de totale omvang van de cache op VRAM. Dit betekent dat je bij gelijke hardware een aanzienlijk grotere contextlengte kunt hanteren of een grotere batch size kunt draaien. Hier staat een subtiele kwaliteitsafruil tegenover: het sterk kwantiseren van de KV-cache kan bij zeer lange contexten leiden tot een lichte daling in de nauwkeurigheid van de attention-scores. In de praktijk blijkt 8-bit KV-quantisatie voor de meeste toepassingen vrijwel verliesvrij te werken, terwijl 4-bit voornamelijk wordt ingezet bij extreem geheugenbeperkte systemen.

Wanneer de schatting afwijkt

De calculator rekent met de puur theoretische omvang van de tensoren. In een productiewezen of lokale setup zijn er diverse factoren waardoor het werkelijke geheugenverbruik hoger ligt dan de berekende waarde. Het is essentieel om deze factoren mee te wegen tijdens de capaciteitsplanning:

• Activation Memory: Tijdens de forward pass moeten tussenliggende resultaten van matrixvermenigvuldigingen tijdelijk in het VRAM worden opgeslagen. Dit geheugen fluctueert continu per gegenereerde token.
• Geheugenfragmentatie: Naarmate verzoeken met wisselende contextlengtes doorelkaar worden verwerkt, kan er ongebruikte ruimte tussen geheugenblokken ontstaan (externe fragmentatie). Moderne technieken zoals PagedAttention verminderen dit probleem sterk, maar sluiten het nooit 100% uit.
• Framework Overhead: Inference-servers zoals vLLM, TensorRT-LLM of Ollama reserveren bij het opstarten vooraf een vast percentage van het VRAM (bijvoorbeeld 90%) als geheugenpool. Hierin zitten ook interne datastructuren en CUDA-contexten inbegrepen.
• Modelgewichten: De modelparameters zelf eisen de basisruimte op. Een 8B parameter model in 4-bit precisie neemt al zo'n 5,5 GiB aan statisch VRAM in beslag nog vóór de eerste token verwerkt wordt.

Gebruik de calculator daarom nadrukkelijk als een rekenkundige ondergrens. Om de totale systeembelasting en de operationele kosten van langdurige processen te begrijpen, verwijzen we naar het overzicht over het stroomverbruik en de hardwarebelasting van lokale AI. Voor een snelle naslag van alle gebruikte vaktermen kun je terecht in de AI-begrippenlijst.

Voorbeeldberekening

Om de formules achter de calculator inzichtelijk te maken, lopen we een rekenvoorbeeld stap voor stap door. Stel dat we beschikken over een model met de volgende kenmerken:

De exacte wiskundige opbouw van de formule volgt drie stappen:

Stap 1: Bepaal de effectieve KV-dimensie per laag
Omdat er sprake is van Grouped-Query Attention met 8 KV-heads op 32 attention heads, is de KV-dimensie kleiner dan de totale hidden size:
kv_dim = hidden_size × (kv_heads / heads) = 4096 × (8 / 32) = 1024

Stap 2: Bereken de geheugenomvang per token per laag
Per token moeten we zowel een Key-vector als een Value-vector opslaan (factor 2). Bij een FP16-precisie kost elke waarde 2 bytes:
bytes_per_token_per_laag = 2 × kv_dim × (precisie_bits / 8) = 2 × 1024 × 2 = 4096 bytes (4 KiB per laag)

Stap 3: Vermenigvuldig met het aantal lagen, de contextlengte en de batch size
Vermenigvuldig dit met de 32 lagen van het netwerk, de contextlengte van 8.192 tokens en een batch size van 1:
totaal_bytes = 8192 × 32 × 4096 × 1 = 1.073.741.824 bytes

Om te rekenen naar mebibytes (MB) delen we door 1024² (1.048.576). Dit geeft exact 1024 MB. Om te rekenen naar gibibytes (GiB) delen we door 1024³ (1.073.741.824). Het eindresultaat is exact 1,00 GiB.

Ter vergelijking: indien dit exacte model gebruik zou maken van klassieke Multi-Head Attention (waarbij KV-heads gelijk is aan 32), dan zou de geheugenomvang per laag stijgen van 4 KiB naar 16 KiB per token. Het totale cache-geheugen voor dezelfde 8.192 tokens zou in dat geval uitkomen op 4,00 GiB. Dit toont aan dat het instellen van de juiste GQA-verhouding in de calculator de berekende geheugenbelasting exact met een factor vier verlaagt.