Schnellstart von llama.cpp mit CLI und Server

llama.cpp ist eine C/C++-Inferenz-Engine für GGUF-Modelle: llama-cli für interaktive Chats, llama-completion für skriptgesteuerte Prompts und llama-server für eine OpenAI-kompatible HTTP-API.

Falls Sie sich noch zwischen lokalen, selbst gehosteten und Cloud-Ansätzen entscheiden, beginnen Sie mit dem Grundlagenguide LLM-Hosting im Jahr 2026: Lokale, Selbst-gehostete & Cloud-Infrastrukturen im Vergleich.

Warum llama.cpp im Jahr 2026

llama.cpp ist eine leichte Inferenz-Engine mit einer Ausrichtung auf:

• Portabilität über CPUs und mehrere GPU-Backends,
• vorhersagbare Latenz auf einem einzelnen Rechner,
• flexible Bereitstellung, von Laptops bis hin zu On-Premise-Knoten.

Es glänzt, wenn Sie Datenschutz und Offline-Betrieb wünschen, wenn Sie eine deterministische Kontrolle über Laufzeitflags benötigen oder wenn Sie Inferenz in ein größeres System einbetten möchten, ohne einen vollständigen Python-lastigen Stack auszuführen.

Es ist auch hilfreich, llama.cpp zu verstehen, selbst wenn Sie später einen Server-Laufzeitprozess mit höherer Durchsatzleistung wählen. Wenn Ihr Ziel beispielsweise maximaler Servicedurchsatz auf GPUs ist, sollten Sie es möglicherweise mit vLLM vergleichen, indem Sie Folgendes verwenden: vLLM Quickstart: Hochleistungs-LLM-Serving und Sie können Werkzeugauswahlen in Folgendem benchmarken: Ollama vs. vLLM vs. LM Studio: Bester Weg, LLMs lokal im Jahr 2026 auszuführen?.

Wenn Ollama speziell der zu überlegende Alternative zu llama-server ist, ist llama.cpp vs. Ollama im Jahr 2026 der dedizierte Paarevergleich, mit konkreten Auslösern dafür, wann Sie bei Ollama bleiben und wann Sie zu direktem llama.cpp wechseln sollten.

llama.cpp auf Windows, macOS und Linux installieren

Die folgenden Befehle entsprechen llama.cpp v0.6.0 (5. Oktober 2026). Ein Katalogeintrag für dieselbe Laufzeitumgebung – GGUF-Inferenz auf CPU- und Beschleunigerbackends, versioniert nach Build-Commit – finden Sie in der llama.cpp-Laufzeitreferenz auf LLM Systems. Es gibt vier praktische Installationswege, abhängig davon, ob Sie Bequemlichkeit, Portabilität oder maximale Leistung wünschen.

Installation über Paketmanager

Dies ist die schnellste Option, um „es zum Laufen zu bringen“.

# macOS oder Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

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

# Ubuntu (universe). Dieses Paket hinkt dem Upstream weit hinterher:
# 8681+dfsg gegenüber dem aktuellen Build b11433 / v0.6.0, daher fehlen neuere Flags.
sudo apt install llama.cpp-tools

Tipp: Prüfen Sie nach der Installation, ob die Werkzeuge vorhanden sind:

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

Installation über vorgefertigte Binärdateien

Wenn Sie eine saubere Installation ohne Compiler wünschen, verwenden Sie die offiziellen vorgefertigten Binärdateien, die in den llama.cpp-GitHub-Releases veröffentlicht werden. Diese decken in der Regel mehrere Betriebssystemziele und mehrere Backends ab (Variante nur für CPU und GPU-fähige Varianten).

Ein häufiger Arbeitsablauf:

# 1) Das richtige Archiv für Ihr Betriebssystem und Backend herunterladen
# 2) Entpacken
# 3) Aus dem entpackten Ordner ausführen

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

Den offiziellen Container ausführen

Das Projekt veröffentlicht Server-Images im GitHub Container Registry. Das CPU-Image ist ghcr.io/ggml-org/llama.cpp:server; das CUDA-Image ist :server-cuda. Der Container muss auf allen Schnittstellen lauschen, da die Standardbindung immer noch 127.0.0.1 ist:

docker run --gpus all -p 8080:8080 \
  -v /path/to/models:/models \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/my-model.gguf -c 4096 --host 0.0.0.0 -ngl all

Build aus dem Quellcode für Ihre exakte Hardware

Wenn Sie das beste Performance-Potenzial aus Ihrem CPU-/GPU-Backend herausholen möchten, bauen Sie den Quellcode mit CMake.

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

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

Nach dem Build befinden sich die Binärdateien typischerweise hier:

ls -la ./build/bin/

GPU-Builds in einem Befehl

Aktivieren Sie das Backend, das zu Ihrer Hardware passt (Beispiele für CUDA und 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: Vollständiger Build-Gang

Auf Ubuntu 24.04 mit einer NVIDIA-GPU benötigen Sie vor dem Build das CUDA-Toolkit und OpenSSL. Hier ist eine getestete Abfolge:

1. CUDA-Toolkit 13.1 installieren. Dieser Walkthrough pinnt den lokalen Installer 13.1.1. Ein neueres Toolkit aus dem Ubuntu-24.04-Repository von NVIDIA folgt den gleichen Pin-Datei- und lokalen-deb-Schritten mit aktualisierten Dateinamen.

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. CUDA zu Ihrer Umgebung hinzufügen (an ~/.bashrc anhängen):

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

Führen Sie dann source ~/.bashrc aus oder öffnen Sie ein neues Terminal.

3. OpenSSL-Entwicklungsheaders installieren (erforderlich für einen sauberen Build):

sudo apt update
sudo apt install libssl-dev

4. llama.cpp bauen (aus dem Verzeichnis, das Ihr llama.cpp-Clone enthält, mit aktiviertem CUDA):

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

Dadurch werden llama-cli, llama-mtmd-cli, llama-server, llama-embedding und llama-gguf-split im llama.cpp-Verzeichnis erstellt.

Sie können auch mehrere Backends kompilieren und Geräte zur Laufzeit auswählen. Dies ist nützlich, wenn Sie denselben Build auf heterogenen Maschinen ausrollen.

GGUF-Modell und Quantisierung auswählen

Um Inferenz auszuführen, benötigen Sie eine GGUF-Modelldatei (*.gguf). GGUF ist ein Ein-Datei-Format, das Modellgewichte plus standardisierte Metadaten bündelt, die von Engines wie llama.cpp benötigt werden.

Zwei Möglichkeiten, ein Modell zu erhalten

Option A: Eine lokale GGUF-Datei verwenden

Laden Sie eine GGUF herunter oder kopieren Sie sie in ./models/:

mkdir -p models
# Platzieren Sie Ihre GGUF unter models/my-model.gguf

Führen Sie sie dann über den Pfad aus:

llama-cli -m models/my-model.gguf -p "Hallo! Erkläre, was llama.cpp ist." -n 128 -st

Option B: llama.cpp vom Hugging Face herunterladen lassen

Moderne llama.cpp-Builds können von Hugging Face herunterladen und Dateien in einem lokalen Cache behalten. Dies ist oft der einfachste Arbeitsablauf für schnelle Experimente.

# Modell von HF herunterladen und einen Prompt ausführen
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "Es war einmal," \
  -n 200 \
  -st

Sie können auch die Quantisierung im Repository-Auswahltool angeben und dem Tool die Auswahl einer passenden Datei überlassen:

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Fassen Sie das Konzept der Quantisierung in einem Absatz zusammen." \
  -n 160 \
  -st

Wenn Sie später einen vollständig offline-fähigen Arbeitsablauf benötigen, erzwingt --offline die Verwendung des Caches und verhindert Netzwerkzugriffe.

Quantisierungswahl für lokale Inferenz

Quantisierung ist die praktische Antwort auf die Frage „Welche GGUF-Quantisierung sollten Sie für lokale Inferenz wählen“, da sie direkt einen Trade-off zwischen Qualität, Modellgröße und Geschwindigkeit darstellt.

Ein pragmatiser Ausgangspunkt:

• Beginnen Sie mit einer Q4- oder Q5-Variante für CPU-lastige Maschinen,
• Wechseln Sie zu höherer Präzision (oder weniger aggressiver Quantisierung), wenn Sie den RAM oder VRAM dafür aufbringen können,
• Wenn das Modell für Ihre Aufgabe „dumm wirkt“, liegt die Lösung oft in einem besseren Modell oder einer weniger aggressiven Quantisierung, nicht nur in Sampling-Anpassungen.

Denken Sie auch daran, dass die Kontextfenstergröße wichtig ist: Größere Kontextgrößen erhöhen den Speicherverbrauch (manchmal drastisch), selbst wenn die GGUF-Datei selbst passt.

llama-cli Quickstart und wichtige Parameter

llama-cli ist der schnellste Weg, um zu validieren, dass Ihr Modell geladen wird, Ihr Backend funktioniert und Ihre Prompts funktionieren.

llama-cli ist seit dem Neuschreiben im Dezember 2025 ein interaktiver Chat-Client. Wenn das Modell eine Chat-Vorlage mitliefert, ist der Gesprächsmodus standardmäßig aktiviert und --no-conversation wird mit einem Hinweis auf llama-completion abgelehnt. Dieses zweite Binärprogramm ist das alte llama-cli: ein Prompt herein, eine Vervollständigung heraus, geeignet für Skripte und Pipes. Aus dem neuen Client heraus erzeugt --single-turn (-st) eine Antwort und beendet sich.

Eine Antwort, dann beenden

llama-cli \
  -m models/my-model.gguf \
  -p "Schreibe einen kurzen Vergleich von TCP vs. UDP." \
  -n 200 \
  -st

Derselbe Prompt über das nicht-interaktive Binärprogramm:

llama-completion \
  -m models/my-model.gguf \
  -p "Schreibe einen kurzen Vergleich von TCP vs. UDP." \
  -n 200 \
  --no-conversation

Interaktiver Chat-Lauf

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Du bist ein präziser System Engineering Assistent." \
  --ctx-size 4096

--conversation ist nicht mehr erforderlich. Um die Generierung zu beenden, wenn das Modell eine bestimmte Sequenz ausgibt, verwenden Sie einen Reverse Prompt.

Die wichtigsten llama-cli-Flags, die zählen

Konzentrieren Sie sich darauf, diejenigen, die Richtigkeit, Latenz und Speicher dominieren, statt 200 Flags auswendig zu lernen.

Modell und Download

Kontext und Durchsatz

GPU-Offload und Hardwareauswahl

Sampling und Ausgabequalität

Beispiel-Workloads mit llama-cli

Eine Datei zusammenfassen, nicht nur einen Prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Sie fassen technische Dokumente zusammen. Ausgabe maximal fünf Punkte." \
  --file ./docs/incident-report.txt \
  -n 300 \
  -st

Ergebnisse reproduzierbarer machen

Wenn Sie Prompts debuggen, fixieren Sie den Seed und reduzieren Sie die Zufälligkeit:

llama-cli \
  -m models/my-model.gguf \
  -p "Extrahieren Sie die wichtigsten Risiken aus diesem Design-Notiz." \
  -n 200 \
  --seed 42 \
  --temp 0.2 \
  -st

llama-server Quickstart mit OpenAI-kompatibler API

llama-server ist ein eingebauter HTTP-Server, der Folgendes bereitstellen kann:

• OpenAI-kompatible Endpunkte für Chat, Vervollständigungen, Embeddings und Antworten,
• eine Web-UI für interaktive Tests,
• optionale Monitoring-Endpunkte für Produktionsvisibilität.

Einen Server mit einem lokalen Modell starten

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

Standardmäßig lauscht er auf 127.0.0.1:8080.

Um extern zu binden (z. B. innerhalb von Docker oder einem LAN), geben Sie Host und Port an:

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

Optionale, aber wichtige Server-Flags

Wenn Sie in Containern laufen, können viele Einstellungen auch über LLAMA_ARG_*-Umgebungsvariablen gesteuert werden.

Beispiel-API-Aufrufe

Chat-Vervollständigungen mit 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": "Sie sind ein hilfsbereiter Assistent." },
      { "role": "user", "content": "Geben Sie mir eine kurze llama.cpp-Checkliste." }
    ],
    "temperature": 0.7
  }'

Tipp für echte Deployments: Wenn Sie --api-key setzen, können Sie es über einen x-api-key-Header senden (oder weiter die Authorization-Header verwenden, je nach Ihrem Gateway).

OpenAI-Python-Client, der auf llama-server zeigt

Mit einem OpenAI-kompatiblen Server können viele Clients funktionieren, indem nur base_url geändert wird – so sprechen auch Forschungsagenten wie lukeswade/deep-research direkt mit llama-server, ohne eine separate Adapter-Ebene. Selbst-gehostete Deep Research Systeme: 12 Werkzeuge im Vergleich behandelt dieses Projekt und andere, die auf OpenAI-kompatible lokale Endpunkte zeigen.

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": "Sie sind ein präziser Assistent."},
        {"role": "user", "content": "Erklären Sie Threads vs. Batch-Größe in llama.cpp."},
    ],
)

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

Embeddings

OpenAI-kompatible Embeddings werden unter /v1/embeddings bereitgestellt, aber das Modell muss einen Embedding-Pooling-Modus unterstützen, der nicht none ist.

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"
  }'

Wenn Sie ein dediziertes Embedding-Modell ausführen, erwägen Sie, den Server im nur-Embeddings-Modus zu starten:

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

oder wenn Sie llama-cpp mit einem Embedding-Modell auf der CPU ausführen möchten:

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

probieren Sie es so aus:

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

Mehrere Modelle aus einem Prozess bereitstellen

Die obigen Beispiele binden llama-server beim Start an ein einzelnes Modell. Wenn Sie zwischen Modellen auf Basis pro Anfrage wechseln müssen – ohne den Prozess neu zu starten – ist das genau der Zweck des Router-Modus. Siehe llama-server Router-Modus: Dynamischer Modellwechsel ohne Neustarts. Für einen skriptbaren Unload-all-Flow, der VRAM freigibt, ohne den Router neu zu starten, siehe Alle llama.cpp-Router-Modelle entladen, ohne neu zu starten.

Leistung, Monitoring und Produktion-Härtung

Die FAQ-Frage „Welche llama.cpp-Befehlszeilenoptionen sind für Geschwindigkeit und Speicher am wichtigsten“ wird viel einfacher, wenn man Inferenz wie ein System behandelt:

• Speicherdecke ist in der Regel die erste Einschränkung (RAM auf CPU, VRAM auf GPU).
• Kontextgröße ist ein großer Speicher-Multiplikator.
• GPU-Ebenen-Offload ist oft der schnellste Weg zu höheren Tokens pro Sekunde.
• Batch-Größen und Threads können den Durchsatz verbessern, können aber auch den Speicherverbrauch erhöhen.

Für eine tiefere, engineering-first-Perspektive, siehe: LLM-Leistung im Jahr 2026: Benchmarks, Engpässe & Optimierung.

Wenn Sie gemessene llama-cli-ähnliche Ergebnisse auf einer 16-GB-Klasse-GPU wünschen – Tokens pro Sekunde, VRAM und GPU-Last bei der Durchsuchung des Kontexts (19K / 32K / 64K) über dichte und MoE-GGUFs – siehe 16-GB-VRAM-LLM-Benchmarks mit llama.cpp (Geschwindigkeit und Kontext).

Für Qwen 3.6 unterstützt llama.cpp die eingebaute Multi-Token-Prediction-Spekulative-Dekodierung. Schalten Sie sie mit --spec-type draft-mtp ein; --spec-draft-n-max legt fest, wie viele Token der Draft-Kopf vorschlägt (Standard 3). v0.6.0 erweitert denselben MTP-Pfad auf Qwen4Exp. Für den Methodenvergleich, siehe Spekulative Dekodierung. Für gemessene Qwen 3.6-Zahlen auf 16 GB, siehe Qwen 3.6 MTP vs. Standard auf 16GB-GPU.

llama-server mit Prometheus und Grafana überwachen

llama-server stellt Prometheus-kompatible Metriken unter /metrics nur bereit, wenn --metrics aktiviert ist. Richten Sie einen Prometheus-Scrape-Job auf diesen Pfad. Dashboards und Alarm-Schwellenwerte für llama.cpp, vLLM und TGI finden Sie in LLM-Inferenz in Produktion überwachen (2026): Prometheus & Grafana für vLLM, TGI, llama.cpp.

Basis-Härtungs-Checkliste

Wenn Ihr llama-server über den localhost erreichbar ist:

• verwenden Sie --api-key (oder --api-key-file), damit Anfragen authentifiziert werden,
• vermeiden Sie das Binden an 0.0.0.0, es sei denn, Sie benötigen es,
• erwägen Sie TLS über die SSL-Flags des Servers oder Terminierung von TLS an einem Reverse Proxy,
• beschränken Sie die Parallelität mit --parallel, um die Latenz unter Last zu schützen,
• lassen Sie --tools und --agent aus. Beide sind experimentell und stellen Datei- und Shell-Operationen über die API bereit; das Aktivieren einer von beiden beschränkt auch CORS auf localhost.

Troubleshooting: Schnelle Lösungen

Das Modell lädt, aber die Antworten sind seltsam im Chat

Chat-Endpunkte funktionieren am besten, wenn das Modell eine unterstützte Chat-Vorlage hat. Wenn die Ausgaben unstrukturiert aussehen, versuchen Sie Folgendes:

• einen expliziten --system-prompt übergeben (der Gesprächsmodus ist in llama-cli bereits Standard),
• sicherstellen, dass Ihr Modell eine instruktions- oder chat-abgestimmte Variante ist,
• das Testen mit der Server-Web-UI, bevor Sie es in eine App einbinden. v0.6.0 hat diese UI mit einem Hugging Face Hub-Browser neu aufgebaut, sodass ein Modell von der Seite heruntergeladen werden kann, nicht nur von der CLI.

Denkmodelle wickeln die Antwort in Reasoning-Traces ein. --reasoning off unterdrückt das, und --reasoning-format deepseek verschiebt den Trace in reasoning_content statt in content.

Sie stoßen auf Speicherüberlauf

Reduzieren Sie den Kontext oder wählen Sie eine kleinere Quantisierung:

• senken Sie --ctx-size,
• reduzieren Sie --n-gpu-layers, wenn VRAM das Problem ist, oder setzen Sie --cpu-moe, damit die Experten-Gewichte eines MoE-Modells im RAM bleiben,
• wechseln Sie zu einem kleineren Modell oder einer stärker komprimierten Quantisierung,
• quantisieren Sie den KV-Cache mit --cache-type-k q8_0 --cache-type-v q8_0.

Der Kontext oder die GPU-Aufteilung ist nicht das, was Sie wollten

--fit ist standardmäßig aktiv und überschreibt Speichereinstellungen, die Sie nicht gesetzt haben, mit dem Ziel, 1024 MiB auf jedem Gerät frei zu lassen (--fit-target). Es verkleinert den Kontext, aber nie unter --fit-ctx (4096) und nur, wenn Sie -c nicht übergeben haben. Es berührt die Ebenenplatzierung nicht, sobald Sie -ngl übergeben. --fit off deaktiviert den Mechanismus. Wenn die Logs n_gpu_layers already set by user sagen, ist Ihr explizites -ngl das, was geladen wurde, und fit wird keinen Speicherüberlauf daraus retten.

Es ist langsam auf der CPU

Beginnen Sie mit:

• --threads gleich Ihren physischen Kernen,
• moderate Batch-Größen,
• Validierung, dass Sie einen Build installiert haben, der zu Ihrer Maschine passt (CPU-Funktionen und Backend).

Referenzen

• Offizielles llama.cpp-Repository und Dokumentation
• Offizielle CLI-Flags-Dokumentation
• Offizielle llama-server-Dokumentation und API-Details