LiteLLM AI Gateway

📅 Juni 2026 · Letztes Update: 07.06.2026

1. Warum ein AI-Gateway?

Stell dir vor, du betreibst 20 KI-Agenten — jeder mit eigener Konfiguration, eigenem Modell, eigenem API-Key. Jetzt kommt ein neues, besseres Modell auf den Markt. Ohne Gateway: Du änderst 20 Konfigurationen einzeln, startest 20 Dienste neu, vergisst zwei davon und wunderst dich über Fehler.

Mit LiteLLM als zentralem Gateway änderst du ein Modell-Alias in der Admin-UI — und alle 20 Agenten nutzen beim nächsten Request automatisch das neue Modell. Kein Neustart, kein Konfigurations-Chaos.

Die konkreten Vorteile im Betrieb:

• Zentraler Model-Switch: Ein Synonym (z.B. „Large Flash") zeigt auf ein echtes Modell — ändert sich das Ziel, merken es alle Agenten
• Virtual Keys pro Agent: Jeder Agent bekommt einen eigenen Key mit Budget-Limit — Abrechnung pro Team/Agent statt pro Provider
• Kostenkontrolle: Admin-UI zeigt Token-Verbrauch und Spend pro Key, Team und Modell — tagesaktuell
• Provider-Agnostisch: DeepSeek, OpenAI, Anthropic, Ollama — alle hinter einer einzigen, OpenAI-kompatiblen API
• Fallback & Load-Balancing: Automatisches Retry bei Fehlern, Verteilung auf mehrere Provider

2. Architektur & Datenfluss

LiteLLM sitzt als Proxy zwischen allen KI-Agenten und den LLM-Providern. Jeder Request läuft durch denselben Endpunkt:

Agent A ──sk-aaa──┐
Agent B ──sk-bbb──┤              ┌──────────────┐
Agent C ──sk-ccc──┼─────────────►│   LiteLLM    │──► DeepSeek
Agent D ──sk-ddd──┤   Port 4000  │   Gateway    │──► Ollama (lokal)
                  ▼              │ + PostgreSQL │──► OpenAI / Anthropic
           Virtual Keys          └──────────────┘
           + Budget-Limits       Admin-UI :4000

Der Stack besteht aus nur zwei Docker-Containern:

3. Setup: Docker Compose & Config

3.1 docker-compose.yml

services:
  postgres:
    image: postgres:16-alpine
    container_name: litellm-db
    environment:
      POSTGRES_USER: litellm
      POSTGRES_DB: litellm
      POSTGRES_HOST_AUTH_METHOD: trust
    ports:
      - "127.0.0.1:5433:5432"
    volumes:
      - litellm_pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]

  litellm:
    image: docker.litellm.ai/berriai/litellm:main-stable
    container_name: litellm-proxy
    depends_on:
      postgres:
        condition: service_healthy
    network_mode: "host"
    volumes:
      - ./config.yaml:/app/config.yaml
    env_file:
      - .env
    restart: unless-stopped

volumes:
  litellm_pgdata:

3.2 config.yaml (Basis-Konfiguration)

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

litellm_settings:
  drop_params: true

model_list:
  - model_name: deepseek-v4-flash
    litellm_params:
      model: deepseek/deepseek-v4-flash
      api_key: os.environ/DEEPSEEK_API_KEY

  - model_name: Large Pro
    litellm_params:
      model: openai/Large Pro
      api_base: http://localhost:4000/v1
      api_key: os.environ/LITELLM_MASTER_KEY

3.3 .env (Umgebungsvariablen)

DEEPSEEK_API_KEY=sk-...
LITELLM_MASTER_KEY=sk-...
LITELLM_SALT_KEY=sk-...
DATABASE_URL=postgresql://litellm@localhost:5433/litellm

Master- und Salt-Key mit OpenSSL generieren:

LITELLM_MASTER_KEY="sk-$(openssl rand -hex 16)"
LITELLM_SALT_KEY="sk-$(openssl rand -hex 16)"

4. Model-Management mit der Admin-UI

Die Admin-UI ist das Herzstück des Setups — erreichbar unter http://<host>:4000, Login mit Benutzername admin und dem LITELLM_MASTER_KEY als Passwort.

Sie bietet:

• 📊 Dashboard: Token-Verbrauch, Spend, Requests pro Key/Team/Modell
• 🔑 Key-Management: Virtual Keys erstellen, Budgets setzen, widerrufen
• 🏗️ Model-Übersicht: Alle konfigurierten Modelle mit Health-Status
• 🔄 Synonyme: Modell-Aliase anlegen und Ziel-Modell jederzeit ändern

Das ist der entscheidende Vorteil: Synonyms erlauben es, ein Alias wie „Large Flash" zu definieren und später auf ein anderes physisches Modell umzubiegen — ohne dass ein einziger Agent seine Konfiguration ändern muss.

5. Virtual Keys & Kosten-Tracking

Jeder Agent bekommt einen eigenen Virtual Key — mit Budget-Limit, Modell-Beschränkung und Metadaten:

# Key für Coding-Agenten erstellen
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer <master-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "agent-benno",
    "team_id": "factory-devs",
    "models": ["Large Flash", "Large Pro"],
    "metadata": {"agent": "benno", "role": "coding"},
    "max_budget": 50.0,
    "budget_duration": "1mo"
  }'

Spend-Tracking pro Key und Team:

# Verbrauch pro Team
curl http://localhost:4000/team/info?team_id=factory-devs \
  -H "Authorization: Bearer <master-key>"

# Verbrauch pro Key
curl http://localhost:4000/key/info?key=sk-... \
  -H "Authorization: Bearer <master-key>"

6. Hermes-Integration

KI-Agenten (in diesem Beispiel Hermes-Agenten) nutzen LiteLLM über das OpenAI-Provider-Interface. Die Konfiguration im Profil:

# config.yaml (Hermes-Profil)
model:
  provider: openai
  base_url: http://<litellm-host>:4000
  default: Large Flash

providers:
  openai:
    base_url: http://<litellm-host>:4000
    key_env: OPENAI_API_KEY

credential_pool_strategies:
  openai: fill_first

# .env (Hermes-Profil)
OPENAI_API_KEY=sk-<virtual-key>

Das Schöne daran: In der .env steht nur noch der Virtual Key. Welches Modell dahinter steckt, entscheidet LiteLLM. Möchte man für einen bestimmten Agenten ein anderes Modell, ändert man das Synonym in der Admin-UI — oder vergibt einen anderen Virtual Key mit anderer Modell-Zuordnung.

7. Betrieb & Lessons Learned

Was gut läuft

• Admin-UI ist Gold wert: Modell-Aliase umbiegen, neue Keys anlegen, Spend tracken — alles ohne Config-Dateien oder Neustarts. Die UI zeigt tagesaktuell, welcher Agent wie viele Tokens verbraucht.
• Zwei Container, minimaler Overhead: ~230 MB RAM im Idle. PostgreSQL auf Alpine hält den Footprint klein.
• Host-Networking spart Konfiguration: Kein Bridge-Netzwerk-Debugging — LiteLLM sieht localhost und erreicht PostgreSQL und Ollama direkt.
• OpenAI-Kompatibilität: Jedes Tool, das OpenAI-APIs spricht, funktioniert mit LiteLLM — ohne Adapter.

Lessons Learned

• Salt-Key ist heilig: Einmal gesetzt, nie ändern. Ein verlorener Salt-Key bedeutet: alle verschlüsselten Provider-Keys in der DB sind unbrauchbar. Backup des Keys ist Pflicht.
• Virtual Keys nur über API generieren: Direkte SQL-Inserts in die LiteLLM_VerificationToken-Tabelle funktionieren nicht — LiteLLM hasht die Keys mit sk--Präfix und der Hash stimmt nicht mit rohen DB-Tokens überein.
• UI-Managed Models bevorzugen: Models per Admin-UI anlegen statt in config.yaml — sie bekommen dann kein „Defined in config"-Badge und lassen sich flexibler verwalten. config.yaml nur für die physischen Provider-Modelle nutzen.
• Entrypoint für Custom Callbacks: Für produktionsrelevante Fixes (z.B. DeepSeek-null-content-Fix) braucht man einen eigenen Entrypoint, der vor dem Start einen Callback registriert. LiteLLM's callbacks-Feld in config.yaml unterstützt nur ~50 Built-in-Integrationen — Custom Python-Callbacks brauchen einen Wrapper.
• Trust-Auth nur mit localhost-Bindung: PostgreSQL ohne Passwort ist nur sicher, solange der Port ausschließlich auf 127.0.0.1 gebunden ist. docker compose ps regelmäßig prüfen, dass kein 0.0.0.0:5433 auftaucht.

Monitoring

• Health-Check: curl http://localhost:4000/health/readiness → {"status":"healthy","db":"connected"}
• Model-Liste: curl -H "Authorization: Bearer <mk>" http://localhost:4000/v1/models
• Admin-UI: http://<host>:4000 → Login mit admin / Master-Key

8. Fazit & Ausblick

LiteLLM als zentrales AI-Gateway ist eine der besten Infrastruktur-Entscheidungen für Multi-Agent-Setups. Der initiale Aufwand (15 Minuten Setup) amortisiert sich beim ersten Model-Wechsel, der statt 30 Minuten Config-Arbeit nur noch einen Klick braucht. Für Teams und Agent-Factories mit mehr als 5 regelmäßig genutzten LLM-Endpunkten ist ein Gateway praktisch Pflicht.