Snelstart van llama.cpp met CLI en server

Ik keer steeds terug naar llama.cpp voor lokale inferentie: het geeft je controle die Ollama en anderen abstracteren, en het werkt gewoon. Het is eenvoudig om GGUF-modellen interactief uit te voeren met llama-cli of een OpenAI-compatibele HTTP-API bloot te stellen met llama-server.

Als je nog steeds besluit tussen lokale, zelf-gehoste en cloud-aanpakken, begin dan met de pijlergids LLM-hosting in 2026: Lokaal, zelf-gehost en cloud-infrastructure vergeleken.

Waarom llama.cpp in 2026

llama.cpp is een lichtgewicht inferentie-engine met een voorkeur voor:

• portabiliteit over CPUs en meerdere GPU-backends,
• voorspelbare latentie op een enkele machine,
• flexibiliteit in implementatie, van laptops tot on-prem nodes.

Het blinkt uit als je privacy en offline-werkzaamheid wilt, als je deterministische controle nodig hebt over runtime-vlaggen, of als je inferentie wilt integreren in een groter systeem zonder een volledige Python-zware stack te draaien.

Het is ook nuttig om llama.cpp te begrijpen, zelfs als je later kiest voor een server-runtime met hogere doorvoer. Als je doel bijvoorbeeld maximale server-doorvoer op GPUs is, kun je het ook vergelijken met vLLM via: vLLM Quickstart: High-Performance LLM Serving en je kunt toolkeuzes benchmarken in: Ollama vs vLLM vs LM Studio: Beste manier om LLM’s lokaal uit te voeren in 2026?.

Installeer llama.cpp op Windows, macOS en Linux

Er zijn drie praktische installatiemethoden, afhankelijk van of je gemak, portabiliteit of maximale prestaties wilt.

Installeren via pakketmanagers

Dit is de snelste “het draaien” optie.

# macOS of Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS of Linux (Nix)
nix profile install nixpkgs#llama-cpp

Tip: controleer na installatie of de tools bestaan:

llama-cli --version
llama-server --version

Installeren via vooraf gemaakte binaries

Als je een schone installatie wilt zonder compilers, gebruik dan de officiële vooraf gemaakte binaries die in de llama.cpp GitHub-releases zijn gepubliceerd. Deze dekken doorgaans meerdere OS-doelen en meerdere backends (CPU-only en GPU-geschakelde varianten).

Een gebruikelijke workflow:

# 1) Download het juiste archief voor je OS en backend
# 2) Pak het uit
# 3) Voer het uit in de uitgepakte map

./llama-cli --help
./llama-server --help

Bouwen vanuit bron voor je exacte hardware

Als je erop uit bent om de beste prestaties uit je CPU/GPU-backend te halen, bouw dan vanuit de bron met CMake.

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# CPU-build
cmake -B build
cmake --build build --config Release

Na het bouwen bevinden de binaries zich doorgaans hier:

ls -la ./build/bin/

GPU-builds in één commando

Schakel de backend in die bij je hardware hoort (voorbeelden getoond voor CUDA en Vulkan):

# NVIDIA CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Vulkan
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Ubuntu 24.04 + NVIDIA GPU: volledige build-walkthrough

Op Ubuntu 24.04 met een NVIDIA GPU heb je de CUDA-toolkit en OpenSSL nodig voordat je begint. Hier is een geteste volgorde:

1. Installeer CUDA-toolkit 13.1

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

2. Voeg CUDA toe aan je omgeving (voeg toe aan ~/.bashrc):

# cuda toolkit
export PATH=/usr/local/cuda-13.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64:$LD_LIBRARY_PATH

Voer vervolgens source ~/.bashrc uit of open een nieuw terminalvenster.

3. Installeer OpenSSL-development-headers (vereist voor een schone build):

sudo apt update
sudo apt install libssl-dev

4. Bouw llama.cpp (vanuit de map die je llama.cpp-clone bevat, met CUDA ingeschakeld):

cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

Dit produceert llama-cli, llama-mtmd-cli, llama-server, llama-embedding en llama-gguf-split in de llama.cpp-map.

Je kunt ook meerdere backends compileren en apparaten tijdens runtime kiezen. Dit is handig als je dezelfde build op heterogene machines implementeert.

Kies een GGUF-model en een kwantisatie

Om inferentie uit te voeren, heb je een GGUF-modelbestand (*.gguf) nodig. GGUF is een enkel-bestandsformaat dat modelgewichten bundelt plus gestandaardiseerde metadata die nodig is voor engines zoals llama.cpp.

Twee manieren om een model te krijgen

Optie A: Gebruik een lokaal GGUF-bestand

Download of kopieer een GGUF naar ./models/:

mkdir -p models
# Plaats je GGUF op models/my-model.gguf

Voer het vervolgens uit via pad:

llama-cli -m models/my-model.gguf -p "Hello! Leg uit wat llama.cpp is." -n 128

Optie B: Laat llama.cpp downloaden van Hugging Face

Moderne llama.cpp-builds kunnen downloaden van Hugging Face en bestanden in een lokale cache houden. Dit is vaak de eenvoudigste workflow voor snelle experimenten.

# Download een model van HF en voer een prompt uit
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Eens in een tijd," \
  -n 200

Je kunt ook de kwantisatie specificeren in de repo-selector en de tool een overeenkomend bestand laten selecteren:

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Samenvatten van het concept van kwantisatie in één alinea." \
  -n 160

Als je later een volledig offline-werkflow nodig hebt, forceert --offline het gebruik van de cache en voorkomt toegang tot het netwerk.

Kwantisatiekeuze voor lokale inferentie

Kwantisatie is het praktische antwoord op de vraag “Welke GGUF-kwantisatie moet je kiezen voor lokale inferentie” omdat het direct afweegt tussen kwaliteit, modelgrootte en snelheid.

Een pragmatisch startpunt:

• begin met een Q4- of Q5-variant voor CPU-first machines,
• ga over naar hogere precisie (of minder agressieve kwantisatie) als je de RAM of VRAM kunt betalen,
• als het model “dom” voelt voor je taak, is de oplossing vaak een beter model of een minder agressieve kwantisatie, niet alleen sampling-tweaks.

Onthoud ook dat contextvenster belangrijk is: grotere contextgroottes verhogen het geheugengebruik (soms dramatisch), zelfs als het GGUF-bestand zelf past.

llama-cli quickstart en belangrijke parameters

llama-cli is de snelste manier om te valideren dat je model laadt, je backend werkt en je prompts zich gedragen zoals verwacht.

Minimale run

llama-cli \
  -m models/my-model.gguf \
  -p "Schrijf een korte TCP vs UDP-vergelijking." \
  -n 200

Interactieve chat-run

Gespreksmodus is ontworpen voor chat-templates. Het schakelt doorgaans interactief gedrag in en formatteert prompts volgens de template van het model.

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "Je bent een bondige systeemengineer-assistent." \
  --ctx-size 4096

Om generatie te beëindigen wanneer het model een specifieke sequentie afdrukt, gebruik je een reverse-prompt. Dit is vooral nuttig in interactieve modus.

Belangrijkste llama-cli-vlaggen

In plaats van 200 vlaggen te onthouden, focus op degenen die correctheid, latentie en geheugen domineren.

Model en download

Context en doorvoer

GPU-offload en hardwareselectie

Sampling en outputkwaliteit

Voorbeeldwerklasten met llama-cli

Samenvatten van een bestand, niet alleen een prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Je vat technische documenten samen. Maximaal vijf bullets." \
  --file ./docs/incident-report.txt \
  -n 300

Maak resultaten reproduceerbaarder

Wanneer je prompts debugt, fix de seed en verminder willekeur:

llama-cli \
  -m models/my-model.gguf \
  -p "Haal belangrijke risico's uit deze ontwerpnoot." \
  -n 200 \
  --seed 42 \
  --temp 0.2

llama-server quickstart met OpenAI-compatibele API

llama-server is een ingebouwde HTTP-server die kan blootstellen:

• OpenAI-compatibele endpoints voor chat, completions, embeddings en responses,
• een Web UI voor interactief testen,
• optionele monitoring-endpoints voor productie-inzicht.

Start een server met een lokaal model

llama-server \
  -m models/my-model.gguf \
  -c 4096

Standaard luistert het op 127.0.0.1:8080.

Om extern te binden (bijvoorbeeld binnen Docker of een LAN), specificeer host en poort:

llama-server \
  -m models/my-model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

Optionele maar belangrijke server-vlaggen

Als je in containers draait, kunnen veel instellingen ook worden gecontroleerd via LLAMA_ARG_*-omgevingsvariabelen.

Voorbeeld API-aanroepen

Chat completions met curl

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "Je bent een behulpzame assistent." },
      { "role": "user", "content": "Geef me een snelle llama.cpp-checklist." }
    ],
    "temperature": 0.7
  }'

Tip voor echte implementaties: als je --api-key instelt, kun je deze sturen via een x-api-key-header (of blijven Authorization-headers gebruiken, afhankelijk van je gateway).

OpenAI Python-client gericht op llama-server

Met een OpenAI-compatibele server kunnen veel clients werken door alleen base_url te wijzigen.

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required",
)

resp = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "Je bent een bondige assistent."},
        {"role": "user", "content": "Leg threads vs batch size uit in llama.cpp."},
    ],
)

print(resp.choices[0].message.content)

Embeddings

OpenAI-compatibele embeddings zijn beschikbaar op /v1/embeddings, maar het model moet een embedding-poolingmodus ondersteunen die niet none is.

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["hello", "world"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

Als je een dedicated embedding-model draait, overweeg dan om de server in embeddings-only-modus te starten:

llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

of als je llama-cpp met embedding-model op CPU wilt draaien:

CUDA_VISIBLE_DEVICES="" llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

probeer het zo:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "je tekst hier" \
  --pooling last \
  --verbose-prompt

Meerdere modellen serveren vanuit één proces

De bovenstaande voorbeelden binden llama-server bij het opstarten aan één model. Als je per verzoek tussen modellen moet schakelen — zonder het proces te herstarten — is dat waar routermodus voor is. Zie llama-server routermodus: dynamisch modelwisselen zonder herstarts.

Prestaties, monitoring en productie-harding

De FAQ-vraag “Welke llama.cpp-commandoregelopties zijn het belangrijkst voor snelheid en geheugen” wordt veel eenvoudiger als je inferentie als een systeem behandelt:

• Geheugencel is meestal de eerste beperking (RAM op CPU, VRAM op GPU).
• Contextgrootte is een grote geheugenvermenigvuldiger.
• GPU-laag offload is vaak de snelste weg naar meer tokens per seconde.
• Batchgroottes en threads kunnen doorvoer verbeteren, maar kunnen ook de geheugendruk verhogen.

Voor een dieper, engineering-first perspectief, zie: LLM-prestaties in 2026: Benchmarks, Bottlenecks & Optimalisatie.

Als je gemeten llama-cli-stijl resultaten wilt op een GPU van de 16 GB-klasse — tokens per seconde, VRAM en GPU-belasting terwijl je context (19K / 32K / 64K) scant over dichte en MoE-GGUF’s — zie 16 GB VRAM LLM-benchmarks met llama.cpp (snelheid en context).

Monitoring van llama-server met Prometheus en Grafana

llama-server kan Prometheus-compatibele metriken blootstellen op /metrics wanneer --metrics is ingeschakeld. Dit past natuurlijk bij Prometheus scrap-configs en Grafana-dashboards.

Voor dashboards en alerts specifiek voor llama.cpp (en vLLM, TGI): Monitor LLM-inferentie in productie (2026): Prometheus & Grafana voor vLLM, TGI, llama.cpp. Brede gidsen: Observabiliteit: Monitoring, Metrieken, Prometheus & Grafana Gids en Observabiliteit voor LLM-systemen.

Basis hardening-checklist

Wanneer je llama-server bereikbaar is buiten localhost:

• gebruik --api-key (of --api-key-file) zodat verzoeken geauthenticeerd zijn,
• vermijd binding aan 0.0.0.0 tenzij je het nodig hebt,
• overweeg TLS via de SSL-vlaggen van de server of beëindig TLS bij een reverse proxy,
• beperk concurrentie met --parallel om latentie onder last te beschermen.

Snelle oplossingen voor probleemoplossing

Het model laadt maar antwoorden zijn vreemd in chat

Chat-endpoints zijn het beste als het model een ondersteunde chat-template heeft. Als outputs ongeordend lijken, probeer:

• llama-cli --conversation plus een expliciete --system-prompt te gebruiken,
• te verifiëren dat je model een instructie- of chat-gefineerde variant is,
• te testen met de server Web UI voordat je het in een app integreert.

Je stuit op out-of-memory

Verklein de context of kies een kleinere kwantisatie:

• verlaag --ctx-size,
• verlaag --n-gpu-layers als VRAM het probleem is,
• schakel over naar een kleiner model of een meer gecomprimeerde kwantisatie.

Het is traag op CPU

Begin met:

• --threads gelijk aan je fysieke kernen,
• matige batchgroottes,
• valideren dat je een build hebt geïnstalleerd die bij je machine past (CPU-functies en backend).

Referenties

• Officiële llama.cpp-repository en documentatie
• Officiële CLI-vlaggendocumentatie
• Officiële llama-server-documentatie en API-details