Passerelle LiteLLM (litellm)

Passerelle de modèles compatible OpenAI devant les fournisseurs (fournisseurs cloud, moteurs vLLM et Ollama installés par le Manager, enregistrés automatiquement par les liaisons vllm et ollama, et points d'accès existants déclarés comme fournisseurs LiteLLM) : routage, répartition entre répliques, repli, cache Redis et suivi des dépenses. Les identifiants des fournisseurs restent dans ses fichiers sensibles et n'atteignent jamais les agents.

Généré depuis catalog/services/litellm.yaml : ne pas modifier à la main.

Résumé

Version	1.106.5
Usage	installer et configurer, configurer et connecter
Couche	fonctionnelle (catalogue IA)
Catégorie	Passerelles et répartition de charge
Méthodes d'installation	python
Connexion externe	non
Réservé au bac à sable	non

Licence

Identifiant SPDX	MIT
Politique de licence	licence socle (MIT ou Apache-2.0)
Exception de licence	-
Remarque de licence	Cœur MIT uniquement. Le Manager installe litellm sans son extra proxy, qui exige le paquet propriétaire litellm-enterprise (LicenseRef-Proprietary), et ajoute une à une les autres dépendances de cet extra : le proxy et son routeur fonctionnent sans lui. Les fonctions LiteLLM Enterprise (répertoire enterprise/ et paquet litellm-enterprise : SSO de l'interface d'administration, journaux d'audit, garde-fous et budgets avancés, mode d'arrière-plan de l'API Responses) sont sous licence commerciale et ne sont ni installées ni configurées. Pas de méthode podman : l'image officielle ghcr.io/berriai/litellm installe l'extra proxy, donc litellm-enterprise, et copie le répertoire enterprise/.
Composant de la plateforme	litellm

Paquets et artefacts

Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.

Type	Paquet	Version	Licence	Détails
paquet Python	litellm	1.106.5	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	gunicorn	>=23.0.0,<24.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	uvicorn	>=0.33.0,<1.0 (plage)	BSD-3-Clause	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	granian	>=2.7.4,<3.0 (plage)	BSD-3-Clause	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	uvloop	>=0.22.1,<1.0 (plage)	MIT OR Apache-2.0	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	fastapi	>=0.136.3,<1.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	starlette	>=1.0.1,<2.0 (plage)	BSD-3-Clause	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	backoff	>=2.2.1,<3.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	pyyaml	>=6.0.3,<7.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	rq	>=2.7.0,<3.0 (plage)	BSD-2-Clause	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	orjson	>=3.11.6,<4.0 (plage)	MPL-2.0 AND (Apache-2.0 OR MIT)	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	hiredis	>=3.0.0,<4.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	apscheduler	>=3.11.2,<4.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	fastapi-sso	>=0.19.0,<1.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	pyjwt	>=2.13.0,<3.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	python-multipart	>=0.0.27,<1.0 (plage)	Apache-2.0	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	cryptography	>=49.0.0,<51.0 (plage)	Apache-2.0 OR BSD-3-Clause	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	pynacl	>=1.6.2,<2.0 (plage)	Apache-2.0	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	websockets	>=15.0.1,<16.0 (plage)	BSD-3-Clause	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	boto3	>=1.43.117,<2.0 (plage)	Apache-2.0	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	azure-identity	>=1.25.2,<2.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	azure-storage-blob	>=12.28.0,<13.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	mcp	>=2.2.0,<3 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	httpx2	>=2.5.0,<3 (plage)	BSD-3-Clause	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	pydantic	>=2.12.0,<3 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	litellm-proxy-extras	0.4.108	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	restrictedpython	>=8.5,<9.0 (plage)	ZPL-2.1	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	rich	>=13.9.4,<14.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	inquirerpy	>=0.3.4,<1.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	tomlkit	>=0.13.3,<1.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	polars	>=1.38.1,<2.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	soundfile	>=0.12.1,<1.0 (plage)	BSD-3-Clause	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	pyroscope-io	>=0.8.16,<1.0 (plage)	Apache-2.0	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	expression	>=5.6.0,<6.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	prisma	>=0.11 (plage)	Apache-2.0	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	opik	>=1.0 (plage)	Apache-2.0	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	opentelemetry-exporter-otlp-proto-http	>=1.25 (plage)	Apache-2.0	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10
paquet Python	prometheus_client	>=0.20,<1.0 (plage)	MIT	interpréteurs, par ordre de préférence python3.12, python3.11, python3.10

Systèmes et architectures pris en charge

Méthode	Systèmes d'exploitation	Architectures
python	famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman)	x86_64, aarch64 (non restreintes par le descripteur)

Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.

Prérequis

Hôte

• au moins 2048 Mo de mémoire (bloquant, memory).

Réseau et ports

Composant	Nom du port	Port	Ouvert dans le pare-feu de l'hôte
litellm-proxy	api	4000/tcp	oui

Services et connexions nécessaires

• database : postgresql.
• cache : redis (facultative).
• vllm : vllm (facultative).
• ollama : ollama (facultative).
• opik : opik (facultative).
• otel : otel-collector (facultative).

Détail et résolution : voir Dépendances.

Méthodes et modes d'installation

Méthode	Défaut	Ce que la méthode utilise
python	oui	un environnement virtuel Python qui contient les paquets Python du descripteur

Composants

Composant	Type	Méthodes d'installation	Ports
Proxy LiteLLM (litellm-proxy)	maître	python	4000/tcp

Proxy unique (single) (par défaut)

Une seule instance du proxy.

Ce que le mode déploie :

Composant	Placement
litellm-proxy	min 1, max 1

Répliqué (replicated)

Plusieurs proxys derrière HAProxy, qui partagent la base et le cache Redis.

Ce que le mode déploie :

Composant	Placement
litellm-proxy	min 2, recommandé 3

Installer ce service

L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.

1. Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.

2. Choisissez le service. À l'étape Service, sélectionnez Passerelle LiteLLM. La carte affiche la licence MIT et les dépendances dont l'installation a besoin.

3. Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode : single (par défaut), replicated. Chaque mode déploie les composants listés dans Méthodes et modes d'installation.

4. Liez les dépendances. À l'étape Liaisons, choisissez pour chaque dépendance (database, cache, vllm, ollama, opik, otel) Installer avec la plateforme ou Utiliser une connexion existante ; une dépendance facultative peut rester sur Aucune liaison.

5. Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration). Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.

6. Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.

7. Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services.

Connecter un service existant

Schémas	https, http
Port par défaut	4000
Authentification	obligatoire
Contrôle de santé	/health/liveliness

Méthode d'authentification	Champs	Description
bearer	token	Clé maître ou clé virtuelle (sk-...), envoyée en Authorization: Bearer.

Documentation officielle : https://docs.litellm.ai/docs/proxy/virtual_keys

Haute disponibilité

Cluster	réplicas (replication)
Haute disponibilité	externe (external)
Bascule	répartiteur (load-balancer)
Réplication	stockage partagé (shared-store)
Quorum	aucun (none)
Découverte	aucun (none)
Point d'entrée	répartiteur (load-balancer)
Documentation officielle	https://docs.litellm.ai/docs/proxy/prod

Prérequis

Prérequis	Doit être hautement disponible	Modes	Description
database	oui	modes de niveau ha ou cluster	PostgreSQL hautement disponible (clés, budgets, dépenses).
cache	oui	replicated	Redis hautement disponible, obligatoire avec plusieurs instances (limites et cache partagés).

Topologie par mode

Modes	Niveau le plus haut du catalogue	Répartition	Composant du quorum	Domaines de panne	Description
single	autonome (standalone)	unique (single)	-	1	Une instance, sans tolérance aux pannes.
replicated	ha (ha)	actif-actif (active-active)	-	2	Plusieurs proxys derrière HAProxy, partageant PostgreSQL et le cache Redis.

Remarques

• Redis n'est plus facultatif avec plusieurs instances : sans lui les limites de débit et les budgets sont comptés par instance.
• Avec TLS, le HAProxy devant les proxys répliqués doit aussi les joindre en TLS (serveurs de backend avec ssl et l'autorité du Manager comme ca-file), ou laisser passer le flux TLS en mode tcp.

Paramètres de configuration

Réseau

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Port de l'API (port)	port	4000	-	non	non	oui	Port de l'API du proxy (derrière HAProxy en mode répliqué).
TLS (tls_enabled)	bool	false	-	non	non	oui	Servir l'API du proxy, la console d'administration /ui et /metrics/ en TLS avec le certificat que le Manager émet pour chaque hôte depuis son autorité (SSL_CERTFILE_PATH et SSL_KEYFILE_PATH du proxy) ; la liaison de ses consommateurs passe alors en https. Indépendamment de ce paramètre, LiteLLM appelle en https chaque moteur du Manager dont la liaison est en https (vLLM avec son paramètre TLS) et vérifie son certificat avec l'autorité du Manager.
Processus de travail (workers)	int	4	min 1, max 64	non	non	oui	Processus de travail uvicorn du proxy. (recommandé clamp(host.cpu_count, 1, 16))

Modèles et routage

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Liste de modèles (model_list)	json	[]	-	non	non	non	model_list de la configuration LiteLLM (JSON) ; les secrets uniquement sous forme de références os.environ/NOM vers les identifiants des fournisseurs.
Réglages du routeur (router_settings)	json	{"routing_strategy": "simple-shuffle", "num_retries": 2, "timeout": 120, "allowed_fails": 3, "cooldown_time": 60}	-	non	non	non	router_settings de la configuration (replis, nouvelles tentatives, délais).
Délai des requêtes (request_timeout)	int	120	min 5, max 3600	non	non	non	Secondes avant l'abandon d'un appel à un fournisseur.

Sécurité

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Clé maîtresse (master_key)	password	généré	-	non	oui	non	Clé d'administration du proxy (EAI_LITELLM_MASTER_KEY du Control Plane uniquement) ; préfixée par sk-.
Clé des consommateurs (consumer_key)	password	généré	-	non	oui	non	Clé virtuelle non administrative navin-consumers (préfixée par sk-), enregistrée par le nœud au démarrage par POST /key/generate (routes LLM et modèles de model_list seulement) et publiée aux consommateurs par la liaison api ; jamais égale à la clé maîtresse. Clé partagée : la consommation n'est pas suivie par service consommateur.
Clé de salage (salt_key)	password	généré	-	non	oui	non	Clé de chiffrement des identifiants stockés en base (ne jamais la changer après le premier démarrage).
Utilisateur de la console d'administration (ui_username)	string	admin	^[A-Za-z0-9_.@-]{3,64}$	non	non	non	Identifiant de la console d'administration /ui (UI_USERNAME).
Mot de passe de la console d'administration (ui_password)	password	généré	-	non	oui	non	Mot de passe de la console d'administration /ui (UI_PASSWORD), généré à chaque installation et conservé dans le coffre du Manager.
Identifiants des fournisseurs (provider_env)	json	{}	-	non	oui	non	Table NOM: valeur des identifiants et points d'accès des fournisseurs référencés par os.environ/NOM, par exemple VLLM_API_BASE et VLLM_API_KEY d'un serveur vLLM existant ou OLLAMA_API_BASE d'un serveur Ollama existant (écrite dans le fichier sensible providers.yaml, 0640).

Observabilité

Paramètre	Type	Défaut	Valeurs permises	Obligatoire	Secret	Redémarrage	Description
Projet Opik (opik_project)	string	navin-gateway	-	non	non	non	Projet Opik des traces (quand il est lié).
Niveau de journalisation (log_level)	enum	INFO	DEBUG, INFO, WARNING, ERROR	non	non	non	Verbosité du journal du proxy.

Dépendances

Pour chaque dépendance active, le Manager prend la première solution parmi : la liaison choisie dans l'assistant ; un service de la même installation qui la fournit ; un service déjà installé dans le cluster ; la seule connexion du type attendu. Sinon, une dépendance facultative reste non liée, et une dépendance obligatoire est ajoutée à l'installation dans son mode par défaut (la colonne ci-dessous nomme le service du catalogue ajouté).

Liaison	Fournie par	Type de connexion	Point d'accès	Facultative	Quand rien n'est lié	Description
database	postgresql	postgresql	sql	non	postgresql est ajouté à l'installation	Base des clés virtuelles, des journaux de dépenses et des équipes.
cache	redis	redis	redis	oui	reste non liée (facultative)	Cache des réponses et état du routeur partagés par les répliques.
vllm	vllm	-	api	oui	reste non liée (facultative)	Moteur vLLM géré : une entrée hosted_vllm par instance sous le nom du modèle servi (LiteLLM répartit entre les répliques) ; sa clé d'API reste dans l'environnement du proxy.
ollama	ollama	-	api	oui	reste non liée (facultative)	Moteur Ollama géré : une entrée ollama_chat par modèle publié et par instance.
opik	opik	-	api	oui	reste non liée (facultative)	Traçage des appels LLM dans Opik.
otel	otel-collector	-	otlp_http	oui	reste non liée (facultative)	Traces OpenTelemetry (OTLP sur HTTP).

Points d'accès

Point d'accès	Schéma	Composant	Port	Chemin	Paramètre TLS	Paramètres de liaison	Secrets de liaison	Commande de provisionnement
api	http	litellm-proxy	4000 (port)	-	tls_enabled	-	token	-
admin	http	litellm-proxy	4000 (port)	-	tls_enabled	-	token	-

Fichiers de configuration client

Fichiers rendus pour le téléchargement de la configuration client :

• litellm.env (client.env.j2)

Commandes

Commande	Composant	Cible	Description
Disponibilité (readiness)	litellm-proxy	tous les hôtes	Vérifie les connexions à la base et au cache de chaque proxy.
Journaux récents (logs)	litellm-proxy	hôte choisi	Dernières lignes du journal du proxy.

Contrôles de santé

Vivacité (par instance)

Composant	Contrôle	Détails
litellm-proxy	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.port }}/health/liveliness	Attendu 200 ; 60 tentatives ; intervalle 2 s ; délai 5 s
litellm-proxy	{{ paths.opt }}/venv/bin/python {{ paths.etc }}/register.py --check --env {{ paths.etc }}/consumer-key.env	60 tentatives ; intervalle 3 s ; délai 30 s

Disponibilité (contrôle du service)

Contrôle	Détails
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.port }}/health/readiness	Attendu 200 ; 10 tentatives ; intervalle 3 s ; délai 10 s

Contrôles préalables

Contrôle	Type	Signification	Sévérité	Composants
memory	memory_mb {"min": 2048}	au moins 2048 Mo de mémoire	bloquant	tous les composants
api_port_free	port_free {"param": "port"}	port 4000 libre sur l'hôte	bloquant	tous les composants

Désinstallation

Chemins supprimés quand les données sont purgées : {{ paths.log }}.

Liens rapides

• Console d'administration : {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/ui
• Métriques : {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/metrics/

Documentation amont

• Site : https://docs.litellm.ai
• Sources : https://github.com/BerriAI/litellm
• Haute disponibilité : https://docs.litellm.ai/docs/proxy/prod
• Authentification : https://docs.litellm.ai/docs/proxy/virtual_keys