LiteLLM¶

LiteLLM est un proxy open-source qui unifie l'accès à plusieurs APIs de LLM derrière une interface compatible OpenAI. Il est déployé sur le cluster de production pour centraliser et contrôler l'utilisation des modèles d'IA générative Scaleway par les applications.

Contexte et raison d'être¶

Scaleway ne fournit pas de mécanisme natif pour :

Restreindre l'accès aux APIs par application — toute application ayant la clé API Scaleway peut appeler n'importe quel modèle
Distinguer l'usage par application ou par environnement — impossible d'attribuer la consommation à un projet précis

LiteLLM répond à ces deux problèmes en jouant le rôle de proxy : chaque application reçoit sa propre clé API LiteLLM, avec les modèles autorisés explicitement définis. LiteLLM traçe l'usage par clé et transmet les requêtes à Scaleway avec la clé maître.

Architecture¶

Application (clé API LiteLLM propre à l'app)
    ↓ API compatible OpenAI
LiteLLM — cluster service, namespace litellm
    ↓ clé API maître Scaleway
Scaleway Generative APIs (modèles LLM)

Déploiement Terraform¶

Run Terraform	Rôle
`infrastructure/main-infra/scw-service/terraform/032.vault-secrets`	Création des chemins Vault qui accueilleront les clés (projets externes uniquement)
`infrastructure/main-infra/scw-service/terraform/080.litellm_installation`	Installation de LiteLLM sur le cluster
`infrastructure/main-infra/scw-service/terraform/081.litellm_configuration`	Configuration des modèles et des clés API par application

Mettre à jour la liste des modèles disponibles¶

La liste des modèles Scaleway disponibles est consultable ici : https://www.scaleway.com/fr/tarifs/model-as-a-service/

Elle est définie dans scw-init-config/001.config_infrastructure/terraform.tfvars sous la clé gen_apis_models_definition.

Après modification, appliquer le run 081.litellm_configuration.

Créer une clé API pour une application¶

Éditer scw-init-config/002.config_applications et définir :

generative_api_access à true
generative_api_models avec les modèles souhaités (issus de 001.config)

"app_name" = {
  project_name          = "app_name"
  generative_api_access = true
  generative_api_models = ["gpt-oss-120b", "mistral-small-3.2-24b-instruct-2506"]
}

Puis appliquer 081.litellm_configuration.

Cela crée automatiquement une entrée litellm_api_key dans Vault sous ademe/apps/<projet>/<env>, pour chaque environnement applicatif, à référencer dans les secrets du chart Helm de l'application.

Créer une clé API pour un projet externe¶

Un projet externe est un projet hébergé en dehors de l'infrastructure ADEME, auquel on ouvre l'accès aux services mutualisés — ici les APIs d'IA générative. Il n'a ni projet Scaleway, ni environnements int / rec / preprod / prod, ni arborescence ademe/apps/<projet> dans Vault. Il est donc déclaré à part, dans sa propre variable.

1. Déclarer le projet¶

Éditer scw-init-config/002.config_applications/terraform.tfvars, variable external_projects_config :

external_projects_config = {
  "geco" = {
    generative_api_access = true
    generative_api_models = ["gpt-oss-120b"]
  }
}

Contrairement à projects_config, il n'y a pas de clé project_name : la clé de la map fait office de nom de projet.

2. Appliquer les runs, dans l'ordre¶

# 002 : publie la config dans son state, lu par les deux runs suivants
cd infrastructure/main-infra/scw-init-config/002.config_applications && terraform apply

# 032 : crée le chemin Vault, vide
cd ../../scw-service/terraform/032.vault-secrets && terraform apply

# 081 : crée l'utilisateur LiteLLM et écrit la clé dans le chemin
cd ../081.litellm_configuration && terraform apply

032 avant 081

Le run 081 lit le chemin Vault avant de l'écrire, pour ne pas régénérer une clé déjà distribuée. Une lecture Vault sur un chemin inexistant échoue dès le plan : 032 doit donc être appliqué avant, une seule fois par projet externe.

Le run 032 crée le chemin avec une valeur vide et ignore ensuite son contenu (ignore_changes), ce qui lui évite d'écraser la clé écrite par 081 aux applies suivants. 081 conserve la clé déjà en place et n'en génère une nouvelle que si le chemin est vide — supprimer la valeur dans Vault est donc la façon de faire tourner une clé.

3. Récupérer la clé¶

	Applications internes	Projets externes
Déclaration	`projects_config`	`external_projects_config`
Nombre de clés	une par environnement	une seule
Utilisateur LiteLLM	`<env>-<projet>-user`	`ext-<projet>-user`
Chemin Vault	`ademe/apps/<projet>/<env>`	`ademe/external_apps/<projet>`
Accès Vault	`APPSVC-Reader` / `-Operator` / `-Admin`	`APPSVC-Admin` uniquement

Accès Vault volontairement restreint

Les policies APPSVC-Reader et APPSVC-Operator s'arrêtent au préfixe ademe/data/apps/* : elles ne couvrent pas ademe/external_apps/*. Seul APPSVC-Admin, dont la policy porte sur ademe/data/*, peut lire ces clés. C'est un choix : ces secrets ne sont consommés par aucun workload du cluster, ils sont transmis au tiers hors bande. Ouvrir l'accès aux autres rôles demanderait d'étendre le module scw-tf-modules/vault-oidc-global-policies.

Le préfixe external_apps étant hors de l'arborescence apps, il n'apparaît pas dans l'UI Vault pour les rôles non-admin.

Interface d'administration¶

L'UI LiteLLM est accessible à l'adresse : https://litellm.svc.ademe-scw.fr/ui/login/

La clé de connexion (master key) est stockée dans le secret Kubernetes litellm-masterkey-secret (namespace litellm).

TODO¶

Implémenter les budgets et quotas par application (ressource Terraform déjà présente sous forme commentée — la complexité réside dans la définition de la structure de données par utilisateur)