Quantisatie in de praktijk: zelf een model comprimeren

In de route van lokaal AI-gebruik bevindt dit artikel zich tussen het selecteren van een basismodel en het daadwerkelijk draaien van een geoptimaliseerde server: we gaan van kiezen naar het technisch voorbereiden en tunen van gewichten. Voordat je begint met kwantiseren, is het essentieel om te controleren of je werkstation voldoet aan de basiseisen voor videogeheugen en systeembusbreedte; raadpleeg welke hardware je nodig hebt voor lokale LLM's om te bepalen hoeveel VRAM jouw configuratie beschikbaar heeft. Voor een stabiele compileeromgeving met C++ tools is een Linux-installatie aan te raden; lees lokale LLM's draaien op Linux voor het inrichten van de benodigde build-essentials en CUDA-toolkits. Wie eerst wil bepalen welk type architectuur het beste aansluit bij de beoogde taak, kan navigeren naar een lokaal model kiezen voor een vergelijking tussen basis- en instructmodellen.

Kwantisatie reduceert de precisie van individuele modelparameters (gewichten) van 16-bit drijvende-kommagetallen naar compacte 4-, 5- of 8-bit representaties, waardoor een model tot 70% minder geheugen inneemt met een minimaal verlies aan redeneerkracht; voor de theoretische wiskunde en de verschillen tussen datatypes verwijzen we naar de uitleg over kwantisatie en datatypes. In dit artikel voeren we het volledige conversieproces zelf uit op de commandoregel met llama.cpp.

Waarom zelf een model kwantiseren in plaats van downloaden?

Op platforms zoals Hugging Face zijn duizenden kant-en-klare GGUF-bestanden te vinden, vaak geleverd door community-leden. Toch zijn er dwingende redenen om het conversie- en compressieproces in eigen hand te nemen. Nieuwe modelarchitecturen of recente checkpoints van gefinetunede modellen zijn vaak nog niet direct als GGUF beschikbaar. Als ontwikkelaar wil je niet wachten tot iemand anders een conversiescript draait, zeker niet wanneer je werkt met vertrouwelijke domeinspecifieke data of net een eigen LoRA-adapter hebt samengevoegd met een basismodel.

Daarnaast heb je met een eigen kwantisatiepijplijn volledige controle over de toegepaste matrix-type selectie (zoals k-quants met wisselende precisie per laag) en het gebruik van een representatieve importance matrix (imatrix). Hiermee voorkom je dat een willekeurige generieke kwantisatie belangrijke aandachtskoppen (attention heads) degradeert. Ook weet je zeker dat het bronbestand niet gemanipuleerd is met afwijkende tokenizers of corrupte metadata.

De bouwstenen: llama.cpp compileren met hardwareversnelling

Het hart van de kwantisatietoolchain is llama.cpp. Om dit efficiënt te draaien, compileren we de C++ broncode met ondersteuning voor je specifieke GPU-architectuur (CUDA voor Nvidia, ROCm voor AMD, of Metal voor Apple Silicon). We klonen de repository en bouwen de binaries llama-quantize en llama-imatrix.

# Installeer vereiste pakketten (Ubuntu / Debian)
sudo apt update && sudo apt install -y git build-essential cmake ccache python3-pip python3-venv

# Clone de officiële llama.cpp repository
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# Bouw met CUDA ondersteuning (voor Nvidia GPU's)
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)

# Maak een geïsoleerde Python-omgeving aan voor conversiescripts
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Na het voltooien van het bouwproces vind je de uitvoerbare bestanden in de map build/bin/. Controleer met het commando ./build/bin/llama-cli --version of de CUDA-backend actief is. Dit voorkomt dat latere matrixberekeningen uitsluitend op de CPU plaatsvinden, wat aanzienlijk trager is.

Stap 1: Het bronmodel downloaden (Safetensors formaat)

Kwantisatie start altijd met gewichten in volle precisie (16-bit Float of BFloat16), meestal opgeslagen in het safetensors formaat. Download nooit een reeds gecomprimeerd model om dat nogmaals te kwantiseren; opeenvolgende afrondingsfouten leiden tot onherstelbaar kwaliteitsverlies (kwantisatie-artefacten).

# Installeer de Hugging Face CLI tool
pip install huggingface_hub

# Download een 8B model in FP16 / BF16 safetensors formaat
huggingface-cli download meta-llama/Llama-3.1-8B-Instruct \
  --local-dir ./models/Llama-3.1-8B-Instruct \
  --local-dir-use-symlinks False \
  --exclude "*.pth" "original/*"

Controleer na het downloaden of het bestand config.json, de tokenizer.json en alle .safetensors bestanden compleet in de doelmap staan. Ontbrekende tokenizerbestanden zorgen ervoor dat het conversiescript faalt bij het parseren van speciale tokens.

Stap 2: Conversie van Safetensors naar ongecomprimeerd GGUF (FP16 / BF16)

Voordat we bits kunnen reduceren, moeten de safetensors-bestanden worden omgezet naar het GGUF-formaat. Dit formaat consolideert alle modeltensors, vocabulaire-arrays en hyperparameter-metadata in één bestand of een gestructureerde set shards.

# Voer het conversiescript uit vanuit de actieve venv
python3 convert_hf_to_gguf.py ./models/Llama-3.1-8B-Instruct \
  --outfile ./models/llama-3.1-8b-f16.gguf \
  --outtype f16

Bij een 8B model levert deze stap een bestand op van circa 15 tot 16 GB. Dit bestand bevat nog de exacte numerieke precisie van het bronmodel. Houd er rekening mee dat je tijdens deze stap minimaal 16 GB vrije RAM nodig hebt om de tensorstructuren in het werkgeheugen te herordenen voordat ze naar de schijf worden weggeschreven.

Stap 3: Het genereren van een Importance Matrix (imatrix)

Standaard kwantisatie behandelt elke matrix en elke laag volgens een uniform statistisch schema. Sommige gewichten in een neuraal netwerk zijn echter onevenredig belangrijk voor logische samenhang en syntaxis. Door een importance matrix (imatrix) te berekenen op basis van een kalibratiedataset, meet llama.cpp welke parameters het meest gevoelig zijn voor precisieverlies. Lagen met hoge gevoeligheid behouden vervolgens een hogere bitprecisie, terwijl minder kritieke tensors sterker worden gecomprimeerd.

# Download een representatieve kalibratietekst (bijvoorbeeld WikiText of custom NL teksten)
curl -L -o ./models/calibration_data.txt https://raw.githubusercontent.com/ggerganov/llama.cpp/master/prompts/wiki.test.raw

# Bereken de imatrix via GPU-versnelling
./build/bin/llama-imatrix \
  -m ./models/llama-3.1-8b-f16.gguf \
  -f ./models/calibration_data.txt \
  -o ./models/llama-3.1-8b.imatrix \
  -ngl 99 \
  -c 512 \
  --chunks 64

Dit proces duurt op een moderne GPU ongeveer twee tot vijf minuten voor een 8B model. Het resulterende .imatrix bestand is slechts enkele megabytes groot, maar verbetert de perplexity-score van lagere kwantisaties (zoals Q4_K_M of Q3_K_M) aanzienlijk.

Stap 4: Uitvoeren van de kwantisatie naar K-Quants

Nu alle voorbereidingen zijn getroffen, starten we de eigenlijke kwantisatie met llama-quantize. We kiezen hier voor moderne k-quant formaten (zoals Q4_K_M of Q5_K_M), waarbij verschillende gewichtsblokken binnen het netwerk met verschillende bitdieptes worden opgeslagen voor een optimale balans tussen bestandsgrootte en performantie.

# Kwantisatie naar Q4_K_M met behulp van de gegenereerde imatrix
./build/bin/llama-quantize \
  --imatrix ./models/llama-3.1-8b.imatrix \
  ./models/llama-3.1-8b-f16.gguf \
  ./models/llama-3.1-8b-Q4_K_M.gguf \
  Q4_K_M

# Kwantisatie naar Q5_K_M voor een hogere redeneerprecisie
./build/bin/llama-quantize \
  --imatrix ./models/llama-3.1-8b.imatrix \
  ./models/llama-3.1-8b-f16.gguf \
  ./models/llama-3.1-8b-Q5_K_M.gguf \
  Q5_K_M

De kwantisatiestap verwerkt de tensors sequentieel en duurt gemiddeld 30 tot 90 seconden. Na afronding is het bestand llama-3.1-8b-Q4_K_M.gguf gereduceerd tot circa 4,9 GB, wat probleemloos in een 8 GB of 12 GB GPU past.

Stap 5: Kwaliteitsverificatie en Perplexity meten

Het voltooien van de compressie zonder foutmeldingen betekent niet automatisch dat de uitvoerinhoud intact is gebleven. Om objectief vast te stellen hoeveel precisie verloren is gegaan, berekenen we de perplexity van het gekwantiseerde model ten opzichte van het FP16 origineel. Perplexity is een wiskundige maatstaf voor hoe verrast het taalmodel is door een standaard reeks teksten.

# Test de perplexity van het gekwantiseerde bestand
./build/bin/llama-perplexity \
  -m ./models/llama-3.1-8b-Q4_K_M.gguf \
  -f ./models/calibration_data.txt \
  -c 512 \
  -ngl 99

Een lichte toename in perplexity (bijvoorbeeld van 5.42 naar 5.50) is volkomen normaal bij 4-bit kwantisatie en heeft in alledaagse toepassingen nauwelijks merkbare invloed op de tekstkwaliteit. Schiet de perplexity echter omhoog naar waarden boven de 7.0, dan is er sprake van ernstige degradatie door een verkeerde kalibratie of beschadigde layers.

Praktijktest: Kwaliteitsverschil op Nederlandse instructies

Syntaxis en grammatica in het Nederlands zijn gevoeliger voor agressieve kwantisatie dan het Engels, omdat Nederlandse tokens gemiddeld over minder trainingsparameters beschikken in meertalige basismodellen. Wie structureel aan de slag wil met taaloptimalisatie doet er goed aan de richtlijnen te lezen over hoe je de AI beter laat presteren in het Nederlands om typische anglicismen en zinsbouwproblemen te ondervangen.

Laten we een testopdracht voorleggen aan zowel de Q4_K_M als de Q5_K_M variant om te controleren hoe strak instructies worden opgevolgd:

Prompt: "Leg in exact drie genummerde punten uit wat het verschil is tussen werkgeheugen en videogeheugen bij het draaien van een lokaal taalmodel."

Uitvoer Q5_K_M:
1. Werkgeheugen (RAM) bevindt zich op het moederbord en wordt aangesproken door de CPU; het is relatief traag maar vaak beschikbaar in grotere capaciteiten (bijv. 32 tot 64 GB).
2. Videogeheugen (VRAM) zit direct op de videokaart (GPU) en biedt een vele malen hogere bandbreedte (tot wel 1 TB/s), wat essentieel is voor snelle token-generatie.
3. Als een model volledig in het VRAM past draait het op maximale snelheid; zodra lagen moeten uitwijken naar het reguliere RAM (offloading) daalt de verwerkingssnelheid drastisch.

Uitvoer Q3_K_S (ter vergelijking bij te sterke compressie):
1. RAM is voor normale computerdingen en CPU.
2. VRAM is van de videokaart en is sneller voor AI tensors.
3. Als geheugen vol is stopt het of gaat langzaam. (Punt 3 mist detail en nuance).

In de praktijk zien we dat Q4_K_M en Q5_K_M de grammaticale structuur en de strakke instructiebeperking ("exact drie genummerde punten") foutloos handhaven, terwijl Q3_K_S begint in te boeten op diepgang en woordkeuze.

Integratie in Ollama via een custom Modelfile

Zodra het GGUF-bestand is gevalideerd, kun je het eenvoudig opnemen in je dagelijkse werkomgeving zoals Ollama. Hiervoor schrijven we een eenvoudige Modelfile die verwijst naar het lokale bestandspad.

# Maak een bestand genaamd Modelfile aan
FROM ./models/llama-3.1-8b-Q4_K_M.gguf

# Stel parameters in voor deterministisch gedrag
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER stop "<|eot_id|>"
PARAMETER stop "<|end_of_text|>"

# Definieer het chatsjabloon van Llama 3.1
TEMPLATE """{{ if .System }}<|start_header_id|>system<|end_header_id|>

{{ .System }}<|eot_id|>{{ end }}{{ if .Prompt }}<|start_header_id|>user<|end_header_id|>

{{ .Prompt }}<|eot_id|>{{ end }}<|start_header_id|>assistant<|end_header_id|>

{{ .Response }}<|eot_id|>"""

SYSTEM """Je bent een behulpzame, feitelijke assistent die altijd antwoordt in correct Nederlands."""

Vervolgens registreer je het model in Ollama met het build-commando:

# Bouw het model lokaal in Ollama
ollama create llama3-custom-q4 -f Modelfile

# Start een interactieve sessie
ollama run llama3-custom-q4

Privacy, isolatie en dataveiligheid

Het zelf kwantiseren en lokaal draaien van taalmodellen garandeert dat er geen enkele byte aan invoerdata, documentteksten of interne gewichten naar externe cloudservers wordt verstuurd. Alle bewerkingen — van het compileren van de broncode tot het genereren van de imatrix en het uitvoeren van inferences — vinden volledig geïsoleerd plaats binnen je lokale bestandssysteem. Organisaties die strikte geheimhouding hanteren of moeten voldoen aan de AVG kunnen dit proces draaien op een afgesloten werkstation zonder actieve internetverbinding zodra de broncode en gewichten zijn binnengehaald; bekijk voor een structurele borging het overzicht over privacyvriendelijk AI-gebruik om datalekken bij modelaanroepen definitief uit te sluiten.

Praktijkrisico's en betrouwbaarheid controleren

Hoewel kwantisatie rekenkracht bespaart, introduceert het een subtiel risico: kleine afrondingsfouten in de gewichten kunnen ervoor zorgen dat een model vaker hallucineert bij feitelijke vragen of wiskundige berekeningen. Controleer daarom altijd kritisch de antwoorden van gecomprimeerde modellen; lees de handleiding over AI-antwoorden factchecken om systematisch bronverificatie en controles toe te passen op gegenereerde teksten. Wanneer je lokale AI inricht voor gedeeld gebruik binnen een gezin of op een thuisserver, is het verstandig om het dossier over AI veilig thuis gebruiken door te nemen om te zorgen voor adequate afscherming van gevoelige gegevens en kindvriendelijke filters.

Voor ontwikkelaars die kwantisatie willen inzetten als onderdeel van autonome systemen, pipelines en tool-calling agents, biedt de specialistische gids over AI agent engineer worden in 2026 een compleet overzicht van de vaardigheden die nodig zijn om lokale taalmodellen betrouwbaar te koppelen aan externe API's en databronnen.

Veelvoorkomende fouten en oplossingen

Tijdens het kwantisatieproces kunnen specifieke fouten optreden. Hieronder staan de meest voorkomende knelpunten en de bijbehorende correcties:

• CUDA out of memory tijdens imatrix-berekening: Verlaag de contextlengte in het imatrix-commando met de vlag -c 256 of verlaag het aantal GPU-lagen via -ngl 20 zodat een deel van de berekening in het systeem-RAM plaatsvindt.
• KeyError bij conversiescript: Dit duidt meestal op een afwijkende modelarchitectuur die nog niet wordt ondersteund door de huidige release van llama.cpp. Voer git pull uit in de llama.cpp repository en hercompileer de binary.
• Garbage output (wartaal) na kwantisatie: Dit wordt vrijwel altijd veroorzaakt door een mismatch in de tokenizer of ontbrekende speciale tokens in het brondirectory. Zorg ervoor dat tokenizer.json en tokenizer_config.json aanwezig zijn tijdens het draaien van convert_hf_to_gguf.py.

Met de juiste combinatie van convert_hf_to_gguf.py, llama-imatrix en llama-quantize beschikt je werkstation over een volwaardige pijplijn om elk open model exact op maat te snijden voor jouw beschikbare videogeheugen, met behoud van scherpe redeneerprestaties en volledige privacy.