LiteLLM: ein einheitlicher lokaler Proxy und cloud

#Warum ein LiteLLM-Proxy für lokale Modelle und Cloud-Modelle?

Ein typischer hybrider Stack hat zwei Probleme. Erstens füllt sich der Anwendungscode mit if provider == 'openai' / elif provider == 'ollama'. Zweitens wird die Entscheidung „lokal vs. Cloud“ beim Schreiben des Codes festgeschrieben: Wenn Ollama ausfällt, fällt auch die Anwendung aus; wenn Sie für eine bestimmte Aufgabe auf Claude wechseln möchten, müssen Sie die Anwendung erneut bereitstellen.

LiteLLM löst beide Probleme. Auf Anwendungsebene kommunizieren Sie mit einem einzigen OpenAI-kompatiblen Endpoint (chat/completions, embeddings, streaming). Auf Infrastrukturseite beschreibt eine Datei namens config.yaml Ihre Modelle: logischer Alias, Backend, API-Schlüssel, Fallback-Priorität. Sie ändern die Route, ohne den Code anzufassen.

#So funktioniert es

Der Proxy stellt standardmäßig Port 4000 bereit. Ihre App sendet eine POST-Anfrage an /chat/completions mit model: "chat-fr". LiteLLM prüft seine config.yaml, erkennt, dass chat-fr auf ollama/qwen3.5:9b unter localhost:11434 verweist, stellt die Anfrage, vereinheitlicht die Antwort im OpenAI-Format und gibt das Ergebnis an die App zurück.

Auf App-Seite

Eine einzige URL (http://localhost:4000), ein einziger virtueller Schlüssel, das Standard-SDK von OpenAI genügt.

Seitens des Proxys

Eine model_list ordnet Aliase (chat-fr, code-rapide, analyse-doc) tatsächlichen Backends zu.

Routing

Mehrere Backends für denselben Alias = Lastverteilung, Fallback, automatische Wiederholversuche.

Beobachtbarkeit

Logs, Latenzen, Kosten pro Anfrage und pro virtuellem Schlüssel, exportierbar nach Langfuse, Prometheus oder in eine Postgres-Datenbank.

#Voraussetzungen

Python 3.10+

LiteLLM ist ein pip-Paket. Eine saubere venv oder eine saubere pipx-Umgebung reicht aus.

Ollama läuft

Unter http://localhost:11434 mit mindestens einem heruntergeladenen Modell. Bei Bedarf den Leitfaden zur Installation von Ollama konsultieren.

Cloud-API-Schlüssel (optional)

OPENAI_API_KEY, ANTHROPIC_API_KEY, wenn Sie Anfragen als Fallback in die Cloud routen möchten.

Eine .env-Datei

Damit Schlüssel in config.yaml niemals im Klartext ins Repository eingecheckt werden.

#1. Installation

pip install 'litellm[proxy]'

Das Extra „proxy“ enthält FastAPI, uvicorn und die optionalen Abhängigkeiten (Postgres sowie Redis, wenn Sie ein gemeinsam genutztes Rate-Limiting möchten). Für einen schnellen Test reicht das aus. Für den Produktivbetrieb sollten Sie eher das offizielle Docker-Image verwenden.

docker run -d --name litellm \
  -p 4000:4000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --env-file .env \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml

Stellen Sie sicher, dass es funktioniert:

curl http://localhost:4000/health/liveliness

#2. Eine minimale config.yaml für LiteLLM

Erstellen Sie config.yaml neben Ihrem Projekt. Die Struktur besteht aus drei Abschnitten: model_list (die Aliasse), litellm_settings (globales Verhalten) und general_settings (Authentifizierung, Datenbank).

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

  - model_name: code-rapide
    litellm_params:
      model: ollama/qwen3-coder:30b
      api_base: http://localhost:11434

litellm_settings:
  drop_params: true
  num_retries: 2
  request_timeout: 60

Starten Sie den Proxy mit dieser Konfiguration:

litellm --config config.yaml --port 4000

Auf Anwendungsseite kommuniziert das OpenAI-Python-SDK direkt mit dem Proxy. Keine Abhängigkeit von LiteLLM im Anwendungscode:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-fake-local",  # le proxy n'exige pas de vraie clé par défaut
)

resp = client.chat.completions.create(
    model="chat-fr",
    messages=[{"role": "user", "content": "Résume la photosynthèse en 3 lignes."}],
)
print(resp.choices[0].message.content)

#3. OpenAI und Anthropic hinzufügen

Schlüssel werden niemals fest im Code hinterlegt. Legen Sie sie in einer .env-Datei neben der Konfigurationsdatei ab:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Verweisen Sie dann im YAML mit der Syntax os.environ auf die Variablen – LiteLLM ersetzt sie beim Start durch ihre Werte:

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

  - model_name: chat-gros
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  - model_name: analyse-doc
    litellm_params:
      model: anthropic/claude-haiku-4-5-20251001
      api_key: os.environ/ANTHROPIC_API_KEY

Zu diesem Zeitpunkt verfügen Sie über drei logische Alias-Namen. Der Anwendungscode wählt chat-fr für private Gespräche, chat-gros für lange Anfragen und analyse-doc zum Lesen von PDFs. Im Code taucht kein Schlüssel auf.

#4. Modellbasiertes Routing und automatischer Fallback

Hier zeigt sich der eigentliche Nutzen des Proxys. Zwei Mechanismen sollten Sie kennen: mehrere Einträge unter demselben model_name (Load Balancing) und der Schlüssel fallbacks (Umschalten bei einem Fehler).

1. 01
   Mehrere Einträge, ein einziger Alias

   Sie können model_name: chat-fr zweimal angeben — ein Eintrag verweist auf das lokale Ollama, der andere auf ein Mistral-Modell in der Cloud. LiteLLM verteilt die Anfragen je nach Strategie (standardmäßig simple-shuffle oder usage-based-routing, wenn Sie die Kosten optimieren möchten).
2. 02
   Expliziter Fallback

   Legen Sie in litellm_settings fest, welcher Alias übernimmt, wenn der erste einen Fehler oder einen Timeout zurückgibt. Der Fallback löst automatisch einen erneuten Versuch auf dem Ersatz-Backend aus.
3. 03
   Aktiver Health-Check

   LiteLLM pingt regelmäßig jedes Modell an. Eine Ollama-Instanz, die nicht mehr antwortet, wird als unhealthy markiert und aus dem Pool genommen, bis sie wieder erreichbar ist – Ihre Anfragen werden automatisch an die Cloud weitergeleitet.

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

  - model_name: chat-fr-cloud
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

litellm_settings:
  num_retries: 2
  request_timeout: 30
  fallbacks:
    - chat-fr: ["chat-fr-cloud"]
  context_window_fallbacks:
    - chat-fr: ["chat-fr-cloud"]

Mit dieser Konfiguration verwendet Ihre App immer model: "chat-fr". Wenn Ollama nicht verfügbar ist, eine Zeitüberschreitung auftritt oder der Prompt das lokal zugewiesene Kontextfenster überschreitet (num_ctx wurde reduziert, um VRAM zu sparen), wechselt der Proxy für die App unbemerkt zu GPT-4o-mini. Die App bemerkt davon nichts – sie erhält lediglich eine Antwort, vielleicht etwas langsamer.

#5. Kostenverfolgung und Rate Limiting

Ein hybrider Stack hat versteckte Kosten: Man glaubt, ein lokales Modell zu nutzen, doch 30 % der Anfragen wurden tatsächlich auf GPT-4o umgeleitet. LiteLLM berechnet die Kosten jeder Anfrage anhand einer internen Preistabelle, die mit den öffentlich verfügbaren Preislisten auf dem aktuellen Stand gehalten wird.

Um die Logs dauerhaft zu speichern und ein Dashboard bereitzustellen, binden Sie eine PostgreSQL-Datenbank an:

general_settings:
  master_key: sk-litellm-prod-changeme
  database_url: "postgresql://litellm:pass@localhost:5432/litellm"
  store_model_in_db: true

litellm_settings:
  success_callback: ["langfuse"]   # ou prometheus, datadog, etc.
  cache: true

Sobald Postgres angebunden ist, zeigt die Admin-Oberfläche (http://localhost:4000/ui) die Kosten pro virtuellem Schlüssel, pro Modell und pro Benutzer. Sie können auch virtuelle Schlüssel mit einem gedeckelten Budget erstellen – praktisch, um einem Team Zugang zu geben, ohne eine Kostenüberschreitung zu riskieren.

Ungefähre Kosten für 1 Mio. Ausgabetokens (öffentliche Preise vom Juni 2026, anhand der Preise Ihres Anbieters neu zu berechnen):

Ollama lokal (Qwen 3.5 9B Q4)

0 $ Grenzkosten – Ihre Stromkosten und die Amortisation der GPU.

OpenAI gpt-4o-mini

Etwa 0,60 $ / 1M Ausgabetokens, ideal für den günstigen Fallback.

Anthropic Claude Haiku 4.5

Etwa 5 $ pro 1 Million Ausgabetokens, teurer, aber mit einem hervorragenden Preis-Leistungs-Verhältnis bei der Dokumentenanalyse.

OpenAI gpt-4o

Etwa 10 $ pro 1 Million Ausgabe-Tokens, nur für Aufgaben einsetzen, bei denen 4o-mini nicht gut genug ist.

Beim Rate-Limiting werden pro Modell RPM-Limits (Anfragen pro Minute) und TPM-Limits (Tokens pro Minute) festgelegt. LiteLLM stellt Anfragen je nach Ihrer Konfiguration in eine Warteschlange oder gibt den HTTP-Statuscode 429 zurück:

model_list:
  - model_name: chat-gros
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
      rpm: 60
      tpm: 100000

#Fehlerbehebung

"Model not found", obwohl der Alias existiert

Prüfen Sie die YAML-Einrückung. Ein Leerzeichen zu viel unter litellm_params führt dazu, dass der Proxy den Eintrag ohne Fehlermeldung ignoriert. Führen Sie litellm --config config.yaml --debug aus, um zu sehen, welche model_list tatsächlich geladen wurde.

Der Fallback wird nicht ausgelöst

num_retries muss ≥ 1 sein und das Zeitlimit muss erreicht werden. Standardmäßig ist request_timeout für Ollama sehr großzügig bemessen – setzen Sie den Wert auf 30 Sekunden herunter, damit Fallbacks schnell greifen.

Fehler 401 bei Ollama

ollama/* akzeptiert keinen API-Schlüssel. Wenn Sie api_key in einem Ollama-Eintrag gesetzt haben, entfernen Sie ihn. LiteLLM reicht den Schlüssel unverändert weiter, was zu einem Fehler führt.

Falsch berechnete oder mit null angegebene Kosten

Die Preistabelle hängt von der Version von LiteLLM ab. Aktualisieren Sie LiteLLM (pip install -U 'litellm[proxy]'). Für ein nicht aufgeführtes benutzerdefiniertes Modell geben Sie input_cost_per_token und output_cost_per_token manuell in litellm_params an.

Ungewöhnliche Latenz bei Ollama

Der Proxy führt jede Minute einen Health-Check durch. Wenn Ollama lange braucht, um ein Modell zu laden (Cold Start), überschreitet der Check das Zeitlimit und markiert das Modell als unhealthy. Erhöhen Sie health_check_interval oder laden Sie die Modelle mit ollama run X --keepalive 60m vor.

#Weiterführende Informationen

Mit dieser Konfiguration haben Sie einen einzigen Zugangspunkt für Ihre gesamte KI, lokal oder in der Cloud, mit nahtlosem Wechsel zwischen beiden. Die nächsten naheliegenden Schritte: