Aller au contenu principal

B08 - Gestionnaire de fenêtre de contexte

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

Retour à l'index - English

Rôle et responsabilités​

Planifie le budget de contexte, la compression, la sélection, le résumé et la prévention des débordements.

Composant open source et partie développée​

Formule de planification : B_context = W_model - B_output - B_reasoning - B_safety, où W_model est la fenêtre documentée, B_output la sortie réservée, B_reasoning le budget de raisonnement réservé et B_safety une marge pour les différences de tokenizer et les prompts système. C'est un modèle de planification : la comptabilité réelle dépend du provider (tokenizer, prise en compte ou non des tokens de raisonnement dans la fenêtre, tokens en cache), et les valeurs mesurées reviennent de la Token Accounting (B09).

Stratégies appliquées dans l'ordre quand les segments dépassent B_context : sélection (top-k, déduplication, ACL), compression (suppression du superflu, compression extractive), résumé de l'historique ancien (par un modèle économique via la gateway), réutilisation du cache de prompt pour les préfixes stables, et prévention du débordement : l'appel est rejeté avec context_overflow plutôt que tronqué silencieusement par le provider.

Modèle de données​

Les plans suivent contracts/v1/context-contract.schema.json (budget, segments, classification_max, compression_actions, cache).

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.audit_events.

Endpoints API​

  • POST /v1/context/plan
POST /v1/context/plan HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: fr
Content-Type: application/json

{"model_id": "claude-sonnet-eu", "window": 200000, "output": 8000, "reasoning": 16000, "safety": 4000, "segments": [{"kind": "rag", "tokens": 190000}]}
{"b_context": 172000, "overflow": true, "actions": [{"type": "select", "segment": "rag", "target_tokens": 150000}, {"type": "summarize", "segment": "history"}]}

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")
plan = client.context.plan(window=128000, output=4000, reasoning=2000)

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 plan = await eai.context.plan({ window: 128000, output: 4000, reasoning: 2000, segments: [] });

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var plan = client.context().plan(Map.of("window", 128000, "output", 4000, "reasoning", 2000));

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
plan, err := client.Context.Plan(ctx, map[string]any{"window": 128000, "output": 4000, "reasoning": 2000})

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_context_window_manager_requests_total, eai_context_window_manager_errors_total, eai_context_window_manager_latency_seconds (Prometheus).
  • Traces : spans OpenTelemetry eai.context.* avec propagation W3C traceparent, spans IA envoyés à Opik.
  • Actions d'audit : model.invoke, 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.context (TS eai.context, Java client.context(), Go client.Context). 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.