Jetzt starten wir llama.cpp erstmals mit einem konkreten GGUF-Modell.
Für diesen Aufbau verwenden wir:
unsloth/Muse-Glimmer-30B-GGUF:UD-IQ2_XXS
Warum wählen wir IQ2_XXS?
Unsere Testplattform verfügt nur über eine RTX 3060 mit 12 GB VRAM. Bei größeren Sprachmodellen ist deshalb nicht nur die Größe des Modells selbst entscheidend, sondern auch der zusätzliche Speicherbedarf für Kontext, KV-Cache und den laufenden Inferenzprozess.
Das gewählte 30B-Modell ist als UD-IQ2_XXS mit rund 10,7 GB bereits so quantisiert, dass es grundsätzlich in den verfügbaren VRAM-Bereich einer 12-GB-GPU passt.
Die niedrige Quantisierung ist hier also eine bewusste Entscheidung:
12 GB VRAM → möglichst großes Modell → möglichst kleine Quantisierung
Dadurch können wir auf der RTX 3060 ein deutlich größeres Modell betreiben, als es beispielsweise mit einer Q4-Quantisierung dieser Modellgröße möglich wäre.
Wichtig: Die Größe der GGUF-Datei entspricht nicht dem gesamten benötigten GPU-Speicher. Während der Ausführung benötigt llama.cpp zusätzlichen Speicher für den Kontext und weitere Laufzeitdaten. Deshalb bedeutet eine 10,7-GB-GGUF-Datei nicht automatisch, dass 10,7 GB VRAM ausreichen.
Andere Hardware, andere Quantisierung
Die Wahl der Quantisierung hängt deshalb stark von der vorhandenen GPU und dem verfügbaren VRAM ab.
Mit einer einzelnen RTX 3090 mit 24 GB VRAM stehen deutlich mehr Reserven zur Verfügung. Damit können bei vergleichbaren Modellgrößen auch höher quantisierte Varianten eingesetzt werden.
Bei zwei RTX 3060 mit jeweils 12 GB VRAM kann der verfügbare GPU-Speicher über mehrere GPUs verteilt werden. Damit eröffnen sich ebenfalls Möglichkeiten für größere Modelle oder höhere Quantisierungen.
Genau das ist einer der Vorteile von llama.cpp. Wir sind nicht auf ein einzelnes Modell oder eine bestimmte Quantisierung festgelegt. Je nach vorhandener Hardware können unterschiedliche GGUF-Varianten eingesetzt werden.
Wir wählen für diese Anleitung jedoch bewusst die Variante, die zu unserer 12-GB-Testplattform passt.
Modell über Hugging Face laden
llama.cpp kann Modelle direkt über Hugging Face beziehen. Dafür verwenden wir den -hf-Parameter.
Dazu öffnen wir die bereits erstellte docker-compose.yml erneut:
nano /opt/llamacpp/docker-compose.yml
In der bestehenden Compose-Datei ergänzen wir den folgenden command-Block zwischen dem environment- und dem deploy-Abschnitt:
command: >
-hf unsloth/Muse-Glimmer-30B-GGUF:UD-IQ2_XXS
--host 0.0.0.0
--port 8080
--n-gpu-layers 99
Die Compose-Datei enthält damit zusätzlich:
services:
llamacpp:
image: ghcr.io/ggml-org/llama.cpp:server-cuda
container_name: llamacpp
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- /opt/llamacpp/models/huggingface:/root/.cache/huggingface
environment:
- NVIDIA_VISIBLE_DEVICES=all
- NVIDIA_DRIVER_CAPABILITIES=compute,utility
command: >
-hf unsloth/Muse-Glimmer-30B-GGUF:UD-IQ2_XXS
--host 0.0.0.0
--port 8080
--n-gpu-layers 99
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
Was bewirken die zusätzlichen Parameter?
-hf unsloth/Muse-Glimmer-30B-GGUF:UD-IQ2_XXS
weist llama.cpp an, das angegebene Modell direkt aus dem Hugging-Face-Repository zu verwenden. Die aktuelle llama.cpp-Server-Dokumentation unterstützt diese Form des direkten Hugging-Face-Modellbezugs.
Das Modell wird dabei im zuvor eingerichteten Hugging-Face-Cache abgelegt:
/opt/llamacpp/models/huggingface/
--host 0.0.0.0
Der llama.cpp-Server wird auf allen Netzwerk-Schnittstellen des Containers erreichbar.
--port 8080
Der llama.cpp-Server verwendet innerhalb des Containers Port 8080. Dieser ist durch unsere Compose-Konfiguration bereits nach außen weitergeleitet.
--n-gpu-layers 99
Damit weisen wir llama.cpp an, möglichst viele Modell-Layer auf die GPU auszulagern.
Der Wert könnte beispielsweise auch auf 50 gesetzt werden. Dann würden nicht alle Modellgewichte auf der GPU liegen und ein Teil müsste im System-RAM verarbeitet werden. Dadurch sinkt in der Regel die Tokens/s, da der Zugriff auf den VRAM deutlich schneller ist als auf die im System-RAM liegenden Modellanteile.
Mit 99 versuchen wir daher, möglichst viele Modell-Layer auf der RTX 3060 auszuführen.
Hinweis: Die tatsächliche VRAM-Nutzung hängt unter anderem vom Modell, der Quantisierung und der später gewählten Kontextgröße ab. Die Auslastung überprüfen wir nach dem Start des Modells.
llama.cpp starten
Nachdem die Compose-Datei angepasst wurde, prüfen wir zunächst die Konfiguration:
docker compose config
Wenn keine Fehlermeldung erscheint, starten wir den Container:
docker compose up -d
Beim ersten Start lädt Docker zuerst das llama.cpp-Image herunter. Das kann je nach Internetverbindung einige Zeit dauern. Den Download kannst du in einem zweiten Shell-Fenster zum Beispiel mit btop beobachten.
Anschließend beobachten wir die Logs:
docker logs -f llamacpp
Mit Strg + C verlässt du die Log-Anzeige wieder, der Container läuft dabei weiter.
Beim ersten Start lädt llama.cpp außerdem das Modell herunter, rund 10,7 GB. Danach wird das Modell geladen und die GPU initialisiert.
Ob die RTX 3060 genutzt wird, siehst du auf dem Proxmox-Host (nicht im Container) mit:
nvtop
Sobald das Modell geladen ist und im Log die Meldung zum Server erscheint, ist llama.cpp unter http://192.168.178.134:8080 erreichbar.
🔒 Sicherheit: Mit --host 0.0.0.0 kann jeder in deinem Netzwerk den Server nutzen. Im Heimnetz ist das meist in Ordnung. Gib Port 8080 aber nie im Router ins Internet frei. Optional schützt du den Server mit einem Schlüssel: Ergänze im command-Block die Zeile --api-key DEIN_KEY (ein langes, zufälliges Passwort). Danach trägst du den Schlüssel in den Einstellungen der Web-Oberfläche ein und sendest ihn bei curl mit -H "Authorization: Bearer DEIN_KEY".
Server testen
1. Web-Oberfläche: Öffne http://192.168.178.134:8080 im Browser. Dort kannst du direkt mit dem Modell chatten.
2. Status prüfen:
curl http://192.168.178.134:8080/health
Sobald das Modell geladen ist, kommt {"status":"ok"} zurück. Solange es noch lädt, erscheint eine Fehlermeldung.
3. Chat-Anfrage über die API:
curl http://192.168.178.134:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "Erkläre in zwei Sätzen, was GGUF ist."}
],
"max_tokens": 200
}'
Die Antwort kommt im OpenAI-kompatiblen Format. Damit kannst du den Server auch mit anderen Programmen nutzen, die eine OpenAI-API unterstützen.
Hinweis: In dieser Anleitung geht es bewusst um ein flexibles Standard-llama.cpp-Setup, mit dem sich unterschiedliche GGUF-Modelle ausführen lassen. In Schritt 6 testen wir ein zweites Modell.
