#Pourquoi un proxy LiteLLM local cloud

Une stack hybride typique a deux problèmes. D'abord, le code applicatif se remplit de if provider == 'openai' / elif provider == 'ollama'. Ensuite, la décision "local vs cloud" est figée à l'écriture du code : si Ollama tombe, l'app tombe ; si vous voulez basculer sur Claude pour une tâche précise, il faut redéployer.

LiteLLM résout les deux. Côté application, vous parlez à un endpoint unique compatible OpenAI (chat/completions, embeddings, streaming). Côté infra, un fichier config.yaml décrit vos modèles : alias logique, backend, clé API, priorité de fallback. Vous changez la route sans toucher au code.

En deux mots

LiteLLM = un gateway HTTP qui prend des requêtes OpenAI-compatible et les traduit vers 100+ providers (Ollama, OpenAI, Anthropic, Mistral, Gemini, Azure, Bedrock…). C'est du Python, ça tourne en local, ça s'auto-héberge.

#Comment ça marche

Le proxy expose le port 4000 par défaut. Votre app envoie un POST /chat/completions avec model: "chat-fr". LiteLLM regarde son config.yaml, voit que chat-fr pointe vers ollama/mistral à localhost:11434, fait la requête, normalise la réponse au format OpenAI, et renvoie le résultat à l'app.

Côté app: Une seule URL (http://localhost:4000), une seule clé virtuelle, le SDK OpenAI standard suffit.
Côté proxy: Un model_list mappe des alias (chat-fr, code-rapide, analyse-doc) vers de vrais backends.
Routing: Plusieurs backends pour le même alias = load balancing, fallback, retry automatique.
Observabilité: Logs, latences, coût par requête et par clé virtuelle, exportables vers Langfuse, Prometheus ou un Postgres.

#Prérequis

Python 3.10+: LiteLLM est un package pip. Une venv ou pipx propre suffit.
Ollama qui tourne: Sur http://localhost:11434 avec au moins un modèle pull. Voir le guide installation Ollama si besoin.
Clés API cloud (optionnel): OPENAI_API_KEY, ANTHROPIC_API_KEY si vous voulez router vers le cloud en fallback.
Un fichier .env: Pour ne jamais committer les clés en clair dans config.yaml.

→

Pas obligé d'avoir du cloud

LiteLLM est utile même 100% local. Si vous avez deux modèles Ollama (un petit rapide, un gros précis), le proxy gère le routing entre les deux et la bascule si l'un est saturé.

#1. Installation

Installation avec extras proxy

pip install 'litellm[proxy]'

L'extra proxy embarque FastAPI, uvicorn et les dépendances optionnelles (Postgres, Redis si vous voulez du rate limiting partagé). Pour un test rapide, c'est suffisant. Pour de la production, partez plutôt sur l'image Docker officielle.

Variante Docker

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

Vérifiez que ça tourne :

Health check

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

#2. Un config.yaml LiteLLM minimal

Créez config.yaml à côté de votre projet. La structure tient en trois sections : model_list (les alias), litellm_settings (comportement global) et general_settings (auth, base de données).

config.yaml — Ollama seul

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/mistral
      api_base: http://localhost:11434

  - model_name: code-rapide
    litellm_params:
      model: ollama/qwen2.5-coder:7b
      api_base: http://localhost:11434

litellm_settings:
  drop_params: true
  num_retries: 2
  request_timeout: 60

Lancez le proxy avec ce config :

Démarrage

litellm --config config.yaml --port 4000

Côté application, le SDK OpenAI Python parle directement au proxy. Aucune dépendance à LiteLLM dans le code applicatif :

client.py

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)

Note sur drop_params

drop_params: true demande à LiteLLM d'ignorer silencieusement les paramètres qu'un backend ne supporte pas (ex: logprobs sur Ollama). Sans ça, le proxy renvoie une 400 et casse l'app.

#3. Ajouter OpenAI et Anthropic

On ne hardcode jamais les clés. Mettez-les dans un .env à côté du config :

.env

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

Puis référencez les variables avec la syntaxe os.environ dans le YAML — LiteLLM les substitue au démarrage :

config.yaml — ajout cloud

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/mistral
      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

À ce stade vous avez trois alias logiques. Le code applicatif choisit chat-fr pour les conversations privées, chat-gros pour les requêtes longues, analyse-doc pour la lecture de PDF. Aucune clé n'apparaît dans le code.

Trafic local vs cloud

Un alias qui pointe vers ollama/* reste 100% local. Dès que vous appelez chat-gros ou analyse-doc, la requête sort de votre machine vers OpenAI ou Anthropic. Choisissez l'alias en connaissance de cause côté app — et logguez-le.

#4. Routing par modèle et fallback automatique

La vraie valeur du proxy arrive ici. Deux mécanismes à connaître : plusieurs entrées sous le même model_name (load balancing) et la clé fallbacks (bascule sur erreur).

01
Plusieurs entrées, un seul alias
Vous pouvez déclarer deux fois model_name: chat-fr — une pointant sur Ollama local, l'autre sur un Mistral cloud. LiteLLM répartit les requêtes selon la stratégie (simple-shuffle par défaut, ou usage-based-routing si vous voulez optimiser le coût).
02
Fallback explicite
Dans litellm_settings, déclarez quel alias prend le relais si le premier renvoie une erreur ou un timeout. Le fallback déclenche automatiquement un retry sur le backend de secours.
03
Health check actif
LiteLLM ping périodiquement chaque modèle. Un Ollama qui ne répond plus est marqué unhealthy et sorti du pool tant qu'il ne revient pas — vos requêtes basculent toutes seules sur le cloud.

config.yaml — fallback Ollama → OpenAI

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/mistral
      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"]

Avec cette config, votre app appelle toujours model: "chat-fr". Si Ollama est down, en timeout, ou si le prompt dépasse la fenêtre de contexte locale (8k sur Mistral), le proxy bascule transparent sur GPT-4o-mini. L'app ne voit rien — juste une réponse, peut-être un peu plus lente.

→

Tester le fallback

Coupez Ollama (sudo systemctl stop ollama sur Linux, ou Quit dans la tray Windows) et relancez une requête. Vous devriez voir dans les logs LiteLLM la ligne "Falling back to model chat-fr-cloud". Si rien ne se passe, vérifiez que num_retries n'est pas à 0.

#5. Suivi des coûts et rate limiting

Une stack hybride a un coût caché : on croit utiliser le local, et 30% des requêtes ont en fait basculé sur GPT-4o. LiteLLM calcule le coût de chaque requête à partir d'une table de prix interne (à jour des grilles publiques).

Pour persister les logs et exposer un dashboard, branchez un Postgres :

general_settings avec Postgres

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

Une fois Postgres branché, l'UI admin (http://localhost:4000/ui) montre le coût par clé virtuelle, par modèle, par utilisateur. Vous pouvez aussi créer des clés virtuelles à budget plafonné — pratique pour donner accès à une équipe sans risque de dérapage.

Ordres de grandeur de coût pour 1 M tokens en sortie (prix publics juin 2026, à recalculer chez votre fournisseur) :

Ollama local (Mistral 7B Q4): 0 $ marginal — votre électricité et l'amortissement du GPU.
OpenAI gpt-4o-mini: Autour de 0,60 $ / 1M tokens output, idéal pour le fallback bon marché.
Anthropic Claude Haiku 4.5: Autour de 5 $ / 1M tokens output, plus cher mais excellent rapport qualité/prix sur l'analyse de documents.
OpenAI gpt-4o: Autour de 10 $ / 1M tokens output, à réserver aux tâches où le 4o-mini n'est pas assez bon.

Côté rate limiting, on déclare des limites RPM (requests per minute) et TPM (tokens per minute) par modèle. LiteLLM met en file d'attente ou renvoie une 429 selon votre config :

Limites par modèle

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

Le master_key n'est pas optionnel

Dès que vous exposez le proxy au-delà de localhost (autres machines du LAN, conteneur Docker), définissez un master_key fort dans general_settings. Sans ça, n'importe qui sur le réseau peut consommer vos clés API cloud.

#Dépannage

"Model not found" alors que l'alias existe: Vérifiez l'indentation YAML. Une espace en trop sous litellm_params et le proxy ignore silencieusement l'entrée. Lancez litellm --config config.yaml --debug pour voir le model_list effectivement chargé.
Le fallback ne se déclenche pas: num_retries doit être ≥ 1 et le timeout doit être atteint. Par défaut, request_timeout est très généreux côté Ollama — descendez-le à 30 secondes pour des fallbacks réactifs.
Erreur 401 sur Ollama: ollama/* ne prend pas de clé API. Si vous avez mis api_key sur une entrée Ollama, retirez-la. LiteLLM passe la clé telle quelle, ce qui plante.
Coûts faux ou à zéro: La table de prix dépend de la version de LiteLLM. Mettez à jour (pip install -U 'litellm[proxy]'). Pour un modèle custom non listé, déclarez input_cost_per_token et output_cost_per_token manuellement dans litellm_params.
Latence anormale sur Ollama: Le proxy fait un health check toutes les minutes. Si Ollama est lent à charger un modèle (cold start), le check timeout et marque le modèle unhealthy. Augmentez health_check_interval ou pré-chargez les modèles avec ollama run X --keepalive 60m.

#Pour aller plus loin

Avec ce setup vous avez un point d'entrée unique pour toute votre IA, local ou cloud, avec une bascule transparente. Les étapes naturelles :

Ce guide vous a aidé ?

Un retour, une erreur, une précision ? Faites-nous signe, ça améliore le guide pour tout le monde.

Suite logique

DevOps · 22 min

LiteLLM : un proxy unifié local et cloud