Kobold.cpp installeren voor lokale GGUF-inferentie

Door Ivo Donker — samengesteld met AI-ondersteuning (Claude & Gemini)

Binnen de route van kiezen → installeren → gebruiken → koppelen → beheren bevindt deze handleiding zich direct bij de tweede stap: installeren per platform. Voordat je met inferentiesoftware aan de slag gaat, is het essentieel om te controleren of je werkstation voldoet aan de minimale geheugenspecificaties. Raadpleeg daarom vooraf het overzicht over welke hardware je nodig hebt om LLM's lokaal te draaien om te verifiëren of jouw combinatie van werkgeheugen en videokaart toereikend is voor het gekozen modelformaat.

Kobold.cpp vormt binnen het ecosysteem van lokale taalmodellen een opvallende uitzondering. Waar veel oplossingen afhankelijk zijn van zware Python-omgevingen, Docker-containers of achtergronddaemons, levert Kobold.cpp een compacte C/C++-implementatie die als één enkel uitvoerbaar bestand draait. Het project combineert de rekenkracht van llama.cpp met een ingebouwde webinterface, een uitgebreide OpenAI-compatibele API en geavanceerde geheugenbeheersfuncties zoals Context Shifting en Smart Context. Dit maakt het een bijzonder stabiele basis voor wie direct met GGUF-bestanden wil werken zonder overhead.

Wat Kobold.cpp is en waarin het verschilt van andere engines

Kobold.cpp is een zelfstandige inferentie-engine die primair is ontworpen om GGUF-modellen snel en met minimale systeemvereisten lokaal uit te voeren. Oorspronkelijk ontstaan als backend voor creatieve schrijftoepassingen en interactieve fictie, is het pakket uitgegroeid tot een volwaardige lokale server voor algemene chat, documentanalyse en API-gedreven automatiseringen.

Het structurele verschil met engines zoals Ollama of vLLM zit in de architectuur. Ollama abstraheert veel instellingen weg achter een daemon en beheert eigen modelmanifesten in lagen, terwijl vLLM zich richt op batch-verwerking voor tientallen gelijktijdige gebruikers op Linux-servers. Kobold.cpp focust daarentegen op één enkele gebruiker of een kleine werkgroep, waarbij de gebruiker volledige controle houdt over de toewijzing van VRAM, threads en contextbeheer. Bovendien levert Kobold.cpp een zero-dependency executable: onder Windows download je een .exe die direct start zonder installatieproces of administratorrechten.

Het bestandsformaat dat centraal staat is GGUF. Wie de details van dit formaat wil doorgronden en wil begrijpen hoe gewichten worden gecomprimeerd met minimaal precisieverlies, kan de basis nalezen in de gids over kwantisatie en grote modellen op kleine hardware draaien. Daarnaast legt het netwerkdossier over quantization-formaten kiezen tussen GGUF, AWQ en EXL2 haarfijn uit waarom GGUF de beste keuze is wanneer je modelgewichten flexibel over zowel de GPU als het reguliere werkgeheugen wilt verdelen.

Privacy en databescherming bij lokaal draaien

Een van de belangrijkste redenen om inferentie via Kobold.cpp lokaal uit te voeren, is de absolute controle over inkomende en uitgaande datastromen. Wanneer Kobold.cpp op je computer draait, worden alle berekeningen uitgevoerd op je eigen processor en videokaart. Er vindt geen telemetrie plaats, er worden geen prompts naar externe clouddiensten verstuurd en er is geen internetverbinding vereist om het model te laten functioneren.

Voor organisaties die moeten voldoen aan strenge privacywetgeving biedt deze opzet volledige transparantie. In het document over privacyvriendelijk AI-gebruik wordt dieper ingegaan op de juridische en infrastructurele waarborgen die nodig zijn wanneer je persoonsgegevens of bedrijfsgeheimen lokaal verwerkt. Kobold.cpp bindt zijn webserver standaard uitsluitend aan 127.0.0.1 (localhost), waardoor de poort niet zonder expliciete vlaggen openstaat voor derden op hetzelfde lokale netwerk.

Installatie en download per platform

Omdat Kobold.cpp geschreven is in geoptimaliseerd C/C++, zijn er voorgecompileerde binaries beschikbaar voor Windows, Linux en macOS. Hieronder behandelen we de installatiestappen per besturingssysteem.

Windows (Nvidia CUDA, AMD ROCm of CPU)

Onder Windows is de installatie het eenvoudigst:

1. Ga naar de officiële GitHub-releases van koboldcpp en download het uitvoerbare bestand koboldcpp.exe (voor algemeen gebruik en Nvidia GPU's) of koboldcpp_rocm.exe (voor specifieke AMD Radeon-kaarten).

2. Plaats het bestand in een vaste map, bijvoorbeeld C:\AI\KoboldCPP\.

3. Dubbelklik op het .exe-bestand. Er verschijnt een grafisch configuratiescherm (de launcher) waarin je instellingen en het te laden GGUF-bestand kunt selecteren.

Linux (Handmatig of gecompileerd met CUDA)

Op Linux kun je kiezen tussen het downloaden van een pre-built binary of het zelf compileren voor maximale hardware-optimalisatie. Zelf bouwen met CUDA-ondersteuning levert vaak betere prestaties op:

# Installeer de basisafhankelijkheden
sudo apt-get update && sudo apt-get install -y build-essential libopenblas-dev

# Clone de repository
git clone https://github.com/LostRuins/koboldcpp.git
cd koboldcpp

# Compileer met Nvidia CUDA-versnelling
make LLAMA_CUDA=1 -j$(nproc)

# Start Kobold.cpp via de command-line
./koboldcpp.py --model /pad/naar/model.gguf --gpulayers 33 --contextsize 8192

macOS (Apple Silicon Metal)

Op een Mac met Apple Silicon (M1/M2/M3/M4) maakt Kobold.cpp gebruik van Metal voor versnelling via het geïntegreerde unified memory:

# Clone en compileer met Metal-ondersteuning
git clone https://github.com/LostRuins/koboldcpp.git
cd koboldcpp
make LLAMA_METAL=1 -j8

# Start met Metal offloading
./koboldcpp.py --model /pad/naar/model.gguf --usemetal --contextsize 8192

De grafische interface versus Command-Line vlaggen

Wanneer je de launcher start, kun je de engine handmatig instellen via de grafische knoppen of direct starten met parameters. Voor repetitieve taken of headless-servers is het handig om een startscript te maken.

Hieronder volgt een overzicht van de belangrijkste instelparameters en hun betekenis:

Geheugenallocatie en GPU Offloading: Hoe lagen werken

Een transformermodel bestaat uit een reeks opeenvolgende neurale netwerklagen. Een 8B-model zoals Llama-3.1 heeft 32 decoderlagen plus een invoer- en uitvoerlaag (totaal 33 lagen). Kobold.cpp stelt je in staat om precies te bepalen hoeveel van deze lagen op de videokaart (VRAM) draaien en hoeveel op het werkgeheugen (RAM via de CPU).

Wanneer je alle 33 lagen naar de GPU offloadt via --gpulayers 33, verloopt de generatie op maximale snelheid. Heeft je videokaart echter maar 6 GB VRAM en vereist het model 8 GB, dan kun je een hybride split instellen: bijvoorbeeld 20 lagen op de GPU en 13 lagen op de CPU. De tokensnelheid zakt dan aanzienlijk in vergelijking met volledige GPU-verwerking, maar het model start en functioneert zonder haperingen.

Om te berekenen hoeveel VRAM je nodig hebt, moet je rekening houden met twee componenten: het basismodel en de KV-cache (het contextgeheugen). Een 8B Q4_K_M model neemt ongeveer 4,9 GB in beslag voor de gewichten. Voor een contextlengte van 8192 tokens komt daar bij FP16 KV-cache nog zo'n 1,5 GB bij. Wil je dieper ingaan op het correct afstemmen van je contextlengte om geheugenoverschrijding te voorkomen, lees dan het achtergrondartikel over contextlengte instellen bij lokaal draaien.

Praktijkvoorbeeld: Een GGUF-model laden en testen

Laten we een concreet startcommando doorlopen voor een systeem met een Nvidia RTX 4060 (8 GB VRAM) en 32 GB RAM, waarbij we een 8B-instructiemodel laden:

# Start Kobold.cpp met cuBLAS versnelling en 8k context
koboldcpp.exe --model C:\LLM\Llama-3.1-8B-Instruct.Q4_K_M.gguf \
  --usecublas normal \
  --gpulayers 33 \
  --contextsize 8192 \
  --threads 6 \
  --smartcontext \
  --port 5001

Zodra de terminal aangeeft dat het model succesvol in het geheugen is geladen, opent de ingebouwde webinterface automatisch in je browser op http://127.0.0.1:5001. Kobold Lite biedt direct toegang tot twee modi: 'Story Mode' (vrije tekstgeneratie) en 'Chat Mode' (vraag-en-antwoord interactie met aanpasbare instructiesystemen).

Contextbeheer: Context Shifting en Smart Context

Een uniek technisch voordeel van Kobold.cpp ten opzichte van veel andere tools is het mechanisme genaamd Context Shifting. Bij traditionele inferentieservers wordt de gehele KV-cache gewist en herberekend vanaf het begin zodra een gesprek langer wordt dan het ingestelde contextvenster. Dit leidt bij lange sessies tot een plotselinge 'bevriezing' van enkele seconden of zelfs minuten.

Context Shifting verwijdert bij het bereiken van de contextlimiet alleen de oudste tokens uit het midden van de KV-cache en schuift de resterende tokens naar voren. Hierdoor blijft de initiële systeemprompt behouden, blijven de meest recente berichten intact en hoeft de GPU slechts een minimale correctie uit te voeren. De respons blijft daardoor direct op gang komen, ongeacht hoelang de chatsessie voortduurt.

Koppeling met externe applicaties via de API

Kobold.cpp functioneert niet alleen als zelfstandige chatomgeving, maar ook als backend-server voor externe interfaces zoals SillyTavern, Jan AI, AnythingLLM of je eigen Python-scripts. De server stelt twee API-endpoints beschikbaar:

1. Het Kobold Native Endpoint (http://127.0.0.1:5001/api/v1/generate), waarmee gespecialiseerde interfaces toegang krijgen tot diepgaande sampler-instellingen zoals Mirostat, Tail Free Sampling en Repetition Penalties.

2. Het OpenAI-compatibele Endpoint (http://127.0.0.1:5001/v1/chat/completions), waarmee je Kobold.cpp als 'drop-in replacement' kunt gebruiken in software die standaard ontworpen is voor OpenAI-modellen.

Hieronder staat een minimaal Python-voorbeeld dat communiceert met het lokale OpenAI-endpoint van Kobold.cpp:

import urllib.request
import json

url = "http://127.0.0.1:5001/v1/chat/completions"
headers = {"Content-Type": "application/json"}
payload = {
    "model": "koboldcpp",
    "messages": [
        {"role": "system", "content": "Je bent een deskundige en feitelijke assistent."},
        {"role": "user", "content": "Leg in twee zinnen uit wat het voordeel is van een lokale LLM."}
    ],
    "temperature": 0.7,
    "max_tokens": 150
}

req = urllib.request.Request(url, data=json.dumps(payload).encode('utf-8'), headers=headers)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode('utf-8'))
    print(result["choices"][0]["message"]["content"])

Prestaties testen op Nederlandse instructies

Om te verifiëren of de inferentie correct verloopt en de samplers goed staan ingesteld, is het aan te raden een gestructureerde Nederlandstalige prompt te testen. We evalueren hierbij zowel de logische consistentie als de tokensnelheid (tokens per seconde).

Testinvoer:

"Geef een puntsgewijze vergelijking tussen synchrone en asynchrone netwerkverzoeken in webapplicaties. Richt je op doorvoersnelheid, complexiteit en geheugengebruik."

Resultaat op Llama-3.1-8B-Instruct (Q4_K_M op RTX 4060):

Het model genereert een gestructureerde respons met een verwerkingssnelheid van circa 48 tokens per seconde. De prompt-evaluatie (het inlezen van de invoer) verloopt met meer dan 400 tokens per seconde dankzij cuBLAS Flash Attention. De output toont correcte Nederlandse grammatica en een heldere scheiding tussen de gevraagde criteria.

Foutoplossing en bekende knelpunten

Ondanks de stabiliteit van Kobold.cpp kunnen er situaties optreden waarin het model niet start of onverwacht traag presteert. Als je tegen hardnekkige foutmeldingen aanloopt, bekijk dan de uitgebreide probleemoplosser voor out-of-memory meldingen, trage tokens en GPU-detectieproblemen.

De meest voorkomende operationele knelpunten en hun directe oplossingen:

1. CUDA Out of Memory (OOM): De allocatie van lagen overschrijdt het fysieke VRAM. Verlaag --gpulayers met 2 tot 4 stappen of verklein de --contextsize van bijvoorbeeld 8192 naar 4096 tokens.

2. Extreem lage generatiesnelheid (1-2 tokens/s): Dit duidt erop dat het model volledig op de CPU draait of dat er geheugenswapping plaatsvindt tussen RAM en schijf. Controleer of de juiste backend (cuBLAS, ROCm of Metal) actief is en of --usecublas is meegegeven.

3. Crashes bij het laden van grote contexten: Schakel de vlag --no-mmap in als je schijf traag reageert of als het virtuele geheugen van het besturingssysteem volloopt tijdens het mappen van het GGUF-bestand.

Conclusie en volgende stappen in je lokale opstelling

Kobold.cpp biedt een van de meest betrouwbare en lichte manieren om GGUF-taalmodellen lokaal te draaien. Door de afwezigheid van complexe achtergrondservices en de directe controle over GPU-offloading en contextverschuiving is het een uitstekende basis voor zowel beginners als gevorderde gebruikers die maximale controle over hun hardware willen behouden.