Aller au contenu principal

B04 - Registre des modèles

GroupeTechnologieStatutServicePhase de la feuille de routeContrats
B - Gestion des LLM et Model GatewayDéveloppé (PostgreSQL)à développerllm2model-manifest

Retour à l'index - English

Rôle et responsabilités​

Chaque modèle avec ses champs obligatoires : modalités, limites, raisonnement, résidence, classification, prix, statut.

Position dans l'architecture et interactions​

Source pour le Resolver, le Router, le Context Manager, la tarification et le Governance Registry. Les modèles peuvent être appliqués comme manifestes via POST /v1/manifests/apply (kind: Model). La promotion en approved exige une porte d'évaluation (B12) et une approbation (A12).

Modèle de données​

eai.llm_models stocke le Model Manifest (contracts/v1/model-manifest.schema.json). Champs obligatoires :

ChampSignification
model_idIdentifiant interne stable
providerId du provider dans le Provider Registry
provider_model_idIdentifiant utilisé par l'API du provider
deployment_idDéploiement et région (ex. vllm-paris-a100)
modalitiesModalités d'entrée et de sortie
capabilitieschat, tools, json_schema, streaming, embeddings, reasoning...
context_windowFenêtre maximale documentée en tokens
max_output_tokensNombre maximal de tokens de sortie
reasoning_modesNiveaux d'effort supportés et mécanisme natif
supports_cachingSupport du cache de prompt
supports_batchSupport de l'API batch
supports_streamingSupport du streaming
data_residencyRégions de traitement des données
data_classification_maxClassification maximale autorisée
pricing_versionVersion de grille tarifaire (B10)
quality_profileProfil et scores d'évaluation (B12)
statusapproved, restricted, deprecated, blocked

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_models, eai.audit_events.

Endpoints API​

  • GET /v1/models
  • POST /v1/models
  • GET /v1/models/{model_id}
  • PATCH /v1/models/{model_id}
  • DELETE /v1/models/{model_id}
  • POST /v1/models/{model_id}/status
  • POST /v1/models/{model_id}/disable
POST /v1/models HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: fr
Content-Type: application/json

{"apiVersion": "enterprise-ai.io/v1", "kind": "Model", "metadata": {"name": "claude-sonnet-eu"}, "spec": {"model_id": "claude-sonnet-eu", "provider": "aws_bedrock", "provider_model_id": "eu.anthropic.claude-sonnet-4-20250514-v1:0", "deployment_id": "bedrock-eu-west-3-claude-sonnet-4", "status": "approved", "modalities": {"input": ["text"], "output": ["text"]}, "capabilities": ["chat", "tools", "streaming"], "context_window": 200000, "max_output_tokens": 64000, "reasoning_modes": ["none"], "supports_caching": true, "supports_batch": false, "supports_streaming": true, "data_residency": {"regions": ["eu-west-3"], "jurisdiction": "eu"}, "data_classification_max": "confidential", "pricing_version": "2025-10", "quality_profile": {"general": 0.9}}}
{"status": "approved", "model_id": "claude-sonnet-eu", "provider": "aws_bedrock", "modalities": {"input": ["text"], "output": ["text"]}, "capabilities": ["chat", "tools", "streaming"], "deployment_id": "bedrock-eu-west-3-claude-sonnet-4", "context_window": 200000, "data_residency": {"regions": ["eu-west-3"], "jurisdiction": "eu"}, "supports_batch": false, "pricing_version": "2025-10", "quality_profile": {"general": 0.9}, "reasoning_modes": ["none"], "supports_caching": true, "max_output_tokens": 64000, "provider_model_id": "eu.anthropic.claude-sonnet-4-20250514-v1:0", "supports_streaming": true, "data_classification_max": "confidential", "id": "011711da-6130-4d85-a40c-1681c38c152d", "disabled": false, "pricing": {}, "version": "1.0.0", "owner": "platform-team", "scope": "tenant", "source": "api", "wire_format": "bedrock_converse", "provider_local": false, "provider_row_id": null, "provider_disabled": false, "provider_configured": false, "provider_api_base": "https://bedrock-runtime.{aws_region_name}.amazonaws.com"}

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.models.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.models.list();

Java (enterprise-ai-java):

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

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.Models.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.

Observabilité​

  • Métriques : eai_model_registry_requests_total, eai_model_registry_errors_total, eai_model_registry_latency_seconds (Prometheus).
  • Traces : spans OpenTelemetry eai.models.* avec propagation W3C traceparent, spans IA envoyés à Opik.
  • Actions d'audit : model.create, model.update, model.delete, model.status, 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.models (TS eai.models, Java client.models(), Go client.Models). 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.

Versions, licences, poids, déploiement et retour arrière (LLM_-004, LLM_-016)​

Chaque version (eai.llm_model_versions, V135) porte une licence (expression SPDX ou référence de conditions éditeur https:// ou LicenseRef-) et la provenance des poids : source (hf://, oci://, https://, s3://, registry://), empreinte sha256:, taille. Une version naît draft ; POST .../versions/{version}/approval ouvre une approbation model_version_activation décidée par une autre personne (tenant_admin ou security_officer, séparation des tâches) ; approved_by et approved_at sont recopiés sur la version au moment de la publication. Sans approbation accordée, la publication est refusée (403 model_version_not_approved).

POST .../rollout publie à 100 % ou ouvre un canari (1 à 99 % du trafic, réparti de façon stable par session) ; POST .../rollback interrompt le canari ou restaure la version précédente. Chaque étape est ajoutée à eai.llm_model_rollout_history (V136) et auditée (model.rollout.publish|canary|rollback). Tests : tests/test_llm_model_lifecycle.py.