Pourquoi placer LiteLLM Proxy devant vos modèles
LiteLLM Proxy est une passerelle (ou gateway) LLM auto-hébergée. Elle expose un point d'entrée compatible avec l'API OpenAI, par exemple /v1/chat/completions, et traduit chaque requête vers le fournisseur de votre choix : un Ollama local, Mistral, OpenAI, Anthropic et d'autres. Vos applications, scripts et outils n'ont plus qu'une URL et un format à connaître.
Le proxy apporte surtout ce que les API brutes n'offrent pas : des clés virtuelles distribuées par équipe ou par projet, des budgets et limites de débit, et un seul endroit où vos vraies clés fournisseur sont stockées. Si vous avez lu nos guides sur OmniRoute, Ollama et Open WebUI, LiteLLM en est le complément naturel : Open WebUI et vos applications parlent au proxy, le proxy parle aux modèles.
Il faut un hôte que vous maîtrisez entièrement : Docker, un reverse proxy, un pare-feu. C'est le terrain d'un VPS Linux avec accès root. Un serveur VPS est une machine virtuelle isolée, créée par virtualisation sur un hôte physique partagé : vous y installez votre propre système (Debian ou Ubuntu), vos services et votre pare-feu. Un hébergement mutualisé ne le permet pas, car la configuration y est imposée par l'hébergeur.
Les termes à connaître
Quelques notions reviennent tout au long de ce guide. Elles sont générales et valables quel que soit le modèle que vous servez.
| Terme | Définition |
|---|---|
| Passerelle LLM | Service intermédiaire qui reçoit les requêtes des applications et les route vers un ou plusieurs modèles de langage. |
| API OpenAI (format) | Format de requête HTTP en JSON, devenu un standard de fait que la plupart des clients savent parler. |
| Serveur VPS | Machine virtuelle isolée sur un serveur physique partagé, administrable avec un accès root. |
| Virtualisation | Technique qui fait tourner plusieurs machines virtuelles sur un même matériel physique. |
| Hébergement mutualisé | Site ou service hébergé sur un serveur partagé entre plusieurs clients, avec une configuration imposée. |
| Reverse proxy | Serveur web qui reçoit les connexions publiques en HTTPS et les transmet au service interne. |
| Adresse IP publique | Adresse joignable depuis Internet, que le DNS associe à votre nom de domaine. |
| DNS | Système qui traduit un nom de domaine en adresse IP. Un enregistrement de type A relie le nom à l'adresse IPv4. |
| Pare-feu (firewall) | Filtre qui n'autorise que les ports et les sources prévus. |
| RAM | Mémoire vive du serveur. Le proxy et la base en consomment une part, et un modèle local en demande souvent beaucoup plus. |
| Bande passante | Volume de données transférable par seconde. Les réponses en streaming en consomment en continu. |
| Panel d'administration | Interface web (comme Plesk) qui gère services, domaines et certificats. Ce guide n'en utilise aucun : tout se fait en ligne de commande. |
| Infogérance | Prise en charge de l'administration courante du serveur par un prestataire. Ce guide suppose que vous administrez vous-même. |
D'abord la provenance : ne tirez pas n'importe quelle image
Avant la moindre commande, rappelons le contexte. Selon l'avis publié par LiteLLM, le 21 octobre 2026, la version 1.107.0 a été publiée sur PyPI avec du contenu malveillant, et des images Docker ont été touchées : sur Docker Hub, les tags v1.107.0, latest, main-latest et main-stable ; sur GHCR, les mêmes tags pour ghcr.io/berriai/litellm, litellm-database et litellm-non_root. Nous avons détaillé l'affaire dans notre article d'actualité. La leçon pour un admin : un tag mobile n'est pas une garantie.
Les quatre règles
- Source officielle uniquement :
ghcr.io/berriai/litellm-database(variante avec les composants base de données) oudocker.litellm.ai/berriai/litellm, cité par la documentation officielle. Aucune image d'un tiers. - Tag de version épinglé : jamais
latest,main-latestnimain-stable. Choisissez une version antérieure à la 1.107.0 ou postérieure à la remédiation, et lisez les avis avant de la retenir. - Digest contrôlé : un tag peut être repointé, un digest
sha256désigne un contenu précis. Relevez-le, notez-le, puis épinglez-le. - Signature vérifiée quand c'est possible, avec
cosign, selon la procédure de l'avis (clé publique dont l'empreinte est contrôlée, ou signature keyless pour les versions récentes).
Relever et comparer le digest
docker pull ghcr.io/berriai/litellm-database:<TAG_EPINGLE>
docker image inspect ghcr.io/berriai/litellm-database:<TAG_EPINGLE> \
--format '{{index .RepoDigests 0}}'
Comparez la valeur obtenue avec le digest affiché dans la page GHCR officielle du projet, puis écrivez-la dans votre compose : image: ghcr.io/berriai/litellm-database:<TAG>@sha256:<DIGEST>. Contrôlez aussi que le digest n'est pas celui de l'image compromise, sha256:1bbcb1443bc962e45f5aad53fe3d2c30600e0379715fb6c664cdd3ac126c339e (Docker Hub, d'après l'avis).
Vérifier la signature avec cosign
Pour les versions signées en keyless (à partir de la v1.111.0-dev.3 d'après l'avis), la vérification ressemble à ceci :
cosign verify \
--certificate-identity https://github.com/BerriAI/project-releaser/.github/workflows/release.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/berriai/litellm:<TAG>
Attention : l'avis précise que la version compromise portait aussi une signature valide de l'ancienne clé. Une signature ne remplace donc pas le contrôle du digest et de la version. Et si un de vos conteneurs a tourné avec l'image compromise, rotation immédiate des clés fournisseur, de la master key, des clés virtuelles et du mot de passe de la base, puis reconstruction.
Prérequis sur le VPS
- Un VPS Linux (Debian ou Ubuntu, par exemple) à jour, accès SSH par clé (voir sécuriser SSH).
- Docker et le plugin Compose, comme dans notre guide installer Docker sur un VPS.
- Un nom de domaine dont l'enregistrement DNS (zone A) pointe vers l'adresse IP publique du VPS, pour le HTTPS.
- De la RAM pour le proxy et PostgreSQL. Si Ollama tourne sur la même machine, le modèle dicte le dimensionnement : consultez la documentation de votre modèle pour sa RAM minimale, et prévoyez de la marge pour le système.
Docker Compose avec PostgreSQL
Créez un dossier de travail, puis un fichier .env avec des secrets aléatoires. La documentation officielle génère la master key et le salt ainsi :
mkdir -p /opt/litellm && cd /opt/litellm
printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\nPOSTGRES_PASSWORD=%s\n' \
"$(openssl rand -hex 32)" "$(openssl rand -hex 32)" "$(openssl rand -hex 24)" > .env
chmod 600 .env
Conservez le LITELLM_SALT_KEY : il chiffre les clés fournisseur enregistrées et la documentation indique qu'il n'y a pas de rotation sur place. Sauvegardez-le avec vos secrets, hors du VPS.
Voici un docker-compose.yml minimal. Il lie le proxy à la boucle locale et laisse PostgreSQL hors de tout réseau public :
services:
litellm:
image: ghcr.io/berriai/litellm-database:<TAG>@sha256:<DIGEST>
command: ["--config", "/app/config.yaml"]
restart: unless-stopped
ports:
- "127.0.0.1:4000:4000"
volumes:
- ./config.yaml:/app/config.yaml:ro
env_file: .env
environment:
DATABASE_URL: "postgresql://litellm:${POSTGRES_PASSWORD}@db:5432/litellm"
extra_hosts:
- "host.docker.internal:host-gateway"
depends_on:
- db
db:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_USER: litellm
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: litellm
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:
La base ne publie aucun port : seul le conteneur LiteLLM l'atteint par le réseau Compose. Pour aller plus loin sur ce volet, voyez sécuriser PostgreSQL et Docker Compose sur VPS. Épinglez aussi l'image PostgreSQL à une version majeure précise de votre choix.
Configurer les modèles dans config.yaml
Le fichier config.yaml déclare une liste de modèles. Chaque entrée associe un model_name, le nom que verront vos clients, à des litellm_params : le fournisseur et le modèle réel, avec la clé lue dans l'environnement via os.environ/NOM.
model_list:
- model_name: local-llama
litellm_params:
model: ollama_chat/<MODELE_OLLAMA>
api_base: http://host.docker.internal:11434
- model_name: mistral-large
litellm_params:
model: mistral/mistral-large-latest
api_key: os.environ/MISTRAL_API_KEY
- model_name: openai-chat
litellm_params:
model: openai/<MODELE_OPENAI>
api_key: os.environ/OPENAI_API_KEY
- model_name: claude
litellm_params:
model: anthropic/<MODELE_ANTHROPIC>
api_key: os.environ/ANTHROPIC_API_KEY
Remplacez les noms entre chevrons par ceux de la liste du fournisseur, qui change régulièrement. Ajoutez MISTRAL_API_KEY, OPENAI_API_KEY et ANTHROPIC_API_KEY dans le .env. Le préfixe ollama_chat/ est celui que la documentation utilise pour Ollama.
Joindre Ollama depuis le conteneur
Le localhost d'un conteneur n'est pas celui du VPS. Avec host.docker.internal et la ligne extra_hosts ci-dessus, le conteneur atteint l'hôte. Reste un point : Ollama écoute par défaut sur 127.0.0.1 et ne sera pas joignable depuis le réseau Docker. Deux solutions propres : faire écouter Ollama sur l'adresse du pont Docker uniquement et filtrer le port 11434 avec le pare-feu, ou lancer Ollama dans le même compose et viser http://ollama:11434. N'ouvrez jamais 11434 sur Internet : Ollama n'a pas d'authentification. Le guide gérer les modèles Ollama détaille le reste.
Plusieurs modèles sous un même nom
Plusieurs entrées peuvent partager le même model_name. LiteLLM répartit alors les requêtes entre elles, ce qui sert à doubler un modèle local par un modèle cloud ou à répartir la charge entre deux clés. Consultez la section routage de la documentation pour les stratégies disponibles avant de vous y fier en production.
Démarrer et tester
docker compose up -d
docker compose logs -f litellm
Testez avec la master key, en local sur le VPS :
curl http://127.0.0.1:4000/v1/chat/completions \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"local-llama","messages":[{"role":"user","content":"Dis bonjour en une phrase."}]}'
L'interface d'administration est servie sur /ui (identifiant admin, mot de passe : la master key d'après la documentation). Traitez-la comme un accès administrateur complet du proxy.
Clés virtuelles, équipes et budgets
La master key ne doit servir qu'à administrer. Aux applications et aux équipes, on remet des clés virtuelles générées par l'API, qui exigent la base PostgreSQL. Vos vraies clés fournisseur ne quittent jamais le serveur.
Créer une équipe
curl -X POST http://127.0.0.1:4000/team/new \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H "Content-Type: application/json" \
-d '{"team_alias": "equipe-support"}'
La réponse contient un team_id.
Générer une clé avec modèles, budget et limites
curl -X POST http://127.0.0.1:4000/key/generate \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"team_id": "<TEAM_ID>",
"models": ["local-llama", "mistral-large"],
"max_budget": 20,
"budget_duration": "30d",
"rpm_limit": 60,
"tpm_limit": 100000
}'
Ces champs figurent dans la documentation des clés virtuelles : models restreint les modèles accessibles, max_budget plafonne la dépense, budget_duration la remet à zéro à intervalle donné, rpm_limit et tpm_limit limitent requêtes et jetons. Un budget n'a de sens que si le modèle a un tarif connu : un Ollama local ne coûte rien à LiteLLM, il ne consomme donc pas le budget. Pour des plafonds portés par l'équipe elle-même, consultez la documentation « teams » de votre version : les champs acceptés par /team/new dépendent de la version.
| Élément | Rôle | Où le définir |
|---|---|---|
| Master key | Administration du proxy | .env, jamais distribuée |
| Clé virtuelle | Accès d'une appli ou d'une personne | /key/generate |
| Équipe | Regrouper des clés | /team/new |
| Budget | Plafond de dépense par période | max_budget, budget_duration |
| Limites | Débit par minute | rpm_limit, tpm_limit |
Une clé sans max_budget n'a aucun plafond de dépense : elle est illimitée sur ce point. Pour les clés distribuées à des tiers, fixez toujours un budget et des limites.
Reverse proxy HTTPS
Le port 4000 est lié à 127.0.0.1 : il faut un serveur web faisant office de reverse proxy pour servir l'API. Avec Nginx et un certificat Let's Encrypt (voir Nginx en reverse proxy et Certbot) :
server {
listen 443 ssl;
server_name llm.exemple.fr;
ssl_certificate /etc/letsencrypt/live/llm.exemple.fr/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/llm.exemple.fr/privkey.pem;
location / {
proxy_pass http://127.0.0.1:4000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_buffering off;
proxy_read_timeout 300s;
}
}
proxy_buffering off et un délai de lecture long évitent de couper les réponses en streaming. Avec Apache à la place de Nginx, la logique est la même, avec les modules mod_proxy, mod_proxy_http et mod_ssl. Pour un tour d'horizon complet, voir publier un service en HTTPS.
Côté pare-feu (firewall), n'ouvrez que les ports 22, 80 et 443 : UFW, interface simplifiée d'iptables, suffit pour cela (UFW). Une passerelle d'IA exposée sans protection est une cible : en novembre dernier, une faille d'accès administrateur derrière un reverse proxy a touché un autre outil IA, voir cet article. Si l'interface d'administration n'a pas à être publique, limitez /ui à vos adresses IP ou passez par un réseau privé.
Brancher Open WebUI et vos applications
Dans Open WebUI, ajoutez une connexion de type API OpenAI avec l'URL https://llm.exemple.fr/v1 et une clé virtuelle. Tous les modèles autorisés par cette clé apparaissent dans la liste. N'importe quel client OpenAI fait de même : il suffit de changer la base URL et la clé.
Maintenance et mises à jour
- Mise à jour volontaire : changez le tag et le digest dans le compose, relisez les notes de version et les avis de sécurité, puis
docker compose pull && docker compose up -d. - Sauvegardes (backup) : la base contient équipes, clés et dépenses. Faites un dump régulier (même logique que mysqldump avec
pg_dump) et stockez-le hors du VPS, par exemple sur un NAS ou un stockage distant, chiffré. Les sauvegardes ElypseCloud sont une option : à activer séparément. - Nettoyage : les anciennes images s'accumulent, voir nettoyer Docker.
- Surveillance : suivez les logs du conteneur et les dépenses par clé, et alertez sur les pics d'usage.
Plusieurs serveurs et haute disponibilité
Pour la plupart des équipes, un seul VPS suffit. Si la passerelle devient un point critique, la haute disponibilité vise à éviter qu'une panne unique coupe tout le service : plusieurs instances du proxy, un répartiteur de charge devant elles et une base PostgreSQL centralisée, et non une base par serveur. Un cluster regroupe ces machines. Il ajoute de la complexité, à n'envisager que si le besoin est réel.
Toutes les instances doivent partager les mêmes configurations (config.yaml et .env identiques). Les dumps de la base se rangent sur un NAS ou un stockage distant, pas sur le même disque que la base. Vérifiez dans la documentation de votre version ce qui est supporté en réplication avant de l'adopter.
Checklist avant mise en ligne
- Image officielle, tag épinglé, digest comparé et différent de celui de l'image compromise.
- Master key et salt aléatoires,
.envenchmod 600, salt sauvegardé hors du VPS. - PostgreSQL sans port publié.
- Proxy lié à
127.0.0.1, HTTPS via reverse proxy, pare-feu actif. - Ollama non exposé sur Internet.
- Une clé virtuelle par application ou équipe, avec modèles, budget et limites.
Pour héberger l'ensemble sur votre propre machine, avec les droits root que ces composants demandent, regardez nos VPS Linux ou, pour des modèles plus lourds sur CPU, un serveur dédié.
FiveM
Minecraft
Rust
RedM
Hytale