Aller au contenu principal

B05 - Routeur de modèles

GroupeTechnologieStatutServicePhase de la feuille de routeContrats
B - Gestion des LLM et Model GatewayDéveloppéà développerllm2-

Retour à l'index - English

Rôle et responsabilités​

Règles de routage et chaînes de repli selon usage, classification, région, coût et latence.

Position dans l'architecture et interactions​

Appelé de façon synchrone par la gateway pour chaque requête ; POST /v1/routes/simulate explique le choix sans appeler de modèle. Les règles portent sur la finalité, la classification, la région, l'effort et les objectifs coût/latence, et produisent une chaîne ordonnée.

Modèle de données​

Tables (schéma eai, chaque table tenant porte tenant_id uuid NOT NULL avec une politique RLS sur current_setting('app.tenant_id', true)::uuid) : eai.llm_routes, eai.audit_events.

Endpoints API​

  • GET /v1/routes
  • POST /v1/routes
  • PUT /v1/routes/{id}
  • DELETE /v1/routes/{id}
  • POST /v1/routes/simulate
POST /v1/routes HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: fr
Content-Type: application/json

{"name": "support-eu", "match": {"purpose": "support"}, "strategy": "priority", "candidates": ["fake-gpt"], "priority": 100, "enabled": true}
{"id": "417d22b5-f725-4a5c-a6fe-128310c3d083", "tenant_id": "18de5695-21f9-4053-a4ea-beb4bf2a5932", "name": "support-eu", "match": {"purpose": "support"}, "strategy": "priority", "candidates": ["fake-gpt"], "fallbacks": [], "constraints": {}, "priority": 100, "enabled": true, "created_at": "2026-10-30T02:36:57.212559+01:00", "updated_at": "2026-10-30T02:36:57.212559+01:00", "target_model": "fake-gpt"}

Les erreurs utilisent l'enveloppe commune {"error": {"code", "message", "message_i18n", "details", "request_id"}} ; les listes sont paginées avec limit et cursor.

Utilisation des SDK​

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
items = client.routes.list()

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const items = await eai.routes.list();

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var items = client.routes().list();

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.Routes.List(ctx)

Configuration​

  • Environnement : EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
  • Valeurs Helm : controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config, litellm.enabled, litellm.config.

Contrôles de sécurité​

  • Authentification par JWT OIDC, clé API tenant avec scopes, ou mTLS SPIFFE ; le tenant est résolu depuis l'identifiant, jamais depuis le corps.
  • Autorisation par décisions OpenFGA et OPA ; chaque mutation et décision écrit une ligne eai.audit_events chaînée par hash.
  • Les secrets ne sont jamais renvoyés par l'API ; TLS partout ; les politiques réseau Cilium restreignent qui peut joindre le service.
ContrôleApplication
Listes d'autorisation provider / modèle / régionPar tenant et projet dans eai.policies ; le Router ne sélectionne que des triplets (provider, modèle, région) autorisés
Classification des donnéeseai.data_classification de la requête doit être <= data_classification_max du modèle ; les données très sensibles (restricted, secret) restent sur des modèles locaux (vLLM)
DLPLa DLP Gateway (E02) inspecte puis masque ou tokenise les prompts avant tout appel distant
Isolation des secretsIdentifiants en écriture seule, stockés dans OpenBao, injectés dans LiteLLM lors de la synchronisation, jamais renvoyés par l'API ni journalisés
TLSTLS 1.2+ vers chaque provider, mTLS SPIFFE dans le cluster
Rétention chez le providerLe registre consigne les conditions de rétention / de non-conservation des données (zero data retention) ; les modèles sans conditions acceptables sont restreints
Politique de repliLes chaînes de repli sont filtrées par les mêmes listes : jamais de région, de modèle ou de classification interdits
Garde-fous de coûtEstimation et réservation de quota avant exécution (POST /v1/gateway/estimate, POST /v1/quotas/reserve), coupure du streaming pendant l'exécution quand le budget est atteint
Journalisation sans expositionPrompts et réponses journalisés uniquement selon la politique, masqués, jamais avec des identifiants
Kill switchPOST /v1/providers/{id}/disable et POST /v1/models/{model_id}/disable prennent effet dès l'appel suivant

Les modèles distants sont autorisés pour certains usages (données publiques ou internes, finalités approuvées) tandis que les données très sensibles restent sur des modèles locaux.

Observabilité​

  • Métriques : eai_model_router_requests_total, eai_model_router_errors_total, eai_model_router_latency_seconds (Prometheus).
  • Traces : spans OpenTelemetry eai.routes.* avec propagation W3C traceparent, spans IA envoyés à Opik.
  • Actions d'audit : route.create, route.update, route.delete, policy.evaluate.

Aspects FinOps​

Le coût d'exploitation est imputé par tenant et projet via les labels des Usage Events et les requêtes de ressources Kubernetes ; pas de coût direct par appel.

Modes de défaillance et résilience​

  • Réplicas sans état derrière l'API Gateway, PostgreSQL HA pour l'état ; la sonde GET /readyz retire les pods défaillants.
  • Système externe indisponible : échec fermé pour les décisions de sécurité, code d'erreur explicite, aucun contournement silencieux.

Adoption autonome (client d'un client)​

Un client d'un client peut adopter cette brique seule avec le sous-client SDK Python client.routes (TS eai.routes, Java client.routes(), Go client.Routes). Déploiement minimal : Control Plane API + PostgreSQL + Keycloak (ou clés API), le Control Plane charge tous les domaines de services/control-plane/src/eai/domains ; les composants optionnels du chart se coupent dans deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Tests d'acceptation​

  1. Un tenant ne peut ni lire ni modifier les ressources d'un autre tenant (test RLS).
  2. Chaque mutation produit un événement d'audit vérifiable par GET /v1/audit/verify.
  3. Les erreurs sont renvoyées en anglais et en français selon Accept-Language.

Canari et modes isolés (LLM_-016, LLM_-015)​

Le routeur sert la version canari à sa part de trafic (eai.model_version dans la réponse). En mode local_only ou air_gapped (PUT /v1/llm/isolation, par locataire ou par projet, V139), seuls les fournisseurs locaux (vllm, ollama, lm_studio) et les hôtes internes déclarés sont routables : une route externe est refusée en préflight (403 isolation_external_route) avant tout appel sortant, les replis externes sont retirés, et l'hôte sortant est vérifié une seconde fois (403 isolation_egress_denied). Les replis restent interdits vers une classification ou une région non autorisée (LLM_-007). Tests : tests/test_llm_isolation.py, tests/test_llm_router.py.