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:serverenthältllama-servermit 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-repolädt das Modell beim Start von Hugging Face nachLLAMA_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
/healthmit 200 – darauf bauen die Probes. - Ergebnis für alle weiteren Tage:
http://llamacpp.ki-models:8080/v1, Modellnameqwen2.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-cacheErwartet:
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 -wErwartet (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 -fErwartet 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'; echoErwartet (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=600sErwartet:
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:.messageErwartet (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
failureThresholderhö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=llamacppErwartet 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) '
waitErwartet (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 LadenOOMKilledinkubectl -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.yamlFortschritt 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/metricsErwartet:
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-keyFortschritt 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-modelsnur Traffic auski-gatewayerlaubt. - 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).