Multi-locataire Passerelle IA Espaces d'équipe RBAC Isolation de facturation

Architecture de passerelle LLM multi-locataires pour les équipes

Concevez des passerelles LLM multi-locataires avec espaces d'équipe, clés projet, quotas isolés, journaux d'usage et propriété des médias sans exposer les identifiants.

AveMujica API 15 juil. 2026 11 min de lecture

Une passerelle LLM multi-locataires est un plan de contrôle qui permet à plusieurs équipes, projets et applications de partager un point d'entrée compatible OpenAI tout en séparant les identifiants, les quotas, l'usage et la propriété des médias. Le problème d'architecture ne consiste pas à « ajouter une colonne tenant_id ». Chaque requête doit répondre de façon cohérente à quatre questions : qui appelle, qui paie, quels modèles sont autorisés et quels artefacts pourront ensuite être consultés. Cet article transpose ces questions en modèles de passerelle concrets, notamment les espaces d'équipe, les clés limitées à un projet, les portées de rate limiting et l'isolation des médias pour les tâches d'image et de vidéo.

Pourquoi le multi-locataire apparaît après le premier succès en production

Les premiers déploiements commencent souvent avec une clé d'administration et un canal fournisseur. Cela fonctionne jusqu'à ce que :

les équipes produit, recherche et support partagent le même budget
des prestataires aient besoin d'un accès temporaire aux modèles sans voir les secrets de l'organisation
la finance demande quel projet a généré la facture du mois précédent
l'URL d'une vidéo générée ne doive pas être téléchargeable par une équipe sœur
un agent trop bruyant épuise les rate limits de tous les autres

À ce stade, les frontières de tenancy doivent être appliquées dans la passerelle, pas seulement dans le code applicatif. Les limites souples côté application sont utiles, mais elles n'empêchent ni une clé divulguée ni un worker mal configuré de facturer le mauvais propriétaire. Une passerelle LLM multi-fournisseurs sans isolation des locataires finit par devenir une infrastructure partagée avec un rayon d'impact partagé. Comparez-la au simple reverse proxy de LLM proxy ou passerelle IA : le proxy transmet, tandis que la passerelle multi-locataires autorise et comptabilise.

Modèle de tenancy central : propriétaire, acteur et portée

Conservez trois identités distinctes sur chaque requête :

Acteur — la personne ou l'identité de service qui a initié l'appel.
Propriétaire de facturation — le portefeuille dont le quota est débité lors du règlement.
Portée d'accès — l'équipe ou le projet, ou l'espace personnel, qui délimite les clés, les modèles et les artefacts.

Dans les systèmes structurés comme ce dépôt, les tokens personnels facturent généralement un propriétaire utilisateur, tandis que les tokens d'équipe associent une équipe et un projet et résolvent la facturation vers le portefeuille de l'équipe. Le middleware doit refuser les tokens d'équipe lorsque les espaces d'équipe sont désactivés, lorsque le projet est inactif ou lorsque l'acteur ne possède pas l'action requise pour ce projet. Cette vérification appartient au chemin critique, avant la distribution vers un canal.

Client / agent
   |  Bearer sk-...
   v
Auth middleware
   - resolve token -> user, team_id, project_id, owner_type
   - validate membership + project action grants
   v
Policy + rate-limit scope
   - team:project:user (or personal user scope)
   - model allowlists / group grants
   v
Relay / task submit
   - upstream channel selection
   - pre-consume quota against billing owner
   v
Usage log + optional media persistence
   - store actor, team, project, billing owner
   - authorize later content proxy by same scope

Si l'acteur et le propriétaire de facturation sont fusionnés dans un seul champ, vous ne pouvez plus distinguer « qui a dépensé le budget de l'équipe » de « qui a lancé la génération ». Si la portée n'est qu'une étiquette dans les journaux, l'autorisation de /v1/videos/{id}/content laissera fuiter des ressources entre locataires.

Surfaces de tenancy qui doivent rester alignées

1. Clés API et association au projet

Émettez les clés comme de véritables objets de tenancy :

des clés personnelles pour les environnements individuels
des clés d'équipe liées à team_id + project_id
des autorisations facultatives de groupe ou de modèle limitant les alias stables de la passerelle que la clé peut appeler

Les alias stables, par exemple gpt-image-2 ou un alias produit video-default, doivent être associés aux ID de modèles upstream dans la configuration des canaux. Les clients conservent l'alias ; les opérateurs font évoluer les ID bruts des fournisseurs sans réécrire chaque service. N'intégrez jamais les secrets des fournisseurs dans les environnements clients. Les clients s'authentifient uniquement auprès de la passerelle ; les canaux détiennent les identifiants des fournisseurs. Appliquez la même discipline d'isolation au RBAC pour l'accès aux API IA dans les produits utilisés par plusieurs équipes.

2. Quotas et sécurité de la pré-consommation

La sécurité de facturation est un sujet de tenancy. Pré-consommez le quota du propriétaire de facturation avant un travail coûteux, puis réglez ou remboursez après la réponse upstream. Pour les multiplicateurs médias comme le nombre d'images n ou la durée vidéo, imposez des limites strictes lors de la validation afin qu'un client hostile ou défectueux ne fasse pas déborder le calcul de quota vers une charge négative. Dans ce code, le nombre d'images est plafonné (MaxImageN = 128) et la durée vidéo est plafonnée (MaxTaskDurationSeconds). Les systèmes multi-locataires doivent conserver ces gardes globales, même si les politiques d'équipe ajoutent des budgets de projet plus stricts.

3. Rate limits avec clés de portée composites

Une clé de portée utile ressemble à team:{id}:project:{id}:user:{id} pour le trafic d'équipe, et à une clé utilisateur seule pour le trafic personnel. Cela empêche une tempête d'agents d'un projet de priver un autre projet de capacité de chat. Gardez la décision de limitation indépendante de la sélection du canal : une équipe peut être autorisée à utiliser un modèle tout en restant limitée.

4. Journaux d'usage comme surface d'audit

Chaque appel réglé doit conserver l'acteur, le propriétaire de facturation, l'équipe et le projet lorsqu'ils existent, l'alias de modèle, l'ID de requête et les multiplicateurs médias (n, secondes, taille). La finance comme la sécurité ont besoin de ces champs. Les vues d'usage destinées au produit sont des surfaces de console authentifiées ; la documentation publique doit expliquer le modèle d'audit plutôt que de renvoyer sans cesse vers des routes privées de la console.

5. La propriété des médias n'est pas une métadonnée facultative

Les artefacts image et vidéo survivent à la requête HTTP. Traitez les clés d'objet et les ID de tâche comme des ressources de locataire :

Surface	Portée dans ce dépôt (à vérifier avant toute affirmation)	Règle de propriété
UI/API de l'atelier image	Portée personnelle/session/token sous `/api/user/image-workbench` et variantes par clé API ; les clés d'objet appartiennent à l'utilisateur	Il n'existe actuellement aucune route d'atelier image par équipe/projet
UI/API de l'atelier vidéo	Portée personnelle sous `/api/user/video-workbench` et portée équipe/projet sous `/api/teams/:team_id/video-workbench`	Les exécutions et ressources d'équipe sont autorisées par les droits équipe + projet
Entrée image compatible OpenAI	`POST /v1/images/generations`, `POST /v1/images/edits`	Facturez le propriétaire associé au token ; n'inventez pas un historique d'équipe sans le persister vous-même
Entrée vidéo compatible OpenAI	`POST /v1/videos`, récupération, contenu ; le remix est toujours enregistré	Le GET de contenu doit revérifier le même propriétaire ou la même portée que lors de la création de la tâche

Les URL des fournisseurs expirent souvent. Une passerelle qui persiste les objets dans un stockage privé et les ressert via un proxy autorisé réduit les liens cassés et les expositions publiques accidentelles. Lorsqu'un atelier exige un object storage, échouez de manière fermée si celui-ci est mal configuré, au lieu de renvoyer une URL temporaire sans portée.

Liste de contrôle d'isolation avant d'intégrer une deuxième équipe

Utilisez cette liste comme gate de livraison, pas comme diapositive :

Frontière	Critère de réussite
Auth	Un token d'équipe échoue pour un membre supprimé ou un projet désactivé
Facturation	Une tâche d'équipe ne débite jamais un portefeuille personnel, et inversement
Modèles	Un projet sans autorisation ne peut pas appeler les alias restreints
Journaux	Une requête de journaux inter-équipes renvoie vide ou refusé, jamais des lignes partielles
Médias	Le proxy de contenu vidéo refuse les ID de tâches d'une autre équipe comme introuvables ou interdits
Rate limit	La charge du projet A ne consomme pas le token bucket du projet B
Administration	Les actions du super-administrateur sont auditées séparément de celles des administrateurs de locataire

Les tests automatisés doivent couvrir les refus, pas uniquement le happy path. Les défauts multi-locataires se cachent dans les décisions de « soft 404 » : renvoyer 404 pour une ressource étrangère est souvent préférable à 403 lorsque son existence elle-même est sensible.

Chemin de requête de référence pour un chat limité à une équipe

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $TEAM_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_STABLE_CHAT_ALIAS",
    "messages": [
      {"role": "user", "content": "Summarize yesterday deploy risk for project alpha."}
    ],
    "max_tokens": 400
  }'

La passerelle doit effectuer les opérations internes suivantes :

Authentifier la clé et résoudre team_id / project_id.
Confirmer que l'acteur peut utiliser un token de projet pour ce projet.
Résoudre l'alias de modèle dans l'ensemble de groupes et de canaux autorisés.
Pré-consommer le quota estimé du propriétaire de facturation de l'équipe.
Relayer la requête upstream et écrire un journal de consommation avec les champs acteur + propriétaire.
Exposer les mêmes identifiants dans les vues d'usage authentifiées destinées à la finance et au support.

Médias sous les mêmes règles de token, avec des portées d'atelier différentes

Les endpoint médias ne doivent pas inventer un second système d'authentification pour la facturation. Pour l'entrée compatible OpenAI, préférez les mêmes règles de token et de session :

# Image generation through OpenAI-compatible ingress (GPT Image returns b64_json)
curl https://your-gateway.example.com/v1/images/generations \
  -H "Authorization: Bearer $TEAM_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Product hero shot on matte black pedestal, studio light",
    "size": "1024x1024",
    "n": 1,
    "output_format": "png"
  }'

# Async video job (evaluate Sora 2 only with the official deprecation timeline in mind)
curl https://your-gateway.example.com/v1/videos \
  -H "Authorization: Bearer $TEAM_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_STABLE_VIDEO_ALIAS",
    "prompt": "Slow orbit around a ceramic mug on a wood table",
    "seconds": "4",
    "size": "1280x720"
  }'

Les interfaces d'atelier ont des portées différentes :

L'atelier image est une surface opérateur personnelle : presets, exécutions et ressources appartiennent à l'utilisateur. N'affirmez pas qu'il existe un historique image d'équipe ou des routes /api/teams/:team_id/image-workbench si vous ne les avez pas implémentés.
L'atelier vidéo prend en charge les portées personnelle et équipe/projet. Associez les capacités de génération et de gestion des ressources aux actions d'équipe, et conservez l'historique des exécutions dans le projet lorsque la session est liée à une équipe.

Les endpoint de nouvelle persistance après échec ne doivent pas réattribuer une ressource à un autre propriétaire. Pour un nouveau projet vidéo, privilégiez les fournisseurs et adaptateurs de passerelle que vous pourrez encore prendre en charge après l'arrêt de l'API Videos d'OpenAI / Sora 2 le 2026-09-24 (dépréciations OpenAI). Si vous transportez encore du trafic Sora, planifiez dès maintenant la migration du stockage des tâches et des chemins de code clients.

Couches de politique évolutives sans réécriture des clients

Empilez les politiques de la plus générale à la plus précise :

Valeurs par défaut de la plateforme — n maximal pour les images, durée vidéo maximale, modèles bloqués.
Politique d'équipe — groupes autorisés, alertes de budget, feature flags.
Autorisations de projet — membres autorisés à générer des médias ou à gérer les ressources vidéo.
Contraintes de clé — listes d'IP autorisées, expiration, sous-ensemble de modèles.
Limites d'exécution — RPM/TPM et plafonds de tâches simultanées.

Les clients continuent d'appeler /v1/*. Les opérateurs modifient les politiques dans la configuration d'administration et les correspondances de modèles des canaux. C'est le bénéfice opérationnel d'une passerelle API compatible OpenAI.

Modes de défaillance propres aux passerelles multi-locataires

Repli silencieux du propriétaire : si la résolution d'équipe échoue, ne facturez pas le portefeuille personnel de l'acteur « pour aider ». Refusez la requête.
Affinité de canal partagée sans étiquette d'isolation : les clés de cache doivent inclure la portée du locataire, sinon l'état de routage sticky sera mélangé.
Supposer que l'atelier image connaît les équipes : les ressources image personnelles appartenant à l'utilisateur ne sont pas équivalentes aux projets vidéo d'équipe.
Rétention de journaux ignorant les frontières juridiques : la sortie d'une équipe peut exiger une suppression sélective ; concevez les tâches de rétention avec des filtres de propriétaire.
Confusion du proxy de contenu : l'authentification de session du dashboard et celle par token API doivent appliquer les mêmes contrôles de propriété.
Alertes de budget sans droits d'action : prévenir la finance ne sert à rien si n'importe quel membre peut encore créer des clés.

Les recommandations de l'OWASP LLM Top 10 s'appliquent : l'autonomie excessive, la divulgation d'informations sensibles et la consommation non bornée deviennent des incidents de tenancy lorsqu'un locataire peut en affecter un autre.

Séquence d'implémentation minimale

Modéliser les équipes, projets, membres et droits d'action.
Ajouter les champs de propriétaire aux tokens et journaux de consommation.
Imposer la validation des tokens d'équipe dans le middleware d'authentification.
Limiter les rate limits et les requêtes d'usage à leur portée.
Porter l'autorisation des tâches vidéo et le proxy de contenu vers le même helper de portée ; conserver l'atelier image sous propriété utilisateur sauf ajout volontaire d'une persistance image d'équipe.
Ajouter des tests e2e de refus inter-locataires pour le chat, les octets d'image persistés et le contenu vidéo.
Seulement ensuite, migrer le trafic produit réel vers les clés d'équipe.

Ignorer les tests de refus est la meilleure façon de livrer « une UI multi-locataires » sans sécurité multi-locataires.

Lecture associée

Intégration d'une API de génération vidéo

Sources et lectures complémentaires

Questions de décision

Une base de données séparée est-elle nécessaire pour chaque locataire ?

Non pour la plupart des passerelles IA. L'isolation par ligne avec des filtres de requête rigoureux est courante. Des bases séparées peuvent aider pour l'isolation réglementée ou les limites de stockage entre voisins bruyants, mais elles multiplient les migrations et la configuration des canaux. Décidez selon la conformité, pas selon la mode.

Chaque microservice doit-il créer sa propre clé fournisseur ?

Non. Créez des clés de passerelle par identité de service et gardez les clés des fournisseurs dans les canaux. Vous conservez ainsi la rotation, la visibilité des dépenses et le failover.

Comment les espaces personnels coexistent-ils avec les équipes ?

Conservez le type de propriétaire personnel comme chemin de première classe. Les utilisateurs peuvent prototyper avec des clés personnelles et l'atelier image personnel, puis passer à des clés projet d'équipe pour les dépenses partagées de chat et de vidéo sans changer la forme des requêtes : seuls le Bearer token et la politique changent.

Quelle est la plus grande erreur multi-locataires pour les médias ?

Traiter les URL de résultats upstream comme des liens publics durables, ou supposer que chaque atelier est limité à une équipe. Persistez les médias lorsque le produit exige leur durabilité, servez-les via des routes autorisées, documentez leur expiration lorsqu'ils ne peuvent pas être persistés et indiquez honnêtement si la propriété est personnelle ou d'équipe.

Exercice de migration

Choisissez une application de production et remplacez sa clé d'administration partagée par une clé projet d'équipe. Vérifiez que les journaux de consommation indiquent le bon propriétaire de facturation, que les ID de tâches vidéo étrangers sont refusés sur /v1/videos/{id}/content, que les ressources de l'atelier image restent détenues par l'utilisateur sauf si vous avez construit un partage supplémentaire, et que les rate limits du projet ne se heurtent plus aux tests de charge d'une équipe sœur.