Zum Inhalt springen
Trainingslager IT-Trainingslager

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 8192

Erwartet:

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 -3

Erwartet:

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: --task gibt es in v0.31 nicht mehr. Ältere Anleitungen mit --task embed brechen beim Start ab; nimm --runner pooling (meist erkennt auto Embedding-Modelle selbst).

Sicherheit: Laut Code-Kommentar zu api_key schützt der Key nur /v1, /v2 und /inference. /invocations, /metrics und /health bleiben 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 -6

Erwartet (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.yaml

Erwartet:

      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.yaml

Erwartet:

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-run in kind anwenden. Der Pod bliebe Pending (Insufficient nvidia.com/gpu), und die ResourceQuota von ki-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_KEY

Fortschritt 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.yaml

Tipp: Startet der Pod nicht, prüfe kubectl -n ki-models describe rs -l app=vllm-cpu – ein Quota-Verstoß steht dort als FailedCreate, 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 -u

Erwartet:

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.yaml

Erwartet:

  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 -1

Erwartet:

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-openai ist 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=1 in Produktion.
  • --api-key ersetzt 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.