vLLM produktiv deployen: Betriebsanleitung für Docker, Parameter und Absicherung

vLLM nicht selbst betreiben, sondern betreiben lassen?

Auf dem Managed GPU Server laufen Modell, vLLM und Open WebUI auf einer dedizierten GPU in Deutschland, mit Monitoring und Updates, ab 699 € netto im Monat zzgl. einmaliger Einrichtung. Die laufende Prüfung der Anwendung darüber (Traces, Evaluationen, Kosten) übernimmt Managed LLMOps.

Managed GPU Server ansehen · LLMOps ansehen

Ein vllm serve läuft in Minuten, ein produktiver Betrieb braucht mehr: Speicherrechnung, begrenzte Parameter, Absicherung, Metriken, ein Update-Verfahren und einen Lasttest. Dieser Leitfaden ist eine Betriebsanleitung für vLLM mit Docker, geprüft gegen die vLLM-Dokumentation und den Quellcode. Stand 28. Oktober 2026, aktuelle Version vLLM 0.32.0. Was vLLM ist, erklärt Was ist vLLM?, den Vergleich mit Ollama zeigt vLLM vs. Ollama.

Inhaltsverzeichnis

• Speicher planen: Gewichte und KV-Cache
• vLLM mit Docker Compose starten
• Die Serverparameter, die zählen
• Kubernetes: Hinweise
• Healthchecks und Readiness
• Metriken, LiteLLM und Langfuse
• Absicherung
• Updates und Versions-Pinning
• Typische Fehler
• Lasttest ohne erfundene Zahlen
• Woran sich eine vLLM-Beratung messen lässt
• Stand und Methodik
• Unser Vorgehen bei WZ-IT
• Weiterführende Guides

Speicher planen: Gewichte und KV-Cache

Produktiv heißt zuerst: Kontext und Parallelität passen zum Speicher der GPU. Der GPU-Speicher teilt sich in Gewichte, KV-Cache und Reserve:

1. Gewichte = Dateigröße des Checkpoints (Parameter × Byte je Parameter).
2. KV-Cache je Token = 2 × Layer × KV-Heads × Head-Dimension × Byte (klassische Attention, Werte aus der config.json). Bei Multi-Head Latent Attention speichert vLLM je Layer nur kv_lora_rank + qk_rope_head_dim Werte (Quellcode).
3. Verfügbar für den Cache = GPUs × GPU-Speicher × --gpu-memory-utilization (Default 0,92, CLI-Referenz) - Gewichte - Reserve. Die Summe über alle GPUs gilt, solange die Tensor-Parallelität die KV-Heads nicht übersteigt. Bei MLA-Modellen mit einem latenten KV-Head liegt der Cache je Token auf jeder GPU der Tensor-Parallelität, dort gilt das Budget je GPU (Abhilfe: --decode-context-parallel-size, vLLM-Doku).
4. Sitzungen = Verfügbar ÷ (KV-Cache je Token × Kontextlänge).

Beispiel Ministral 3 14B in FP8 (Model Card): 15,73 GB Gewichte (15.726.706.472 Byte), 40 Layer, 8 KV-Heads, Head-Dimension 128, also 160 KiB je Token in BF16.

Annahmen: 4 GB Reserve je GPU für Aktivierungen und CUDA-Graphen (Planungswert, kein Messwert), KV-Cache in BF16, 1 GB = 10^9 Byte. Die Tabelle rechnet mit dem Default 0,92, die Compose-Datei unten setzt 0,90 und verkleinert das Budget um 1,9 GB (96 GB) beziehungsweise 0,5 GB (24 GB). Auf der 24-GB-Karte reicht der Cache rechnerisch nicht für einen einzelnen Kontext von 32.768 Token, dort braucht es einen kleineren --max-model-len (oder auto, das den größten passenden Wert wählt). Beim Start meldet vLLM die tatsächlichen Werte im Log (Available KV cache memory, GPU KV cache size: … tokens, Maximum concurrency for … tokens per request). Die Herleitung steht in GPU und VRAM für LLMs richtig dimensionieren, Quantisierung behandelt LLM-Quantisierung.

vLLM mit Docker Compose starten

Das Modell wird einmalig vorab geladen (HF_HOME=/srv/models/huggingface hf download mistralai/Ministral-3-14B-Instruct-2512), die vLLM-Fehlerbehebung empfiehlt das. Danach genügt diese compose.yaml (ausgelegt auf die 96-GB-Zeile der Tabelle, auf 24 GB muss --max-model-len kleiner sein):

services:
  vllm:
    image: vllm/vllm-openai:v0.32.0
    restart: unless-stopped
    shm_size: "16gb"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      VLLM_API_KEY: ${VLLM_API_KEY}
      VLLM_NO_USAGE_STATS: "1"
      HF_HUB_DISABLE_TELEMETRY: "1"
      HF_HUB_OFFLINE: "1"
    volumes:
      - /srv/models/huggingface:/root/.cache/huggingface
      - vllm-cache:/root/.cache/vllm
    ports:
      - "127.0.0.1:8000:8000"
    command:
      - --model=mistralai/Ministral-3-14B-Instruct-2512
      - --served-model-name=assistent
      - --tokenizer-mode=mistral
      - --config-format=mistral
      - --load-format=mistral
      - --max-model-len=32768
      - --gpu-memory-utilization=0.90
      - --max-num-seqs=16
      - --enable-auto-tool-choice
      - --tool-call-parser=mistral
volumes:
  vllm-cache:

Was vom Tutorial-Standard abweicht:

• Feste Image-Version statt latest. Das Image startet mit vllm serve, Parameter folgen nach dem Image-Namen. vLLM braucht --ipc=host oder --shm-size (Docker-Doku).
• Compile-Cache auf einem Volume (/root/.cache/vllm). Sonst kompiliert jeder neue Container die Modell-Artefakte erneut.
• GPU-Reservierung nach der Compose-Dokumentation, mit installiertem NVIDIA Container Toolkit.
• Port nur an Loopback. Veröffentlichte Docker-Ports sind sonst auch von außen erreichbar (Docker-Doku).
• Schlüssel in .env (Dateirechte 600), nicht in der Compose-Datei.
• Tokenizer-Modus und Tool-Calling-Flags stammen aus der Model Card. Andere Modelle brauchen andere Parser.
• Optional läuft der Container ohne Root: --user 2000:0 mit Mounts unter /home/vllm (Docker-Doku).

Die Serverparameter, die zählen

Quellen: CLI-Referenz, Optimierungsanleitung und Parallelität.

Parameter lassen sich auch in einer YAML-Datei führen (vllm serve --config), Werte auf der Kommandozeile haben Vorrang (Doku).

Kubernetes: Hinweise

Kubernetes lohnt bei mehreren GPU-Knoten, Replikas oder einem bestehenden Cluster mit Betriebsprozess, für wenige GPUs ist Compose die kleinere Betriebsfläche. Die vLLM-Anleitung für Kubernetes und die Kubernetes-Dokumentation zu GPUs nennen die Eckpunkte:

• GPU unter limits: nvidia.com/gpu gehört in limits. Requests dürfen entfallen (Kubernetes übernimmt dann das Limit) oder müssen gleich groß sein, Requests ohne Limits sind nicht zulässig.
• Gemeinsamer Speicher: ein emptyDir mit medium: Memory unter /dev/shm.
• Modell-Cache auf einem PersistentVolumeClaim, ein Hugging-Face-Token als Secret nur für geschützte Modelle.
• Startup-Probe mit ausreichendem failureThreshold. Ist er zu niedrig, beendet Kubernetes den Container während des Ladens (Log: KeyboardInterrupt: terminated). Den Wert liefert eine Messung der Startzeit ohne Probe.
• Feste Image-Version. Die Beispiele der Doku nutzen latest.

Mehrere Replikas mit Routing und Autoscaling deckt der vom vLLM-Projekt gepflegte production-stack mit Helm-Chart ab. Allgemeine Cluster-Anforderungen behandelt die Kubernetes-Produktionscheckliste.

Healthchecks und Readiness

/health meldet den Zustand der Engine, ohne API-Key. Die Doku nutzt den Endpunkt für Liveness und Readiness. Drei Ergänzungen gehören in den Betrieb:

1. Startup-Probe für die Ladezeit großer Modelle (Kubernetes-Probes).
2. Synthetische Anfrage: Das Monitoring schickt regelmäßig eine kurze Chat-Anfrage mit max_tokens: 1 und API-Key an /v1/chat/completions und misst die Zeit bis zum Antwortbeginn. /health zeigt, dass der Prozess lebt, nicht dass das Modell antwortet.
3. Probes am Proxy vorbei: /health passiert den Reverse Proxy nicht, Probes gehen direkt an Container oder Pod.

Metriken, LiteLLM und Langfuse

vLLM liefert Prometheus-Metriken unter /metrics (Metriken-Doku), auch bei gesetztem --api-key ohne Authentifizierung (Sicherheitsdoku). Zähler tragen in Prometheus das Suffix _total, etwa vllm:prompt_tokens_total im Grafana-Beispiel der Doku. Namen vor Alarmregeln mit curl http://localhost:8000/metrics prüfen, die Tabelle nennt die Zähler mit diesem Suffix.

Alarmschwellen bestimmt das Servicelevel der Anwendung, nicht eine Tabelle. Dauerhaft hohe Cache-Auslastung bei steigenden Preemptions heißt: weniger Kontext, weniger Parallelität oder mehr GPU-Speicher. Veraltete Metriken sind eine Minor-Version später ausgeblendet und eine weitere später entfernt (Metriken-Doku), Dashboards gehören deshalb zum Update-Test.

Ein Gateway ergänzt die Engine-Metriken. LiteLLM spricht vLLM über hosted_vllm/<modell> mit api_base an (Doku) und schreibt mit success_callback: ["langfuse"] Traces nach Langfuse (Doku). So stehen Latenz und Kosten je Anwendung neben den Engine-Werten. Das Gateway ist selbst ein Angriffsziel, siehe LiteLLM-Sicherheitslücke und Gateway-Härtung.

Absicherung

Die Sicherheitsdokumentation von vLLM warnt ausdrücklich davor, sich allein auf --api-key zu verlassen.

• --api-key schützt nur /v1, /v2, /inference und /cohere. Ohne Schlüssel erreichbar bleiben unter anderem /invocations (dieselbe Inferenz wie /v1), /pooling, /classify, /score, /rerank, /metrics, /health, /tokenize, /load sowie Steuerpfade wie /pause, /abort_requests und /update_weights.
• Reverse Proxy mit Allowlist. Nur die benötigten Pfade passieren, alles andere endet mit 403. Rate-Limit und Logging liegen am Proxy. Beispiel für nginx (vor dem Einsatz testen; ohne Pufferung geht die Antwort synchron an den Client, nginx-Doku):

location ~ ^/v1/(chat/completions|completions|models)$ {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_buffering off;      # Streaming ohne Zwischenpuffer
    proxy_read_timeout 600s;  # Default 60s, lange Antworten brauchen mehr
}
location / { return 403; }

• Netz abgrenzen. Bei mehreren Knoten sind PyTorch-Distributed-Verkehr und KV-Transfer unverschlüsselt und gehören in ein isoliertes Netz, VLLM_HOST_IP bekommt eine feste Adresse. Von außerhalb dieses Netzes darf nur der API-Port erreichbar sein.
• Gefährliche Schalter aus: VLLM_SERVER_DEV_MODE=1 (öffnet unter anderem /collective_rpc) nie in Produktion, --enable-tokenizer-info-endpoint nur bei Bedarf.
• Multimodale Eingaben: --allowed-media-domains begrenzt Abrufe gegen SSRF. Öffentlich erreichbare Dienste setzen VLLM_MAX_N_SEQUENCES niedrig (die Doku nennt 64 oder 128 als Beispiel).
• Ein Schlüssel ist kein Rechtekonzept. Schlüssel je Team, Limits und Zuordnung gehören in ein Gateway.
• Datenwege schließen. vLLM sammelt standardmäßig anonyme Nutzungsdaten, abschaltbar mit VLLM_NO_USAGE_STATS=1 oder DO_NOT_TRACK=1 (Doku). Hugging-Face-Telemetrie endet mit HF_HUB_DISABLE_TELEMETRY=1, Abrufe beim Hub mit HF_HUB_OFFLINE=1 (Doku). --enable-log-requests schreibt Parameter, auf DEBUG-Stufe auch Prompts ins Log. Bei Personenbezug bleibt es aus.

Anwendungsrisiken wie Prompt Injection behandelt Schutz vor Prompt Injection, den Zugriff von außen Lokale KI sicher von außen bereitstellen.

Updates und Versions-Pinning

Laut PyPI erschienen 0.28.0 (26.08.2026), 0.29.0, 0.30.0, 0.31.0 und 0.32.0 (18.10.2026) in knapp acht Wochen. Die Docker-Tags tragen die Version (v0.32.0), daneben gibt es latest und nightly.

1. Image pinnen auf Versionsnummer oder Digest, nie auf latest.
2. Zuerst testen: Update auf einer Umgebung mit gleicher GPU und gleichem Modell, danach Startlog (Cache-Größe, Parallelität), Lasttest und Dashboards vergleichen.
3. Rückfall behalten: vorherige Compose-Datei und vorheriges Image bleiben verfügbar.
4. Modellanforderungen prüfen: Neue Modelle verlangen oft neue vLLM-Versionen, die Model Card von Mistral Medium 3.5 nennt zum Beispiel ein Nightly-Build.
5. Caches einplanen: Änderungen an Modell, Konfiguration, torch oder GPU invalidieren den Compile-Cache (Doku), der erste Start nach einem Update dauert länger.
6. Sicherheitsmeldungen verfolgen: Das Projekt koordiniert Schwachstellen in einem eigenen Prozess (Vulnerability Management) und veröffentlicht Security Advisories.

Typische Fehler

Lasttest ohne erfundene Zahlen

Durchsatzzahlen anderer Setups sagen nichts über Ihre Prompts, Ihr Modell und Ihre GPU. Die vLLM-Doku sieht vllm bench serve für Feature- und Regressionstests vor und empfiehlt für Produktionsserver GuideLLM (Benchmarking). Ablauf:

1. Eigene Prompts als .jsonl mit dem Feld prompt, in realer Längenverteilung der Eingaben (kurzer Chat gegen RAG mit langem Kontext). Die Antwortlänge legt --custom-output-len fest (Default 256), mit --custom-output-len -1 gilt je Zeile das Feld output_tokens. Keine Echtdaten mit Personenbezug in Testwerkzeuge kopieren.
2. Stufen: Parallelität schrittweise erhöhen (--max-concurrency, optional --request-rate).
3. Messen: Zeit bis zum ersten Token, Zeit zwischen Tokens und Gesamtlatenz als Perzentile, Fehlerquote, daneben kv_cache_usage_perc, num_requests_waiting und num_preemptions_total aus den Metriken.
4. Prefix-Cache beachten: Wiederholte Läufe mit denselben Prompts blähen den Durchsatz auf. Seed variieren oder den Server neu starten (Doku).
5. Abnahme vorab festlegen, mit --goodput als Ziel je Anfrage. Die Zielwerte setzt der Fachbereich.
6. Wiederholen nach jedem Update und Modellwechsel.

vllm bench serve --backend openai-chat --endpoint /v1/chat/completions \
  --model mistralai/Ministral-3-14B-Instruct-2512 --served-model-name assistent \
  --host 127.0.0.1 --port 8000 \
  --header "Authorization=Bearer ${VLLM_API_KEY}" \
  --dataset-name custom --dataset-path prompts.jsonl --num-prompts 200 \
  --skip-chat-template --max-concurrency 8 \
  --percentile-metrics ttft,itl,e2el --metric-percentiles 50,95,99

Die Optionen stammen aus der Doku zu vllm bench serve. Der Aufruf läuft je Stufe mit anderem --max-concurrency. --skip-chat-template verhindert, dass der Client das Chat-Template zusätzlich zum Server anwendet (der Endpunkt /v1/chat/completions wendet es selbst an). Der Client lädt den Tokenizer des Modells, ohne Hub-Zugang zeigt --tokenizer auf eine lokale Kopie. Gelesen werden Perzentile, nicht Mittelwerte.

Woran sich eine vLLM-Beratung messen lässt

Ob intern oder extern: Diese Fragen müssen sich mit Dateien und Messwerten beantworten lassen.

1. Welche Image-Version läuft, wie ist sie gepinnt, wie sieht der Rückfall aus?
2. Liegt die Speicherrechnung mit Annahmen vor (Gewichte, KV-Cache, Reserve)?
3. Welche Endpunkte sind von außen erreichbar, und wo steht die Allowlist?
4. Welche Metriken und Alarme gibt es, wer empfängt sie?
5. Gibt es einen Lasttest mit eigenen Prompts und schriftlichen Abnahmewerten?
6. Wie läuft ein Update, und welche Tests gehören dazu?
7. Wem gehören Konfiguration, Schlüssel und Zugänge, wie läuft die Rückübergabe?
8. Welche Datenwege verlassen die Umgebung (Telemetrie, Logs, Modell-Downloads)?

Stand und Methodik

• Stand: 28.10.2026. Grundlage sind die vLLM-Dokumentation (Version latest) und der Quellcode im Hauptzweig, abgerufen am 28.10.2026.
• Rechnung: Gewichte aus den Dateigrößen der Hugging-Face-Repositories, Cache-Werte aus der config.json. Die Reserve von 4 GB je GPU ist eine Annahme.
• Nicht gemessen: Der Leitfaden enthält keine Benchmarks und keine Durchsatzwerte. Sie entstehen im eigenen Lasttest.
• Beispielmodell: Ministral 3 14B (Apache 2.0), Flags anderer Modelle stehen in deren Model Cards.

Unser Vorgehen bei WZ-IT

Wir betreiben vLLM auf dem Managed GPU Server: dedizierte NVIDIA-GPU in einem deutschen Rechenzentrum mit abgestimmtem Modell, vLLM und Open WebUI. Vor der Bereitstellung prüfen wir Modell, Quantisierung, Kontext und Parallelität rechnerisch gegen 24 oder 96 GB GPU-Speicher. Zum Betrieb gehören Monitoring von Host, GPU und vLLM, Pflege von Betriebssystem, Treiber und vLLM mit CVE-Einordnung und Störungsbearbeitung. Monitoring erfolgt 24/7, die Reaktion auf P1-Incidents erfolgt entsprechend Service Level. Externe APIs, Telemetrie und Backupziele stimmen wir als eigene Datenwege ab. Wer die Anwendung über der Inferenz laufend prüfen will (Traces, Evaluationen, Kosten, Latenz), nutzt Managed LLMOps mit Langfuse. Auf eigener Hardware im eigenen Netz laufen vLLM und Open WebUI vorinstalliert auf dem AI Cube. Das Fachgebiet beschreibt die Seite vLLM-Expertise, die Betriebswege vergleicht LLM-Hosting.

Weiterführende Guides

• Was ist vLLM? - Engine, PagedAttention und Continuous Batching
• vLLM vs. Ollama - wann welche Engine passt
• GPU und VRAM für LLMs richtig dimensionieren - Herleitung der Speicherrechnung
• Multi-GPU-Inferenz ohne NVLink - Tensor- und Pipeline-Parallelität
• LLM-Quantisierung - FP8, NVFP4 und AWQ im Vergleich
• Was ist LiteLLM? - Gateway vor vLLM
• Was ist Langfuse? - Traces und Evaluationen
• vLLM, Ollama oder llama.cpp - Inferenz-Server im Vergleich
• vLLM mit Qwen3.5-122B auf zwei RTX PRO 6000 - Praxisbeispiel mit Compose und Hybrid-Modell

vLLM in Betrieb nehmen? WZ-IT betreibt vLLM auf dediziertem GPU-Server in Deutschland oder prüft Ihre Anwendung laufend. Managed GPU Server · Managed LLMOps · LLM-Hosting