llama.cpp Quickstart met CLI en Server

Ik kom steeds terug bij llama.cpp voor lokale inferentie — het geeft je controle die Ollama en anderen abstracten, en het werkt gewoon. Eenvoudig om GGUF-modellen interactief te draaien met llama-cli of een OpenAI-compatibele HTTP API te tonen met llama-server.

Als je nog steeds twijfelt tussen lokale, zelfgehoste en cloudbenaderingen, begin dan met de pijlerhandleiding LLM Hosting in 2026: Local, Self-Hosted & Cloud Infrastructure Compared.

Waarom llama.cpp in 2026

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

• draagbaarheid over CPUs en meerdere GPU-backends,
• voorspelbare latentie op één machine,
• implementatieflexibiliteit, van laptops tot on-prem nodes.

Het schijnt wanneer je privacy en offlinebediening wilt, wanneer je deterministische controle over runtime-flags nodig hebt, of wanneer je wil dat inferentie wordt ingebed in een groter systeem zonder een volledige Python-heavy stack te draaien.

Het is ook nuttig om llama.cpp te begrijpen, zelfs als je later een hogedoorstromende serverruntime kiest. Bijvoorbeeld, als je doel is de maximale doorstroming op GPUs te bereiken, dan wil je mogelijk ook vergelijken met vLLM met behulp van: vLLM Quickstart: High-Performance LLM Serving en je kunt benchmarktoolkeuzes testen in: Ollama vs vLLM vs LM Studio: Best Way to Run LLMs Locally in 2026?.

Installeer llama.cpp op Windows, macOS en Linux

Er zijn drie praktische installatiepaden, afhankelijk van of je gemak, draagbaarheid of maximale prestaties wilt.

Installeer via pakketbeheerders

Dit is de snelste optie om het te laten draaien.

# 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: na installatie, controleer of de tools bestaan:

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

Installeer via vooraf gebouwde binairbestanden

Als je een schone installatie zonder compilers wilt, gebruik dan de officiële vooraf gebouwde binairbestanden die zijn gepubliceerd in de llama.cpp GitHub releases. Ze dekken meestal meerdere OS-doelen en meerdere backends (alleen CPU en GPU-geenablede varianten).

Een gebruikelijke workflow:

# 1) Download het juiste archief voor je OS en backend
# 2) Extraheer het
# 3) Voer het uit vanuit het geëxtraheerde map

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

Bouw vanuit de bron voor jouw exacte hardware

Als je geïnteresseerd bent in het uithalen van de beste prestaties uit je CPU/GPU backend, 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 de build, bevinden de binairbestanden zich meestal hier:

ls -la ./build/bin/

GPU builds in één opdracht

Schakel de backend in die overeenkomt met jouw hardware (voorbeelden gegeven 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 voor het bouwen. Hier is een geteste sequentie:

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

Daarna voer je source ~/.bashrc uit of open een nieuw terminalvenster.

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

sudo apt update
sudo apt install libssl-dev

4. Bouw llama.cpp (vanuit de map met jouw llama.cpp clone, 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
cp llama.cpp/build/bin/llama-* llama.cpp

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

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

Kies een GGUF-model en een kwantisatie

Om inferentie te draaien, heb je een GGUF-modelfile (*.gguf) nodig. GGUF is een enkelbestandsformaat dat modelgewichten plus standaardiseerde metadata bevat die nodig zijn voor engines zoals llama.cpp.

Twee manieren om een model te krijgen

Optie A: Gebruik een lokale GGUF-bestand

Download of kopieer een GGUF naar ./models/:

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

Dan draai je het via pad:

llama-cli -m models/my-model.gguf -p "Hallo! 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 houden bestanden in een lokale cache. Dit is vaak de makkelijkste workflow voor snelle experimenten.

# Download een model van HF en draai een prompt
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Er was eens," \
  -n 200

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

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

Als je later een volledig offline workflow nodig hebt, zorgt --offline voor het gebruik van de cache en voorkomt netwerktoegang.

Kwantisatiekeuze voor lokale inferentie

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

Een pragmatische startpunt:

• begin met een Q4 of Q5 variant voor CPU-georiënteerde machines,
• verplaats naar hogere precisie (of minder agressieve kwantisatie) wanneer je de RAM of VRAM kunt betalen,
• wanneer het model “dum” voelt voor jouw taak, is de oplossing vaak een beter model of minder agressieve kwantisatie, niet alleen samplingaftasten.

Herinner je ook dat het contextvenster belangrijk is: grotere contextgrootte verhoogt het geheugengebruik (soms dramatisch), zelfs wanneer het GGUF-bestand zelf past.

llama-cli quickstart en belangrijke parameters

llama-cli is de snelste manier om te valideren dat je model geladen wordt, je backend werkt en je prompts gedragen.

Minimale run

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

Interactieve chat run

Conversatiemodus is ontworpen voor chat sjablonen. Het activeert meestal interactieve gedrag en vormt prompts volgens het model sjabloon.

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

Om generatie te beëindigen wanneer het model een specifieke reeks print, gebruik je een omgekeerde prompt. Dit is vooral handig in interactieve modus.

Belangrijke llama-cli vlaggen

In plaats van 200 vlaggen te onthouden, concentreer je op deze die overheersen correctheid, latentie en geheugen.

Model en download

Context en doorstroming

GPU-afschuiving en hardwarekeuze

Sampling en uitvoerkwaliteit

Voorbeeldtaken met llama-cli

Samenvat een bestand, niet alleen een prompt

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

Maak resultaten herhaalbaarder

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

llama-cli \
  -m models/my-model.gguf \
  -p "Extraheer 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 tonen:

• OpenAI-compatibele eindpunten voor chat, compleeties, embeddings en reacties,
• een Web UI voor interactieve testen,
• optionele monitoringseindpunten voor productieoverzicht.

Start een server met een lokale 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 servervlaggen

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

Voorbeeld API-aanroepen

Chat compleeties 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 blijf je Authorization headers gebruiken afhankelijk van jouw gateway).

OpenAI Python client gericht op llama-server

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

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 concie assistent."},
        {"role": "user", "content": "Leg threads vs batch size in llama.cpp uit."}
    ],
)

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

Embeddingen

OpenAI-compatibele embeddingen worden getoond op /v1/embeddings, maar het model moet een embedding pooling modus 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 specifieke embedding model draait, overweeg dan de server in embedding-only mode te starten:

llama-server \
  -m models/my-embedding-model.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --port 8080

Prestaties, monitoring en productieversterking

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

• Geheugengrens is meestal de eerste beperking (RAM op CPU, VRAM op GPU).
• Contextgrootte is een belangrijke geheugenvermenigvuldiger.
• GPU-laagafschuiving is vaak de snelste weg naar hogere tokens per seconde.
• Batchgroottes en threads kunnen doorstroming verbeteren, maar kunnen ook geheugenbelasting verhogen.

Voor een dieper, engineering-georiënteerde view, zie: LLM Performance in 2026: Benchmarks, Bottlenecks & Optimization.

Monitoring van llama-server met Prometheus en Grafana

llama-server kan Prometheus-compatibele metrieken tonen op /metrics wanneer --metrics is ingeschakeld. Dit combineert natuurlijk met Prometheus scrape configuraties en Grafana dashboards.

Voor dashboards en waarschuwingen specifiek voor llama.cpp (en vLLM, TGI): Monitor LLM Inference in Production (2026): Prometheus & Grafana voor vLLM, TGI, llama.cpp. Breder gidsen: Observability: Monitoring, Metrics, Prometheus & Grafana Guide en Observability for LLM Systems.

Basisversterking checklist

Wanneer jouw llama-server bereikbaar is buiten localhost:

• gebruik --api-key (of --api-key-file) zodat aanvragen geauthenticeerd zijn,
• vermijd het binden aan 0.0.0.0 tenzij je het echt nodig hebt,
• overweeg TLS via de servers SSL-vlaggen of beëindig TLS op een reverse proxy,
• beperk concurrentie met --parallel om latentie onder belasting te beschermen.

Snelle oplossingen voor het oplossen van problemen

Het model laadt, maar de antwoorden zijn vreemd in chat

Chat eindpunten zijn het beste wanneer het model een ondersteunde chat sjabloon heeft. Als de uitvoer ongestructureerd lijkt, probeer dan:

• gebruik llama-cli --conversation plus een expliciete --system-prompt,
• controleer of je model een instructie- of chat-afgestemde variant is,
• test met de server Web UI voordat je het aansluit op een app.

Je raakt uitgeput aan geheugen

Verlaag de context of kies een kleiner kwantiseer:

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

Het is traag op CPU

Begin met:

• --threads gelijk aan jouw fysieke kernen,
• matige batchgroottes,
• valideren dat je een build geïnstalleerd hebt die overeenkomt met jouw machine (CPU kenmerken en backend).

Referenties

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