Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 4: LiteLLM als Gateway – Aliase, Keys, Budgets

Ziel: LiteLLM läuft in ki-gateway vor 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 allein config.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 -1

Erwartet:

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=180s

Erwartet (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 litellm

Erwartet (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-1234 und lab-pg-1234 sind 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"}]}'
done

Erwartet (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-60

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

Erwartet (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/v1

Tipp: Ältere Anleitungen testen Fallbacks mit "mock_testing_fallbacks": true im Request. In v1.104 lehnt der Proxy das mit 400 ab, solange general_settings.dangerously_allow_mock_testing_request_params nicht 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.yaml

Erwartet:

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_KEY setzen, 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.