DEV Community

Cover image for Was ist vLLM? LLM-Inferenz beschleunigen für schnelle und skalierbare APIs
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Was ist vLLM? LLM-Inferenz beschleunigen für schnelle und skalierbare APIs

Entwickeln Sie Large-Language-Model-Anwendungen und stoßen auf langsame Inferenz, hohe Latenz oder GPU-Speichergrenzen? vLLM ist eine Open-Source-Inferenz-Engine für schnelles, speichereffizientes LLM-Serving. In diesem Leitfaden richten Sie vLLM ein, führen Batch-Inferenz aus und starten einen OpenAI-kompatiblen API-Server für Echtzeit-Workloads.

Probieren Sie Apidog noch heute aus

Was ist vLLM?

vLLM ist eine Inferenz-Engine mit hohem Durchsatz für das Serving großer Sprachmodelle. Sie ist besonders relevant, wenn Sie LLMs nicht nur lokal testen, sondern als API für mehrere Benutzer, Services oder Batch-Jobs bereitstellen möchten.

vLLM adressiert zwei typische Engpässe in LLM-Backends:

  • Langsame Inferenz bei Parallelität: Viele gleichzeitige Requests führen schnell zu Warteschlangen und hoher Latenz.
  • Ineffiziente GPU-Speichernutzung: Der KV-Cache von Transformer-Modellen kann viel VRAM belegen und die nutzbare Modellgröße oder Request-Anzahl begrenzen.

Die wichtigsten Konzepte sind:

  • PagedAttention: Verwaltet den Key-Value-Cache in Speicherblöcken statt als große zusammenhängende Bereiche.
  • Kontinuierliches Batching: Nimmt Requests dynamisch in laufende Verarbeitung auf, statt auf statische Batches zu warten.
  • OpenAI-kompatible API: Ermöglicht die Nutzung vieler bestehender Clients und Tools mit selbst gehosteten Modellen.

Warum vLLM für API- und Backend-Teams interessant ist

vLLM eignet sich für Teams, die LLM-Funktionalität produktionsnah bereitstellen möchten:

  • Mehr Durchsatz: Mehr Requests pro Sekunde bei geeigneter GPU-Hardware.
  • Bessere GPU-Auslastung: Kontinuierliches Batching hält die GPU aktiver.
  • Speichereffizienz: PagedAttention reduziert unnötigen VRAM-Verbrauch.
  • Einfache Integration: OpenAI-kompatible Endpunkte für /v1/completions und /v1/chat/completions.
  • Batch- und Online-Inferenz: Einsetzbar für Offline-Jobs und Echtzeit-APIs.
  • Breite Modellunterstützung: Llama, Mistral, Qwen, OPT, Falcon und weitere Modelle von Hugging Face oder ModelScope.

Die vollständige Modellliste finden Sie in der vLLM-Dokumentation.

Tipp: Wenn Sie LLM-APIs entwerfen, testen oder dokumentieren, können Sie Apidog in Ihren Workflow einbinden. Damit lassen sich vLLM-, OpenAI-kompatible oder eigene Endpunkte strukturieren, testen und dokumentieren.

Unterstützte LLMs

vLLM unterstützt viele Transformer-basierte Modelle, unter anderem:

  • Llama-Serie: Llama, Llama 2, Llama 3
  • Mistral und Mixtral
  • Qwen und Qwen2
  • GPT-2, GPT-J, GPT-NeoX
  • OPT
  • Bloom
  • Falcon
  • MPT
  • Weitere Modelle, einschließlich multimodaler Modelle

Prüfen Sie vor der Implementierung die aktuelle Kompatibilität in der offiziellen Liste unterstützter Modelle.

Wenn Ihr Modell nicht explizit gelistet ist, aber dieselbe Architektur wie ein unterstütztes Modell nutzt, kann es funktionieren. Testen Sie es jedoch separat, besonders bei benutzerdefinierten Architekturen oder Modellen mit trust_remote_code.

Schlüsselkonzepte: PagedAttention und kontinuierliches Batching

PagedAttention

Problem:

Traditionelle Attention-Implementierungen speichern den KV-Cache häufig in großen zusammenhängenden Speicherbereichen. Das kann zu Fragmentierung und verschwendetem GPU-Speicher führen.

Lösung:

PagedAttention teilt den KV-Cache in kleinere Blöcke auf, ähnlich wie Paging in Betriebssystemen. Dadurch kann vLLM Speicher flexibler verwalten und gemeinsame Präfixe effizienter behandeln.

Kontinuierliches Batching

Problem:

Bei statischem Batching wartet das System oft, bis ein Batch gefüllt ist. Das erhöht Latenz und lässt GPU-Zeit ungenutzt.

Lösung:

vLLM nimmt neue Requests dynamisch auf, sobald Ressourcen verfügbar sind. Das verbessert den Durchsatz, ohne jeden Request künstlich warten zu lassen.

Voraussetzungen

Für eine typische vLLM-Installation benötigen Sie:

  • Betriebssystem: Linux empfohlen. WSL2 und macOS sind möglich, Linux ist jedoch am besten unterstützt.
  • Python: 3.9, 3.10, 3.11 oder 3.12.
  • NVIDIA-GPU mit CUDA: Für produktive Performance empfohlen.
  • Virtuelle Umgebung: Verwenden Sie venv, Conda oder uv.
  • Ausreichend VRAM: Abhängig von Modellgröße, Quantisierung und Parallelität.

Prüfen Sie Ihre GPU vorab:

nvidia-smi
Enter fullscreen mode Exit fullscreen mode

vLLM installieren

Option 1: Installation mit pip 

python -m venv vllm-env
source vllm-env/bin/activate

pip install vllm
Enter fullscreen mode Exit fullscreen mode

Unter Windows/WSL beachten Sie die jeweilige Aktivierung Ihrer Umgebung. Für native Windows-Setups ist vLLM nicht die primäre Zielplattform.

Installation prüfen:

python -c "import vllm; print(vllm.__version__)"
vllm --help
Enter fullscreen mode Exit fullscreen mode

Option 2: Installation mit Conda 

conda create -n vllm-env python=3.11 -y
conda activate vllm-env

pip install vllm
Enter fullscreen mode Exit fullscreen mode

Wenn Sie eine bestimmte CUDA-/PyTorch-Kombination benötigen, installieren Sie PyTorch zuerst passend zu Ihrer Umgebung und danach vLLM.

Option 3: Installation mit uv 

uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate

uv pip install vllm
Enter fullscreen mode Exit fullscreen mode

Offline-Batch-Inferenz mit vLLM

Batch-Inferenz ist sinnvoll für:

  • Evaluationen
  • Datensatzgenerierung
  • Klassifikations- oder Extraktionsjobs
  • Migrationen bestehender Prompt-Workflows
  • Vorberechnete Antworten oder Embedding-nahe Pipelines

Beispielskript:

from vllm import LLM, SamplingParams

prompts = [
    "Die Hauptstadt Frankreichs ist",
    "Erklären Sie die Relativitätstheorie in einfachen Worten:",
    "Schreiben Sie ein kurzes Gedicht über einen regnerischen Tag:",
    "Übersetzen Sie 'Hello, world!' ins Deutsche:",
]

sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.95,
    max_tokens=150,
    stop=["\n", " Human:", " Assistant:"],
)

llm = LLM(model="mistralai/Mistral-7B-Instruct-v0.1")

outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    print("-" * 40)
    print(f"Prompt: {output.prompt!r}")
    print(f"Antwort: {output.outputs[0].text!r}")
Enter fullscreen mode Exit fullscreen mode

Ausführen:

python batch_inference.py
Enter fullscreen mode Exit fullscreen mode

Praktische Hinweise:

  • vLLM lädt Modelle standardmäßig aus dem Hugging Face Hub.
  • Für ModelScope setzen Sie: 
export VLLM_USE_MODELSCOPE=1
Enter fullscreen mode Exit fullscreen mode
  • Für kleinere GPUs testen Sie zuerst kleinere Modelle.
  • Prüfen Sie bei quantisierten Modellen die jeweilige Modellkarte und die vLLM-Dokumentation.

vLLM als OpenAI-kompatiblen API-Server starten

Für API-Workloads können Sie vLLM als Server betreiben. Dadurch können bestehende OpenAI-kompatible Clients häufig mit minimalen Änderungen weiterverwendet werden.

Server starten 

source vllm-env/bin/activate

vllm serve mistralai/Mistral-7B-Instruct-v0.1
Enter fullscreen mode Exit fullscreen mode

Der Server läuft standardmäßig auf:

http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

Für Zugriff von anderen Maschinen:

vllm serve mistralai/Mistral-7B-Instruct-v0.1 \
  --host 0.0.0.0 \
  --port 8000
Enter fullscreen mode Exit fullscreen mode

Für mehrere GPUs:

vllm serve mistralai/Mistral-7B-Instruct-v0.1 \
  --tensor-parallel-size 2
Enter fullscreen mode Exit fullscreen mode

Mit API-Key:

vllm serve mistralai/Mistral-7B-Instruct-v0.1 \
  --api-key "mein-geheimer-key"
Enter fullscreen mode Exit fullscreen mode

Wichtige Optionen:

  • --host: Host-Adresse, z. B. 0.0.0.0
  • --port: Port, z. B. 8000
  • --tensor-parallel-size: Modell über mehrere GPUs verteilen
  • --api-key: API-Key für Requests erzwingen
  • --generation-config: Generierungskonfiguration steuern
  • --chat-template: Eigene Chat-Vorlage verwenden

Completions-Endpunkt verwenden

cURL 

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.1",
    "prompt": "San Francisco ist eine Stadt in",
    "max_tokens": 50,
    "temperature": 0.7
  }'
Enter fullscreen mode Exit fullscreen mode

Mit API-Key:

curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mein-geheimer-key" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.1",
    "prompt": "Erklären Sie vLLM in einem Satz:",
    "max_tokens": 80
  }'
Enter fullscreen mode Exit fullscreen mode

Python mit OpenAI-Client 

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1",
)

completion = client.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.1",
    prompt="Erklären Sie die Vorteile der Verwendung von vLLM:",
    max_tokens=150,
    temperature=0.5,
)

print(completion.choices[0].text)
Enter fullscreen mode Exit fullscreen mode

Wenn Sie den Server mit API-Key gestartet haben:

client = OpenAI(
    api_key="mein-geheimer-key",
    base_url="http://localhost:8000/v1",
)
Enter fullscreen mode Exit fullscreen mode

Chat-Completions-Endpunkt verwenden

cURL 

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.1",
    "messages": [
      {
        "role": "system",
        "content": "Sie sind ein hilfreicher Assistent."
      },
      {
        "role": "user",
        "content": "Was ist der Hauptvorteil von PagedAttention in vLLM?"
      }
    ],
    "max_tokens": 100,
    "temperature": 0.7
  }'
Enter fullscreen mode Exit fullscreen mode

Python 

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1",
)

chat_response = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.1",
    messages=[
        {
            "role": "system",
            "content": "Sie sind ein hilfreicher Programmierassistent.",
        },
        {
            "role": "user",
            "content": "Schreiben Sie eine einfache Python-Funktion zur Berechnung der Fakultät.",
        },
    ],
    max_tokens=200,
    temperature=0.5,
)

print(chat_response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Mit Apidog können Sie solche Endpunkte als API definieren, Requests testen, Beispielantworten dokumentieren und QA-Flows für OpenAI-kompatible LLM-Backends strukturieren.

Beispiel: Minimaler API-Testplan für Ihren vLLM-Server

Wenn Sie vLLM als internen Service betreiben, testen Sie mindestens diese Fälle:

  1. Health-/Erreichbarkeitstest
    • Server startet
    • Port ist erreichbar
    • /v1/models antwortet 
curl http://localhost:8000/v1/models
Enter fullscreen mode Exit fullscreen mode

  1. Completions-Test

    • Request mit einfachem Prompt
    • Antwort enthält choices
    • max_tokens wird respektiert

  2. Chat-Completions-Test

    • System- und User-Message
    • Antwortformat ist kompatibel mit Ihrem Client

  3. Fehlerfälle

    • Falscher Modellname
    • Fehlender API-Key
    • Ungültiges JSON
    • Zu hohe max_tokens

  4. Lasttest

    • Mehrere parallele Requests
    • GPU-Auslastung beobachten
    • Latenz und Fehlerquote messen

Ein einfacher paralleler Test mit xargs:

seq 1 20 | xargs -n1 -P5 -I{} curl -s http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/Mistral-7B-Instruct-v0.1",
    "prompt": "Nennen Sie einen Vorteil von vLLM:",
    "max_tokens": 40
  }' > /tmp/vllm_test_outputs.jsonl
Enter fullscreen mode Exit fullscreen mode

Attention-Backends: FlashAttention, xFormers und FlashInfer

vLLM unterstützt mehrere Attention-Backends:

  • FlashAttention 1 & 2: Schnell auf vielen modernen NVIDIA-GPUs.
  • xFormers: Breite Kompatibilität, häufig als Fallback nützlich.
  • FlashInfer: Fortgeschrittenes Backend, je nach Setup mit manueller Installation.

Standardmäßig wählt vLLM ein passendes Backend aus. Wenn Sie ein Backend erzwingen möchten, setzen Sie die Umgebungsvariable VLLM_ATTENTION_BACKEND.

Beispiel:

export VLLM_ATTENTION_BACKEND=FLASH_ATTN
vllm serve mistralai/Mistral-7B-Instruct-v0.1
Enter fullscreen mode Exit fullscreen mode

Alternativen:

export VLLM_ATTENTION_BACKEND=XFORMERS
Enter fullscreen mode Exit fullscreen mode 
export VLLM_ATTENTION_BACKEND=FLASHINFER
Enter fullscreen mode Exit fullscreen mode

Fehlerbehebung

1. CUDA Out of Memory

Typische Maßnahmen:

  • Kleineres Modell verwenden
  • max_tokens reduzieren
  • Weniger parallele Requests senden
  • Quantisiertes Modell verwenden, z. B. AWQ oder GPTQ, wenn kompatibel
  • Modell auf mehrere GPUs verteilen: 
vllm serve mistralai/Mistral-7B-Instruct-v0.1 \
  --tensor-parallel-size 2
Enter fullscreen mode Exit fullscreen mode

GPU-Prozesse prüfen:

nvidia-smi
Enter fullscreen mode Exit fullscreen mode

2. Installations- oder Kompatibilitätsprobleme

Prüfen Sie:

  • NVIDIA-Treiber
  • CUDA-Version
  • PyTorch-Version
  • Python-Version
  • vLLM-Version

Siehe auch die PyTorch-Kompatibilitätsmatrix.

Für reproduzierbare Setups können die offiziellen vLLM Docker-Images hilfreich sein.

3. Modell lädt nicht

Prüfen Sie:

  • Ist der Modellname korrekt?
  • Haben Sie Zugriff auf gated Modelle?
  • Ist genug Festplattenspeicher vorhanden?
  • Benötigt das Modell trust_remote_code=True?
  • Funktioniert die Internetverbindung zum Modell-Hub?

Beispiel mit lokalem Modellpfad:

from vllm import LLM

llm = LLM(model="/models/Mistral-7B-Instruct-v0.1")
Enter fullscreen mode Exit fullscreen mode

4. Langsame Inferenz

Mögliche Ursachen:

  • GPU ist nicht ausgelastet
  • Modell ist zu groß für die Hardware
  • Zu lange Prompts oder zu hohe max_tokens
  • Unpassendes Attention-Backend
  • Veraltete Treiber oder Abhängigkeiten

GPU-Auslastung beobachten:

watch -n 1 nvidia-smi
Enter fullscreen mode Exit fullscreen mode

Testen Sie außerdem verschiedene Sampling-Parameter:

{
  "max_tokens": 80,
  "temperature": 0.3,
  "top_p": 0.9
}
Enter fullscreen mode Exit fullscreen mode

5. Unerwartete oder schlechte Antworten

Prüfen Sie:

  • Verwendet das Modell das richtige Prompt-Format?
  • Ist eine Chat-Vorlage erforderlich?
  • Sind temperature und top_p passend?
  • Ist das Modell für Ihre Sprache oder Aufgabe geeignet?
  • Nutzen Sie den richtigen Endpunkt: Completions vs. Chat Completions?

Für Chat-Modelle ist die korrekte Rollenstruktur wichtig:

{
  "messages": [
    {
      "role": "system",
      "content": "Sie sind ein hilfreicher Assistent."
    },
    {
      "role": "user",
      "content": "Erklären Sie PagedAttention."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Praktischer Deployment-Ablauf

Ein einfacher Ablauf für ein internes vLLM-Backend:

  1. Modell auswählen

    • Modellgröße an GPU-VRAM anpassen
    • Modellkarte lesen
    • Lizenz und Zugriff prüfen

  2. Lokalen Smoke-Test durchführen

    • Batch-Inferenz mit wenigen Prompts
    • Antwortqualität prüfen

  3. API-Server starten

    • Host, Port und API-Key konfigurieren
    • Optional mehrere GPUs verwenden

  4. API-Vertrag definieren

    • Request- und Response-Schemas dokumentieren
    • Fehlerantworten festlegen
    • Beispielrequests pflegen

  5. Tests automatisieren

    • Completions
    • Chat Completions
    • Fehlerfälle
    • Latenz und Durchsatz

  6. Monitoring ergänzen

    • GPU-Auslastung
    • Request-Latenz
    • Fehlerquote
    • Speichernutzung

Nächste Schritte

Mit vLLM können Sie LLM-gestützte APIs effizienter bereitstellen und skalieren. Für produktive Workflows sollten Sie neben der Modellinferenz auch API-Design, Tests und Dokumentation standardisieren.

Sinnvolle nächste Schritte:

  • vLLM mit einem kleineren Modell lokal testen
  • OpenAI-kompatible Endpunkte in Ihren bestehenden Client integrieren
  • Lasttests mit realistischen Prompts durchführen
  • API-Requests und Fehlerfälle dokumentieren
  • QA für LLM-Endpunkte automatisieren

Erweiterte vLLM-Funktionen wie Quantisierung, Multi-LoRA, verteiltes Serving und spekulatives Decoding finden Sie in der offiziellen Dokumentation.

Top comments (0)