vLLM mit Docker: Architektur, Performance und Cloud-Deployment

vLLM mit Docker: Architektur, Performance und Cloud-Deployment

Docker ist der direkteste Weg, vLLM hinter einem OpenAI-kompatiblen Endpunkt auf GPUs zu betreiben, die Sie selbst kontrollieren. Ein gutes vLLM-Docker-Deployment ist jedoch mehr als nur ein docker run-Befehl: Es benötigt eine kompatible GPU-Laufzeitumgebung, einen begrenzten Plan für Arbeitsspeicher und Parallelität, Authentifizierung am Netzwerkrand sowie eine reproduzierbare Methode, die Performance vor dem Eintreffen von Traffic zu testen.

Dieser Leitfaden behandelt die Architektur, ein sicheres erstes Deployment, die Stellschrauben, die die Kapazität tatsächlich verändern, und den Weg von einer GPU zu einer Cloud-GPU-Flotte.

Verwenden Sie vLLM Docker, wenn Sie Kontrolle über Modellgewichte, Deployment-Standort, Laufzeiteinstellungen oder eine kontinuierliche selbst gehostete Auslastung benötigen. Wenn die Betriebskosten diesen Kontrollgewinn überwiegen, sind eine verwaltete Modell-API oder ein einheitliches Gateway oft die bessere Abgrenzung.

Was vLLM Docker Ihnen bietet

vLLM veröffentlicht ein offizielles Docker-Image vllm/vllm-openai, das einen OpenAI-kompatiblen Server startet. Damit ist vLLM Docker eine nützliche Brücke zwischen einem Modell-Repository und Anwendungen, die bereits das OpenAI-Client-Format verwenden: Modellauflistung, Chat-Completions, Completions, Embeddings und verwandte kompatible Endpunkte hängen vom Modell und der bereitgestellten Serverversion ab. Die Docker-Dokumentation von vLLM enthält die aktuellen Beispiele für Images und Laufzeitumgebungen.

Die praktische Konsequenz ist einfach: Ihre Anwendung sollte keinen speziell entwickelten Modellserver-Client benötigen, nur weil Sie einen Workload auf Ihre eigene GPU verlagern. Sie benötigt weiterhin einen expliziten Modellnamen, einen API-Schlüssel, ein Timeout und ein Wiederholungsverhalten, das Ihrem eigenen Verfügbarkeitsziel entspricht.

So funktioniert die vLLM-Docker-Architektur

Auf hoher Ebene besteht vLLM Docker aus fünf Schichten:

1. Ihr Client sendet eine authentifizierte Anfrage an einen OpenAI-kompatiblen Endpunkt.
2. Der API-Server validiert und tokenisiert die Anfrage und übergibt sie dann an die vLLM-Engine.
3. Der Scheduler bündelt kompatible Arbeit und verteilt sie an einen oder mehrere GPU-Worker.
4. GPU-Worker halten Modellgewichte und den Key-Value-(KV)-Cache, während sie Tokens generieren.
5. Die Antwort wird über den API-Server zurück an den Client gestreamt.

Die zentrale Performance-Idee ist PagedAttention. Anstatt für die maximal mögliche Länge einer Anfrage einen großen zusammenhängenden KV-Cache-Bereich zu reservieren, verwaltet vLLM den KV-Zustand in Blöcken. Dadurch lassen sich Workloads mit variabler Länge leichter im verfügbaren Speicher unterbringen, und abgeschlossene Anfragen können Blöcke für spätere Arbeit freigeben. Das ursprüngliche PagedAttention-Paper beschreibt den Scheduler, GPU-Worker, logische und physische KV-Blöcke sowie den Zielkonflikt zwischen Cache-Auslastung und Batching.

Diese Architektur hat eine wichtige betriebliche Konsequenz: VRAM ist nicht nur die „Modellgröße“. Er wird zwischen Modellgewichten, Laufzeit-Overhead, Aktivierungen und einem KV-Cache geteilt, dessen Bedarf mit Kontextlänge und parallelen Anfragen wächst. Behandeln Sie Kontext, Parallelität und Speicherauslastung als eine Entscheidung – nicht als drei separate Tuning-Aufgaben.

Bevor Sie vLLM Docker auf einer Cloud-GPU ausführen

Beginnen Sie mit vier Prüfungen:

1. Wählen Sie einen getesteten Image-Tag. Pinnen Sie in der Produktion einen vLLM-Release-Tag, anstatt latest blind zu folgen. Lesen Sie die Dokumentation, die zu diesem Tag passt, bevor Sie sich auf ein Flag oder einen Standardwert verlassen.
2. Verwenden Sie ein Modell, das Sie herunterladen und bereitstellen dürfen. Einige Repositories erfordern ein Hugging-Face-Token oder die Annahme einer Modelllizenz. Pinnen Sie die Modellrevision, nachdem Sie sie validiert haben.
3. Überprüfen Sie den GPU-Zugriff außerhalb des Modell-Containers. Installieren Sie den NVIDIA-Host-Treiber und das NVIDIA Container Toolkit und validieren Sie anschließend einen GPU-fähigen Container mit nvidia-smi. Der Installationsleitfaden von NVIDIA behandelt die Voraussetzungen auf dem Host und die Konfiguration der Laufzeitumgebung.
4. Halten Sie den Port zunächst privat. Binden Sie ihn für einen Proof of Concept auf einem einzelnen Host an die Loopback-Schnittstelle, oder halten Sie den Dienst in einem privaten Subnetz hinter TLS, Authentifizierung und einem Reverse Proxy/Load Balancer. Betrachten Sie den reinen Modellserver nicht als nach außen gerichtete Sicherheitsgrenze.

Verwenden Sie den Beispielbefehl von NVIDIA, bevor Sie vLLM selbst debuggen:

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Wenn dieser Befehl die erwartete GPU nicht erkennen kann, stoppen Sie dort. Ein Modellserver-Log behebt keinen fehlenden Treiber, keine unkonfigurierte Container-Laufzeitumgebung und keine GPU, die der Cloud-VM nie zugewiesen wurde.

Einen vLLM-Docker-Server mit einer einzelnen GPU ausführen

Das Folgende ist ein bewusst klein gehaltener Ausgangspunkt. Es orientiert sich am Muster des offiziellen Images, fügt jedoch einen API-Schlüssel hinzu und bindet den veröffentlichten Port an das Loopback-Interface. Ersetzen Sie die Platzhalter durch ein Modell und ein Image-Tag, die Sie getestet haben.

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

Die Shared-Memory-Einstellung und das Einbinden des Hugging-Face-Caches folgen dem offiziellen Beispiel für vLLM Docker. Das Cache-Mount verhindert, dass dieselben Modellgewichte beim Neuerstellen des Containers erneut heruntergeladen werden. Der API-Schlüssel ist eine Anwendungskontrolle und kein Ersatz für Netzwerkisolierung, TLS, Ratenbegrenzungen oder einen Secret Manager.

Vergewissern Sie sich, dass der Server das erwartete Modell bereitstellt, bevor Sie eine Anwendung verbinden:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

Senden Sie dann eine kleine Anfrage mit derselben Modellkennung, die von /v1/models zurückgegeben wurde:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

Wenn Ihr Modell keine nutzbare Chat-Vorlage enthält, können Chat-Completion-Anfragen fehlschlagen, obwohl der Container gestartet wurde. vLLM dokumentiert, wie Sie --chat-template für Modelle bereitstellen, deren Tokenizer-Konfiguration keine solche Vorlage enthält; testen Sie dies vor dem Rollout einer Anwendung. Siehe die Hinweise zu Chat-Vorlagen.

Den Leistungsrahmen festlegen, bevor Flags geändert werden

Es gibt keinen universell richtigen vLLM-Docker-Befehl. Die passende Konfiguration hängt von Modellarchitektur, GPU-Typ und -Speicher, der Verteilung der Ein-/Ausgabelängen, Parallelität und dem Latenzziel ab. Erstellen Sie mit einer repräsentativen Arbeitslast eine Baseline und ändern Sie dann jeweils nur eine Variable.

Erfassen Sie mindestens diese Messwerte:

• Erfolgs-/Fehlerrate von Anfragen sowie Neustart-/OOM-Ereignisse.
• Zeit bis zum ersten Token (TTFT) und Zeit pro Ausgabe-Token (TPOT), segmentiert nach Prompt-Länge.
• End-to-End-Latenz bei p50 und p95/p99 unter der erwarteten Parallelität.
• Eingabe-Token, Ausgabe-Token, Wartezeit in der Queue, aktive Anfragen und GPU-Speichernutzung.
• Durchsatz nur zusammen mit dem Latenz- und Qualitätsziel, das er erfüllt hat.

Die vLLM-Docker-Flags, die die Kapazität wesentlich verändern

Die genauen Standardwerte und das Verhalten der Optionen sind versionsabhängig. Die aktuelle Referenz zu Engine-Argumenten von vLLM definiert die Steuerung für Scheduler, Cache, Parallelität und Queue; die Referenz zur Cache-Konfiguration erläutert die Einstellungen für Speichernutzung und Präfix-Cache.

Eine praktische Reihenfolge für das Tuning

1. Legen Sie --max-model-len anhand der Anwendungsgrenzen realistisch fest.
2. Beginnen Sie bei der Speicherauslastung konservativ und lassen Sie Spielraum für Treiber-/Runtime-Overhead.
3. Führen Sie Lasttests für --max-num-seqs und --max-num-batched-tokens mit realen Prompt- und Completion-Längen durch.
4. Fügen Sie Tensor-Parallelismus nur hinzu, wenn eine GPU das Modell nicht aufnehmen kann oder das Ziel dafür nicht erreicht.
5. Fügen Sie Replikate hinter einem Load Balancer hinzu, wenn Anforderungen an Verfügbarkeit oder aggregierten Traffic unabhängige Fehlerdomänen erfordern.

Diese Reihenfolge verhindert einen häufigen Fehler: GPUs hinzuzufügen oder die Parallelität zu erhöhen, bevor Sie wissen, ob die Arbeitslast tatsächlich durch Kontext, Warteschlange, Speicher oder Rechenleistung begrenzt wird.

vLLM Docker über mehrere GPUs skalieren

Für ein Modell, das mehrere GPUs benötigt, unterstützt vLLM Serving mit Tensor- und Pipeline-Parallelismus. Stellen Sie auf einem Host die GPUs dem Container bereit und setzen Sie die Tensor-Parallelgröße auf die Anzahl der GPUs, die Sie diesem Modellserver bewusst zuweisen:

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

Der Leitfaden zu Parallelismus und Skalierung von vLLM dokumentiert Tensor-Parallelismus, Pipeline-Parallelismus sowie die Wahl zwischen Single-Node- und Multi-Node-Ausführung. Übernehmen Sie 4 aus dem Beispiel nicht für einen Knoten mit zwei GPUs: Stimmen Sie das Flag auf die diesem Server zugewiesenen GPUs ab und validieren Sie Kommunikationstopologie, Speicherausgleich und Fehlerverhalten.

Details zur Implementierung, Topologieprüfungen und eine Entscheidung zwischen Tensor- und Pipeline-Parallelismus finden Sie in Flatkeys Leitfaden zur vLLM-Inferenz mit mehreren GPUs. Für eine Entscheidung zur Serving-Runtime statt zu einem Docker-Deployment siehe vLLM vs. SGLang.

Struktur eines Cloud-Deployments für die Produktion

Ein vLLM-Docker-Deployment für die Produktion trennt normalerweise den öffentlichen Edge von der GPU-Ausführung:

Legen Sie den Hugging-Face-Cache auf dauerhaftem oder bewusst vorgewärmtem Speicher ab, damit ein gewöhnlicher Neustart nicht zu einem überraschenden Modelldownload führt. Bewahren Sie die Lizenz und Zugriffskontrollen des Modells in Ihren Deployment-Unterlagen auf. Das Pinnen des Image-Tags allein reicht nicht aus, wenn das Modell-Repository auf einen sich bewegenden Branch verweist.

Für Hintergrundinformationen zur GPU-Auswahl, kontextgesteuerter Speicherplanung und dazu, wann Cloud-Infrastruktur die richtige Wahl ist, verknüpfen Sie dieses Runbook mit Flatkeys Leitfaden zu LLM-GPU-Speicheranforderungen, Leitfaden zur GPU-Cloud und Framework GPU-Cloud vs. Modell-API.

vLLM Docker ohne Raten beheben

Wenn der Server läuft, sich das Anwendungsverhalten aber weiterhin von einer gehosteten API unterscheidet, überprüfen Sie die Kompatibilität von Endpunkten und Parametern ausdrücklich. Flatkeys Leitfaden zu OpenAI-kompatiblen Inferenzservern behandelt die clientseitige Migration und die Kompatibilitätstestoberfläche.

Wann Sie vLLM Docker nicht selbst betreiben sollten

Self-Hosting ist eine Infrastrukturverpflichtung. Sie verantworten Image-Updates, Modellprovenienz, GPU-Kapazität, Knotenausfälle, Zugriffskontrolle, Latenzvalidierung und den Bereitschaftsprozess. Das kann die richtige Abwägung sein, wenn Laufzeitkontrolle die Anforderung ist.

Für Workloads, bei denen Modellauswahl, Providerverfügbarkeit oder operative Einfachheit wichtiger sind als direkte GPU-Kontrolle, sollten Sie einen verwalteten API-Pfad in der Architektur beibehalten. Flatkey ist für den ergänzenden Workflow konzipiert: eine einzige OpenAI-kompatible Integration für den Zugriff auf Modelle über verschiedene Provider hinweg mit zentralisierter Abrechnung, während ein selbst gehosteter vLLM-Endpunkt für die Workloads, die ihn tatsächlich benötigen, weiterhin eine Option bleibt.

Der richtige nächste Schritt besteht nicht darin, einen Benchmark isoliert zu maximieren. Bevor Sie vLLM Docker hinter Produktionsverkehr einsetzen, fixieren Sie Image und Modell, weisen Sie die GPU-Laufzeit nach, legen Sie eine explizite Kontext- und Warteschlangenrichtlinie fest, testen Sie mit produktionsnahen Anfragen und dokumentieren Sie den Fehlerpfad.

Häufig gestellte Fragen

Ist vLLM Docker dasselbe wie eine verwaltete LLM-API?

Nein. vLLM Docker bietet Ihnen eine Modellbereitstellungs-Laufzeit auf GPUs, die Sie selbst betreiben. Eine verwaltete API abstrahiert Modell-Hosting und GPU-Betrieb. Beide können eine OpenAI-kompatible Client-Schnittstelle bereitstellen, aber die operative Verantwortung ist unterschiedlich.

Benötigt vLLM Docker das NVIDIA Container Toolkit?

Für NVIDIA-GPU-Container benötigt der Host einen kompatiblen NVIDIA-Treiber und eine konfigurierte GPU-Container-Laufzeit. Das NVIDIA Container Toolkit ist der von NVIDIA dokumentierte Standardweg, um GPUs für Docker-Container verfügbar zu machen.

Welche vLLM-Docker-Option sollte ich zuerst optimieren?

Legen Sie zunächst eine realistische maximale Kontextlänge fest und testen Sie dann Speicherauslastung, Parallelität und Batch-Token-Limits mit einem repräsentativen Anfrage-Mix. Das Ändern von Optionen ohne eine Workload-Basis führt meist zu nicht reproduzierbaren Ergebnissen.

Kann vLLM Docker ein Modell über mehrere GPUs hinweg ausführen?

Ja. vLLM unterstützt Serving mit Tensor-Parallelität und Pipeline-Parallelität. Beginnen Sie mit einem einzelnen Host und validieren Sie die exakte GPU-Anzahl, Topologie und das Kommunikationsverhalten, bevor Sie das Design erweitern.

Quellen und weiterführende Literatur

• vLLM: Docker verwenden
• vLLM: Parallelität und Skalierung
• vLLM: Engine-Argumente
• Installationsanleitung für das NVIDIA Container Toolkit
• Effizientes Speichermanagement für das Serving großer Sprachmodelle mit PagedAttention