Construire une passerelle LLM avec LiteLLM (2026)

Vous avez Claude Code, Codex CLI, une clé API DeepSeek et un quota gratuit GLM — mais les clés vivent dans quatre endroits différents, chaque outil est configuré différemment, et votre facturation est un vrai casse-tête à suivre. LiteLLM Proxy réunit ces quatre éléments en un seul : une passerelle HTTP locale avec une interface unifiée compatible OpenAI. Chaque outil IA pointe vers la même adresse, et vous gérez toutes vos clés et règles de routage dans un seul config.yaml.

Ceci est un tutoriel pratique — pas de théorie, on construit directement. En partant de zéro, à la fin vous aurez :

• Claude Code routé via LiteLLM Proxy vers DeepSeek / GLM (connexion directe depuis la Chine continentale, coût réduit)
• OpenAI Codex CLI utilisant le même Proxy pour mélanger Claude Sonnet 5 et DeepSeek pour la programmation
• Bascule automatique quand votre route principale tombe en panne, et rotation automatique entre plusieurs clés (pour éviter les limites de débit)
• Des clés virtuelles à distribuer aux membres de l'équipe, chacune avec son propre plafond de dépense
• Un déploiement Docker de production avec PostgreSQL + Redis

1. Architecture : ce que vous allez construire

┌─────────────────────────────────────────────────┐
│           Votre machine locale / serveur          │
│                                                 │
│  Claude Code ──┐                                │
│  Codex CLI   ──┼──► LiteLLM Proxy :4000 ──────► │──► API Anthropic
│  script quelconque ──┘  (routage géré par config) │──► API OpenAI
│                     │                           │──► API DeepSeek (connexion directe)
│                     ├── équilibrage de charge    │──► API Zhipu GLM (connexion directe)
│                     ├── bascule automatique      │──► SiliconFlow et autres relais
│                     ├── gestion des clés virtuelles │
│                     └── suivi des coûts          │
└─────────────────────────────────────────────────┘

Toutes les requêtes des outils IA arrivent de façon unifiée sur http://localhost:4000, et LiteLLM se charge de :

• Traduire les requêtes au format Anthropic (envoyées par Claude Code) vers le format OpenAI / DeepSeek / GLM
• Router les requêtes au format OpenAI (envoyées par Codex) vers n'importe quel fournisseur
• Basculer automatiquement vers un modèle de secours en cas d'échec de la route principale
• Faire tourner plusieurs clés API pour éviter qu'une seule clé ne soit limitée en débit

2. Installer LiteLLM

# Recommandé : uv (10 fois plus rapide)
uv tool install 'litellm[proxy]'

# ou pip
pip install 'litellm[proxy]'

# Vérifier
litellm --version
# Devrait afficher v1.91.0 ou supérieur

3. La structure centrale du config.yaml

Toute la configuration de LiteLLM Proxy tient dans un seul fichier config.yaml. Voici d'abord le squelette :

model_list:              # votre « menu de modèles » exposé publiquement
  - model_name: xxx      # le nom utilisé par le client qui appelle
    litellm_params:
      model: provider/model-id   # le fournisseur et le modèle réellement appelés
      api_key: os.environ/XXX    # la clé est lue depuis une variable d'environnement, jamais codée en dur

litellm_settings:        # paramètres globaux de comportement
  drop_params: true      # ignore automatiquement les paramètres non pris en charge par le modèle cible
  num_retries: 3

general_settings:        # paramètres du serveur Proxy
  master_key: sk-1234    # la clé requise pour appeler le Proxy

router_settings:         # stratégie de routage
  routing_strategy: simple-shuffle

model_name est le nom que voient les outils externes — vous pouvez le choisir librement. C'est litellm_params.model qui indique vers quel fournisseur LiteLLM transmet réellement la requête.

4. Connecter Claude Code

Claude Code utilise le format de l'API Anthropic Messages. LiteLLM traduit automatiquement ce format vers celui du fournisseur cible, puis retraduit la réponse en sens inverse.

4.1 Principe de fonctionnement

Claude Code lit deux variables d'environnement :

• ANTHROPIC_BASE_URL : où envoyer les requêtes API (à remplacer par l'adresse de votre LiteLLM)
• ANTHROPIC_AUTH_TOKEN : le jeton Bearer d'autorisation (renseignez le master_key de LiteLLM)

4.2 Étapes de configuration

Étape 1 : configurez dans config.yaml les modèles que vous voulez que Claude Code utilise :

model_list:
  # Modèle principal de Claude Code : Claude Sonnet 5 (officiel Anthropic)
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  # Secours économique : DeepSeek V4 Flash (connexion directe, coût ↓90%)
  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_API_KEY

  # Secours gratuit : GLM-4.7-Flash (gratuit en permanence)
  - model_name: glm-flash
    litellm_params:
      model: zai/glm-4.7-flash
      api_key: os.environ/ZAI_API_KEY

general_settings:
  master_key: sk-my-proxy-key

Étape 2 : démarrez LiteLLM Proxy :

litellm --config config.yaml
# Sortie : LiteLLM Proxy running on http://0.0.0.0:4000

Étape 3 : définissez les variables d'environnement, puis démarrez Claude Code :

# Définir les variables d'environnement (ajoutez-les à ~/.zshrc ou ~/.bashrc pour que ce soit permanent)
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-my-proxy-key"

# Utiliser Claude natif d'Anthropic (par défaut)
claude

# Basculer vers DeepSeek (économie)
claude --model deepseek-flash

# Basculer vers GLM gratuit
claude --model glm-flash

# Activer la fonction de bascule via /model dans le panneau (nécessite Claude Code v2.1.129+)
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
claude  # une fois lancé, utilisez la commande /model pour lister et basculer

4.3 Vérifier que ça fonctionne

# Vérifier directement avec curl que le Proxy relaie bien les requêtes au format Claude Code
curl http://localhost:4000/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-my-proxy-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "deepseek-flash",
    "max_tokens": 50,
    "messages": [{"role": "user", "content": "Réponds ok"}]
  }'
# Devrait renvoyer la réponse de DeepSeek, mais au format Anthropic Messages

5. Connecter OpenAI Codex CLI

Codex CLI (@openai/codex) utilise le format OpenAI Chat Completions. Il lit deux variables : OPENAI_BASE_URL et OPENAI_API_KEY.

5.1 Installer Codex CLI

npm install -g @openai/codex
# ou
yarn global add @openai/codex

5.2 Configuration

Codex utilise le format OpenAI et appelle directement le point de terminaison /v1/chat/completions, sans couche de traduction supplémentaire :

# Pointer Codex vers LiteLLM Proxy (point de terminaison compatible OpenAI)
export OPENAI_BASE_URL="http://localhost:4000"
export OPENAI_API_KEY="sk-my-proxy-key"   # master_key de LiteLLM

# Faire tourner Codex avec Claude Sonnet 5 (relayé via le Proxy)
codex --model claude-sonnet-5

# Faire tourner Codex avec DeepSeek (moins cher)
codex --model deepseek-flash --full-auto

# Utiliser la version gratuite de GLM
codex --model glm-flash

5.3 Configuration permanente via Codex config.toml

# ~/.codex/config.toml
model = "deepseek-flash"          # utilise DeepSeek par défaut
provider = "openai"
base-url = "http://localhost:4000"

[model-options]
temperature = 0.2

Une fois configuré, un simple codex suffit — plus besoin d'ajouter --model à chaque fois.

6. Connecter DeepSeek (équilibrage de charge multi-clés)

L'API officielle de DeepSeek (api.deepseek.com) n'est pas accessible en connexion directe depuis la Chine continentale ; il est recommandé de passer par un relais comme SiliconFlow pour appeler les modèles DeepSeek. Utiliser plusieurs clés de plusieurs comptes permet de répartir la pression liée aux limites de débit.

6.1 Via SiliconFlow (connexion directe)

model_list:
  # Clé SiliconFlow 1 (principale)
  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1
      rpm: 50   # cette clé est limitée à 50 requêtes par minute

  # Clé SiliconFlow 2 (répartition du trafic)
  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_2
      rpm: 50

  # DeepSeek version phare (haute qualité, un peu plus cher)
  - model_name: deepseek-pro
    litellm_params:
      model: openai/deepseek-v4-pro
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1

Avec deux entrées portant le même model_name: deepseek-flash, LiteLLM effectue automatiquement l'équilibrage de charge entre elles — quand la clé 1 est limitée en débit, il bascule automatiquement sur la clé 2, de façon totalement transparente.

6.2 Via DeepSeek officiel (nécessite un proxy réseau)

  - model_name: deepseek-official
    litellm_params:
      model: deepseek/deepseek-chat   # le préfixe deepseek/ est intégré à litellm
      api_key: os.environ/DEEPSEEK_API_KEY

6.3 Configurer les variables d'environnement

# Fichier .env ou export direct
export SILICONFLOW_KEY_1="sk-sf-xxxxxxxx"
export SILICONFLOW_KEY_2="sk-sf-yyyyyyyy"
export DEEPSEEK_API_KEY="sk-deepseek-zzzzzzzz"

7. Connecter Zhipu GLM (y compris le palier gratuit)

Zhipu AI (bigmodel.cn) dispose d'une API en connexion directe depuis la Chine continentale, et GLM-4.7-Flash est gratuit en permanence — un modèle MoE de 31 milliards de paramètres, 59,2 % sur SWE-bench, un contexte de 200K — adapté comme solution de secours à faible coût.

7.1 Inscription et obtention d'une clé

1. Rendez-vous sur bigmodel.cn pour vous inscrire
2. Après vérification d'identité, obtenez un quota gratuit de 20 millions de tokens
3. Générez une clé API depuis le panneau de contrôle

7.2 Configuration du config.yaml

model_list:
  # GLM gratuit haut de gamme (gratuit en permanence, bonne capacité de programmation)
  - model_name: glm-flash
    litellm_params:
      model: zai/glm-4.7-flash    # le préfixe zai/ intégré à LiteLLM prend en charge Zhipu
      api_key: os.environ/ZAI_API_KEY

  # GLM version phare (payante, plus performante)
  - model_name: glm-pro
    litellm_params:
      model: zai/glm-5.2
      api_key: os.environ/ZAI_API_KEY

  # GLM version vision (gratuite)
  - model_name: glm-vision
    litellm_params:
      model: zai/glm-4.6v-flash
      api_key: os.environ/ZAI_API_KEY

export ZAI_API_KEY="your-glm-api-key"

7.3 Vérifier la connectivité avec GLM

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-my-proxy-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-flash",
    "messages": [{"role": "user", "content": "Présente-toi en une phrase"}]
  }'

8. Bascule automatique : basculer vers un modèle de secours quand le principal tombe

C'est l'une des fonctionnalités les plus utiles de LiteLLM : quand le modèle principal tombe (limite de débit, panne, erreur), il bascule automatiquement vers un modèle de secours, sans que l'appelant ne s'en aperçoive.

8.1 Définir les priorités avec le paramètre order

model_list:
  # Principal : Claude Sonnet 5 (le plus performant, utilisé en priorité)
  - model_name: best-model
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
      order: 1   # priorité la plus élevée

  # Secours 1 : DeepSeek (économique, connexion directe)
  - model_name: best-model
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1
      order: 2   # utilisé si Claude tombe

  # Secours 2 : GLM gratuit (filet de sécurité)
  - model_name: best-model
    litellm_params:
      model: zai/glm-4.7-flash
      api_key: os.environ/ZAI_API_KEY
      order: 3   # dernier recours

Toutes ces entrées partagent le même model_name, et l'appel se fait de façon unifiée avec best-model. LiteLLM essaie d'abord order=1, puis bascule automatiquement vers order=2 en cas d'échec, puis vers order=3.

8.2 Utiliser le paramètre fallbacks pour un filet de sécurité entre groupes de modèles

litellm_settings:
  # Bascule inter-groupe en cas d'échec du modèle principal
  fallbacks:
    - claude-sonnet-5: ["deepseek-flash", "glm-flash"]
    - deepseek-flash: ["glm-flash"]

  # Bascule spécifique en cas de limite de débit (erreur 429)
  content_policy_fallbacks:
    - claude-sonnet-5: ["deepseek-flash"]

  # Bascule en cas de dépassement de la fenêtre de contexte
  context_window_fallbacks:
    - claude-sonnet-5: ["glm-flash"]   # GLM dispose d'un contexte de 200K

  num_retries: 3        # 3 tentatives par déploiement avant de basculer
  allowed_fails: 3      # plus de 3 échecs en 1 minute déclenche le refroidissement
  cooldown_time: 30     # 30 secondes de refroidissement

9. Le config.yaml complet (les quatre réunis)

Combinez toutes les configurations précédentes en un config.yaml complet, directement utilisable :

# config.yaml — configuration de la passerelle LiteLLM quatre-en-un
# Claude Code + Codex CLI + DeepSeek + GLM

model_list:
  # ── Claude Sonnet 5 (officiel Anthropic) ──────────────────────
  - model_name: claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

  # ── DeepSeek Flash (SiliconFlow, connexion directe, rotation à deux clés) ───────
  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1
      rpm: 50

  - model_name: deepseek-flash
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_2
      rpm: 50

  # ── DeepSeek version phare (haute qualité) ─────────────────────────────
  - model_name: deepseek-pro
    litellm_params:
      model: openai/deepseek-v4-pro
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1

  # ── GLM gratuit (filet de sécurité permanent et gratuit) ────────────────────────
  - model_name: glm-flash
    litellm_params:
      model: zai/glm-4.7-flash
      api_key: os.environ/ZAI_API_KEY

  # ── GLM version phare payante ────────────────────────────────────
  - model_name: glm-pro
    litellm_params:
      model: zai/glm-5.2
      api_key: os.environ/ZAI_API_KEY

  # ── best-model : groupe de bascule automatique avec priorités ─────────────────
  - model_name: best-model
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
      order: 1

  - model_name: best-model
    litellm_params:
      model: openai/deepseek-v4-flash
      api_base: https://api.siliconflow.cn/v1
      api_key: os.environ/SILICONFLOW_KEY_1
      order: 2

  - model_name: best-model
    litellm_params:
      model: zai/glm-4.7-flash
      api_key: os.environ/ZAI_API_KEY
      order: 3

litellm_settings:
  drop_params: true
  num_retries: 3
  request_timeout: 60
  allowed_fails: 3
  cooldown_time: 30
  fallbacks:
    - claude-sonnet-5: ["deepseek-flash", "glm-flash"]
    - deepseek-flash: ["glm-flash"]
  context_window_fallbacks:
    - claude-sonnet-5: ["glm-flash"]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  alerting: ["slack"]    # optionnel, alertes Slack sur requêtes lentes/erreurs

router_settings:
  routing_strategy: simple-shuffle

# Fichier .env (dans le même répertoire)
ANTHROPIC_API_KEY=sk-ant-xxx
SILICONFLOW_KEY_1=sk-sf-xxx
SILICONFLOW_KEY_2=sk-sf-yyy
ZAI_API_KEY=your-glm-key
LITELLM_MASTER_KEY=sk-my-proxy-2026

# Démarrer (lit automatiquement le .env du répertoire courant)
litellm --config config.yaml

# Vérifier que tous les modèles sont disponibles
curl http://localhost:4000/models \
  -H "Authorization: Bearer sk-my-proxy-2026" | python3 -m json.tool

10. Clés virtuelles et budgets d'équipe

Pour un usage en équipe, ne distribuez pas le master_key à tout le monde — utilisez des clés virtuelles pour donner à chacun un plafond indépendant :

10.1 Créer une clé virtuelle

# Créer une clé virtuelle pour la développeuse Alice (plafond mensuel de 5 $, uniquement deepseek-flash et glm-flash)
curl -X POST http://localhost:4000/key/generate \
  -H "Authorization: Bearer sk-my-proxy-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "dev-team",
    "max_budget": 5.0,
    "budget_duration": "30d",
    "models": ["deepseek-flash", "glm-flash"],
    "metadata": {"user": "alice@company.com"}
  }'

# Réponse : {"key": "sk-virtual-abc123", "expires": "2026-08-08", ...}

# Alice utilise sa clé virtuelle pour appeler Codex — elle ne peut utiliser que les modèles autorisés, et tout dépassement de budget est automatiquement refusé
export OPENAI_API_KEY="sk-virtual-abc123"
export OPENAI_BASE_URL="http://localhost:4000"
codex --model deepseek-flash

10.2 Consulter les dépenses

# Voir le détail des dépenses d'une clé donnée
curl http://localhost:4000/key/info?key=sk-virtual-abc123 \
  -H "Authorization: Bearer sk-my-proxy-2026"

# Voir le récapitulatif des dépenses de toutes les clés
curl http://localhost:4000/global/spend \
  -H "Authorization: Bearer sk-my-proxy-2026"

11. Déploiement Docker en production

11.1 Déploiement rapide en conteneur unique

# docker-compose.yml (version minimale)
version: '3.8'
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    env_file:
      - .env
    command: --config /app/config.yaml --port 4000 --num_workers 8
    restart: unless-stopped

docker compose up -d
docker compose logs -f litellm   # consulter les journaux

11.2 Déploiement de production complet (PostgreSQL + Redis)

Pour un scénario de production dépassant 1000 RPM, PostgreSQL est nécessaire pour persister les clés virtuelles et les données de dépense, et Redis pour partager l'état de limitation de débit de façon distribuée :

# docker-compose.prod.yml
version: '3.8'
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${'{POSTGRES_PASSWORD}'}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 10s

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml
    env_file:
      - .env
    environment:
      - DATABASE_URL=postgresql://litellm:${'{POSTGRES_PASSWORD}'}@postgres:5432/litellm
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    command: --config /app/config.yaml --port 4000 --num_workers 8
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:

Activez Redis dans la section router_settings du config.yaml :

router_settings:
  routing_strategy: usage-based-routing  # stratégie nécessitant Redis
  redis_host: redis
  redis_port: 6379
  cache_responses: true   # les requêtes strictement identiques renvoient directement le cache, réduisant les coûts

12. Débogage et dépannage

12.1 Activer les journaux détaillés

# Activer le mode debug au démarrage
litellm --config config.yaml --detailed_debug

# Permet de voir : la décision de routage pour chaque requête, les journaux de nouvelles tentatives, le fournisseur réellement utilisé

12.2 Vérification de santé

# Vérifier l'état du Proxy lui-même
curl http://localhost:4000/health

# Vérifier si tous les modèles configurés sont accessibles
curl http://localhost:4000/health/liveliness \
  -H "Authorization: Bearer sk-my-proxy-2026"

12.3 Guide rapide des erreurs courantes

13. FAQ

Q : J'utilise toujours Claude Code avec l'API officielle Anthropic — passer par le Proxy va-t-il affecter l'appel d'outils (Tool Use) ?

R : LiteLLM offre une prise en charge complète de l'API Anthropic Messages pour Claude Code, y compris tool_use, system prompt, vision et streaming. Si le modèle cible est nativement Anthropic (préfixe anthropic/), le relais se fait sans aucune perte. Si la cible est DeepSeek / GLM, LiteLLM convertit le format tool_use d'Anthropic vers le format function_calling d'OpenAI — la plupart des scénarios d'outils fonctionnent normalement, mais de très rares fonctionnalités propres à Anthropic peuvent nécessiter des ajustements.

Q : Le mode --full-auto de Codex CLI est-il sûr à utiliser via le Proxy ?

R : La sécurité dépend du modèle et de votre système, pas du Proxy. --full-auto laisse Codex exécuter automatiquement des opérations sur les fichiers — il est recommandé de le faire tourner dans un conteneur Docker ou une VM séparée, que vous utilisiez un Proxy ou non.

Q : GLM-4.7-Flash étant gratuit, est-il suffisant pour faire tourner Claude Code en programmation ?

R : GLM-4.7-Flash obtient un score de 59,2 % sur SWE-bench, comparable au Claude 3.5 Sonnet des premières générations, et gère très bien les tâches de taille moyenne. Pour des refontes complexes touchant plusieurs fichiers, il est préférable de revenir à Claude Sonnet 5 ; pour la génération de code simple au quotidien, les explications et les corrections de bugs, GLM-Flash suffit largement, et gratuitement.

Q : Le Proxy conserve-t-il le contenu de mes requêtes ?

R : Par défaut, non. Seule l'activation d'un callback comme Langfuse / MLflow enregistre le contenu. Les données de consommation des clés virtuelles (nombre de tokens, coût) sont stockées dans PostgreSQL, mais elles n'incluent pas le contenu des requêtes lui-même.

Q : Peut-on déployer le Proxy dans le cloud pour que toute l'équipe l'utilise ?

R : Oui, c'est l'usage le plus typique du mode Proxy. Une fois déployé sur un serveur cloud, changez ANTHROPIC_BASE_URL=https://votre-domaine, ajoutez HTTPS (Nginx/Caddy) et un pare-feu. Distribuez à chacun une clé virtuelle, sans jamais avoir besoin de partager la clé API réelle.