Tag 4: LiteLLM als Gateway – Aliase, Keys, Budgets
Ziel: LiteLLM läuft in
ki-gatewayvor deinen Modellservern, vergibt Virtual Keys mit Budget und Rate-Limit, fällt bei Ausfällen zurück und liefert Metriken. · Dauer: ca. 90 min · Voraussetzung: Tag 2
Briefing
- LiteLLM Proxy spricht nach außen die OpenAI-API und leitet an beliebige Backends weiter (llama.cpp, vLLM, Mistral API …). Getestet mit v1.104.2.
- Clients sehen nur Aliase:
chat-small,chat-large,code,embed. Welches Modell dahinter steckt, entscheidet alleinconfig.yaml. - Master-Key = Admin. Virtual Keys
(in Postgres) bekommen Modelle, Budget,
rpm/tpm-Limits. - Router: Retries pro Deployment, Fallback auf einen anderen Alias, Timeouts.
- Im kind-Lab zeigen drei Chat-Aliase auf dasselbe 0,5B-Modell. Ab Tag 11/12 änderst du nur die Config.
Client (curl, Open WebUI, Continue) Authorization: Bearer sk-...
│ http://llm.ki.localtest.me/v1 (Ingress)
▼
ki-gateway: litellm:4000 ──── postgres:5432 (Keys, Budgets, Spend)
│ chat-small / chat-large / code │ embed
▼ ▼
ki-models: llamacpp:8080 (Tag 2) llamacpp-embed:8080 (heute)
Drill 1: LiteLLM lokal ausprobieren
Erst ohne Kubernetes: LiteLLM im eigenen venv, llama.cpp aus Tag 2 per Port-Forward.
mkdir -p ~/ki-lab/tag04 ~/ki-lab/code/litellm
python3 -m venv ~/ki-lab/.venv-litellm
~/ki-lab/.venv-litellm/bin/pip install --quiet 'litellm[proxy]==1.104.2' \
prometheus_client
~/ki-lab/.venv-litellm/bin/litellm --version | tail -1Erwartet:
LiteLLM: Current Version = 1.104.2
prometheus_client fehlt im Extra proxy,
wird aber für /metrics gebraucht (im Container-Image ist es
enthalten).
Jetzt die Konfiguration. Werte mit os.environ/ liest
LiteLLM zur Laufzeit aus der Umgebung – dieselbe Datei läuft lokal und
im Cluster.
cat > ~/ki-lab/code/litellm/config.yaml <<'EOF'
# LiteLLM Proxy – Lab-Konfiguration (Tag 4)
# Backends kommen aus Umgebungsvariablen:
# CHAT_API_BASE = http://llamacpp.ki-models:8080/v1 (Tag 2)
# LARGE_API_BASE = wie CHAT_API_BASE (eigene Variable für den Fallback-Drill)
# EMBED_API_BASE = http://llamacpp-embed.ki-models:8080/v1 (Tag 4)
# Im kind-Lab zeigen chat-small, chat-large und code auf dasselbe
# 0,5B-Modell. Ab Tag 11/12 tauschst du nur diese Datei, nie die Clients.
model_list:
- model_name: chat-small
litellm_params:
model: openai/qwen2.5-0.5b
api_base: os.environ/CHAT_API_BASE
api_key: "none" # llama.cpp ohne --api-key
rpm: 60 # Kapazität dieses Deployments
input_cost_per_token: 0.000001 # Lab-Preise, damit Budgets greifen
output_cost_per_token: 0.000002
model_info:
mode: chat
- model_name: chat-large
litellm_params:
model: openai/qwen2.5-0.5b
api_base: os.environ/LARGE_API_BASE
api_key: "none"
timeout: 120
input_cost_per_token: 0.000003
output_cost_per_token: 0.000006
model_info:
mode: chat
- model_name: code
litellm_params:
model: openai/qwen2.5-0.5b
api_base: os.environ/CHAT_API_BASE
api_key: "none"
model_info:
mode: chat
- model_name: embed
litellm_params:
model: openai/all-minilm
api_base: os.environ/EMBED_API_BASE
api_key: "none"
model_info:
mode: embedding
router_settings:
num_retries: 2 # erneute Versuche bei 5xx/Timeout
timeout: 60 # Sekunden pro Versuch
fallbacks:
- chat-large: ["chat-small"]
- code: ["chat-small"]
litellm_settings:
drop_params: true # unbekannte OpenAI-Parameter verwerfen
callbacks: ["prometheus"] # /metrics aktivieren
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
database_url: os.environ/DATABASE_URL
EOF| Teil | Bedeutung |
|---|---|
model_name |
Alias, den Clients schicken |
model: openai/qwen2.5-0.5b |
Provider-Präfix openai/ + Modellname am Backend |
*_cost_per_token |
eigene Preise – lokale Modelle kosten sonst 0, Budgets griffen nie |
fallbacks |
schlägt chat-large nach allen Retries fehl, antwortet
chat-small |
Start ohne Datenbank – Aliase funktionieren, Keys noch nicht:
kubectl -n ki-models port-forward svc/llamacpp 8080:8080 >/dev/null &
cd ~/ki-lab/code/litellm
export CHAT_API_BASE=http://127.0.0.1:8080/v1 LARGE_API_BASE=http://127.0.0.1:8080/v1
export EMBED_API_BASE=http://127.0.0.1:8080/v1 LITELLM_MASTER_KEY=sk-lab-master-1234
~/ki-lab/.venv-litellm/bin/litellm --config config.yaml --port 4000 \
> ~/ki-lab/tag04/litellm.log 2>&1 &
until curl -sf 127.0.0.1:4000/health/liveliness >/dev/null; do sleep 2; done
export KI_API=http://127.0.0.1:4000/v1 KI_KEY=sk-lab-master-1234 KI_MODEL=chat-small
curl -s $KI_API/models -H "Authorization: Bearer $KI_KEY" | jq -r '.data[].id'
ask "Nenne die Hauptstadt von Frankreich in einem Wort."Erwartet (Antworttext weicht ab):
chat-small
chat-large
code
embed
Paris.
sk-lab-master-1234 ist ein Lab-Wert. Aufräumen:
kill %2 %1 (LiteLLM, Port-Forward).
Fortschritt speichern? Kostenlos registrieren
Drill 2: Ein Embedding-Server für
embed
Für den Alias embed braucht es ein Embedding-Modell.
llama.cpp kann das mit --embeddings;
all-MiniLM-L6-v2 in Q8 ist 25 MB groß und liefert 384
Dimensionen.
cd ~/ki-lab/code/litellm
grep -A12 'args:' llamacpp-embed.yaml
kubectl apply -f llamacpp-embed.yaml
kubectl -n ki-models rollout status deploy/llamacpp-embed --timeout=180sErwartet (nicht live in kind getestet):
args:
- --hf-repo
- second-state/All-MiniLM-L6-v2-Embedding-GGUF
- --hf-file
- all-MiniLM-L6-v2-Q8_0.gguf
- --alias
- all-minilm
- --embeddings
- --ctx-size
- "512"
- --threads
- "1"
- --metrics
deployment.apps/llamacpp-embed created
service/llamacpp-embed created
deployment "llamacpp-embed" successfully rolled out
Das Modell liegt nur in einem emptyDir – bei 25 MB lohnt
kein PVC. Requests 250m CPU / 256 MiB passen neben llamacpp
in die Quota von ki-models (Tag 1).
kubectl -n ki-models describe quota ki-models | grep -E 'requests|limits'Erwartet (nicht live getestet, Werte mit llamacpp aus Tag 2):
limits.memory 2560Mi 8Gi
requests.cpu 1250m 4
requests.memory 1280Mi 6Gi
Fortschritt speichern? Kostenlos registrieren
Drill 3: Secrets und Postgres
Virtual Keys, Budgets und Spend-Logs liegen in Postgres. Im Lab reicht ein StatefulSet; in Produktion nimmst du CloudNativePG (Tag 12).
kubectl -n ki-gateway create secret generic litellm-secrets \
--from-literal=master-key=sk-lab-master-1234
kubectl -n ki-gateway create secret generic litellm-pg \
--from-literal=username=litellm --from-literal=password=lab-pg-1234
kubectl apply -f ~/ki-lab/code/litellm/postgres.yaml
kubectl -n ki-gateway rollout status sts/postgres --timeout=180s
kubectl -n ki-gateway exec postgres-0 -- pg_isready -U litellm -d litellmErwartet (nicht live in kind getestet):
secret/litellm-secrets created
secret/litellm-pg created
service/postgres created
statefulset.apps/postgres created
partitioned roll out complete: 1 new pods have been updated...
/var/run/postgresql:5432 - accepting connections
Sicherheit:
sk-lab-master-1234undlab-pg-1234sind Lab-Werte. Der Master-Key darf alles – auch Keys erzeugen und Budgets löschen. Echte Werte kommen aus OpenBao über External Secrets (Tag 12).
Fortschritt speichern? Kostenlos registrieren
Drill 4: LiteLLM im Cluster
Die Config wird zur ConfigMap, das Manifest litellm.yaml
setzt die Backend-Adressen und baut DATABASE_URL aus dem
Secret zusammen.
cd ~/ki-lab/code/litellm
kubectl -n ki-gateway create configmap litellm-config --from-file=config.yaml
grep -E 'image:|_API_BASE|DATABASE_URL' -A1 litellm.yaml | grep -vE '^--'Erwartet:
image: ghcr.io/berriai/litellm:v1.104.2
args: ["--config", "/etc/litellm/config.yaml", "--port", "4000"]
- name: CHAT_API_BASE
value: http://llamacpp.ki-models:8080/v1
- name: LARGE_API_BASE
value: http://llamacpp.ki-models:8080/v1
- name: EMBED_API_BASE
value: http://llamacpp-embed.ki-models:8080/v1
- name: DATABASE_URL
value: postgresql://$(DB_USER):$(DB_PASS)@postgres:5432/litellm
$(DB_USER) ersetzt Kubernetes selbst, weil
DB_USER weiter oben in derselben env-Liste
steht.
kubeconform -strict -summary litellm.yaml
kubectl apply -f litellm.yaml
kubectl -n ki-gateway rollout status deploy/litellm --timeout=300s
export KI_API=http://llm.ki.localtest.me/v1 KI_KEY=sk-lab-master-1234
export KI_MODEL=chat-small
curl -s http://llm.ki.localtest.me/health/readiness | jq -c '{status, db}'
ask "Sag nur: Hallo"Erwartet (Readiness und Antwort live gegen einen lokalen Proxy getestet, Rollout in kind nicht):
Summary: 3 resources found in 1 file - Valid: 3, Invalid: 0, Errors: 0, Skipped: 0
deployment.apps/litellm created
service/litellm created
ingress.networking.k8s.io/litellm created
deployment "litellm" successfully rolled out
{"status":"healthy","db":"connected"}
Hallo!
Warum dauert der erste Start? LiteLLM spielt beim Booten seine
Prisma-Migrationen ein (über 180 Stück). Darum hat die
startupProbe 30 × 10 s Geduld.
Achtung: Das Image ist rund 390 MB komprimiert (arm64). Ist der Docker-Speicher knapp, lade es vorher per
kind load docker-image(Tag 1,preload.sh).
Fortschritt speichern? Kostenlos registrieren
Drill 5: Virtual Keys mit Modellen und Budget
Ein Team bekommt einen eigenen Key: nur chat-small und
embed, Budget 0,001 (Lab-Währung), Reset monatlich.
M="Authorization: Bearer sk-lab-master-1234"; J="Content-Type: application/json"
GW=http://llm.ki.localtest.me
TEAM_KEY=$(curl -s $GW/key/generate -H "$M" -H "$J" -d '{
"key_alias": "team-a", "models": ["chat-small", "embed"],
"max_budget": 0.001, "budget_duration": "30d",
"rpm_limit": 3, "tpm_limit": 5000, "metadata": {"team": "plattform"}}' \
| jq -r .key)
echo "$TEAM_KEY" | cut -c1-6
for i in 1 2 3 4; do
curl -s -o /dev/null -w "Aufruf $i: %{http_code}\n" $GW/v1/chat/completions \
-H "Authorization: Bearer $TEAM_KEY" -H "$J" \
-d '{"model":"chat-small","max_tokens":5,
"messages":[{"role":"user","content":"Hi"}]}'
doneErwartet (live gegen lokalen Proxy; wann das Budget reißt, hängt von der Promptlänge ab):
sk-2Wn
Aufruf 1: 200
Aufruf 2: 200
Aufruf 3: 422
Aufruf 4: 422
curl -s $GW/v1/chat/completions -H "Authorization: Bearer $TEAM_KEY" -H "$J" \
-d '{"model":"chat-small","messages":[{"role":"user","content":"Hi"}]}' \
| jq -r .error.type
curl -s $GW/v1/chat/completions -H "Authorization: Bearer $TEAM_KEY" -H "$J" \
-d '{"model":"chat-large","messages":[{"role":"user","content":"Hi"}]}' \
| jq -r '.error | "\(.code) \(.type)"'
curl -s "$GW/key/info?key=$TEAM_KEY" -H "$M" \
| jq '.info | {key_alias, spend, max_budget, budget_reset_at}'Erwartet (live gegen lokalen Proxy):
budget_exceeded
403 key_model_access_denied
{
"key_alias": "team-a",
"spend": 0.001128,
"max_budget": 0.001,
"budget_reset_at": "2026-11-01T00:00:00+00:00"
}
Warum 422 und nicht 429? Budget ist kein Rate-Limit: Der Key bleibt
gesperrt, bis budget_reset_at erreicht ist oder ein Admin
das Budget erhöht (/key/update). Spend schreibt LiteLLM
gepuffert – spend kann einige Sekunden hinterherhinken.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Rate-Limits
CI_KEY=$(curl -s $GW/key/generate -H "$M" -H "$J" \
-d '{"key_alias":"ci-bot","models":["chat-small"],"rpm_limit":2}' | jq -r .key)
for i in 1 2 3; do
curl -s -o ~/ki-lab/tag04/r$i.json -w "Aufruf $i: %{http_code}\n" \
$GW/v1/chat/completions -H "Authorization: Bearer $CI_KEY" -H "$J" \
-d '{"model":"chat-small","max_tokens":5,
"messages":[{"role":"user","content":"Hi"}]}'
done
jq -r .error.message ~/ki-lab/tag04/r3.json | cut -c1-60Erwartet (live gegen lokalen Proxy):
Aufruf 1: 200
Aufruf 2: 200
Aufruf 3: 429
Rate limit exceeded for api_key: 7fd67576a0e2bc5fb9a77c2584e
| Limit | Wirkt auf | Antwort |
|---|---|---|
rpm_limit / tpm_limit am Key |
einen Client | 429 |
rpm in litellm_params |
ein Backend-Deployment | Router weicht aus oder 429 |
max_budget |
Kosten eines Keys | 422 budget_exceeded |
models |
erlaubte Aliase | 403 key_model_access_denied |
Im Fehlertext steht der Hash des Keys, nie der Key selbst – so landen Logs ohne Geheimnis im Ticket.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Retries und Fallbacks
Simuliere den Ausfall des Backends hinter chat-large,
indem du nur dessen Adresse verbiegst:
kubectl -n ki-gateway set env deploy/litellm \
LARGE_API_BASE=http://gibtsnicht.ki-models:8080/v1
kubectl -n ki-gateway rollout status deploy/litellm --timeout=300s
curl -s -D ~/ki-lab/tag04/h.txt $GW/v1/chat/completions -H "$M" -H "$J" \
-d '{"model":"chat-large","max_tokens":10,
"messages":[{"role":"user","content":"Sag nur: Hallo"}]}' \
| jq -c '{model, content: .choices[0].message.content}'
grep -iE 'x-litellm-(attempted|model-api-base)' ~/ki-lab/tag04/h.txtErwartet (live gegen lokalen Proxy mit totem Backend; Antworttext weicht ab):
{"model":"qwen2.5-0.5b","content":"Hallo!"}
x-litellm-model-api-base: http://llamacpp.ki-models:8080/v1
x-litellm-attempted-retries: 0
x-litellm-attempted-fallbacks: 1
Der Client hat chat-large bestellt und eine Antwort
bekommen – geliefert hat chat-small. Die Header verraten
es; bei normalem Betrieb steht model auf dem Alias. Retries
greifen bei 5xx und Timeouts eines erreichbaren Backends, ein
Verbindungsfehler geht hier direkt in den Fallback.
kubectl -n ki-gateway set env deploy/litellm \
LARGE_API_BASE=http://llamacpp.ki-models:8080/v1Tipp: Ältere Anleitungen testen Fallbacks mit
"mock_testing_fallbacks": trueim Request. In v1.104 lehnt der Proxy das mit 400 ab, solangegeneral_settings.dangerously_allow_mock_testing_request_paramsnicht gesetzt ist – zu Recht, in Produktion bleibt das aus.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Metriken und Spend
callbacks: ["prometheus"] aktiviert
/metrics. Der Endpoint verlangt in v1.104 einen Key und
antwortet unter /metrics/ (mit Redirect):
curl -s -o /dev/null -w '%{http_code}\n' $GW/metrics/
curl -sL $GW/metrics -H "$M" | grep -E \
'^litellm_(proxy_total_requests_metric_total|spend_metric_total)' \
| sed -E 's/^litellm_(.*)\{.*key_alias="([^"]*)".*_model="([^"]*)".*\} /\1 \2 \3 /'Erwartet (live gegen lokalen Proxy, Labels und Zahlen weichen ab):
401
proxy_total_requests_metric_total open-webui chat-small 5.0
proxy_total_requests_metric_total open-webui embed 3.0
spend_metric_total open-webui chat-small 0.0036509999999999993
spend_metric_total open-webui embed 0.0
| Metrik | Frage |
|---|---|
litellm_proxy_total_requests_metric_total |
Wer ruft was wie oft auf? |
litellm_spend_metric_total |
Wer verbraucht welches Budget? |
litellm_deployment_successful_fallbacks_total |
Wie oft sprang der Fallback ein? |
litellm_remaining_api_key_budget_metric |
Welcher Key läuft gleich leer? |
Prometheus braucht für den Scrape also einen Key
(authorization im ServiceMonitor). Alternative:
litellm_settings.require_auth_for_metrics_endpoint: false –
dann aber /metrics per NetworkPolicy abschirmen. Einzelne
Aufrufe zeigt die Datenbank:
curl -s "$GW/spend/logs?summarize=false" -H "$M" \
| jq -c '.[0:2][] | {model_group, total_tokens, status}'Erwartet (live gegen lokalen Proxy, gekürzt):
{"model_group":"chat-small","total_tokens":566,"status":"success"}
{"model_group":"chat-large","total_tokens":0,"status":"failure"}
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
GW=http://llm.ki.localtest.me; M="Authorization: Bearer sk-lab-master-1234"
check "Postgres bereit" \
'kubectl -n ki-gateway exec postgres-0 -- pg_isready -U litellm -d litellm'
check "LiteLLM ready, DB verbunden" \
'[ "$(curl -s $GW/health/readiness | jq -r .db)" = connected ]'
check "4 Aliase" \
'[ "$(curl -s $GW/v1/models -H "$M" | jq ".data | length")" -eq 4 ]'
check "Embeddings 384-dim" \
'[ "$(curl -s $GW/v1/embeddings -H "$M" -H "Content-Type: application/json" \
-d "{\"model\":\"embed\",\"input\":\"Pod\"}" \
| jq ".data[0].embedding | length")" -eq 384 ]'
check "Key team-a existiert" \
'curl -s "$GW/key/list?return_full_object=true" -H "$M" \
| jq -e ".keys[] | select(.key_alias==\"team-a\")"'
check "/metrics nur mit Key" \
'[ "$(curl -sL -o /dev/null -w "%{http_code}" $GW/metrics)" = 401 ]'Challenge
Ersetze dein Manifest durch das offizielle Helm-Chart
oci://ghcr.io/berriai/litellm-helm (Version 1.104.2) – mit
deinen Secrets und deinem Postgres, ohne das Bitnami-Postgres des
Charts. Rendere es und prüfe, welche Objekte es zusätzlich erzeugt.
Hinweis: Die Schlüssel heißen
masterkeySecretName, db.useExisting und
db.deployStandalone; das Chart erwartet
master_key: os.environ/PROXY_MASTER_KEY.
Lösung
cd ~/ki-lab/code/litellm
cat > values-helm.yaml <<'EOF'
# Alternative zu litellm.yaml: offizielles Chart (oci://ghcr.io/berriai/litellm-helm)
# Nutzt dieselben Secrets (litellm-secrets, litellm-pg) und den Postgres aus Tag 4.
image:
pullPolicy: IfNotPresent # Default "Always" zieht bei jedem Start neu
masterkeySecretName: litellm-secrets
masterkeySecretKey: master-key
db:
useExisting: true
deployStandalone: false # kein Bitnami-Postgres aus dem Chart
endpoint: postgres
database: litellm
secret:
name: litellm-pg
usernameKey: username
passwordKey: password
envVars:
CHAT_API_BASE: http://llamacpp.ki-models:8080/v1
LARGE_API_BASE: http://llamacpp.ki-models:8080/v1
EMBED_API_BASE: http://llamacpp-embed.ki-models:8080/v1
resources:
requests: {cpu: 250m, memory: 768Mi}
limits: {memory: 1536Mi}
proxy_config:
model_list:
- model_name: chat-small
litellm_params:
model: openai/qwen2.5-0.5b
api_base: os.environ/CHAT_API_BASE
api_key: "none"
general_settings:
master_key: os.environ/PROXY_MASTER_KEY # setzt das Chart aus dem Secret
EOF
helm template litellm oci://ghcr.io/berriai/litellm-helm --version 1.104.2 \
-n ki-gateway -f values-helm.yaml > ~/ki-lab/tag04/helm.yaml
awk '/^kind:/{k=$2} /^ name:/{print k, $2}' ~/ki-lab/tag04/helm.yaml
kubeconform -strict -summary ~/ki-lab/tag04/helm.yamlErwartet:
ConfigMap litellm-config
Service litellm
Deployment litellm
Job litellm-migrations
Pod "litellm-test-connection"
Pod "litellm-env-test"
Summary: 6 resources found in 1 file - Valid: 6, Invalid: 0, Errors: 0, Skipped: 0
Neu gegenüber deinem Manifest: ein Job für die
Prisma-Migrationen (der Proxy selbst bekommt
DISABLE_SCHEMA_UPDATE=true, damit mehrere Replikas nicht
gleichzeitig migrieren) und zwei Helm-Test-Pods. Die ConfigMap heißt wie
deine (litellm-config) – vor einem
helm install also erst
kubectl delete -f litellm.yaml und die ConfigMap löschen.
Für die vollständige Config kopierst du model_list und
router_settings aus config.yaml unter
proxy_config.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Postgres hochverfügbar (CloudNativePG) mit Backups; Redis, sobald mehr als ein Proxy-Replica Rate-Limits und Budgets teilen muss (Tag 12).
- Master-Key nur für Automatisierung (Terraform/OpenTofu, CI),
Menschen über SSO in die Admin-UI; Keys pro Team mit Budget und
Ablaufdatum (
duration). LITELLM_SALT_KEYsetzen, bevor Provider-Credentials in der DB landen – nachträglich ändern macht sie unlesbar.- Echte Preise der externen APIs pflegen, interne GPU-Kosten als
Verrechnungssatz (
input_cost_per_token) eintragen – sonst sind Budgets wertlos. - Image per Digest pinnen und Changelogs lesen: LiteLLM released fast
täglich, Defaults (z. B.
/metrics-Auth, Mock-Parameter) ändern sich.