Bereitstellen von vLLM in production

#Was vLLM leistet und was es voraussetzt

vLLM ist eine Open-Source-Inferenz-Engine, die am Sky Computing Lab der UC Berkeley entstand. Ihr zentrales Konzept, PagedAttention, verwaltet den Schlüssel-Wert-Cache des Attention-Mechanismus seitenweise, ähnlich wie den virtuellen Speicher eines Betriebssystems. Laut der ursprünglichen Projektankündigung von 2023 verschwendeten bestehende Systeme einen großen Teil ihres Speichers, und vLLM erreichte in damaligen Tests bis zu den 24-fachen Durchsatz von Hugging Face Transformers und bis zu den 3,5-fachen Durchsatz von TGI. Diese Zahlen sind alt und gelten nur für diesen Testaufbau: Sie zeigen eine Richtung auf, nicht die Leistung, die Sie mit Ihrem Modell und Ihrer Karte erzielen werden.

Als Voraussetzungen nennt die aktuelle Dokumentation Linux und Python 3.10 bis 3.13; auf dem Mac gibt es einen separaten Weg, vLLM-Metal, der auf MLX basiert. Der Server stellt eine OpenAI-kompatible API bereit, lauscht standardmäßig auf Port 8000 und stellt jeweils nur ein Modell bereit: Für mehrere Modelle sind mehrere Instanzen erforderlich.

#Wann vLLM statt Ollama wählen

Der Unterschied liegt nicht in der Fähigkeit, Anfragen parallel zu verarbeiten, die auch Ollama bietet, sondern darin, wie der Speicher aufgeteilt wird. Laut der FAQ von Ollama multipliziert die parallele Verarbeitung eines Modells die Kontextgröße mit der Anzahl der Anfragen: Ein Kontext von 2.000 Tokens wird bei 4 parallelen Anfragen zu einem Kontext von 8.000 Tokens im Speicher, der im Voraus reserviert wird. vLLM weist seinem Cache bei Bedarf Speicher in Blöcken zu und bündelt laufende Anfragen in denselben Berechnungen.

Faustregel: Wenn weniger als drei Personen das Modell gleichzeitig nutzen oder Sie häufig das Modell wechseln möchten, reicht Ollama aus. Bei drei oder mehr gleichzeitigen Nutzern oder einem einzigen Modell, das durchgehend bereitgestellt wird, lohnt sich der zusätzliche Aufwand für vLLM. Der Vergleichsleitfaden erläutert die Wahl im Detail.

#Wann vLLM eine schlechte Wahl ist

vLLM bringt einem einzelnen Nutzer mit einer GPU mit 8 bis 12 GB keinen Vorteil: Für einen gemeinsam genutzten Cache fehlt der Speicher, und Ollama oder llama.cpp lassen sich einfacher starten. Es eignet sich schlecht, wenn Sie im Laufe des Tages zwischen fünf Modellen wechseln, da für jedes Modell eine Instanz neu gestartet werden muss. Auf einem Mac führt der Weg über MLX. Wenn Sie schließlich eine Chatoberfläche für das Team statt einer API für hohe Last benötigen, eignet sich ein Stack aus Ollama und Open WebUI besser und erfordert weniger Betriebsaufwand.

• Ollama oder vLLM im Produktionsbetrieb: der Vergleich
• vLLM: Was es ist, für wen es geeignet ist und wann Sie es einsetzen sollten

#Den Speicherbedarf bestimmen: die Berechnung, die vor allem anderen erfolgen muss

Ein vLLM-Server wird anhand des Schlüssel-Wert-Caches dimensioniert, nicht anhand der Modellgewichte. Nach dem Laden des Modells reserviert vLLM einen Anteil des GPU-Speichers, laut dem aktuellen Konfigurationscode standardmäßig 92 %, und verwendet den gesamten verbleibenden Speicher für den Cache. Dieser verbleibende Speicher bestimmt, wie viele Konversationstokens gleichzeitig vorgehalten werden können und damit, wie viele Nutzer Sie gleichzeitig bedienen können.

Nehmen wir Qwen2.5-7B-Instruct, dessen Modellprofil 7,61 Milliarden Parameter, 28 Schichten und 4 Schlüssel-Wert-Köpfe (gruppierte Attention) angibt. Die Modellgewichte benötigen bei 16 Bit etwa 15,2 GB. Der Cache für ein Token benötigt 2 (Schlüssel und Werte) × 28 Schichten × 4 Köpfe × 128 Dimensionen × 2 Byte, also 57.344 Byte, etwa 56 KiB.

Diese Obergrenzen sind hoch angesetzt: Rechenpuffer und CUDA-Graphen beanspruchen einen Teil des verbleibenden Speichers, und das Modell kann ein anderes Profil haben. Die Methode gilt weiterhin für jedes Modell: Lesen Sie die Anzahl der Schichten und der Key-Value-Heads im Modelldatenblatt nach, berechnen Sie den Speicherbedarf pro Token und teilen Sie den verbleibenden Speicher durch diesen Wert. Wenn die Logs Präemptionen melden, empfiehlt die Dokumentation, gpu_memory_utilization zu erhöhen oder max_num_seqs zu reduzieren.

Zwei Maßnahmen vergrößern den Cache, ohne die Grafikkarte zu wechseln: eine quantisierte Modellversion laden, die einen Teil des von den Gewichten belegten Speichers freigibt, oder --max-model-len begrenzen, wodurch kein Platz für Kontexte reserviert wird, die niemand nutzt. Die erste Maßnahme kann etwas Qualität kosten; die zweite hat keine Nachteile, solange Ihre Anfragen kurz bleiben.

#1. Installation

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

Die Dokumentation empfiehlt uv, das automatisch die passende PyTorch-Version anhand Ihres CUDA-Treibers auswählt. Für eine AMD-GPU erfolgt die Installation über einen speziellen Index; für Intel, TPU oder Ascend gibt es Plugins. Im Produktivbetrieb vermeidet das Docker-Image Konflikte zwischen CUDA-Versionen und lässt sich durch einen einfachen Wechsel des Tags aktualisieren.

#2. Server starten

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --api-key "$VLLM_API_KEY"

Der Befehl vllm serve ersetzt den alten Aufruf python -m vllm.entrypoints.openai.api_server, den die aktuelle Dokumentation nicht mehr verwendet. Beim ersten Start werden die Modellgewichte von Hugging Face heruntergeladen: Planen Sie ausreichend Festplattenspeicher ein (etwa 15 GB für ein 7B-Modell mit 16 Bit). Der Server verwendet standardmäßig die Datei generation_config.json aus dem Modellrepository und damit die vom Herausgeber empfohlenen Sampling-Parameter; --generation-config vllm stellt die Standardwerte von vLLM wieder her.

curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

#3. Docker und systemd

Das offizielle Image vllm/vllm-openai ist der sicherste Weg. Binden Sie den Hugging Face-Cache ein, um die Gewichte nicht erneut herunterzuladen, sowie ein Volume für den Kompilierungscache: Andernfalls startet jeder neue Container mit einem leeren Cache und kompiliert die Artefakte seines Modells erneut. Beachten Sie, dass das Image standardmäßig als root ausgeführt wird; die Dokumentation beschreibt die Ausführung mit einem nicht privilegierten Benutzer (--user 2000:0).

docker run --rm --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v vllm-cache:/root/.cache/vllm \
  -p 8000:8000 \
  --ipc=host \
  -e VLLM_API_KEY=$VLLM_API_KEY \
  vllm/vllm-openai:latest \
  Qwen/Qwen2.5-7B-Instruct

[Unit]
Description=vLLM OpenAI API
After=network.target

[Service]
Type=simple
User=vllm
EnvironmentFile=/etc/vllm/env
ExecStart=/opt/vllm/bin/vllm serve Qwen/Qwen2.5-7B-Instruct --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

#4. Die Parameter, die zählen

Ein Grundsatz aus der Dokumentation: Wenn das Modell auf eine einzige GPU passt, ist eine verteilte Ausführung wahrscheinlich unnötig; passt es nicht auf eine einzelne GPU, aber auf einen Knoten, verwendet man Tensorparallelismus mit --tensor-parallel-size. Bereits quantisierte Modelle werden ohne besondere Option direkt vom Hub geladen: Die Option --quantization dient nur der dynamischen Quantisierung.

• KV-Cache quantisieren: VRAM sparen
• Flash Attention: in llama.cpp, Ollama und vLLM aktivieren

#5. Den Durchsatz korrekt messen

Der Befehl vllm bench serve sendet Anfragen an den Server und meldet den Durchsatz, die Zeit bis zum ersten Token (TTFT) und die Latenz zwischen Tokens. Die Dokumentation erläutert, dass diese Benchmarks vor allem der Bewertung von Funktionen und der Erkennung von Regressionen dienen, und empfiehlt GuideLLM zum Testen eines Produktionsservers.

vllm bench serve \
  --backend vllm \
  --model Qwen/Qwen2.5-7B-Instruct \
  --endpoint /v1/completions \
  --dataset-name sharegpt \
  --dataset-path CHEMIN/ShareGPT_V3_unfiltered_cleaned_split.json \
  --num-prompts 200

#Inbetriebnahme und Betrieb

Nach der Dimensionierung folgt die Inbetriebnahme immer derselben Abfolge. Sie gilt für ein Team von etwa zwanzig Personen, die dasselbe Modell mit 7 bis 8 Milliarden Parametern auf einer Grafikkarte mit 24 oder 48 GB abfragen.

1. 01
   Modell und Format auswählen

   Nur ein Modell pro Instanz. Bevorzugen Sie je nach verfügbarem Speicher ein Repository mit einem bereits quantisierten Modell oder einem Modell im 16-Bit-Format.
2. 02
   Den Cache berechnen

   Wenden Sie den Token-basierten Berechnungsansatz aus dem Abschnitt zur Dimensionierung an, um --max-model-len und --max-num-seqs festzulegen.
3. 03
   In Docker starten

   Verwenden Sie das offizielle Image mit eingebundenem Hugging Face-Cache und einem festgeschriebenen Versions-Tag statt latest, damit eine Aktualisierung das Verhalten nicht verändert.
4. 04
   Proxy hinzufügen

   Reverse-Proxy mit einer Positivliste für Routen, TLS und einer Begrenzung der Anfragerate, ergänzt durch den API-Schlüssel.
5. 05
   Messen

   Starten Sie einen Lasttest mit vllm bench serve, variieren Sie dabei den Seed und notieren Sie die TTFT und den Gesamtdurchsatz.
6. 06
   Überwachen

   Binden Sie die Erfassung der Metriken vom Endpunkt /metrics in Ihr Monitoring-Tool ein.

Achten Sie auf Signale, die auf einen Cache-Mangel hindeuten: Präemptionen in den Protokollen, steigende TTFT und länger werdende Warteschlangen. Die Dokumentation weist darauf hin, dass Präemption, deren Standardmodus die Neuberechnung ist, den Dienst schützt, aber die Ende-zu-Ende-Latenz verschlechtert. Wenn sie häufig auftritt, erhöhen Sie gpu_memory_utilization, verkürzen Sie den Kontext oder begrenzen Sie die Anzahl gleichzeitiger Anfragen. Fügen Sie als letzten Ausweg eine GPU hinzu und verteilen Sie das Modell mithilfe von Tensorparallelismus.

#6. Sicherheit und Netzwerkzugriff: --api-key reicht nicht aus

Anders als oft zu lesen ist, kann vLLM einen API-Schlüssel prüfen, mit --api-key oder der Umgebungsvariable VLLM_API_KEY. Die Sicherheitsdokumentation betont jedoch: Der Schlüssel schützt nur die Routen unter /v1, /v2, /inference und /cohere. Andere Routen bleiben ohne Authentifizierung, darunter Inferenzrouten außerhalb von /v1, Steuerungsrouten wie /pause oder /abort_requests sowie /health. Verlassen Sie sich daher niemals allein auf --api-key.

Reverse Proxy

Schalten Sie nginx, Envoy oder ein Kubernetes-Gateway vor vLLM, verwenden Sie eine Zulassungsliste mit ausschließlich den Routen, die zugänglich sein sollen, und blockieren Sie alle anderen.

Netzwerk

Ein VPN oder ein isoliertes Netzwerk: Die Kommunikation zwischen den Knoten einer verteilten Bereitstellung ist standardmäßig nicht abgesichert.

Entwicklungsmodus

Aktivieren Sie niemals VLLM_SERVER_DEV_MODE=1 im Produktivbetrieb: Dadurch werden gefährliche Endpunkte zugänglich.

Grenzen

Setzen Sie Rate-Limiting und die Validierung von Anfragen auf Proxy-Ebene um, wie es die Dokumentation empfiehlt.

Protokolle

Notieren Sie, wer was sendet, für Debugging und Audit-Zwecke.

• Einen Server für lokale KI absichern: Authentifizierung, Reverse Proxy, Netzwerkzugriff

• Quelle: Schnellstart von vLLM
• Quelle: Sicherheit von vLLM
• Quelle: vLLM mit Docker
• Quelle: Ankündigung von vLLM und PagedAttention