vLLM ist ein Hochdurchsatz-Server für offene Large Language Models (LLMs). Statt einer Cloud-API betreiben Sie Modelle wie Llama, Mistral, Qwen oder Hermes auf dem eigenen GPU-Server und sprechen sie über eine OpenAI-kompatible HTTP-Schnittstelle an. Die Anleitung zeigt das offizielle Image vllm/vllm-openai mit Docker Compose, dauerhafte Modellablage, VRAM-Begrenzung per Quantisierung und Hermes-Modelle mit Tool-Calling.

Abgrenzung: vLLM ist auf GPU-Serving mit hohem Durchsatz ausgelegt (PagedAttention, Batching). Für einen Nutzer oder CPU-Betrieb ist Ollama mit Open WebUI schlanker. vLLM lohnt sich bei vielen parallelen Anfragen, niedriger Latenz und OpenAI-API als Backend.

Kurzfassung: NVIDIA-Treiber und nvidia-container-toolkit installieren, dann ein kleines Modell zum Test starten und per curl prüfen.

# Schnelltest: kleines Modell auf Port 8000
docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen3-0.6B

# Test
curl http://localhost:8000/v1/models

Voraussetzungen

NVIDIA-GPU mit CUDA Compute Capability 7.5 oder höher (z. B. T4, RTX 20xx/30xx/40xx, L4, A100, H100). Ältere Karten wie V100 (7.0) unterstützt vLLM nicht mehr.
VRAM-Faustregel: 7B in FP16 rund 16 GB, quantisiert (AWQ/GPTQ, 4 Bit) 6 bis 8 GB. 13B rund 26 GB in FP16, 70B nur quantisiert oder auf mehreren GPUs. Für Produktivbetrieb mindestens 24 GB VRAM.
Linux-Server (x86_64) mit Debian 12 oder Ubuntu 24.04, mindestens 32 GB RAM und 100 GB freiem Speicher für Modelle, aktuellem NVIDIA-Treiber, Docker und Docker Compose. Grundlagen: Docker Compose und Stacks.
Das nvidia-container-toolkit (Schritt 1), damit Container per --gpus all auf die GPU zugreifen.
Hugging-Face-Konto mit Token (HF_TOKEN) für gated Modelle wie meta-llama/*, Lizenz vorher auf huggingface.co akzeptieren.
Optional Domain und Reverse Proxy für HTTPS (Schritt 8).

Hardware für diese Anleitung

Enthält Werbelinks

Grafikkarte mit viel VRAM	Der Grafikspeicher entscheidet, welche Modelle laufen. Faustregel bei 4-Bit-Quantisierung: 8 GB für 7–8B-Modelle, 16 GB für 14B, 24 GB für die 30B-Klasse.	Grafikkarten bei Amazon (Werbelink)
Arbeitsspeicher	32 GB RAM, damit Modelle, die nicht ganz in den Grafikspeicher passen, auf die CPU ausweichen können.	Bei Amazon ansehen (Werbelink)
Welche Karte passt?	Unsere Kaufberatung vergleicht die Karten nach VRAM und Budget.	Zur Kaufberatung

Vorhandene Hardware reicht oft. Die Liste zeigt, worauf es bei einem Neukauf ankommt. * Werbelink

Schritt 1: GPU-Zugriff für Docker einrichten

Das nvidia-container-toolkit gibt Containern GPU-Zugriff. Der NVIDIA-Treiber muss installiert sein (nvidia-smi auf dem Host). Installation unter Debian/Ubuntu:

# NVIDIA-Container-Toolkit-Repository einbinden
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Installieren und Docker-Runtime konfigurieren
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker

# GPU-Zugriff im Container prüfen
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Verifizieren: Der Testcontainer gibt die nvidia-smi-Tabelle mit Ihrer Karte und der Treiberversion aus. Schlägt der Befehl fehl, liegt es meist am Treiber oder an der Runtime-Konfiguration (siehe Troubleshooting).

Schritt 2: Projektverzeichnis und .env anlegen

Legen Sie ein Stack-Verzeichnis mit einer .env für Hugging-Face-Token und API-Schlüssel an, damit keine Geheimnisse in der compose.yaml stehen.

mkdir -p ~/vllm && cd ~/vllm

Datei .env (Werte anpassen). Setzen Sie VLLM_API_KEY auf ein langes Zufallspasswort (z. B. openssl rand -hex 32), sobald die API über den Host hinaus erreichbar ist:

# ~/vllm/.env
HF_TOKEN=hf_IHR-HUGGINGFACE-TOKEN
VLLM_API_KEY=IHR-LANGER-ZUFALLS-API-KEY

Für gated Modelle (z. B. meta-llama/Llama-3.1-8B-Instruct) akzeptieren Sie die Lizenz auf huggingface.co, sonst scheitert der Download mit 401/403.

Verifizieren: ls -la ~/vllm zeigt die Datei .env; nach chmod 600 ~/vllm/.env hat sie die Rechte -rw-------.

Schritt 3: compose.yaml erstellen

Die compose.yaml startet vLLM mit GPU-Zugriff, legt den Hugging-Face-Cache in ein benanntes Volume und stellt Shared Memory bereit.

# ~/vllm/compose.yaml
services:
  vllm:
    image: vllm/vllm-openai:v0.31.0
    container_name: vllm
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - hf-cache:/root/.cache/huggingface
    environment:
      - HF_TOKEN=${HF_TOKEN}
      - VLLM_API_KEY=${VLLM_API_KEY}   # optional: API absichern
    ipc: host          # alternativ: shm_size: '8gb'
    command: >
      --model Qwen/Qwen2.5-7B-Instruct
      --served-model-name qwen2.5-7b
      --max-model-len 8192
      --gpu-memory-utilization 0.90
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  hf-cache:

Stellschrauben:

--model: Hugging-Face-Repo-ID des Modells (Pflicht).
--served-model-name: Alias des Modells in der API.
--max-model-len: Maximale Kontextlänge. Begrenzt direkt den VRAM-Bedarf; bei OOM-Fehlern zuerst reduzieren.
--gpu-memory-utilization: Anteil des GPU-Speichers (0 bis 1, Standard 0.9). 0.90 reserviert dauerhaft 90 % des VRAM.
ipc: host: Shared Memory für vLLM. Ohne (oder shm_size: '8gb') stürzt der Server ab, Docker gibt standardmäßig nur 64 MB.

Die Version ist festgeschrieben (v0.31.0, Stand Oktober 2026, siehe Häufige Fragen). Für AMD-GPUs gibt es vllm/vllm-openai-rocm mit eigenen Geräteoptionen (vLLM-Doku).

Verifizieren: docker compose config --quiet im Ordner ~/vllm endet ohne Ausgabe; bei Syntaxfehlern nennt Compose Zeile und Ursache.

Schritt 4: vLLM starten und Logs prüfen

Starten Sie den Stack und verfolgen Sie beim ersten Mal die Logs. Der erste Start dauert, weil vLLM das Modell von Hugging Face lädt (danach liegt es im Volume).

cd ~/vllm
docker compose up -d
docker compose logs -f vllm

Verifizieren: In den Logs erscheinen Application startup complete bzw. Uvicorn running on http://0.0.0.0:8000, und docker compose ps zeigt den Dienst als running. Strg+C beendet nur die Log-Ansicht.

Schritt 5: Server testen (curl)

vLLM bietet eine OpenAI-kompatible API ohne Oberfläche und Anmeldung. Prüfen Sie Health-Endpunkt und Modelle:

# Health und geladene Modelle
curl http://localhost:8000/health
curl -H "Authorization: Bearer IHR-LANGER-ZUFALLS-API-KEY" http://localhost:8000/v1/models

Dann ein Chat-Aufruf gegen /v1/chat/completions. Als Modellnamen setzen Sie den Alias aus --served-model-name:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer IHR-LANGER-ZUFALLS-API-KEY" \
  -d '{"model":"qwen2.5-7b","messages":[{"role":"user","content":"Was ist vLLM?"}]}'

Den Header Authorization: Bearer *** brauchen Sie nur bei gesetztem VLLM_API_KEY. Weitere Endpunkte: /v1/completions, /v1/embeddings.

Verifizieren: /health antwortet mit HTTP 200, /v1/models listet qwen2.5-7b, und der Chat-Aufruf liefert JSON mit choices[0].message.content. Ohne gültigen Schlüssel antwortet der Server mit 401.

Schritt 6: Modelle wählen: Llama, Mistral, Qwen und Quantisierung

Die Hugging-Face-Repo-ID im Argument --model bestimmt, welches Modell läuft. Nach einer Änderung genügt docker compose up -d. Beispiele:

Modell (HF-ID)	Familie	Hinweis
`meta-llama/Llama-3.1-8B-Instruct`	Meta Llama	Gated: HF_TOKEN und akzeptierte Lizenz nötig
`mistralai/Mistral-7B-Instruct-v0.3`	Mistral	Teils gated; sehr effizient
`Qwen/Qwen2.5-7B-Instruct`	Qwen	Offen, guter Allrounder
`Qwen/Qwen2.5-7B-Instruct-AWQ`	Qwen (AWQ)	4-Bit-quantisiert, deutlich weniger VRAM

Reicht der VRAM nicht, nutzen Sie ein quantisiertes Modell. AWQ und GPTQ in 4 Bit senken den Bedarf eines 7B-Modells grob auf 6 bis 8 GB. Das Verfahren geben Sie über --quantization an:

# Quantisiertes Modell (AWQ) für wenig VRAM
docker run --runtime nvidia --gpus all -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 --ipc=host vllm/vllm-openai:v0.31.0 \
  --model Qwen/Qwen2.5-7B-Instruct-AWQ --quantization awq --max-model-len 8192

Ergänzen Sie die Argumente in der compose.yaml unter command. Gängige Werte für --quantization: awq, awq_marlin, gptq, gptq_marlin, fp8, compressed-tensors; vorquantisierte Modelle erkennt vLLM meist selbst. GGUF braucht aktuell das Plugin vllm-gguf-plugin. Mit mehreren GPUs verteilt --tensor-parallel-size N ein großes Modell.

Verifizieren: Die Logs melden beim Start die gewählte Quantisierung, nvidia-smi zeigt den erwarteten Speicherbedarf, und /v1/models listet das neue Modell.

Schritt 7: Hermes-Modelle mit Tool-Calling serven

Hermes (Nous Research) sind feinabgestimmte offene Modelle auf Llama- bzw. Qwen-Basis mit ChatML-Format, geeignet für Tool-/Function-Calling und strukturierte JSON-Ausgabe, etwa als Agenten-Backend. Für die Tool-Auswertung brauchen Sie zwei Flags:

# Hermes mit Tool-/Function-Calling
docker run --runtime nvidia --gpus all -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HF_TOKEN=$HF_TOKEN" -p 8000:8000 --ipc=host vllm/vllm-openai:v0.31.0 \
  --model NousResearch/Hermes-3-Llama-3.1-8B --enable-auto-tool-choice --tool-call-parser hermes

In der Compose-Variante stehen Modell und Flags unter command:

    command: >
      --model NousResearch/Hermes-3-Llama-3.1-8B
      --served-model-name hermes-3-8b
      --enable-auto-tool-choice
      --tool-call-parser hermes
      --max-model-len 8192

Tool-Calling funktioniert ab Hermes 2 Pro (Hermes-2-Pro-* und Hermes-3-*). Meiden Sie Hermes-2-Theta-*: Laut vLLM-Doku ist dort die Qualität der Tool-Aufrufe durch den Merge-Schritt verschlechtert.

Verifizieren: Senden Sie eine Chat-Anfrage mit einem Feld tools (Funktionsdefinition) und einer passenden Frage. Die Antwort enthält choices[0].message.tool_calls mit Funktionsname und Argumenten statt reinem Text.

Schritt 8: Reverse Proxy, HTTPS und API-Schutz

vLLM hat keine Benutzerverwaltung. Ist Port 8000 aus dem Internet erreichbar, kann jeder Ihre API nutzen. Absichern:

API-Schlüssel setzen: über VLLM_API_KEY (oder --api-key). Clients senden dann den Header Authorization: Bearer ….
Nicht direkt freigeben: Port 8000 per Firewall auf das interne Netz beschränken (oder als 127.0.0.1:8000:8000 veröffentlichen) und einen Reverse Proxy mit TLS davorsetzen.

Ein minimales nginx-Beispiel, das HTTPS terminiert und an vLLM weiterreicht:

server {
    listen 443 ssl;
    server_name IHRE-DOMAIN.de;

    ssl_certificate     /etc/letsencrypt/live/IHRE-DOMAIN.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/IHRE-DOMAIN.de/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_buffering off;   # wichtig für Streaming-Antworten
    }
}

Als Oberfläche binden Sie vLLM als OpenAI-Backend in LibreChat oder Open WebUI ein (Base-URL http://IHR-SERVER:8000/v1, API-Schlüssel). Siehe Open WebUI im Docker-Betrieb.

Verifizieren: curl -I https://IHRE-DOMAIN.de/health liefert HTTP 200 mit gültigem Zertifikat; ein Aufruf von /v1/models ohne Schlüssel liefert 401. Von außen ist Port 8000 nicht erreichbar.

Schritt 9: Update und Backup

Für ein Update tragen Sie die neue Version in der compose.yaml ein, ziehen das Image und erstellen den Container neu:

cd ~/vllm
docker compose pull && docker compose up -d
docker compose logs -f vllm

Lesen Sie vorher die Release Notes: Umbenannte oder entfernte Engine-Argumente verhindern den Start.

Beispiel Update von v0.30.0 auf v0.31.0: Die Argumente dieser Anleitung (--model, --served-model-name, --max-model-len, --gpu-memory-utilization, --quantization, --enable-auto-tool-choice, --tool-call-parser hermes) und VLLM_API_KEY gibt es unverändert weiter. Entfernt bzw. geändert wurden laut Release Notes unter anderem die Umgebungsvariablen VLLM_PREFIX_CACHE_RETENTION_INTERVAL und VLLM_MM_HASHER_ALGORITHM, die GPTQ-Aktivierungsreihenfolge (g_idx), und Scale-out-Endpunkte müssen nun per --enable-scale-out statt über VLLM_ENABLE_SCALE_OUT_ENDPOINTS eingeschaltet werden. Außerdem rechnen YaRN-Aliasse von Modellherstellern max_model_len nicht mehr hoch. Wer eines davon nutzt, passt die compose.yaml vor dem Update an. Das Standard-Image v0.31.0 ist auf CUDA 13.0 gebaut; für ältere Treiber gibt es weiterhin den Tag v0.31.0-cu129 (CUDA 12.9).

Für das Backup zählen:

compose.yaml und .env: die eigentliche Konfiguration, gehört in ein Backup oder eine Versionsverwaltung.
Das Volume hf-cache enthält die Modellgewichte. Ohne Sicherung lädt vLLM sie neu (Zeit, Bandbreite). Da die HF-IDs in der compose.yaml den Stand festlegen, ist das Volume-Backup oft verzichtbar.

# Hugging-Face-Cache-Volume als tar sichern
docker run --rm -v vllm_hf-cache:/data -v $(pwd):/backup alpine \
  tar czf /backup/hf-cache-backup.tar.gz -C /data .

Verifizieren: Nach dem Update zeigt docker compose images den neuen Tag, /health antwortet mit 200. Das Backup-Archiv lässt sich mit tar tzf hf-cache-backup.tar.gz | head auflisten.

Troubleshooting

Absturz mit shm- oder CUDA-Fehler beim Start: Fehlendes Shared Memory. Setzen Sie ipc: host bzw. shm_size: '8gb'.
VRAM-OOM beim Laden: Modell oder Kontext zu groß. Wählen Sie ein kleineres oder quantisiertes Modell (AWQ/GPTQ), reduzieren Sie --max-model-len und senken Sie --gpu-memory-utilization (z. B. 0.85).
Download bricht mit 401/403 ab: Gated Modell. Prüfen Sie, ob HF_TOKEN gesetzt ist und die Lizenz auf huggingface.co akzeptiert wurde.
--gpus all schlägt fehl: nvidia-container-toolkit fehlt oder die Runtime ist nicht konfiguriert. Testen Sie mit docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi und wiederholen Sie bei Bedarf Schritt 1.
Container startet nach Update nicht, „unrecognized arguments“: Ein Engine-Argument wurde umbenannt oder entfernt. Gleichen Sie command mit der Engine-Args-Doku der neuen Version ab.
Modell wird bei jedem Neustart neu geladen: Der Cache ist nicht dauerhaft. Prüfen Sie, ob das Volume hf-cache auf /root/.cache/huggingface eingebunden ist.
Hermes ruft keine Tools auf: Es fehlen --enable-auto-tool-choice --tool-call-parser hermes, oder Sie nutzen Hermes 2 Theta.

Häufige Fragen

Brauche ich zwingend eine GPU?

Praktisch ja: vllm/vllm-openai setzt eine NVIDIA-Karte mit Compute Capability 7.5 oder höher voraus. Für CPU-Betrieb oder Einzelnutzer passt Ollama besser.

Wie viel VRAM brauche ich für ein 7B-Modell?

Siehe Voraussetzungen: in FP16 rund 16 GB, mit 4-Bit-Quantisierung etwa 6 bis 8 GB, zuzüglich Speicher für den Kontext (KV-Cache).

Ist vLLM wirklich OpenAI-kompatibel?

Ja. Die Endpunkte unter /v1 entsprechen der OpenAI-API; bestehende Clients stellen Sie über Base-URL und API-Schlüssel um.

Was unterscheidet Hermes von Llama oder Mistral?

Hermes-Modelle sind auf Tool-Calling und JSON-Ausgabe abgestimmt (siehe Schritt 7), etwa als Backend für n8n-Workflows.

Sollte ich :latest oder eine feste Version nutzen?

Zum Ausprobieren genügt :latest. Im Betrieb schreiben Sie eine Version fest (z. B. vllm/vllm-openai:v0.31.0), weil :latest ohne Ankündigung wechselt und umbenannte Argumente mitbringen kann.

Kann ich mehrere Modelle gleichzeitig serven?

Eine vLLM-Instanz bedient ein Modell. Für mehrere Modelle starten Sie mehrere Dienste mit eigenen Ports und passendem --gpu-memory-utilization.

Fazit

Entscheidend sind: GPU per nvidia-container-toolkit, Shared Memory über ipc: host, Hugging-Face-Cache als Volume, VRAM über Quantisierung und --max-model-len. Sichern Sie die API mit Schlüssel und Reverse Proxy ab, bevor Sie sie über den Host hinaus öffnen.

Weiterführende Anleitungen und Quellen

Quellen (offizielle vLLM-Dokumentation):