llama.cpp-Server mit Docker: LFM3 lokal auf der CPU betreiben

llama.cpp ist die Inferenz-Engine, auf der viele lokale KI-Werkzeuge aufbauen. Mit Version v0.8.0 vom 28. Oktober 2026 kommt die Unterstützung für LiquidAIs neue LFM3-Familie hinzu, dazu eine überarbeitete Web-UI und neue Server-Endpunkte für Audio. Diese Anleitung zeigt, wie Sie llama-server per Docker Compose auf einem Linux-Server ohne Grafikkarte betreiben: mit LFM3-1.7B, OpenAI-kompatibler API hinter einem API-Schlüssel, Weboberfläche, Update-Weg und geprüfter Sicherung.

Voraussetzungen

Für LFM3-1.7B in der Quantisierung Q4_K_M reicht ein kleiner Server. Planen Sie mindestens Folgendes ein:

• Linux-Server mit x86-64- oder ARM64-CPU und mindestens 4 Kernen, eine Grafikkarte ist nicht nötig
• 4 GB freien Arbeitsspeicher (der Container belegte mit 8.192 Token Kontext knapp 1 GB, das Limit im Compose-File liegt bei 4 GB)
• Rund 5 GB freien Speicherplatz für Image, Modell und eine Sicherung
• Docker Engine mit Docker Compose Plugin, eingerichtet wie in der Anleitung Docker Compose unter Linux als Selfhosting-Grundlage
• HTTPS-Zugriff auf ghcr.io und huggingface.co

Schritt 1: Das passende Image zu v0.8.0 finden

llama.cpp baut für jeden Commit auf dem Hauptzweig ein Build-Release mit fortlaufender Nummer (bNNNN). Die versionierten Releases wie v0.8.0 sind zusätzliche Markierungen auf einem dieser Builds. Einen Tag server-v0.8.0 gibt es in der Registry nicht (404). Welches Image passt, zeigt der Commit-Vergleich: v0.8.0 zeigt auf Commit 8642541 („bump version to 0.8.0“), und genau dieser Commit ist auch Build b11960. Das Image trägt die passenden Labels:

org.opencontainers.image.version   b11960
org.opencontainers.image.revision  8642541b255bfb5dc39cd351a178be09013a55d6
org.opencontainers.image.created   2026-10-28T12:40:49Z

Nicht jeder Build bekommt ein eigenes Server-Image. In der Registry folgen auf server-b11913 die Tags server-b11946 und server-b11960, neuere Builds wie b11974 haben bisher kein Server-Tag. Der Tag server-b11960 zeigt auf denselben Multi-Arch-Index (sha256:8052c13e…) wie der gleitende Tag :server zum Zeitpunkt des Releases. Schreiben Sie in Ihrer Konfiguration den festen Tag fest, nicht :server: Der gleitende Tag springt mit jedem neuen Server-Build weiter. Gegen nachträglich verschobene Tags hilft der Digest: ghcr.io/ggml-org/llama.cpp:server-b11960@sha256:8052c13edd987de8858f8150031e025ac3d66823f09cf3ec8220899c4abce220.

Verifizieren: Nach dem Start (Schritt 3) meldet der Container seine Version selbst:

docker compose exec llama /app/llama-server --version

version: 0.8.0-dev (build 11960, commit 8642541b2)
built with GNU 14.2.0 for Linux x86_64

Der Zusatz -dev stammt aus dem Build-System; Build-Nummer und Commit sind identisch mit dem Release.

Schritt 2: Projektordner, compose.yaml und .env anlegen

Legen Sie einen Ordner an, etwa /opt/llama, und darin die folgende compose.yaml. Das Modell liegt in einem benannten Volume, der Server liest Pfad, Alias, Kontext und Threads aus Umgebungsvariablen. Jede Kommandozeilen-Option hat eine solche Variable (LLAMA_ARG_…).

services:
  llama:
    image: ghcr.io/ggml-org/llama.cpp:${LLAMA_TAG}
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - models:/models
    environment:
      LLAMA_ARG_MODEL: /models/LFM3-1.7B-Q4_K_M.gguf
      LLAMA_ARG_ALIAS: lfm3-1.7b
      LLAMA_ARG_CTX_SIZE: 8192
      LLAMA_ARG_N_PARALLEL: 2
      LLAMA_ARG_THREADS: 4
      LLAMA_API_KEY: ${LLAMA_API_KEY}
    mem_limit: 4g

volumes:
  models:

Dazu die .env im selben Ordner. Den Schlüssel erzeugen Sie zufällig:

cat > .env <<EOF
LLAMA_TAG=server-b11960
LLAMA_API_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

Die wichtigsten Einstellungen im Überblick:

Einstellung	Wert	Bedeutung
Image	ghcr.io/ggml-org/llama.cpp:server-b11960	CPU-Variante, entspricht v0.8.0
Port	8080	API und Web-UI
Volume	models:/models	GGUF-Dateien
LLAMA_ARG_MODEL	/models/LFM3-1.7B-Q4_K_M.gguf	fester Modellpfad
LLAMA_ARG_ALIAS	lfm3-1.7b	Modellname in der API
LLAMA_ARG_CTX_SIZE	8192	Kontext gesamt, wird auf die Slots verteilt
LLAMA_ARG_N_PARALLEL	2	gleichzeitige Anfragen (Slots)
LLAMA_ARG_THREADS	4	CPU-Threads für die Berechnung
LLAMA_API_KEY	aus .env	Pflicht-Schlüssel für die API

Einen eigenen Healthcheck brauchen Sie nicht: Das Image bringt bereits einen mit (curl -f http://localhost:8080/health). Wie Sie Compose-Stacks darüber hinaus mit Secrets und Healthchecks härten, beschreibt Docker Compose absichern: Secrets, Healthchecks, Non-Root.

Verifizieren: docker compose config gibt die zusammengesetzte Konfiguration ohne Fehler aus, der Tag und ein 64-stelliger Schlüssel sind eingesetzt.

Schritt 3: Modell laden und Server starten

Das Image enthält curl. Damit laden Sie die GGUF-Datei direkt in das Volume, ohne etwas auf dem Host zu installieren:

docker compose run --rm --no-deps --entrypoint curl llama \
  -fL -o /models/LFM3-1.7B-Q4_K_M.gguf \
  https://huggingface.co/LiquidAI/LFM3-1.7B-GGUF/resolve/main/LFM3-1.7B-Q4_K_M.gguf
docker compose run --rm --no-deps --entrypoint sha256sum llama /models/LFM3-1.7B-Q4_K_M.gguf

Die Prüfsumme muss mit dem Wert auf der Hugging-Face-Seite übereinstimmen: 3793e1e6e2266919d6e015287221b41100175a98eddaba92e111aed3b05c93c4 bei 1.099.627.808 Byte. Alternativ kann llama-server Modelle selbst von Hugging Face holen (Option -hf bzw. Variable LLAMA_ARG_HF_REPO, Ablage im Cache-Verzeichnis). Der feste Dateipfad ist eindeutiger und einfacher zu sichern. LiquidAI nennt Build b11960 (v0.8.0) als Mindestversion für LFM3. Danach starten Sie den Dienst:

docker compose up -d
docker compose logs --no-log-prefix llama | grep -E "load_model|listening"

I srv    load_model: loading model '/models/LFM3-1.7B-Q4_K_M.gguf'
I srv    load_model: initializing, n_slots = 2, n_ctx_slot = 4096, kv_unified = 'false'
I srv  server_on_li: listening on http://0.0.0.0:8080

Verifizieren: docker compose ps zeigt den Dienst nach wenigen Sekunden als healthy, curl -s localhost:8080/health liefert {"status":"ok"}.

Schritt 4: OpenAI-kompatible API und API-Schlüssel prüfen

Prüfen Sie zuerst, dass der Schlüssel wirkt. Ohne oder mit falschem Schlüssel muss die API ablehnen, nur /health ist laut Dokumentation bewusst öffentlich:

curl -s -w ' %{http_code}\n' localhost:8080/health
curl -s -w ' %{http_code}\n' localhost:8080/v1/models
curl -s -w ' %{http_code}\n' -H 'Authorization: Bearer falsch' localhost:8080/v1/models

{"status":"ok"} 200
{"error":{"message":"Invalid API Key","type":"authentication_error","code":401}} 401
{"error":{"message":"Invalid API Key","type":"authentication_error","code":401}} 401

Mit Schlüssel liefert /v1/models das Modell unter seinem Alias, und /v1/chat/completions beantwortet Anfragen im OpenAI-Format.:

K=$(grep ^LLAMA_API_KEY= .env | cut -d= -f2)
curl -s -H "Authorization: Bearer $K" localhost:8080/v1/models | jq -r '.data[].id'
curl -s localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $K" -H 'Content-Type: application/json' \
  -d '{"model":"lfm3-1.7b","temperature":0.1,"max_tokens":200,"reasoning_effort":"none",
       "messages":[{"role":"user","content":"Erkläre in zwei Sätzen, wofür ein Reverse Proxy gut ist."}]}' \
  | jq -r '.choices[0].message.content'

lfm3-1.7b
Ein Reverse Proxy verbirgt die Endanfragen hinter einem Server und leitet sie an mehrere
Backend-Server weiter, was den Traffic zentralisiert, die Last verteilt und die Sicherheit erhöht. ...

Wichtig ist "reasoning_effort":"none": LFM3 denkt standardmäßig zuerst nach und liefert diesen Teil getrennt in reasoning_content. Ohne die Option brauchte dieselbe Frage 582 statt 70 Token, die Antwort war inhaltlich gleichwertig.

Verifizieren: Ohne Schlüssel 401, mit Schlüssel 200 und eine deutsche Antwort mit finish_reason stop.

Schritt 5: Die Web-UI nutzen

Unter http://SERVER:8080/ liefert llama-server eine Chat-Oberfläche aus. Die Seite selbst lädt ohne Schlüssel, alle Aufrufe dahinter laufen aber über dieselbe geschützte API. Den Schlüssel tragen Sie deshalb in den Einstellungen der Oberfläche im Feld „API Key“ ein, sonst bleibt die Modellliste leer. Pro Antwort zeigt sie Token-Zahl, Dauer und Geschwindigkeit.

Neu in v0.8.0 sind laut Release-Notes eine Suche über alle Konversationen, das Kompaktieren langer Unterhaltungen und das Durchsuchen und Herunterladen von Modellen direkt von Hugging Face. In der Modellverwaltung löscht der Menüpunkt „Delete from disk“ die Datei aus dem Volume, also Vorsicht.

Nutzbar ist nicht die angezeigte Trainingslänge, sondern LLAMA_ARG_CTX_SIZE geteilt durch die Zahl der Slots.

Verifizieren: Die Oberfläche zeigt unten das Modell lfm3 1.7B, eine Testfrage wird beantwortet und erscheint danach in der Suche.

Schritt 6: Ressourcen einschätzen und anpassen

Gemessen auf einem Testhost mit 16 Threads und Limit auf vier Threads:

Messwert	Ergebnis
Prompt-Verarbeitung	rund 107 Token/s (API), 129 Token/s (Web-UI)
Textgenerierung	rund 27 Token/s
RAM des Containers	938,7 MiB bei 8.192 Token Kontext und 2 Slots
Ladezeit des Modells	etwa 1 Sekunde

Setzen Sie LLAMA_ARG_THREADS höchstens auf die Zahl der physischen Kerne, die der Server für llama.cpp entbehren kann; andere Dienste auf dem Host brauchen ebenfalls Rechenzeit. Mehr Kontext und Slots kosten RAM; das mem_limit schützt andere Dienste. Welche Modellgröße zu welcher Hardware passt, vergleicht Ollama-Modelle nach VRAM und Quantisierung auswählen; die Faustregeln gelten für GGUF-Dateien in llama.cpp genauso.

Verifizieren: docker stats --no-stream zeigt den Speicherverbrauch des Containers, die Antwort der API enthält unter timings die Werte prompt_per_second und predicted_per_second.

Schritt 7: Auf ein neues Image aktualisieren

Ein Update ist ein Tausch des Tags in der .env. Im Test lief der Stack zuerst mit server-b11946 (Ausgabe 0.7.0-dev (build 11946, commit 8ca4060b7)) und wurde dann auf server-b11960 gehoben:

sed -i 's/^LLAMA_TAG=.*/LLAMA_TAG=server-b11960/' .env
docker compose pull
docker compose up -d
docker compose exec llama /app/llama-server --version

Compose meldet Recreate, der neue Container lädt dasselbe Modell aus dem Volume und war nach vier Sekunden wieder erreichbar. Nehmen Sie nur Tags der Form server-bNNNN und lesen Sie vorher die Release-Notes. Über neue Tags informiert Sie ein Werkzeug wie Diun, siehe Container-Updates mit Diun und WUD.

Verifizieren: --version zeigt die neue Build-Nummer, /health liefert 200 und /v1/models listet weiter lfm3-1.7b.

Schritt 8: Sichern und wiederherstellen

Der Server hält keine Datenbank. Was Sie verlieren können, sind die Modelldatei im Volume sowie compose.yaml und .env mit Tag und Schlüssel. Die Chats der Web-UI speichert der Browser. Die Sicherung läuft bei gestopptem Dienst über einen Hilfscontainer:

docker compose stop
mkdir -p backup && cp compose.yaml .env backup/
docker run --rm -v llama_models:/models:ro -v "$PWD/backup":/backup \
  alpine tar cf /backup/llama-models.tar -C /models .
docker run --rm -v llama_models:/models:ro alpine sha256sum /models/LFM3-1.7B-Q4_K_M.gguf

Den genauen Volume-Namen (Ordnername plus _models) zeigt docker volume ls. Für den Restore-Nachweis haben wir den Totalverlust simuliert: docker compose down -v löscht Container und Volume, danach existierte kein Volume mehr. Wiederherstellen:

docker compose up --no-start
docker run --rm -v llama_models:/models -v "$PWD/backup":/backup:ro \
  alpine tar xf /backup/llama-models.tar -C /models
docker run --rm -v llama_models:/models:ro alpine sha256sum /models/LFM3-1.7B-Q4_K_M.gguf
docker compose up -d

Die Prüfsumme vor und nach dem Restore war identisch (3793e1e6…c93c4). Zusätzlich lief ein Container ohne Netzwerk (--network none, LLAMA_ARG_OFFLINE=1) auf dem wiederhergestellten Volume: Er meldete nach sechs Sekunden {"status":"ok"}. Der reguläre Stack antwortete danach auf die Bitte „Antworte nur mit: Restore erfolgreich“ wörtlich mit Restore erfolgreich, im Log stand kein Download.

Verifizieren: Gleiche Prüfsumme vor und nach dem Restore, /health 200 und eine Antwort über /v1/chat/completions mit dem alten Schlüssel aus der gesicherten .env.

Troubleshooting

Symptom	Ursache	Lösung
failed to open GGUF file '/models/LFM3-1.7B-Q4_K_M.ggfu' (No such file or directory), Exit-Code 1	Tippfehler im Modellpfad oder Datei nicht im Volume	Pfad in LLAMA_ARG_MODEL prüfen, Inhalt mit docker compose run --rm --no-deps --entrypoint ls llama -l /models ansehen
HTTP 400 request (8111 tokens) exceeds the available context size (4096 tokens)	Kontext pro Slot zu klein (8.192 geteilt durch 2 Slots)	LLAMA_ARG_CTX_SIZE erhöhen oder LLAMA_ARG_N_PARALLEL auf 1 senken
HTTP 401 Invalid API Key	Header fehlt oder Schlüssel falsch	Authorization: Bearer <Schlüssel> senden, Wert aus der .env nehmen
Leere Antwort, finish_reasonlength	LFM3 hat das Token-Limit mit Nachdenken verbraucht	"reasoning_effort":"none" setzen oder max_tokens erhöhen
curl auf / liefert 415 Error: gzip is not supported by this browser	Die Web-UI wird nur komprimiert ausgeliefert	Kein Fehler: Browser senden Accept-Encoding: gzip, für Skripte /health nutzen

Lauscht der Server auf einem öffentlich erreichbaren Host, sperren Sie Port 8080 mit der Firewall (etwa ufw, siehe Linux-Server mit ufw und fail2ban absichern) und stellen Sie einen Reverse Proxy mit TLS davor. So empfiehlt es auch die Projektdokumentation.

Häufige Fragen

Warum nicht einfach Ollama?

Ollama bündelt eine eigene llama.cpp-Version, neue Architekturen kommen dort oft später an. Ollama 0.40.12 lieferte LFM3 nur als MLX-Variante für Apple-Hardware aus, auf Linux ließ sich das Modell damit noch nicht betreiben. llama-server unterstützt LFM3 ab v0.8.0 direkt.

Kann ich die GPU-Variante verwenden?

Ja, es gibt eigene Images wie server-cuda, server-vulkan oder server-rocm. Laut Dokumentation werden die GPU-Images in der CI nur gebaut, nicht getestet. Für CUDA brauchen Sie zusätzlich das NVIDIA Container Toolkit.

Was ist mit /tts und /v1/realtime?

Beide Endpunkte sind neu in v0.8.0 und für Audiomodelle gedacht, etwa LFM3-Audio-2B und LFM3-Omni-2B. /tts erzeugt Sprache aus Text, /v1/realtime setzt das Realtime-Protokoll von OpenAI für Gespräche und Transkription über WebSocket um. Mit einem reinen Textmodell wie LFM3-1.7B spielen sie keine Rolle.

Wie binde ich andere Werkzeuge an?

Basis-URL http://SERVER:8080/v1, Schlüssel aus der .env, Modell lfm3-1.7b.

Fazit

Mit v0.8.0 ist llama-server eine vollwertige Alternative zu Ollama für alle, die genau wissen wollen, welche Engine und welche Modelldatei laufen. Das Release-Image ist über Build-Nummer und Commit eindeutig zuzuordnen, ein fester Tag macht Updates planbar. LFM3-1.7B läuft auf vier CPU-Threads flott genug für interne Assistenten und Zusammenfassungen, die Sicherung umfasst nur Modelldatei und Konfiguration.

Weiterführende Anleitungen und Quellen

• EmbeddingGemma 2 lokal auf der CPU mit Ollama und llama.cpp
• Ollama und Open WebUI mit Docker
• OpenCode als Docker-Server lokal betreiben
• llama.cpp: Release v0.8.0
• llama.cpp: Dokumentation llama-server
• llama.cpp: Docker-Images
• Hugging Face: LiquidAI/LFM3-1.7B-GGUF