LiteLLM proxy : unifier APIs Claude, Mistral, Ollama — tutoriel 2026

Introduction

Imaginez la situation suivante : votre PME dakaroise utilise Claude pour la rédaction de rapports, Mistral pour la classification de tickets support, et un modèle Ollama local pour les traitements sensibles qui ne doivent pas quitter votre réseau. Trois fournisseurs, trois SDKs, trois modes d’authentification, trois façons différentes de gérer les erreurs et les limites de débit. Quand un fournisseur change ses tarifs ou qu’une API tombe en panne à 2h du matin, c’est votre équipe qui gère le désordre en urgence.

LiteLLM proxy résout exactement ce problème. C’est un serveur mandataire open source — un gateway — qui expose une seule interface HTTP au format OpenAI, quelle que soit la destination réelle des requêtes. Derrière ce point d’entrée unique se cachent plus de 140 fournisseurs et 2 500 modèles : Anthropic Claude, Mistral AI, Ollama, AWS Bedrock, Azure OpenAI, Google Gemini, Cohere, HuggingFace, vLLM et bien d’autres. Le résultat est radical : votre code applicatif ne change jamais, même quand vous basculez de Claude vers Mistral pour réduire les coûts. Vous conservez aussi une vue centralisée des dépenses, des utilisateurs et des performances via un tableau de bord web intégré.

Ce tutoriel vous guide pas à pas : de l’architecture initiale au déploiement Docker, de la configuration des modèles à la gestion des budgets par utilisateur, jusqu’à l’intégration avec OpenWebUI et Continue.dev. Durée estimée : 20 minutes pour une instance fonctionnelle, 45 minutes pour une configuration production complète.

Prérequis

• Docker Engine 24+ et Docker Compose v2 installés (docs.docker.com/engine/install)
• 1 Go de RAM minimum pour un déploiement de test ; 4 CPU et 8 Go RAM pour la production
• Un terminal avec accès sudo (Linux/macOS) ou PowerShell administrateur (Windows)
• Au moins une clé API : ANTHROPIC_API_KEY pour Claude, MISTRAL_API_KEY pour Mistral, ou Ollama installé localement
• Niveau intermédiaire : connaissance de base de Docker, YAML, et appels HTTP REST
• Temps estimé : 20 minutes (test) à 45 minutes (configuration complète)

Étape 1 — Architecture : comprendre les trois blocs

Avant de lancer la moindre commande, il est essentiel de comprendre ce que vous allez construire. LiteLLM proxy repose sur trois composants qui s’assemblent via Docker Compose : le serveur proxy lui-même, une base de données PostgreSQL, et l’interface web de gestion (UI). Comprendre le rôle de chaque bloc vous permettra de diagnostiquer les problèmes et de faire évoluer l’architecture plus tard.

Le serveur proxy (conteneur litellm) est le cœur du dispositif. Il reçoit toutes les requêtes HTTP entrantes — que ce soit depuis votre application Python, depuis OpenWebUI, depuis Continue.dev, ou depuis n’importe quel client OpenAI-compatible — et les achemine vers le bon fournisseur selon votre fichier de configuration. C’est lui qui gère l’authentification des virtual keys, le routing, les fallbacks, les retries, et la mesure des coûts en temps réel.

La base de données PostgreSQL stocke tout ce qui doit persister entre les redémarrages : les virtual keys créées, les budgets par utilisateur et par équipe, les logs de chaque requête avec son coût, et les métadonnées des modèles. Sans PostgreSQL, le proxy fonctionne toujours mais vous perdez toutes les fonctionnalités de gestion : pas de virtual keys persistantes, pas de tableau de bord, pas de suivi des dépenses.

L’interface web est accessible par défaut sur le port 4000 à l’URL /ui. Elle offre un tableau de bord des dépenses par modèle, par clé et par équipe, la création et la révocation de virtual keys, la configuration des budgets, et la visualisation des logs. C’est votre panneau de contrôle centralisé pour toute l’équipe, sans avoir à toucher au terminal.

Les trois blocs communiquent ainsi : votre application envoie une requête HTTP POST à http://localhost:4000/v1/chat/completions avec un en-tête Authorization: Bearer sk-votre-virtual-key. Le proxy valide la clé contre PostgreSQL, vérifie que le budget n’est pas épuisé, achemine la requête vers le bon fournisseur LLM, enregistre le résultat et le coût dans la base, puis retourne la réponse au format OpenAI standard à votre application.

Étape 2 — Déployer LiteLLM proxy via Docker

LiteLLM propose une image Docker spécialisée pour les déploiements avec base de données : ghcr.io/berriai/litellm-database. Cette image inclut les drivers PostgreSQL et les migrations de schéma automatiques au premier démarrage, ce qui simplifie considerablement la mise en place par rapport à l’image de base. Créez un répertoire de travail dédié, puis définissez les trois fichiers de configuration.

Commencez par créer le fichier docker-compose.yml dans votre répertoire de travail :

version: "3.9"

services:
  litellm:
    image: ghcr.io/berriai/litellm-database:main-latest
    # IMPORTANT : éviter les versions 1.82.7 et 1.82.8 (incident supply chain mars 2026)
    # Utiliser main-latest qui pointe sur 1.83.0+
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    environment:
      - DATABASE_URL=postgresql://litellm:litellm_pass@db:5432/litellm_db
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - MISTRAL_API_KEY=${MISTRAL_API_KEY}
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=litellm
      - POSTGRES_PASSWORD=litellm_pass
      - POSTGRES_DB=litellm_db
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres_data:

Créez ensuite le fichier .env dans le même répertoire pour stocker vos secrets sans les écrire en dur dans le YAML. Ce fichier ne doit jamais être commité dans un dépôt Git :

LITELLM_MASTER_KEY=sk-mon-super-master-key-admin
ANTHROPIC_API_KEY=sk-ant-api03-votre-cle-anthropic
MISTRAL_API_KEY=votre-cle-mistral-ai

Notez que LITELLM_MASTER_KEY doit commencer par sk- — c’est la clé administrateur principale qui vous permettra de créer des virtual keys pour vos utilisateurs. Une fois ces deux fichiers en place, lancez la stack :

docker compose up -d

Au premier démarrage, PostgreSQL s’initialise en quelques secondes, puis LiteLLM effectue les migrations de schéma automatiquement. Attendez environ 30 secondes, puis vérifiez que le proxy répond avec une requête de santé :

curl http://localhost:4000/health

Une réponse {"status": "healthy"} confirme que le proxy est opérationnel. Si vous obtenez une erreur de connexion, vérifiez les logs avec docker compose logs litellm — les erreurs de migration PostgreSQL ou de variable d’environnement manquante y apparaissent clairement.

Étape 3 — Configurer config.yaml avec la model_list

Le fichier config.yaml est le fichier de configuration central de LiteLLM. C’est ici que vous déclarez tous les modèles disponibles via votre proxy, leurs paramètres de connexion, et les paramètres globaux du serveur. La structure repose sur trois sections principales : model_list (la liste des modèles), litellm_settings (comportement du moteur), et general_settings (paramètres du serveur).

Voici un config.yaml complet qui expose Claude, Mistral via l’API officielle, et Ollama en local — les trois providers les plus courants dans une configuration PME ouest-africaine :

model_list:
  # --- Claude via API Anthropic ---
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5-20250929
      api_key: os.environ/ANTHROPIC_API_KEY

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

  # --- Mistral via API officielle ---
  - model_name: mistral-small
    litellm_params:
      model: mistral/mistral-small-latest
      api_key: os.environ/MISTRAL_API_KEY

  - model_name: mistral-medium
    litellm_params:
      model: mistral/mistral-medium-latest
      api_key: os.environ/MISTRAL_API_KEY

  # --- Ollama en local (réseau interne) ---
  - model_name: llama3-local
    litellm_params:
      model: ollama/llama3.1
      api_base: http://host.docker.internal:11434

  - model_name: mistral-local
    litellm_params:
      model: ollama/mistral
      api_base: http://host.docker.internal:11434

litellm_settings:
  drop_params: true          # Ignore les paramètres non supportés par le provider
  request_timeout: 60        # Timeout global en secondes
  num_retries: 2             # Retries automatiques en cas d'erreur transitoire

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
  store_model_in_db: true    # Permet de modifier les modèles depuis l'UI

Quelques points importants sur cette configuration. La notation os.environ/NOM_VARIABLE est la syntaxe LiteLLM pour lire une valeur depuis les variables d’environnement — elle est préférable à l’écriture directe de la valeur dans le fichier YAML. Le paramètre drop_params: true est particulièrement utile quand vous basculez entre providers : certains paramètres OpenAI (comme logprobs) ne sont pas supportés par tous les fournisseurs, et LiteLLM les ignore silencieusement plutôt que de renvoyer une erreur. Après avoir créé ou modifié ce fichier, redémarrez le proxy avec docker compose restart litellm pour appliquer la configuration.

Étape 4 — Virtual keys et budgets utilisateurs

Les virtual keys sont l’une des fonctionnalités les plus puissantes de LiteLLM proxy dans un contexte d’équipe ou de PME. Plutôt que de distribuer votre clé Anthropic ou Mistral directement à chaque développeur ou application — ce qui rend la révocation et la gestion des coûts quasi-impossibles — vous créez des clés virtuelles avec des permissions et des budgets granulaires. Chaque virtual key est une clé de la forme sk-... qui s’authentifie auprès du proxy, lequel utilise ensuite la vraie clé API en arrière-plan.

Pour créer une virtual key, vous appelez le endpoint /key/generate avec votre master key en en-tête d’autorisation :

curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-mon-super-master-key-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "dev-mamadou",
    "models": ["claude-haiku", "mistral-small", "llama3-local"],
    "max_budget": 10.0,
    "budget_duration": "30d",
    "metadata": {"team": "backend", "user": "mamadou.diallo"}
  }'

Cette commande crée une clé pour le développeur Mamadou avec un budget mensuel de 10 dollars (ou 10 unités de votre devise de référence), limitée aux trois modèles déclarés. La réponse contient la key générée, par exemple sk-abc123xyz..., que vous transmettez au développeur. Ce dernier l’utilise exactement comme une clé OpenAI standard dans ses appels API. Quand le budget de 10 dollars est atteint, le proxy renvoie automatiquement une erreur 429 Budget Exceeded sans impacter les autres clés. Pour créer une clé équipe avec un budget partagé, ajoutez le paramètre team_id et définissez d’abord l’équipe via /team/new.

L’interface web à http://localhost:4000/ui permet également de créer et gérer les clés visuellement, sans passer par l’API REST — ce qui est plus accessible pour les membres non-techniques de votre équipe.

Étape 5 — Routing, fallback et load balancing

Le routing intelligent est ce qui transforme LiteLLM d’un simple proxy en un véritable orchestrateur de LLMs. Deux scénarios sont particulièrement précieux : le fallback automatique (si un provider est en panne, on bascule sur un autre) et le load balancing (répartir la charge entre plusieurs déploiements du même modèle pour éviter les limites de débit).

Pour configurer le fallback, il faut utiliser des groupes de modèles. Dans le config.yaml, on peut assigner le même model_name à plusieurs providers — LiteLLM les traitera comme un pool et routera selon la stratégie choisie :

model_list:
  # Groupe "chat" : Claude en priorité, Mistral en fallback, Ollama en dernier recours
  - model_name: chat
    litellm_params:
      model: anthropic/claude-haiku-4-5-20251001
      api_key: os.environ/ANTHROPIC_API_KEY
    model_info:
      mode: chat
      order: 1     # Priorité la plus haute

  - model_name: chat
    litellm_params:
      model: mistral/mistral-small-latest
      api_key: os.environ/MISTRAL_API_KEY
    model_info:
      mode: chat
      order: 2     # Fallback si Claude échoue

  - model_name: chat
    litellm_params:
      model: ollama/mistral
      api_base: http://host.docker.internal:11434
    model_info:
      mode: chat
      order: 3     # Dernier recours : Ollama local, sans coût réseau

router_settings:
  routing_strategy: priority-based
  num_retries: 2
  retry_after: 5
  allowed_fails: 3
  cooldown_time: 30

Avec cette configuration, toutes les requêtes envoyées au modèle chat passent d’abord par Claude Haiku. Si Claude renvoie une erreur de rate limit ou une erreur 5xx deux fois de suite, LiteLLM bascule automatiquement sur Mistral Small. Si Mistral échoue à son tour, la requête est envoyée au modèle Ollama local — qui ne dépend d’aucune connectivité Internet. Le paramètre cooldown_time: 30 signifie que Claude sera mis « en attente » 30 secondes avant d’être réessayé, permettant à l’API de récupérer.

Pour le load balancing horizontal — par exemple si vous avez deux clés Anthropic avec des limites distinctes — il suffit de déclarer le même model_name avec deux clés différentes et d’utiliser la stratégie usage-based-routing : LiteLLM dirige chaque requête vers la clé qui a le plus de capacité disponible à cet instant. C’est transparent pour votre application.

Étape 6 — Logging et tracking des coûts

Le tracking des coûts est automatique dès que PostgreSQL est connecté : chaque requête génère une ligne dans la table LiteLLM_SpendLogs avec le modèle utilisé, l’identifiant de la virtual key, le nombre de tokens d’entrée et de sortie, et le coût calculé selon la grille tarifaire officielle de chaque provider. LiteLLM maintient en interne une base de données des prix par token de tous les modèles supportés et la met à jour régulièrement.

Pour activer un logging plus verbeux et intégrer un outil de monitoring externe, ajoutez la section litellm_settings dans votre config.yaml :

litellm_settings:
  success_callback: ["langfuse"]   # ou ["helicone"], ["langsmith"], etc.
  failure_callback: ["langfuse"]
  langfuse_public_key: os.environ/LANGFUSE_PUBLIC_KEY
  langfuse_secret_key: os.environ/LANGFUSE_SECRET_KEY
  langfuse_host: https://cloud.langfuse.com

Si vous préférez rester en self-hosted sans dépendance externe, le tableau de bord intégré de LiteLLM suffit pour la majorité des besoins. Accédez à http://localhost:4000/ui, connectez-vous avec votre master key, puis naviguez vers l’onglet Usage. Vous y verrez les dépenses agrégées par jour, par modèle, par clé et par équipe, avec des graphiques d’évolution sur les 30 derniers jours. Pour consulter les logs individuels de chaque requête (utile pour déboguer), l’onglet Logs affiche le détail — prompt, réponse, durée, coût — avec un filtre par clé ou par modèle.

Pour exporter les données brutes dans votre propre outil analytics, l’API REST expose un endpoint /spend/logs qui accepte des paramètres de date et de filtre, et retourne un JSON structuré que vous pouvez ingérer dans n’importe quel pipeline de données.

Étape 7 — Intégration OpenWebUI et Continue.dev

L’un des avantages majeurs d’un proxy OpenAI-compatible est que tout outil qui supporte OpenAI fonctionne immédiatement avec LiteLLM, sans aucune modification de code. OpenWebUI et Continue.dev sont deux des intégrations les plus populaires dans un contexte de développement.

OpenWebUI est une interface web de chat self-hosted. Pour le connecter à LiteLLM, il suffit de définir deux variables d’environnement lors du démarrage du conteneur OpenWebUI :

docker run -d \
  --name openwebui \
  -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://litellm:4000/v1 \
  -e OPENAI_API_KEY=sk-votre-virtual-key-openwebui \
  --network votre-reseau-docker \
  ghcr.io/open-webui/open-webui:main

Assurez-vous que le conteneur OpenWebUI est sur le même réseau Docker que le proxy LiteLLM pour que la résolution DNS interne (litellm) fonctionne. Une fois démarré, OpenWebUI liste automatiquement tous les modèles déclarés dans votre config.yaml — Claude, Mistral, et vos modèles Ollama — dans le sélecteur de modèles de l’interface. Vos utilisateurs naviguent entre les modèles depuis l’interface graphique sans manipuler aucune clé API.

Continue.dev est l’extension de complétion de code pour VS Code et JetBrains. Sa configuration se fait dans le fichier ~/.continue/config.json :

{
  "models": [
    {
      "title": "Claude Sonnet (via LiteLLM)",
      "provider": "openai",
      "model": "claude-sonnet",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-votre-virtual-key-continue"
    },
    {
      "title": "Mistral Small (via LiteLLM)",
      "provider": "openai",
      "model": "mistral-small",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-votre-virtual-key-continue"
    }
  ]
}

Le point clé ici est d’utiliser "provider": "openai" même pour Claude ou Mistral — c’est LiteLLM qui fait la traduction transparente. Le nom de modèle (claude-sonnet, mistral-small) doit correspondre exactement au model_name déclaré dans votre config.yaml. Chaque développeur de votre équipe peut avoir sa propre virtual key avec son propre budget mensuel, traçable individuellement depuis le tableau de bord.

Erreurs fréquentes

Adaptation au contexte ouest-africain

LiteLLM proxy prend une dimension stratégique particulière pour les PME et startups de l’Afrique de l’Ouest. Trois enjeux concrets justifient son adoption même pour des équipes de moins de dix personnes.

Centraliser la facturation est le premier bénéfice immédiat. Dans de nombreuses équipes dakaroises, abidjanaises ou bambakoises, chaque développeur utilise sa propre clé API avec sa propre carte bancaire — quand il en a une. La question des cartes Visa internationale et des limites de paiement mobil money est réelle. Avec LiteLLM proxy, une seule clé API par fournisseur suffit pour toute l’organisation. L’administrateur paie une seule facture mensuelle chez Anthropic et une chez Mistral, puis distribue des virtual keys à coût nul à tous les membres. Les budgets par clé évitent les mauvaises surprises : un stagiaire qui laisse tourner un script en boucle ne peut pas dépasser son allocation de 5 dollars mensuelle.

Basculer intelligemment entre Claude et Mistral selon le coût et la qualité est le deuxième levier. Claude Sonnet excelle pour les tâches de raisonnement complexe, la rédaction élaborée, et l’analyse de documents longs — mais son coût par token est nettement plus élevé que Mistral Small. Pour une PME qui traite des centaines de tickets support par jour, utiliser Claude pour les requêtes simples de classification est un gaspillage. La stratégie recommandée est de créer deux groupes de modèles dans le config.yaml : un groupe premium (Claude) pour les tâches à forte valeur, et un groupe economique (Mistral Small ou Haiku) pour les traitements de masse. Votre application choisit le groupe selon la complexité estimée de la tâche. Vous pouvez même automatiser ce choix avec le routage par métadonnées de LiteLLM.

Le fallback vers Ollama local en cas de coupure réseau est sans doute l’adaptation la plus critique au contexte ouest-africain. Les interruptions de connectivité Internet — qu’elles durent dix minutes ou plusieurs heures — sont une réalité quotidienne dans de nombreuses villes de la sous-région. Avec la configuration de fallback présentée à l’étape 5, votre application continue de fonctionner même sans accès à Internet : LiteLLM bascule automatiquement sur votre modèle Ollama local (Mistral 7B ou Llama 3 selon ce que votre matériel supporte). La qualité sera inférieure, mais le service reste disponible. Pour les structures qui traitent des données sensibles — dossiers médicaux, données financières — ce modèle hybride cloud/local permet aussi de respecter des contraintes de localisation des données sans sacrifier la disponibilité.

Enfin, pour les équipes qui déploient sur des VPS avec une connexion limitée, l’option Redis (recommandée pour les déploiements multi-instances) peut être désactivée sans problème pour une instance unique. Le proxy reste fonctionnel avec PostgreSQL seul, sur une machine aussi modeste qu’un VPS 2 vCPU / 4 Go RAM chez des hébergeurs africains comme Tier.Net, OVH Dakar, ou African Data Centres.

Tutoriels frères

• OpenWebUI : installer et configurer votre interface LLM self-hosted — comment déployer l’interface de chat, gérer les utilisateurs et connecter vos modèles
• Ollama : servir des LLMs en local sur Linux et VPS — installation, téléchargement de modèles, API REST et optimisation GPU/CPU
• vLLM : déployer un serveur d’inférence haute performance — pour les équipes qui ont besoin de throughput élevé avec des modèles open source

Pour aller plus loin

• Retour au pilier : LLM en self-hosted pour PME francophone : OpenWebUI, LiteLLM, vLLM (2026)
• Documentation officielle : docs.litellm.ai — référence complète, tous les providers, tous les paramètres
• Code source : github.com/BerriAI/litellm — issues, releases, changelog, exemples de configurations
• Prochain tutoriel recommandé : une fois LiteLLM en place, l’étape naturelle est de déployer OpenWebUI pour offrir une interface de chat à votre équipe sans écrire une seule ligne de code frontend.

FAQ