Tag 3: vLLM-Grundlagen – Engine, Sizing, Manifest
Ziel: Du rechnest den Speicherbedarf eines Modells aus, kennst die wichtigen vLLM-Flags mit ihren Defaults und hast ein geprüftes GPU-Manifest für Tag 11. · Dauer: ca. 75 min · Voraussetzung: Tag 2
Briefing
- vLLM ist die Standard-Engine für LLMs auf GPUs:
OpenAI-API, Continuous Batching, viele Modelle. Dieses Kapitel bezieht
sich auf v0.31.0 (Image
vllm/vllm-openai:v0.31.0, rund 10 GB). - PagedAttention: Der KV-Cache (Zwischenergebnisse jedes Tokens) liegt in festen Blöcken wie Speicherseiten. Kein Verschnitt, viele Anfragen teilen sich die GPU, gleiche Prompt-Anfänge werden wiederverwendet (Prefix-Caching).
- Continuous Batching: Neue Anfragen steigen in jeden Rechenschritt ein, statt auf einen vollen Batch zu warten.
- Den GPU-Speicher teilen sich Gewichte (fix) und KV-Cache (der Rest). Der Rest bestimmt, wie viele Anfragen parallel laufen.
- In kind gibt es keine GPU: Heute rechnest, liest und validierst du. vLLM auf der CPU ist optional (Drill 5).
GPU-Speicher (z. B. L4, 24 GiB)
┌────────────────────────────────────────────┬────────┐
│ --gpu-memory-utilization 0.92 = 22 GiB │ Rest │
│ ┌──────────────┬──────────┬──────────────┐ │ CUDA, │
│ │ Gewichte │ Aktivie- │ KV-Cache │ │ andere │
│ │ 8B bf16=15GiB│ rungen │ = Parallel- │ │ │
│ │ │ ~1,5 GiB │ kapazität │ │ │
│ └──────────────┴──────────┴──────────────┘ │ │
└────────────────────────────────────────────┴────────┘
Drill 1: Speicherbedarf rechnen
Gewichte: Parameter × Bytes pro Gewicht. KV-Cache pro Token: 2 (K und
V) × Layer × KV-Heads × head_dim × Bytes. Die Werte stehen in der
config.json des Modells.
mkdir -p ~/ki-lab/tag03 ~/ki-lab/code/vllm-basics
curl -sL https://huggingface.co/Qwen/Qwen3-8B/resolve/main/config.json \
| jq -c '{num_hidden_layers, num_key_value_heads, head_dim, torch_dtype}'Erwartet:
{"num_hidden_layers":36,"num_key_value_heads":8,"head_dim":128,"torch_dtype":"bfloat16"}
Das Skript rechnet für dich weiter:
cat > ~/ki-lab/code/vllm-basics/sizing.py <<'EOF'
#!/usr/bin/env python3
"""Grobe vLLM-Sizing-Rechnung: Gewichte + KV-Cache pro Token und pro GPU.
Aufruf: python3 sizing.py <hf-repo> <params_mrd> <gpu_gib> [max_len] [kv_bytes]
Beispiel: python3 sizing.py Qwen/Qwen3-8B 8.2 24 8192 2
"""
import json
import sys
import urllib.request
GIB = 1024**3
def load_config(repo: str) -> dict:
url = f"https://huggingface.co/{repo}/resolve/main/config.json"
with urllib.request.urlopen(url, timeout=20) as resp:
cfg = json.load(resp)
return cfg.get("text_config", cfg) # multimodale Modelle verschachteln
def main() -> None:
if len(sys.argv) < 4:
sys.exit(__doc__)
repo, params = sys.argv[1], float(sys.argv[2])
gpu_gib = float(sys.argv[3])
max_len = int(sys.argv[4]) if len(sys.argv) > 4 else 8192
kv_bytes = int(sys.argv[5]) if len(sys.argv) > 5 else 2 # bf16=2, fp8=1
util = 0.92 # vLLM-Default --gpu-memory-utilization
c = load_config(repo)
layers = c["num_hidden_layers"]
kv_heads = c.get("num_key_value_heads", c["num_attention_heads"])
head_dim = c.get("head_dim") or c["hidden_size"] // c["num_attention_heads"]
weights = params * 1e9 * 2 / GIB # bf16-Gewichte
per_token = 2 * layers * kv_heads * head_dim * kv_bytes # K und V
budget = gpu_gib * util - weights - 1.5 # ~1,5 GiB Aktivierungen/Graphen
tokens = int(budget * GIB / per_token) if budget > 0 else 0
print(f"Modell {repo}")
print(f"Layer/KV-Heads {layers}/{kv_heads}, head_dim {head_dim}")
print(f"Gewichte (bf16) {weights:5.1f} GiB")
print(f"KV pro Token {per_token / 1024:5.1f} KiB")
print(f"KV-Budget {max(budget, 0):5.1f} GiB = {tokens} Tokens")
print(f"Volle Sequenzen {tokens // max_len} à {max_len} Tokens")
if __name__ == "__main__":
main()
EOF
cd ~/ki-lab/code/vllm-basics
python3 sizing.py Qwen/Qwen3-8B 8.2 24 8192Erwartet:
Modell Qwen/Qwen3-8B
Layer/KV-Heads 36/8, head_dim 128
Gewichte (bf16) 15.3 GiB
KV pro Token 144.0 KiB
KV-Budget 5.3 GiB = 38639 Tokens
Volle Sequenzen 4 à 8192 Tokens
Nur vier volle 8k-Gespräche gleichzeitig – auf einer 24-GiB-Karte ist ein 8B-Modell in bf16 eng. Zwei Hebel, ohne die Hardware zu ändern:
python3 sizing.py Qwen/Qwen3-8B 8.2 24 8192 1 | tail -3Erwartet:
KV pro Token 72.0 KiB
KV-Budget 5.3 GiB = 77278 Tokens
Volle Sequenzen 9 à 8192 Tokens
Warum? --kv-cache-dtype=fp8 halbiert den KV-Cache. Der
zweite Hebel sind quantisierte Gewichte (AWQ/FP8, Tag 11): 8 GiB statt
15 GiB lassen mehr Platz für den Cache. Die Rechnung ist eine
Abschätzung – vLLM loggt beim Start die echte Zahl:
GPU KV cache size: … tokens, Maximum concurrency for 8,192 tokens per request: …x.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Flags und Defaults aus der Quelle
Defaults ändern sich zwischen Versionen. Prüfe sie im Code des Tags, den du betreibst – nicht im Blog von letztem Jahr.
SRC=https://raw.githubusercontent.com/vllm-project/vllm/v0.31.0/vllm
curl -sL $SRC/config/cache.py | grep -nE \
'^ (gpu_memory_utilization|enable_prefix_caching|cache_dtype): '
curl -sL $SRC/config/scheduler.py \
| grep -nE '^ (max_num_seqs|enable_chunked_prefill): 'Erwartet:
103: gpu_memory_utilization: float = Field(default=0.92, gt=0, le=1)
123: cache_dtype: CacheDType = "auto"
142: enable_prefix_caching: bool = True
63: max_num_seqs: int = Field(default=DEFAULT_MAX_NUM_SEQS, ge=1)
135: enable_chunked_prefill: bool = True
| Flag | Default v0.31 | Wann ändern |
|---|---|---|
--max-model-len |
aus Modell (Qwen3-8B: 40960) | fast immer kleiner setzen, spart KV-Cache |
--gpu-memory-utilization |
0.92 |
0.85–0.90, wenn DCGM o. Ä. mitläuft |
--max-num-seqs |
256 (L4/RTX), 1024 (H100) |
begrenzt parallele Sequenzen |
--max-num-batched-tokens |
2048 (L4/RTX) |
höher = Durchsatz, niedriger = TTFT |
--kv-cache-dtype |
auto (= Modell-dtype) |
fp8 verdoppelt die Kapazität |
--quantization |
aus Modell-Config | selten nötig, AWQ/FP8-Modelle erkennt vLLM |
--tensor-parallel-size |
1 |
Modell größer als eine GPU |
--served-model-name |
wie --model |
kurzer Name für LiteLLM (Tag 4) |
--enable-prefix-caching |
an, wenn das Modell es kann | --no-enable-prefix-caching nur zum Debuggen |
--api-key / VLLM_API_KEY |
keiner | immer setzen, schützt aber nur /v1/* |
--runner pooling |
auto |
Embedding-Modelle (statt des alten --task embed) |
--enable-auto-tool-choice |
aus | mit --tool-call-parser für Tool Calling |
Achtung:
--taskgibt es in v0.31 nicht mehr. Ältere Anleitungen mit--task embedbrechen beim Start ab; nimm--runner pooling(meist erkenntautoEmbedding-Modelle selbst).
Sicherheit: Laut Code-Kommentar zu
api_keyschützt der Key nur/v1,/v2und/inference./invocations,/metricsund/healthbleiben offen – vLLM gehört hinter LiteLLM und eine NetworkPolicy (Tag 12).
Die Werte von max-num-seqs und
max-num-batched-tokens hängen von der GPU ab:
curl -sL $SRC/engine/arg_utils.py \
| grep -nE 'GiB_bytes:|GiB_bytes and|UsageContext.OPENAI_API_SERVER: [0-9]+' | head -6Erwartet (gekürzt):
2858: if device_memory >= 160 * GiB_bytes:
2862: UsageContext.OPENAI_API_SERVER: 16384,
2866: UsageContext.OPENAI_API_SERVER: 1024,
2868: elif device_memory >= 70 * GiB_bytes and "a100" not in device_name:
2872: UsageContext.OPENAI_API_SERVER: 8192,
2876: UsageContext.OPENAI_API_SERVER: 1024,
Unter 70 GiB (L4, RTX 4000 Ada, RTX 4090) greift der
else-Zweig mit 2048 Tokens und
256 Sequenzen.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Das GPU-Manifest
Die Vorlage für Tag 11 liegt im Buch-Code unter
vllm-basics/vllm-gpu.yaml (kopiert nach
~/ki-lab/code/). Lies den Container-Teil:
sed -n '/containers:/,/ports:/p' ~/ki-lab/code/vllm-basics/vllm-gpu.yamlErwartet:
containers:
- name: vllm
image: vllm/vllm-openai:v0.31.0
args:
- Qwen/Qwen3-8B
- --served-model-name=qwen3-8b
- --max-model-len=8192
- --gpu-memory-utilization=0.90
- --max-num-seqs=32
- --kv-cache-dtype=fp8
env:
- name: HF_HOME
value: /data/hf
- name: VLLM_API_KEY
valueFrom:
secretKeyRef: {name: vllm-api, key: key, optional: true}
- name: HF_TOKEN
valueFrom:
secretKeyRef: {name: hf-token, key: token, optional: true}
ports:
| Stelle | Warum |
|---|---|
args ohne vllm serve |
Das Image hat ENTRYPOINT ["vllm", "serve"]. |
HF_HOME auf PVC |
Der Download (16 GiB) passiert nur einmal. |
/dev/shm als emptyDir: Memory |
Docker-Default 64 MiB reicht PyTorch nicht. |
strategy: Recreate |
Eine GPU: Der alte Pod muss sie erst freigeben. |
startupProbe 90 × 10 s |
Download, Laden und CUDA-Graphen dauern Minuten. |
Validieren ohne GPU:
cd ~/ki-lab/code/vllm-basics
kubeconform -strict -summary vllm-gpu.yaml
kubectl apply --dry-run=client -f vllm-gpu.yamlErwartet:
Summary: 3 resources found in 1 file - Valid: 3, Invalid: 0, Errors: 0, Skipped: 0
persistentvolumeclaim/hf-cache created (dry run)
deployment.apps/vllm-chat created (dry run)
service/vllm-chat created (dry run)
Achtung: Nicht ohne
--dry-runin kind anwenden. Der Pod bliebePending(Insufficient nvidia.com/gpu), und die ResourceQuota vonki-models(Tag 1) erlaubt ohnehin nur 6 GiB Requests.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Die API von vLLM
vLLM spricht dieselbe OpenAI-API wie llama.cpp an Tag 2. Clients merken den Wechsel nur am Modellnamen.
| Endpoint | Zweck | Auth mit --api-key |
|---|---|---|
/v1/models, /v1/chat/completions |
OpenAI-API | ja |
/v1/completions, /v1/embeddings |
Text-/Embedding-API | ja |
/health |
200, sobald die Engine läuft | nein |
/metrics |
Prometheus | nein |
Auf der GPU (Tag 11) sieht der erste Test so aus:
kubectl -n ki-models port-forward svc/vllm-chat 8000:8000 >/dev/null &
export KI_API=http://127.0.0.1:8000/v1 KI_KEY=$VLLM_KEY KI_MODEL=qwen3-8b
curl -s $KI_API/models -H "Authorization: Bearer $KI_KEY" \
| jq -c '.data[] | {id, root, max_model_len}'
ask "Was ist PagedAttention? Ein Satz."Erwartet (nicht live getestet, kann je nach Version abweichen):
{"id":"qwen3-8b","root":"Qwen/Qwen3-8B","max_model_len":8192}
PagedAttention verwaltet den KV-Cache in festen Blöcken ...
In LiteLLM (Tag 4) hängst du vLLM so ein – der Provider-Präfix
hosted_vllm/ kennt vLLM-Besonderheiten,
openai/ funktioniert ebenfalls:
- model_name: chat-large
litellm_params:
model: hosted_vllm/qwen3-8b
api_base: http://vllm-chat.ki-models:8000/v1
api_key: os.environ/VLLM_API_KEYFortschritt speichern? Kostenlos registrieren
Drill 5 (optional): vLLM auf der CPU in kind
Die Datei vllm-cpu.yaml nutzt das x86-Image
vllm/vllm-openai-cpu:v0.31.0. Für ARM-Macs gibt es
vllm/vllm-openai-cpu:v0.31.0-arm64 (rund 1,1 GB
komprimiert, entpackt deutlich mehr); auf einem ARM-Mac änderst du die
Zeile image: vorher auf diese Variante. Mach den Drill nur
mit mindestens 8 GB freiem Docker-Speicher. Der Pod passt mit 2 CPU / 3
GiB neben llamacpp in die Quota von
ki-models.
grep -A3 'VLLM_CPU_KVCACHE_SPACE' ~/ki-lab/code/vllm-basics/vllm-cpu.yaml
kubectl apply -f ~/ki-lab/code/vllm-basics/vllm-cpu.yaml
kubectl -n ki-models rollout status deploy/vllm-cpu --timeout=15m
kubectl -n ki-models logs deploy/vllm-cpu | grep -m1 'KV cache size'Erwartet (nicht live getestet, kann je nach Version abweichen):
- name: VLLM_CPU_KVCACHE_SPACE # GiB für den KV-Cache
value: "1"
- name: HF_HOME
value: /data/hf
deployment.apps/vllm-cpu created
service/vllm-cpu created
deployment "vllm-cpu" successfully rolled out
... CPU KV cache size: 87,... tokens, Maximum concurrency for 2,048 tokens ...
Warum VLLM_CPU_KVCACHE_SPACE? Auf der CPU gibt es kein
--gpu-memory-utilization; die Variable legt den KV-Cache in
GiB fest. Setzt du sie größer als das Memory-Limit, beendet der
OOM-Killer den Pod.
kubectl -n ki-models delete -f ~/ki-lab/code/vllm-basics/vllm-cpu.yamlTipp: Startet der Pod nicht, prüfe
kubectl -n ki-models describe rs -l app=vllm-cpu– ein Quota-Verstoß steht dort alsFailedCreate, nicht am Pod.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Metriken, die zählen
vLLM exportiert Prometheus-Metriken mit Präfix vllm:.
Welche es in deiner Version gibt, zeigt die Quelle:
M='num_requests_(running|waiting)|kv_cache_usage_perc|time_to_first_token_seconds'
M="$M|inter_token_latency_seconds|generation_tokens|prefix_cache_(hits|queries)"
curl -sL $SRC/v1/metrics/loggers.py | grep -oE "name=\"vllm:($M)\"" | sort -uErwartet:
name="vllm:generation_tokens"
name="vllm:inter_token_latency_seconds"
name="vllm:kv_cache_usage_perc"
name="vllm:num_requests_running"
name="vllm:num_requests_waiting"
name="vllm:prefix_cache_hits"
name="vllm:prefix_cache_queries"
name="vllm:time_to_first_token_seconds"
| Metrik | Bedeutung | Llama.cpp-Pendant (Tag 2) |
|---|---|---|
vllm:num_requests_waiting |
Warteschlange – Skalierungssignal | requests_deferred |
vllm:kv_cache_usage_perc |
KV-Cache-Füllstand 0–1 | – |
vllm:time_to_first_token_seconds |
TTFT-Histogramm | – |
vllm:generation_tokens_total |
erzeugte Tokens (Counter) | tokens_predicted_total |
Counter bekommen in Prometheus das Suffix _total. Die
drei Abfragen für dein Dashboard (Tag 9 und 15):
histogram_quantile(0.95,
sum by (le) (rate(vllm:time_to_first_token_seconds_bucket[5m])))
sum(rate(vllm:generation_tokens_total[1m]))
max(vllm:kv_cache_usage_perc)
Steht kv_cache_usage_perc dauerhaft nahe 1 und steigt
num_requests_waiting, ist der KV-Cache der Engpass – nicht
die Rechenleistung.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Über eine Engine hinaus – production-stack, KServe, llm-d
Ein vLLM-Pod ist eine Engine. Mehrere Replikas brauchen einen Router, der Prefix-Cache-Treffer ausnutzt statt Round-Robin zu verteilen.
| Projekt | Was es bringt | Wann |
|---|---|---|
| vLLM production-stack | Helm-Chart: Engines + Router (prefixaware, kvaware), LMCache | kleiner Einstieg, ein Team |
| KServe | InferenceService/LLMInferenceService,
Scale-to-Zero |
Plattform mit vielen Modellen |
| llm-d (CNCF Sandbox) | Prefix-aware Routing, Prefill/Decode getrennt, KV-Offload | große Cluster, viele GPUs |
| LiteLLM (Tag 4) | Keys, Budgets, Fallbacks über alle Backends | immer davor |
Rendere den production-stack, ohne etwas zu installieren:
cat > ~/ki-lab/code/vllm-basics/values-vllm-stack.yaml <<'EOF'
# vLLM production-stack: ein Modell + Router (nur helm template im kind-Lab)
servingEngineSpec:
runtimeClassName: "" # RKE2 + GPU Operator: "nvidia" (Tag 10)
modelSpec:
- name: qwen3-8b
repository: vllm/vllm-openai
tag: v0.31.0
modelURL: Qwen/Qwen3-8B
replicaCount: 1
requestCPU: 4
requestMemory: 24Gi
requestGPU: 1
pvcStorage: 40Gi
vllmConfig:
maxModelLen: 8192
gpuMemoryUtilization: 0.90
enablePrefixCaching: true
routerSpec:
routingLogic: prefixaware # statt roundrobin: Prefix-Cache-Treffer
EOF
cd ~/ki-lab/code/vllm-basics
helm template stack vllm-stack --version 0.1.13 \
--repo https://vllm-project.github.io/production-stack \
-f values-vllm-stack.yaml > ~/ki-lab/tag03/stack.yaml
grep -E '^kind: (Deployment|Service)$' -A3 ~/ki-lab/tag03/stack.yaml \
| grep -E '^ name:'
kubeconform -strict -summary ~/ki-lab/tag03/stack.yamlErwartet:
name: "stack-router-service"
name: "stack-qwen3-8b-engine-service"
name: "stack-deployment-router"
name: "stack-qwen3-8b-deployment-vllm"
Summary: 9 resources found in 1 file - Valid: 9, Invalid: 0, Errors: 0, Skipped: 0
grep -A16 'image: "vllm/vllm-openai' ~/ki-lab/tag03/stack.yaml | grep -E '^ +- 'Erwartet:
- "vllm"
- "serve"
- "Qwen/Qwen3-8B"
- "--host"
- "0.0.0.0"
- "--port"
- "8000"
- "--enable-prefix-caching"
- "--max-model-len"
- "8192"
- "--gpu_memory_utilization"
- "0.9"
Warum? Das Chart übersetzt vllmConfig in genau die Flags
aus Drill 2. Wer das Mapping kennt, debuggt jedes Chart. Die
Router-Images stehen per Default auf latest – im Betrieb
immer pinnen.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/ki-lab/code/vllm-basics
check "Sizing-Skript rechnet" \
'python3 sizing.py Qwen/Qwen3-8B 8.2 24 8192 | grep -q "144.0 KiB"'
check "GPU-Manifest valide" 'kubeconform -strict vllm-gpu.yaml'
check "vLLM-Tag gepinnt" 'grep -q "vllm/vllm-openai:v0.31.0" vllm-gpu.yaml'
check "max-model-len gesetzt" 'grep -q -- "--max-model-len=" vllm-gpu.yaml'
check "/dev/shm gemountet" 'grep -q "mountPath: /dev/shm" vllm-gpu.yaml'
check "production-stack gerendert" \
'grep -q stack-qwen3-8b-deployment-vllm ~/ki-lab/tag03/stack.yaml'Challenge
Ein Kunde will Qwen/Qwen2.5-Coder-7B-Instruct (7,6 Mrd.
Parameter) auf einer RTX 4000 Ada (20 GiB) mit 16k Kontext für 10
Entwickler. Reicht das in bf16? Wenn nicht: Welche Flags änderst du, und
mit welchem Ergebnis?
Hinweis: Rechne mit dem Skript beide Varianten für
kv_bytes und vergleiche mit 10 Sequenzen.
Lösung
cd ~/ki-lab/code/vllm-basics
python3 sizing.py Qwen/Qwen2.5-Coder-7B-Instruct 7.6 20 16384 | tail -4
python3 sizing.py Qwen/Qwen2.5-Coder-7B-Instruct 7.6 20 16384 1 | tail -1Erwartet:
Gewichte (bf16) 14.2 GiB
KV pro Token 56.0 KiB
KV-Budget 2.7 GiB = 51378 Tokens
Volle Sequenzen 3 à 16384 Tokens
Volle Sequenzen 6 à 16384 Tokens
Auch mit --kv-cache-dtype=fp8 nur 6 volle Sequenzen.
Realistisch: --max-model-len=8192 (selten nutzen alle
gleichzeitig 16k) plus ein AWQ- oder FP8-quantisiertes Modell (rund 8
GiB Gewichte statt 14). Dann bleiben über 8 GiB für den KV-Cache und
weit mehr als 10 parallele Sequenzen. Code-Assistenten senden viele
kurze FIM-Anfragen (Tag 14), Prefix-Caching hilft zusätzlich.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Image per Digest pinnen;
vllm/vllm-openaiist rund 10 GB – Registry-Mirror (z. B. Harbor) und vorgeladene Nodes sparen Minuten pro Rollout. - Modelle nicht bei jedem Start von Hugging Face ziehen: internes
Modell-Repo oder vorbefüllte PVCs,
HF_HUB_OFFLINE=1in Produktion. --api-keyersetzt keine Netzwerkgrenze: NetworkPolicy, nur LiteLLM darf auf Port 8000 (Tag 12).- Sizing immer mit echtem Lasttest bestätigen
(
vllm bench serve), Ziel-SLOs für TTFT und Tokens/s vorher festlegen. - Mehr als ein Replica: prefix-aware Routing (production-stack, llm-d) statt Round-Robin des Kubernetes-Service.