Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 2: Erstes Modell im Pod

Ziel: Ein Qwen2.5-0.5B-Modell läuft mit llama.cpp in ki-models, spricht die OpenAI-API, lädt aus einem PVC-Cache und hat passende Probes und Ressourcen. · Dauer: ca. 75 min · Voraussetzung: Tag 1

Briefing

  • llama.cpp rechnet Modelle im Format GGUF auf der CPU (oder GPU). Das Image ghcr.io/ggml-org/llama.cpp:server enthält llama-server mit OpenAI-API.
  • Quantisierung speichert Gewichte mit weniger Bits. Q4_K_M (rund 4,5 Bit) ist der übliche Kompromiss aus Größe und Qualität.
  • --hf-repo lädt das Modell beim Start von Hugging Face nach LLAMA_CACHE. Liegt das auf einem PVC, entfällt der Download beim nächsten Start.
  • Während Download und Laden lauscht der Server noch nicht. Erst danach antwortet /health mit 200 – darauf bauen die Probes.
  • Ergebnis für alle weiteren Tage: http://llamacpp.ki-models:8080/v1, Modellname qwen2.5-0.5b.
 kubectl port-forward :8080 ─► Service llamacpp:8080 ─► Pod llamacpp
                                                        │ llama-server
                                                        │ /v1/chat/completions
                                                        │ /health  /metrics
                                                        └─► PVC model-cache (/models)
                                                            models--Qwen--...GGUF

Drill 1: Modell auswählen und Größe rechnen

Faustregel für den RAM: Parameter × Bits / 8, plus KV-Cache für den Kontext, plus etwa 10 % Laufzeit-Overhead.

curl -s https://huggingface.co/api/models/Qwen/Qwen2.5-0.5B-Instruct-GGUF/tree/main \
  | jq -r '.[] | select(.path|endswith(".gguf"))
           | "\(.size/1048576|floor) MB  \(.path)"'

Erwartet:

1207 MB  qwen2.5-0.5b-instruct-fp16.gguf
395 MB  qwen2.5-0.5b-instruct-q2_k.gguf
412 MB  qwen2.5-0.5b-instruct-q3_k_m.gguf
408 MB  qwen2.5-0.5b-instruct-q4_0.gguf
468 MB  qwen2.5-0.5b-instruct-q4_k_m.gguf
467 MB  qwen2.5-0.5b-instruct-q5_0.gguf
497 MB  qwen2.5-0.5b-instruct-q5_k_m.gguf
620 MB  qwen2.5-0.5b-instruct-q6_k.gguf
644 MB  qwen2.5-0.5b-instruct-q8_0.gguf
Modell Parameter Q4_K_M-Datei RAM im Pod (ca.)
Qwen2.5-0.5B-Instruct 0,5 Mrd. 0,47 GB 0,8–1 GB
Ministral-3 3B 3 Mrd. ca. 2 GB 3–4 GB
Qwen3-8B 8 Mrd. ca. 5 GB 6–7 GB

Warum ist Q4 nur ein Drittel von FP16 und nicht ein Viertel? Bei kleinen Modellen sind Embedding- und Ausgabeschicht ein großer Anteil, und die bleiben höher aufgelöst. Ab 3B passt die Rechnung besser. Für den Laptop nimmst du 0.5B; 3B ist die größere Option, wenn Docker 12 GB RAM hat.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Modell-Cache als PVC

mkdir -p ~/ki-lab/tag02 && cd ~/ki-lab/tag02
cat > pvc.yaml <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: model-cache
  namespace: ki-models
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: standard
  resources:
    requests:
      storage: 2Gi
EOF
kubectl apply -f pvc.yaml
kubectl -n ki-models get pvc model-cache

Erwartet:

persistentvolumeclaim/model-cache created
NAME          STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   ...
model-cache   Pending                                      standard       ...

Pending ist richtig: WaitForFirstConsumer (Tag 1) legt das Volume erst an, wenn der Pod geplant ist. 2 GiB reichen für das 0.5B-Modell und eine zweite Quantisierung zum Vergleich.

Fortschritt speichern? Kostenlos registrieren

Drill 3: llama.cpp als Deployment

cat > ~/ki-lab/tag02/llamacpp.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: llamacpp
  namespace: ki-models
  labels:
    app: llamacpp
spec:
  replicas: 1
  strategy:
    type: Recreate            # RWO-PVC: nie zwei Pods gleichzeitig
  selector:
    matchLabels:
      app: llamacpp
  template:
    metadata:
      labels:
        app: llamacpp
    spec:
      nodeSelector:
        ki-lab/role: models
      containers:
        - name: server
          image: ghcr.io/ggml-org/llama.cpp:server-b11515
          imagePullPolicy: IfNotPresent
          args:
            - --hf-repo
            - Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M
            - --alias
            - qwen2.5-0.5b
            - --ctx-size
            - "4096"
            - --parallel
            - "2"
            - --threads
            - "2"
            - --metrics
          env:
            - name: LLAMA_CACHE
              value: /models
          ports:
            - name: http
              containerPort: 8080
          resources:
            requests:
              cpu: "1"
              memory: 1Gi
            limits:
              cpu: "2"
              memory: 2Gi
          volumeMounts:
            - name: models
              mountPath: /models
      volumes:
        - name: models
          persistentVolumeClaim:
            claimName: model-cache
---
apiVersion: v1
kind: Service
metadata:
  name: llamacpp
  namespace: ki-models
  labels:
    app: llamacpp
spec:
  selector:
    app: llamacpp
  ports:
    - name: http
      port: 8080
      targetPort: http
EOF
kubectl apply -f ~/ki-lab/tag02/llamacpp.yaml
kubectl -n ki-models get pods -w

Erwartet (gekürzt, kann abweichen; Ctrl+C beendet -w):

NAME                        READY   STATUS              RESTARTS   AGE
llamacpp-7d9c6b8f5d-x2k4q   0/1     ContainerCreating   0          2s
llamacpp-7d9c6b8f5d-x2k4q   1/1     Running             0          4s

Ohne Probes meldet Kubernetes den Pod sofort als 1/1 Running, obwohl das Modell noch lädt. Das reparierst du in Drill 5.

Argument Wirkung
--hf-repo repo:Q4_K_M Modell von Hugging Face laden, Quantisierung wählen
--alias qwen2.5-0.5b Modellname in der API (model-Feld)
--ctx-size 4096 Kontext für alle Slots zusammen (bestimmt KV-Cache)
--parallel 2 zwei Anfragen gleichzeitig, je 2048 Tokens Kontext
--threads 2 CPU-Threads, passend zum CPU-Limit
--metrics Prometheus-Endpunkt /metrics

Host und Port setzt das Image selbst (LLAMA_ARG_HOST=0.0.0.0, LLAMA_ARG_PORT=8080). Jedes Argument gibt es auch als Umgebungsvariable LLAMA_ARG_*.

Den Download verfolgen:

kubectl -n ki-models logs deploy/llamacpp -f

Erwartet beim ersten Start (gekürzt, Zeitstempel = Minuten.Sekunden seit Start):

0.00.149 I srv  llama_server: initializing ...
0.00.705 W srv  llama_server: security: no API key is set and CORS allows all origins
6.32.803 I srv    load_model: loading model 'Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M'
6.33.516 I srv    load_model: initializing, n_slots = 2, n_ctx_slot = 2048, ...
6.33.526 I srv  llama_server: model loaded
6.33.526 I srv  llama_server: listening on http://0.0.0.0:8080

Zwischen initializing und loading model lädt der Server 468 MB, ohne etwas zu loggen. Die sechs Minuten oben entsprechen etwa 1,3 MB/s. Die Warnung zum API-Key greift die Challenge auf.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Die OpenAI-API

kubectl -n ki-models port-forward svc/llamacpp 8080:8080 >/dev/null &
export KI_API=http://127.0.0.1:8080/v1 KI_MODEL=qwen2.5-0.5b
curl -s $KI_API/models \
  | jq '.data[] | {id, owned_by, meta: (.meta | {n_params, size, n_ctx_train})}'

Erwartet:

{
  "id": "qwen2.5-0.5b",
  "owned_by": "llamacpp",
  "meta": {
    "n_params": 630167424,
    "size": 485452288,
    "n_ctx_train": 32768
  }
}

Jetzt der Helfer aus Tag 0 und eine Anfrage mit allen Details:

ask "Antworte in einem Satz: Was ist Kubernetes?"
curl -s $KI_API/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "qwen2.5-0.5b",
  "messages": [{"role": "user", "content": "Nenne drei Kubernetes-Objekte."}],
  "max_tokens": 60}' \
  | jq '{model, finish: .choices[0].finish_reason, usage,
         tps: .timings.predicted_per_second}'

Erwartet (Text und Zahlen weichen ab):

Kubernetes ist eine moderne, kompatibler und extensiv installierte Cloud-Stack, ...
{
  "model": "qwen2.5-0.5b",
  "finish": "length",
  "usage": {
    "completion_tokens": 60,
    "prompt_tokens": 37,
    "total_tokens": 97,
    "prompt_tokens_details": {
      "cached_tokens": 24
    }
  },
  "tps": 92.7
}
Feld Bedeutung
finish_reason: length max_tokens erreicht, Antwort abgeschnitten (stop = fertig)
prompt_tokens Frage plus Chat-Template des Modells
cached_tokens Prompt-Anfang aus dem KV-Cache wiederverwendet
timings llama.cpp-Extra: Tokens pro Sekunde

Ein 0.5B-Modell klingt flüssig, erzählt aber Unsinn. Für die Infrastruktur ist das egal: Latenz, Durchsatz und Speicher misst du hier genauso wie später mit 8B auf der GPU.

Chat-Oberflächen streamen Tokens einzeln (Server-Sent Events):

curl -sN $KI_API/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "qwen2.5-0.5b", "stream": true, "max_tokens": 30,
  "messages": [{"role": "user", "content": "Zähle bis fünf."}]}' \
  | sed -n 's/^data: //p' | grep -v '^\[DONE\]' \
  | jq -rj '.choices[0].delta.content // empty'; echo

Erwartet (Text weicht ab, erscheint Wort für Wort):

Ja, ich zähle bis fünf. Ich bin eine digitale Person und kann ...

Warum curl -N? Ohne schaltet curl den Ausgabepuffer nicht ab, und du siehst die Antwort erst am Ende. Dasselbe Problem macht später ein Ingress mit Proxy-Buffering (Tag 5).

Fortschritt speichern? Kostenlos registrieren

Drill 5: Probes für langsame Starter

Ein Pod, der Ready meldet, bevor das Modell geladen ist, bekommt Traffic und liefert Fehler. Und eine Liveness-Probe ohne Startup-Probe tötet den Pod mitten im Download.

cat > ~/ki-lab/tag02/probes.yaml <<'EOF'
spec:
  template:
    spec:
      containers:
        - name: server
          startupProbe:          # Download + Laden: bis zu 10 min
            httpGet:
              path: /health
              port: http
            periodSeconds: 10
            failureThreshold: 60
          readinessProbe:
            httpGet:
              path: /health
              port: http
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /health
              port: http
            periodSeconds: 20
            timeoutSeconds: 5
            failureThreshold: 3
EOF
kubectl -n ki-models patch deployment llamacpp --patch-file ~/ki-lab/tag02/probes.yaml
kubectl -n ki-models rollout status deployment llamacpp --timeout=600s

Erwartet:

deployment.apps/llamacpp patched
Waiting for deployment "llamacpp" rollout to finish: 0 of 1 updated replicas ...
deployment "llamacpp" successfully rolled out

Der Patch ist ein Strategic Merge: Container werden über name zusammengeführt, Image und Argumente bleiben. Wie die Startup-Probe arbeitet, zeigen die Events:

kubectl -n ki-models get events --field-selector reason=Unhealthy \
  -o custom-columns=ZEIT:.lastTimestamp,MELDUNG:.message

Erwartet (gekürzt, kann abweichen):

ZEIT                   MELDUNG
2026-10-09T21:30:12Z   Startup probe failed: Get "http://10.244.1.7:8080/health":
                       dial tcp 10.244.1.7:8080: connect: connection refused
Probe Frage Folge bei Fehler
startup Ist das Modell geladen? nach 60 × 10 s Neustart
readiness Darf Traffic kommen? Pod raus aus dem Service
liveness Hängt der Server? Neustart

Achtung: Langsames Netz oder größere Modelle brauchen mehr als 10 Minuten. Dann failureThreshold erhöhen oder das Modell vorab per Init-Container in den Cache laden. Sonst landet der Pod in einer Neustart-Schleife, und der Download beginnt von vorn.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Ressourcen und Durchsatz

kubectl -n ki-models top pod -l app=llamacpp

Erwartet im Leerlauf (Werte weichen ab):

NAME                        CPU(cores)   MEMORY(bytes)
llamacpp-6f8b9c7d4b-q8m2n   1m           560Mi

Rund 560 MiB: Gewichte (463 MiB, per mmap als Page-Cache), KV-Cache für 4096 Tokens und Puffer. Das Limit von 2 GiB lässt Luft für längere Prompts. Jetzt vier Anfragen gleichzeitig auf zwei Slots:

for i in 1 2 3 4; do
  curl -s $KI_API/chat/completions -H 'Content-Type: application/json' -d '{
    "model": "qwen2.5-0.5b", "max_tokens": 300,
    "messages": [{"role": "user",
                  "content": "Schreib ein langes Gedicht über Pods."}]}' \
    -o /dev/null -w "req$i %{time_total}s\n" &
done
sleep 1
curl -s http://127.0.0.1:8080/metrics \
  | grep -E '^llamacpp:requests_(processing|deferred) '
wait

Erwartet (Zeiten hängen von deiner CPU ab):

llamacpp:requests_processing 2
llamacpp:requests_deferred 2
req4 9.201145s
req2 9.202780s
req1 16.502873s
req3 16.502954s

Zwei Anfragen rechnen, zwei warten in der Schlange und brauchen fast doppelt so lange. --parallel erhöht die Gleichzeitigkeit, teilt aber Kontext und CPU. Genau dieses Muster löst vLLM mit Continuous Batching besser (Tag 3).

Tipp: Setzt du das Speicher-Limit auf 400Mi, siehst du nach dem Laden OOMKilled in kubectl -n ki-models get pods. Modelle sterben am RAM, nicht an der CPU.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Metriken

curl -s http://127.0.0.1:8080/metrics | grep -E \
  '^llamacpp:(prompt_tokens_total|tokens_predicted_total|predicted_tokens_seconds) '
curl -s http://127.0.0.1:8080/slots | jq -c '.[] | {id, n_ctx, is_processing}'

Erwartet (Zahlen weichen ab):

llamacpp:prompt_tokens_total 72
llamacpp:tokens_predicted_total 245
llamacpp:predicted_tokens_seconds 96.7325
{"id":0,"n_ctx":2048,"is_processing":false}
{"id":1,"n_ctx":2048,"is_processing":false}
Metrik Zeigt
tokens_predicted_total erzeugte Tokens (Counter, Basis für Kosten)
predicted_tokens_seconds Durchschnitt Tokens/s beim Generieren
requests_processing belegte Slots
requests_deferred wartende Anfragen – das Signal zum Skalieren

Prometheus scrapt das ab Tag 9 über ein ServiceMonitor. Den Port-Forward brauchst du jetzt nicht mehr: kill %1.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Neustart aus dem Cache

kubectl -n ki-models exec deploy/llamacpp -- \
  find /models -name '*.gguf' -exec ls -lhL {} \;
kubectl -n ki-models delete pod -l app=llamacpp
SECONDS=0
kubectl -n ki-models rollout status deployment llamacpp
echo "bereit nach $SECONDS s"
kubectl -n ki-models logs deploy/llamacpp | grep -E 'loading model|listening'

Erwartet (gekürzt, kann abweichen):

-rw-r--r-- 1 root root 469M ... /models/models--Qwen--Qwen2.5-0.5B-Instruct-GGUF/
  snapshots/9217f5db79a29953eb74d5343926648285ec7e67/qwen2.5-0.5b-instruct-q4_k_m.gguf
pod "llamacpp-6f8b9c7d4b-q8m2n" deleted
deployment "llamacpp" successfully rolled out
bereit nach 13 s
0.00.707 I srv    load_model: loading model 'Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M'
0.01.456 I srv  llama_server: listening on http://0.0.0.0:8080

Aus dem Cache ist das Modell nach 1,5 Sekunden geladen, der Rest ist Pod-Start und die erste Probe nach 10 Sekunden. LLAMA_CACHE nutzt das Layout des Hugging-Face-Hub-Cache (models--<org>--<repo>/blobs, snapshots). Dasselbe Layout nutzt vLLM ab Tag 3 und Tag 11.

Die fertige Datei mit PVC, Probes und Service liegt als ~/ki-lab/code/kind-lab/llamacpp.yaml im Begleitmaterial. Nach jedem Cluster-Neubau reicht:

kubectl apply -f ~/ki-lab/code/kind-lab/llamacpp.yaml

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
ex() { kubectl -n ki-models exec deploy/llamacpp -- curl -s "localhost:8080$1"; }
check "PVC model-cache Bound" \
  '[ "$(kubectl -n ki-models get pvc model-cache \
       -o jsonpath={.status.phase})" = Bound ]'
check "Pod Ready" \
  'kubectl -n ki-models wait pod -l app=llamacpp --for=condition=Ready --timeout=5s'
check "Startup-Probe gesetzt" \
  'kubectl -n ki-models get deploy llamacpp -o yaml | grep -q startupProbe'
check "Modell qwen2.5-0.5b" 'ex /v1/models | grep -q qwen2.5-0.5b'
check "Service-Endpunkt" \
  'kubectl -n ki-models get endpointslice -l kubernetes.io/service-name=llamacpp \
     -o jsonpath="{.items[0].endpoints[0].addresses[0]}" | grep -q .'
check "Metriken an" 'ex /metrics | grep -q llamacpp:tokens_predicted_total'
check "GGUF im Cache" \
  'kubectl -n ki-models exec deploy/llamacpp -- find /models -name "*.gguf" | grep -q .'

Challenge

Jeder Pod im Cluster kann dein Modell gerade ohne Anmeldung nutzen. Schütze llama.cpp mit dem Lab-Key sk-lab-llama-1234 aus einem Secret und beweise: ohne Key 401, mit Key 200, /health bleibt für die Probes offen.

Hinweis: llama.cpp liest den Key aus der Umgebungsvariable LLAMA_API_KEY, und kubectl set env --from=secret/... übernimmt die Keys eines Secrets als Variablen.

Lösung

kubectl -n ki-models create secret generic llamacpp-api-key \
  --from-literal=LLAMA_API_KEY=sk-lab-llama-1234
kubectl -n ki-models set env deploy/llamacpp --from=secret/llamacpp-api-key
kubectl -n ki-models rollout status deploy/llamacpp
ex() { kubectl -n ki-models exec deploy/llamacpp -- curl -s "$@"; }
ex localhost:8080/v1/models; echo
ex -o /dev/null -w '%{http_code}\n' localhost:8080/v1/models \
  -H 'Authorization: Bearer sk-lab-llama-1234'
ex -w ' %{http_code}\n' localhost:8080/health
ex -o /dev/null -w 'metrics %{http_code}\n' localhost:8080/metrics

Erwartet:

secret/llamacpp-api-key created
deployment.apps/llamacpp env updated
deployment "llamacpp" successfully rolled out
{"error":{"message":"Invalid API Key","type":"authentication_error","code":401}}
200
{"status":"ok"} 200
metrics 401

Auch /metrics verlangt jetzt den Key, Prometheus bräuchte ihn ebenfalls. Die Kapitel ab Tag 3 erwarten den Modellserver ohne Key, abgesichert wird zentral am Gateway (Tag 4). Nimm den Key darum wieder heraus:

kubectl -n ki-models set env deploy/llamacpp LLAMA_API_KEY-
kubectl -n ki-models delete secret llamacpp-api-key

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Modelle nicht beim Pod-Start aus dem Internet laden: Ein Init-Container oder Job holt sie einmal aus einem internen Mirror (Artifactory, S3, OCI-Registry), Pods starten mit --offline.
  • Modellserver nie direkt exponieren. Zugriff nur über das Gateway (LiteLLM) mit Virtual Keys, dazu eine NetworkPolicy, die in ki-models nur Traffic aus ki-gateway erlaubt.
  • Modell-Revision pinnen (Commit-Hash statt main), Lizenz und Prüfsumme dokumentieren, sonst ändert sich das Modell unbemerkt beim nächsten Download.
  • Ressourcen nach Messung setzen, nicht nach Gefühl: RAM-Request ≈ gemessener Bedarf, Limit mit Reserve für den maximalen Kontext.
  • CPU-Inferenz taugt für Embeddings, Tests und Notbetrieb. Chat für ein Team braucht eine GPU (Tag 10 und 11).