vLLM Docker: GPU-basierten Inferenzserver innerhalb weniger Minuten starten

vLLM veröffentlicht ein offizielles Docker-Image, vllm/vllm-openai, das einen sofort einsatzbereiten, mit der OpenAI-API kompatiblen Inferenzserver enthält. Der schnellste Weg: Installieren Sie das NVIDIA Container Toolkit auf dem Hostsystem und führen Sie das Image dann mit --gpus all sowie einer Hugging-Face-Modell-ID aus. Sobald das Modell heruntergeladen ist, läuft der Server auf Port 8000 und akzeptiert dieselben Anfragen wie die OpenAI-API.

Voraussetzungen

• Docker Engine 20.10+ — Docker Desktop unter Windows und macOS funktioniert über das WSL2-Backend.
• NVIDIA-GPU mit einem Treiber, der CUDA 12.x unterstützt. Führen Sie aus: nvidia-smi um dies zu bestätigen; die angezeigte „CUDA-Version“ ist die höchste Version, die Ihr Treiber unterstützt.
• NVIDIA Container Toolkit — die Schnittstelle, über die Docker auf die GPU zugreifen kann. Siehe den nächsten Abschnitt.
• Ausreichend VRAM für Ihr Zielmodell. Verwenden Sie den VRAM-Rechner um vor dem Herunterladen eines Modells zu prüfen, ob genügend Speicherplatz vorhanden ist.

Installation des NVIDIA Container Toolkit

Überspringen Sie diesen Abschnitt, falls docker run --gpus all nvidia/cuda:12.0-base nvidia-smi bereits auf Ihrem System funktioniert.

Linux (Ubuntu/Debian):

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

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

RHEL/CentOS: Ersetzen Sie die deb Repository-URL durch die entsprechende rpm URL aus der NVIDIA-Dokumentation und verwenden Sie dnf anstelle von apt-get.

Windows (WSL2): Installieren Sie den NVIDIA-Treiber für Windows auf dem Host – eine separate Installation des Container-Toolkits innerhalb von WSL2 ist nicht erforderlich. Docker Desktop übernimmt die GPU-Durchleitung automatisch.

macOS: NVIDIA-GPUs werden unter macOS nicht unterstützt. vLLM lässt sich auf Apple Silicon über Docker mit GPU-Beschleunigung nicht ausführen. Für lokale Inferenz auf Apple-Hardware empfehlen wir stattdessen einen CPU-only-Build oder eine andere Laufzeitumgebung.

Minimaler Ausführungsbefehl

docker run --runtime nvidia --gpus all 
  --ipc=host 
  -v ~/.cache/huggingface:/root/.cache/huggingface 
  -p 8000:8000 
  vllm/vllm-openai:latest 
  --model meta-llama/Meta-Llama-3-8B-Instruct

Um ein geschütztes Modell (z. B. Llama 3 oder Mistral) herunterzuladen, übergeben Sie zusätzlich -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Speichern Sie das Token in einer .env -Datei und übergeben Sie diese mittels --env-file .env statt direkt in der Shell-Historie – so vermeiden Sie Sicherheitsrisiken.

Einbinden des Hugging-Face-Caches

vLLM lädt Modellgewichte in den Ordner /root/.cache/huggingface innerhalb des Containers herunter. Ohne Volume-Mount wird bei jedem docker run das gesamte Modell erneut heruntergeladen – oft 5–80 GB. Die Mount-Zeile lautet:

-v ~/.cache/huggingface:/root/.cache/huggingface

Falls Ihre Modelle sich an einem anderen als dem Standardort befinden, setzen Sie -e HF_HOME=/your/path und diesen Pfad stattdessen einbinden. Für Umgebungen ohne Internetzugang laden Sie das Modell zunächst mit huggingface-cli download herunter und übergeben dann --model /pfad/in/container zusammen mit einer Volume-Einbindung des Verzeichnisses mit den Gewichten.

Wichtige vLLM-Server-Flags

Diese Flags werden nach dem Imagename übergeben – sie sind Argumente für den vLLM-Serverprozess, nicht für Docker.

Sind Sie sich unsicher, ob Ihre GPU über ausreichend VRAM für ein bestimmtes Modell verfügt? Die Leitfaden zu VRAM-Anforderungen listet gängige Modelle auf, und der VRAM-Rechner ermöglicht es Ihnen, Quantisierung und Batch-Größe einzugeben. Für Entscheidungen beim Hardwarekauf siehe die GPU-Empfehlungsanleitung.

Freigabe und Testen des OpenAI-kompatiblen Endpunkts

Sobald der Container die Meldung INFO: Application startup completeausgibt, ist die API aktiv.

# Liste geladener Modelle
curl http://localhost:8000/v1/models

# Textergänzung
curl http://localhost:8000/v1/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "Die Hauptstadt Frankreichs ist", "max_tokens": 20}'

# Chat-Ergänzung
curl http://localhost:8000/v1/chat/completions 
  -H "Content-Type: application/json" 
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "messages": [{"role": "user", "content": "Hallo"}]}'

Jeder OpenAI-kompatible Client – das Python- openai SDK, LangChain, LlamaIndex – funktioniert, indem Sie base_url="http://localhost:8000/v1" festlegen und einen beliebigen nicht-leeren String als api_key.

Beispiel für Docker Compose

Für dauerhafte Bereitstellungen ist eine Compose-Datei einfacher zu verwalten als ein langer docker run Befehl:

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "8000:8000"
    ipc: host
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: >
      --model meta-llama/Meta-Llama-3-8B-Instruct
      --gpu-memory-utilization 0.90
      --max-model-len 8192

Beginnen Sie mit docker compose up -d. Der deploy.resources -Block entspricht in Compose v3 der Option --gpus all.

Häufige Fehler und deren Behebung

Häufig gestellte Fragen

Welches vLLM-Docker-Image-Tag sollte ich verwenden?

vllm/vllm-openai:latest verfolgt die aktuellste Version und eignet sich gut für Experimente. Für Produktionsumgebungen sollten Sie stattdessen auf ein bestimmtes Versions-Tag festlegen (z. B. v0.6.0) – dadurch werden Builds reproduzierbar. Jedes Release-Tag auf Docker Hub gibt die CUDA-Version an, gegen die das Image kompiliert wurde; diese muss kleiner oder gleich der von Ihrem Treiber unterstützten CUDA-Version sein.

Kann ich vLLM in Docker ohne GPU ausführen?

Das Standard-Image erfordert eine NVIDIA-GPU. Eine rein CPU-basierte Inferenz ist möglich, indem vLLM aus dem Quellcode mit VLLM_TARGET_DEVICE=cpukompliliert wird; allerdings ist die Durchsatzleistung um Größenordnungen geringer und für Produktions-Serving nicht praktikabel. Für CPU-basierte lokale Inferenz sind llama.cpp oder Ollama besser geeignete Alternativen – siehe dazu den Ollama-Leitfaden für einen Vergleich.

Wie führe ich ein gesperrtes Modell aus, für das ein Hugging-Face-Token erforderlich ist?

Übergeben Sie das Token als Umgebungsvariable: -e HUGGING_FACE_HUB_TOKEN=hf_yourtoken. Speichern Sie es in einer .env -Datei und verweisen Sie darauf mittels --env-file .env – so vermeiden Sie, dass das Token im Shell-Verlauf sichtbar wird. Der Server nutzt das Token beim ersten Herunterladen des Modells; danach ist es nicht mehr erforderlich, sobald die Gewichte lokal zwischengespeichert sind.

Was bewirkt die Option –tensor-parallel-size und wann benötige ich sie?

Tensor-Parallelisierung verteilt die Gewichtsmatrizen des Modells auf mehrere GPUs und ermöglicht so den Einsatz von Modellen, die zu groß für eine einzelne GPU sind. Legen Sie diesen Wert auf die Anzahl der GPUs fest, die Sie nutzen möchten (üblich sind 2 oder 4). Diese Zahl muss mit der Anzahl der GPUs übereinstimmen, die Sie über --gpusangeben, und die Anzahl der Aufmerksamkeitsköpfe des Modells muss durch diese Zahl teilbar sein.

Ist der Betrieb von vLLM in Docker kosteneffizienter als eine verwaltete API?

Das hängt vollständig von Ihrem Anfragenvolumen ab. Bei Self-Hosting fallen hohe Fixkosten an (GPU-Instanz oder Hardware), jedoch nahezu keine variablen Kosten pro Anfrage. Verwaltete APIs verursachen keine Fixkosten, berechnen aber pro Token Gebühren. Nutzen Sie den Selbsthosting vs. API-Rechner , um Ihren Break-even-Punkt zu ermitteln, bevor Sie sich für eine Infrastruktur entscheiden.

Wie stelle ich mehrere Modelle gleichzeitig bereit?

Führen Sie je ein Container pro Modell aus, wobei jeder Container einem anderen Host-Port zugeordnet ist (z. B. 8000, 8001). vLLM unterstützt derzeit kein Multi-Model-Serving innerhalb eines einzigen Prozesses. Platzieren Sie einen Reverse-Proxy wie nginx oder Caddy vor den Containern, um Anfragen nach Modellname an den entsprechenden Port weiterzuleiten.