Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Un agent, un routeur et deux modèles en amont

Une application d’agent qui atteint deux modèles de fournisseurs en amont par un seul routeur interne au cluster, compilée en manifestes Kubernetes.

L’agent demande un modèle par un seul nom. Derrière ce nom se trouve un routeur qui détient une table d’alias, et derrière la table se trouvent deux fournisseurs. L’agent n’apprend jamais quel fournisseur a répondu, ne détient jamais d’informations d’identification d’un fournisseur et ne change pas lorsque la table est redirigée — ce qui est précisément la raison d’y placer un routeur.

Ce workspace ne rédige aucune entité de catalogue qui lui soit propre. Chaque Component, Feature et Recipe qu’il nomme est livré dans le catalogue de la bibliothèque standard ; les trois fichiers d’entité présents ici — un Aggregate, un Manifest et une Release — sont tout ce que quiconque écrit.

Ce qu’il construit

agent ───────────────────┐ ┌────► openai/gpt-4o
│ │ │
▼ ├────► router ──────┤
checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4
(run state) │
│
an Ingress at ───────────┘
assistant.example.internal

Le routeur a deux voies d’entrée pour les requêtes — l’agent l’atteint par son arête model, et tout ce qui est à l’extérieur l’atteint par l’Ingress — et une voie de sortie par entrée de la table. Un troisième port sert ses métriques à un scraper à l’intérieur du cluster.

Trois composants, et chacun remplit une fonction différente :

instanceComponent du cataloguece qu’il est ici
routercore/gateway/litellmle composant de routage : un endpoint, une table d’alias, deux fournisseurs en amont. Il publie son adresse et l’alias que demande l’agent
agentcore/ai-agent/langgraphl’application, qui exécute sa propre image de graphe
checkpointercore/datastore/valkeylà où l’agent conserve l’état de ses exécutions, sélectionné par la catégorie datastore

Deux arêtes uses, toutes deux vers des sockets que déclare le Component de l’agent : model (obligatoire, admettant un composant de modèle ou une passerelle servant une API de modèle — le routeur est le second cas) et checkpointer_db (obligatoire, sélectionnant selon la catégorie datastore). Six rattachements de Feature sur quatre sortes de Feature — cinq sur le routeur, un sur la connexion model de l’agent — dont chacun met quelque chose dans la sortie rendue ; la section ci-dessous montre ce que produit chacun.

Générer l’exemple

Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

Terminal window
aggrega scaffold --example ai-agent-and-model-router

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd ai-agent-and-model-router

Build

Terminal window
aggrega build --release release.yaml --auto-pull

Une release a besoin d’un lockfile avant son build, et les lockfiles sont générés plutôt que livrés, de sorte qu’un clone neuf n’en contient aucun. aggrega build est en lecture seule par défaut : sans lockfile, il s’arrête et nomme les deux façons de poursuivre. Résolvez-en un d’abord, ou laissez le build le remplir :

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Ce workspace résout ses entités depuis le registre par défaut que nomme .aggrega-config.yaml, de sorte qu’aucun flag --catalog n’est nécessaire.

La réalisation du rattachement selection du routeur exécute un plugin qui n’est livré ni dans le compilateur ni dans le catalogue, l’étape de configuration de la passerelle pipeline-step/litellm-gateway-config, que la résolution récupère depuis le registre que nomme default_registry, hub.aggrega.ai.

Plusieurs sections ci-dessous vous demandent de modifier une ligne et de relancer le build. Le lockfile épingle un digest pour chaque entité que la release a résolue, y compris l’Aggregate et le Manifest de ce répertoire, et enregistre la Release elle-même par le digest de son contenu — de sorte que modifier l’un de ces trois fichiers rend le lockfile obsolète, et le build suivant s’arrête plutôt que d’effectuer le rendu avec un épinglage périmé. Le message nomme ce qui a changé — la Release par son fichier, l’Aggregate ou le Manifest par son nom — et affiche le digest qu’il a enregistré à côté de celui qu’il a trouvé. Un pull enregistre la modification tout en respectant chaque autre épinglage :

Terminal window
aggrega pull --release release.yaml

Exécutez-le et relancez le build, ou lancez le build avec --auto-pull, qui exécute d’abord le même pull. Dans les deux cas, l’arrêt est le but plutôt qu’un obstacle : un build n’effectue pas le rendu avec un épinglage qu’il voit périmé.

Le build affiche, <workspace> désignant le dossier de cet exemple :

verify: plugin pipeline-step/litellm-gateway-config:1.0.0 host functions match the published .wasm
[… omitted: three warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping]
Pull complete: release.lock (entities=24, source_artifacts=0, external_inputs=0)
[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]
Build completed: 12 files written to <workspace>/dist

Les entités sont vérifiées par rapport aux conventions du catalogue une fois pendant la résolution du lockfile et une fois pendant le build de la release, et chaque avertissement que soulèvent ces vérifications est affiché sous forme de ligne lint: ; cette release n’en soulève aucun. Pour exécuter les mêmes vérifications seules, et lire chaque avertissement en entier avec le fichier d’entité dont il provient et ce qui le rendrait conforme :

Terminal window
aggrega lint --release release.yaml

qui signale ici conventions checked: 19 entities, 0 advisory finding(s).

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier de l’espace de travail ne contient pas encore de dossier `ai-agent-and-model-router`, appelez une seule fois l’outil `scaffold` avec `example` défini sur `ai-agent-and-model-router` et sans `dir` : il écrit l’exemple dans un nouveau dossier `ai-agent-and-model-router`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `ai-agent-and-model-router`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `ai-agent-and-model-router/dist/`.

L’arborescence rendue

dist/helm/
├── agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml
├── agent-deployment.yaml
├── checkpointer-default-service.yaml
├── checkpointer-deployment.yaml
├── router--api-zukey--router-secret-router-api-key.yaml
├── router--metrics--router-servicemonitor-router-scrape.yaml
├── router--provider-zukey--router-secret-router-provider-key.yaml
├── router--published--router-ingress-router-ingress.yaml
├── router-default-service.yaml
├── router-deployment.yaml
└── router/
├── litellm-gateway-config/
│ └── configmap.yaml
└── request-guard/
└── request-guard.yaml

Sous router/ se trouvent les fichiers qu’émet elle-même la Recipe du routeur. Tous deux proviennent de bundles que la Recipe importe plutôt qu’elle ne les écrit, de sorte que chacun se trouve sous la clé sous laquelle il a été importé, litellm-gateway-config et request-guard.

Tout ce qu’un rattachement a apporté se trouve dans le même répertoire que les manifestes propres au composant, avec deux coordonnées dans son nom de fichier : le composant auquel il a été rattaché et le nom donné au rattachement. router--metrics-- est le rattachement metrics sur router. Ce qui vient d’où reste lisible dans l’arborescence, et chaque fichier se trouve là où le trouvera un outil qui lit un seul répertoire — ce que font les consommateurs de cette cible, sauf indication contraire de votre part.

Les deux coordonnées sont encodées plutôt qu’écrites telles que vous les avez saisies, car elles partagent une chaîne avec le nom propre du fichier. Un caractère qu’un nom de fichier ne peut pas porter sans risque devient -z suivi d’une lettre : api_key devient api-zukey ; router_model.credential — le nom que prend le rattachement sur la connexion router_model de l’agent, soit l’alias de la connexion, un point et le slot — devient router-zumodel-zdcredential ; et feature.aggrega.ai/monitoring — un nom de rattachement que forge l’annotation propre d’une Feature — deviendrait feature-zdaggrega-zdai-zsmonitoring. Le nom propre du fichier conserve les points qu’il contient, de sorte que le suffixe .yaml se lit toujours comme un suffixe.

Lorsqu’une page ici affiche ce qu’un build a produit, le bloc est copié d’une exécution réelle — voir Lire la sortie sur ces pages pour la convention et la marque qu’elle utilise pour les lignes omises.

La table de routage

La raison d’être du routeur est sa table, et celle-ci atteint la sortie rendue au lieu de rester dans le fichier rédigé. Voici le bloc data entier de dist/helm/router/litellm-gateway-config/configmap.yaml :

data:
config.yaml: |
model_list:
- model_name: assistant
litellm_params:
model: openai/gpt-4o
api_key: os.environ/LITELLM_PROVIDER_API_KEY
- model_name: assistant
litellm_params:
model: anthropic/claude-sonnet-4
api_key: os.environ/LITELLM_PROVIDER_API_KEY
litellm_settings:
callbacks:
- /etc/litellm-request-guard/request_field_filter.filter
- prometheus
router_settings:
routing_strategy: latency-based-routing

et le bloc data de la seconde ConfigMap, dist/helm/router/request-guard/request-guard.yaml, sans le texte des fichiers qu’elle contient :

data:
request_field_filter.py: |
[… omitted: the text of the router's request guard, a Python module described below]
path-allowlist.conf: |
[… omitted: the configuration of the router's path allowlist, described below]

Cinq choses méritent d’être lues dans ces blocs.

Les deux entrées publient le même alias. C’est ce qui donne au routeur un choix à faire à chaque requête, et les router_settings à la fin du corps disent comment il le fait : latency-based-routing, écrit là par le rattachement selection du routeur plutôt que par sa propre Recipe, comme le montre plus bas la section consacrée à ce rattachement. Une table dont les alias sont tous distincts route par nom seulement, et la stratégie n’y change rien. Partager un alias est aussi la raison pour laquelle les deux entrées sont saisies à la main dans values.models plutôt que servies par des composants de modèle câblés au socket models du routeur : un modèle câblé est servi sous l’alias de sa propre connexion, qu’aucune autre entrée ne peut publier, si bien que deux modèles câblés n’en partagent jamais un. La seconde raison tient à Anthropic : le routeur écrit l’entrée d’un modèle câblé uniquement via l’API d’OpenAI, alors que le modèle d’Anthropic répond à sa propre API ; câbler core/ai-model/anthropic arrête donc le build, avec un message demandant de saisir plutôt ce modèle en amont dans la table.

Les cibles sont des chaînes que le compilateur n’interprète pas. openai/gpt-4o est un pointeur déterministe : le proxy en cours d’exécution le résout lorsqu’il sert une requête. Le compilateur ne contacte jamais un fournisseur au moment du build, il ne peut donc pas vous dire qu’une cible existe, qu’elle est correctement orthographiée ou que votre compte peut l’atteindre. Remplacez openai/gpt-4o par openai/not-a-real-model et le build réussit quand même — l’échec survient au moment de la requête, de la part du fournisseur.

Aucune valeur d’informations d’identification ne figure dans ce fichier. Chaque entrée nomme plutôt une variable d’environnement, via l’indirection propre au proxy. La valeur arrive dans le conteneur par une tout autre voie, présentée plus bas.

Chaque requête rencontre d’abord un garde. La première entrée de callbacks enregistre le module request_field_filter par le chemin complet de son fichier : la seconde ConfigMap est montée dans le conteneur du routeur sous /etc/litellm-request-guard, un répertoire à part à côté de /etc/litellm, où la première est montée et où le proxy lit sa configuration. Cette seconde ConfigMap provient de LiteLLMGuard#/artifacts/RequestGuard, un bundle qu’importe chaque Recipe exécutant ce proxy, de sorte que le garde et la liste d’autorisation ci-dessous ont un seul texte partout où le proxy s’exécute. La Recipe du routeur livre ce garde dans chaque Release, parce que le routeur détient les informations d’identification du fournisseur. Il ne transmet d’un appelant que les champs de requête que le proxy déclare pour la route empruntée par la requête, plus ceux que la Release nomme dans l’infra.admitted_request_fields du routeur, et répond à tout autre champ par une erreur qui le nomme, sans rien transmettre — ainsi un appelant ne peut ni diriger le routeur vers une adresse à lui via une liste de modèles dans le corps de la requête, ni envoyer sa propre clé de fournisseur à la place de celle du routeur. Un appelant ne peut pas non plus définir l’identité que le routeur écrit lui-même dans chaque requête — le hachage de la clé qu’il a vérifiée, l’équipe et l’organisation de cette clé, et l’utilisateur final : sur une requête responses ou messages, où le routeur garde les metadata de l’appelant séparées des siennes, il supprime tout champ d’équipe, d’organisation ou d’utilisateur final que l’appelant y a écrit et le garde refuse une requête qui y nomme la clé, metadata.user_api_key, et sur toute autre route la valeur du routeur remplace celle que l’appelant a envoyée. Cette Release n’admet rien de plus. La seconde entrée, prometheus, est le callback de métriques propre au proxy, que la valeur metrics_enabled du routeur active ; le rattachement metrics ci-dessous collecte ce qu’il enregistre.

Seules les routes propres au routeur sont joignables. Le garde ne voit que les routes qui lui remettent la requête, aussi l’autre fichier de la seconde ConfigMap configure-t-il le second conteneur du pod, qui monte cette seule ConfigMap et exécute l’image officielle de nginx comme liste d’autorisation de chemins. Le routeur lui-même écoute sur l’adresse de loopback du pod, où rien d’extérieur au pod ne l’atteint, et la liste d’autorisation écoute sur le port 4000, le port que cible le Service ci-dessous. Elle ne transmet une requête que lorsque sa méthode et son chemin correspondent à l’une des routes que sert le routeur — les routes de requêtes de modèle que vérifie le garde, dans les graphies que sert le routeur quel que soit l’alias, dont /v1/chat/completions et /v1/messages ; la liste des modèles ; les contrôles de santé ; et, parmi ses routes d’administration, la gestion des clés — et répond 403 à tout autre chemin, sans rien transmettre. Ainsi, les routes de comptage de tokens du proxy, ses routes de passage direct vers les API propres des fournisseurs, ses autres routes d’administration et sa console d’administration ne sont pas joignables à travers le routeur, pas plus qu’une route de modèle dont le chemin contient le nom du modèle, comme le font les chemins qu’envoie le client d’Azure : là, le proxy lit des mots dans le chemin, alias compris, pour décider comment il enregistre une requête, et le routeur y refuserait une requête pour l’assistant propre à cette table. Les métriques du proxy ne font pas non plus partie de ces routes : le port 4000 répond 403 à /metrics. Avec metrics_enabled du routeur à true, comme l’Aggregate le définit, la liste d’autorisation écoute aussi sur le port 9090 et n’y transmet qu’un GET de /metrics, vers l’écouteur que le proxy garde pour ses métriques sur l’adresse de loopback, en répondant 403 à toute autre requête. Ce port ne vérifie aucun appelant, et les métriques nomment les clés hachées, les alias de clés et les e-mails des utilisateurs auxquels le routeur attribue les dépenses.

Ce que publie le routeur

La Recipe du routeur publie les deux clés que publie tout composant de modèle : un endpoint, l’URL de base remise à une bibliothèque cliente, et un model, le nom qu’une requête demande. C’est ce qui permet au socket model de l’agent d’accepter le routeur à la place d’un modèle. Le sélecteur du socket est component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api : il admet un composant de la catégorie modèle ou passerelle qui porte model.aggrega.ai/api, l’étiquette qui nomme l’API de modèle qui répond à l’adresse que publie le composant. Le routeur porte model.aggrega.ai/api: openai. Une passerelle qui ne sert aucune API de modèle ne porte pas une telle étiquette, et une arête de l’agent vers celle-ci arrête le build, en nommant le socket et le sélecteur que la cible ne satisfait pas.

L’adresse est le Service qu’émet la propre Recipe du routeur — la spec entière de dist/helm/router-default-service.yaml :

spec:
type: ClusterIP
selector:
app: router
ports:
- name: http
port: 4000
targetPort: http
- name: metrics
port: 9090
targetPort: metrics

La Recipe compose l’endpoint qu’elle publie, http://router-default:4000/v1, à partir des deux mêmes faits dont le Service tire son nom et son port : le nom propre du composant et son infra.port. Le port que cible le Service, http, est celui sur lequel écoute la liste d’autorisation de chemins du routeur ; metrics, le second, est là parce que les métriques du routeur sont activées, et ne transporte qu’elles. Rien dans les trois fichiers n’écrit router-default en toutes lettres. Renommez le composant router — sa clé dans l’Aggregate et dans la Release, et l’arête de l’agent qui le nomme — et l’adresse que reçoit l’agent suit : renommé gateway, l’OPENAI_BASE_URL de l’agent vaut http://gateway-default:4000/v1.

Le nom est l’alias que le routeur publie comme son modèle. Cette table publie un seul alias, assistant, depuis ses deux entrées, donc le routeur publie celui-là et son values.model est omis. Donnez à la seconde entrée un alias à elle — summarizer, par exemple — et le build s’arrête avant que quoi que ce soit ne soit rendu, parce que le routeur ne peut en publier qu’un. L’arrêt est E0033, une assertion échouée du Component du routeur, et son message se termine par la phrase propre à la règle : values.model is not set, but values.models publishes 2 aliases (assistant, summarizer), so the gateway cannot tell which one a component wired to it asks for; set values.model to one of them (values.model n’est pas défini, mais values.models publie 2 alias (assistant, summarizer), la passerelle ne peut donc pas savoir lequel demande un composant câblé à elle ; définissez values.model sur l’un d’eux). Définir model: assistant à côté de models lève l’arrêt, et l’agent reçoit de nouveau assistant. Un appelant qui veut summarizer le demande par son nom au même endpoint.

Ce que reçoit l’agent

La Recipe de l’agent lit ses deux arêtes ainsi que les valeurs propres de l’agent, et les transforme en environnement du conteneur. Voici le bloc env entier de dist/helm/agent-deployment.yaml :

env:
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: agent-router-model.credential
key: api-key
- name: LANGGRAPH_DEFAULT_RECURSION_LIMIT
value: "25"
- name: OPENAI_BASE_URL
value: http://router-default:4000/v1
- name: OPENAI_MODEL
value: assistant
- name: LANGGRAPH_CHECKPOINTER_HOST
value: checkpointer-default
- name: LANGGRAPH_CHECKPOINTER_PORT
value: "6379"
- name: LANGGRAPH_GRAPH_ENTRYPOINT
value: app.graph:graph

La première vient du rattachement que porte l’arête model, et le fournisseur helm écrit une telle entrée, lue depuis un Secret, avant les entrées simples. La limite de récursion est le recursion_limit propre à l’agent, sous la variable que LangGraph lit de lui-même ; les deux suivantes viennent de l’arête model, les deux d’après de l’arête checkpointer_db, et la dernière est le graph_entrypoint propre à l’agent, sous un nom par défaut que lit le code de l’application, et qu’un bloc inject sur le composant lui-même remplacerait. Notez ce que l’Aggregate n’a pas eu à dire : aucune des deux arêtes ne porte de bloc inject, parce que la Recipe consommatrice livre chaque connexion sous des noms par défaut, qu’un bloc inject sur l’arête remplacerait. Le développeur déclare que l’agent utilise un modèle ; la variable sous laquelle arrive son endpoint est celle que lit la bibliothèque cliente, et elle reste ce que l’arête dicte.

Notez aussi LANGGRAPH_CHECKPOINTER_PORT: "6379". La Release déclare checkpointer: {} et ne configure rien, donc ce port est la valeur par défaut du schéma propre au Component de cache, matérialisée et acheminée à travers l’arête.

L’agent parle au routeur exactement dans le dialecte qu’il utiliserait pour parler directement à un fournisseur — une URL de base, un nom de modèle et une clé. C’est ce qui permet d’insérer, de déplacer ou de rediriger le routeur sans que l’application change.

Les six rattachements, et ce que rend chacun d’eux

Un rattachement qui ne change rien dans la sortie n’enseigne rien. Chacun de ces six y met quelque chose.

api_key sur le routeur — la clé qu’il exige des appelants

core/referenced-secret, qui remplit un emplacement que déclare le Component du routeur ; la clé qu’elle contient est celle que LiteLLM appelle sa clé maîtresse. Elle rend son propre Secret, et le conteneur du routeur y fait référence. Extrait de dist/helm/router--api-zukey--router-secret-router-api-key.yaml :

stringData:
master-key: "dev-router-admin-key-change-me"

et dans l’env du conteneur du routeur, extrait de dist/helm/router-deployment.yaml :

- name: LITELLM_MASTER_KEY
valueFrom:
secretKeyRef:
name: router-api-key
key: master-key

Le conteneur porte une référence, pas la valeur. Le nom du Secret est publié par le rattachement et lu par le consommateur, si bien qu’aucun des deux côtés ne le redérive.

provider_key sur le routeur — la clé qu’il présente en amont

La même Feature dans un autre emplacement, et la différence entre les deux emplacements est la raison d’être du routeur. Ce sont les seules informations d’identification des entrées saisies dans values.models, ici les deux ; un modèle câblé au socket models du routeur présente plutôt la clé que porte sa propre connexion, jamais celle-ci. Extrait de dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml :

stringData:
provider-key: "upstream-provider-key-change-me"

et dans le même env du conteneur :

- name: LITELLM_PROVIDER_API_KEY
valueFrom:
secretKeyRef:
name: router-provider-key
key: provider-key

Ce rattachement modifie aussi la table de routage. Revenez au bloc data de la table de routage plus haut : chaque entrée de la table porte api_key: os.environ/LITELLM_PROVIDER_API_KEY, qui nomme cette même variable. Retirez le rattachement provider_key de l’Aggregate et relancez le build. Le build signale onze fichiers au lieu de douze — le Secret a disparu — et la ConfigMap de la table de routage diffère exactement de ces deux lignes api_key et de rien d’autre ; la ConfigMap du garde est inchangée. Le reste de la table conserve l’ordre et la mise en forme rédigés, le routeur sert et route toujours, et une requête routée échoue désormais chez le fournisseur faute d’informations d’identification à présenter.

Le nom de la variable est rédigé une seule fois dans la Recipe du routeur et lu depuis là à la fois par la table de routage et par l’environnement du conteneur, de sorte qu’une table ne peut pas en venir à nommer une variable que rien ne définit.

Les deux informations d’identification restent séparées, et cette séparation est ce qu’apporte le routeur : la clé amont reste dans le routeur, et l’application appelante ne détient rien d’autre que la clé du routeur.

credential sur la connexion model de l’agent — la clé qu’il présente au routeur

De nouveau core/referenced-secret, de l’autre côté de la même conversation. Le socket model de l’agent déclare un emplacement credential, donc la clé est rattachée sur la connexion sur laquelle elle est présentée, sous l’arête dans l’Aggregate :

uses:
model:
router_model:
target: router
features:
credential:
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.router_admin_key }}"

Extrait de dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml :

stringData:
api-key: "dev-router-admin-key-change-me"

C’est la même valeur que la master-key du routeur ci-dessus, et elle n’est pas écrite deux fois. Les deux rattachements lisent un même paramètre remonté :

origin: "{{ .parameters.router_admin_key }}"

L’Aggregate déclare le paramètre et la Release le remplit, si bien que la clé a un seul lieu où elle est rédigée et que les deux Secrets ne peuvent pas être modifiés séparément. Modifiez-la une fois dans la Release et les deux Secrets rendus changent ensemble.

Chaque rattachement rend malgré tout son propre Secret, nommé d’après le composant qui le consomme — et, pour celui de l’agent, d’après la connexion sur laquelle il est rattaché : agent-router-model.credential. Ce que partage le paramètre partagé, c’est la valeur, pas la ressource.

published sur le routeur — une adresse hors du cluster

core/public-ingress, qui ne remplit aucun emplacement : elle est admise par son propre sélecteur, component.aggrega.ai/type=server, que porte le routeur. Elle apporte une ressource dont la Recipe du routeur ne sait rien. La spec entière de dist/helm/router--published--router-ingress-router-ingress.yaml :

spec:
rules:
- host: assistant.example.internal
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: router-default
port:
name: http

Le développeur la rattache dans l’Aggregate avec le path, parce que les requêtes que sert une application font partie de ce qu’est l’application. L’opérateur écrit le host et le nom du port sur l’entrée de la Release pour le même rattachement : l’hôte est le nom que l’environnement donne au routeur, donc l’opérateur le nomme par environnement, dans la Release de chaque environnement. Le Service backend n’a été fourni par aucun des deux : service_name n’est pas défini, et la réalisation du rattachement se rabat sur le Service qu’émet la propre Recipe du routeur. Il n’y a pas de champ ingressClassName dans la sortie, parce que rien n’en a défini un et que la réalisation omet ce qu’on ne lui a pas donné, laissant la classe par défaut du cluster prendre en charge la ressource.

metrics sur le routeur — une cible de scraping

core/prometheus-exporter, admise par le même sélecteur, qui apporte une autre ressource à elle. Chaque paramètre qu’elle accepte relève du dimensionnement par l’opérateur plutôt que de l’intention de l’application — la fréquence à laquelle une plateforme collecte, et le port et le chemin qu’elle lit, sont des propriétés de la plateforme — donc c’est l’opérateur qui la rattache, dans la Release, sur l’entrée du routeur, avec son type à côté de son infra. L’Aggregate ne la mentionne pas :

components:
router:
features:
metrics:
type: core/prometheus-exporter
infra:
interval: 30s
port: metrics
path: /metrics

La spec entière de dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml :

spec:
selector:
matchLabels:
app.kubernetes.io/name: router
endpoints:
- port: metrics
interval: 30s
path: /metrics

Le port nomme un port du Service plutôt qu’un numéro : metrics, que la Recipe du routeur émet parce que l’Aggregate définit la valeur metrics_enabled du routeur, et qui sert ses métriques. C’est aussi le nom de port par défaut de la Feature, écrit ici en toutes lettres avec les deux autres réglages. Le port http vers lequel route l’Ingress ci-dessus répond 403 à /metrics, donc une collecte dirigée là ne récupérerait rien. Que les métriques soient servies ou non est le choix du développeur, fait dans l’Aggregate ; à quelle fréquence, sur quel port et quel chemin une plateforme les collecte est celui de l’opérateur, fait ici.

selection sur le routeur — comment il choisit entre ses cibles

core/target-selection, qui se rattache à une passerelle portant gateway.aggrega.ai/intelligence: semantic, comme le fait le routeur. La façon dont le routeur choisit fait partie de ce que l’application lui demande, donc le développeur la rattache dans l’Aggregate, avec sa strategy comme valeur :

components:
router:
features:
selection:
type: core/target-selection
values:
strategy: latency

et le Manifest la lie à la réalisation pour ce routeur :

core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0

Elle ne rend aucun fichier à elle. Sa réalisation écrit un réglage dans la table de routage que rend la Recipe du routeur — les deux dernières lignes du bloc data ci-dessus :

router_settings:
routing_strategy: latency-based-routing

Avec elle, le proxy envoie chaque requête pour assistant à l’entrée dont les dix dernières réponses ont pris le moins de temps en moyenne, par token de sortie lorsqu’une réponse indique ses tokens, et une entrée pas encore essayée compte comme la plus rapide, si bien que chacune est essayée avant que les moyennes décident. Retirez le rattachement de l’Aggregate et relancez le build : le build signale toujours douze fichiers, et la ConfigMap de la table de routage diffère exactement de ces deux lignes. La Recipe du routeur n’écrit aucune stratégie à elle, et sans stratégie le proxy choisit au hasard entre les deux entrées.

Demandez plutôt strategy: cost et le build s’arrête, sans rien écrire. L’arrêt est E0033, une assertion échouée de la réalisation, et son message se termine par la phrase propre à la règle : core/target-selection attachment “selection” on “router” asks for strategy cost, but core/gateway/litellm cannot choose between the entries of its model map by cost: the proxy looks each entry’s target up, exactly as written, in its own price table, which names OpenAI’s and Anthropic’s models without the provider prefix a target carries (gpt-4o, not openai/gpt-4o) and which the proxy may fetch afresh when it starts, and it prices an entry it does not find, and that carries no price of its own, at a fixed fallback, so the entries sharing an alias are priced alike and the choice falls to their order. Ask for strategy latency, or remove the attachment (le rattachement core/target-selection “selection” sur “router” demande la stratégie cost, mais core/gateway/litellm ne peut pas choisir entre les entrées de sa table de modèles selon le coût : le proxy recherche la cible de chaque entrée, exactement telle qu’elle est écrite, dans sa propre table de prix, qui nomme les modèles d’OpenAI et d’Anthropic sans le préfixe de fournisseur que porte une cible (gpt-4o, et non openai/gpt-4o) et que le proxy peut récupérer à nouveau au démarrage, et il attribue à une entrée qu’il ne trouve pas, et qui ne porte aucun prix propre, un prix de repli fixe, si bien que les entrées partageant un alias reçoivent le même prix et que le choix revient à leur ordre. Demandez la stratégie latency, ou retirez le rattachement). Les deux cibles ici sont écrites de cette façon, donc le proxy enverrait chaque requête à la première d’entre elles alors que l’Aggregate demandait le coût.

Là où le compilateur n’interprète pas

L’adresse et le nom de modèle de l’agent sont lus dans ce que publie le routeur, si bien qu’aucune paire de noms dans les trois fichiers ne doit être maintenue en phase à la main. Ce que le build vérifie bel et bien, c’est la règle propre au routeur selon laquelle l’alias qu’il publie est l’un de ceux que publie sa table — une règle que déclare son Component et que le build évalue, comme toute autre assertion que porte une entité.

Le reste n’est que des chaînes acheminées d’un endroit à un autre. Le compilateur route l’adresse et l’alias sans les lire : il ne sait pas que l’un est un nom d’hôte et l’autre un nom de modèle, et il n’a accès à aucun cluster en cours d’exécution pour vérifier que quelque chose répond à router-default:4000. L’étiquette model.aggrega.ai/api qui a admis le routeur est le même genre de chaîne — le sélecteur du socket la fait correspondre, et rien ne vérifie quelle API répond réellement là. Et chaque target de la table est un pointeur que résout le proxy en cours d’exécution : remplacez openai/gpt-4o par openai/not-a-real-model et le build réussit toujours, l’échec survenant au moment de la requête.

C’est la même propriété qui fait fonctionner le reste de l’exemple. Comme le compilateur n’interprète pas ce qu’il achemine, le routeur peut être redirigé vers un autre fournisseur, l’agent peut être câblé à un autre routeur, et la réalisation des informations d’identification peut être remplacée par une réalisation adossée à un magasin — le tout sans que le compilateur ait besoin de comprendre quoi que ce soit, et sans que l’agent change.

L’adapter

  • Rediriger un fournisseur. Modifiez une target dans la table du routeur. Rien d’autre ne change : ni le modèle, ni l’agent, ni un Secret rendu.

  • Ajouter un troisième fournisseur. Ajoutez une entrée à la table. Si elle publie l’alias existant, la stratégie se met à choisir entre trois. Si elle en publie un nouveau, la table publie deux alias, et le values.model du routeur nomme celui qui est remis à l’agent ; un appelant qui veut l’autre le demande par son nom. Un modèle que le catalogue modélise et dont l’API est l’API d’OpenAI peut plutôt être câblé au socket models du routeur, sous un alias qui lui est propre et en présentant la clé que porte sa connexion ; values.model nomme alors l’alias remis à l’agent.

  • Récupérer plutôt les informations d’identification depuis un magasin. Faites pointer vers helm/k8s-external-secret l’unique ligne du Manifest qui lie core/referenced-secret, puis relancez le build. Chaque Secret rendu devient un ExternalSecret nommant une entrée dans un magasin de secrets du cluster, qu’un opérateur de magasin réconcilie — et la référence rendue de chaque consommateur reste identique octet pour octet, car le localisateur est publié par le côté producteur plutôt que convenu entre les deux. Rien d’autre dans les trois fichiers ne doit changer pour que le build réussisse.

    Une chose doit toutefois être réécrite avant que le remplacement ait un sens : origin change de signification entre les deux réalisations. La réalisation de ce workspace le lit comme la valeur à stocker ; l’autre le lit comme la clé à récupérer. Remplacez la ligne sans revoir les valeurs de origin et le remoteRef.key rendu est l’espace réservé, quel qu’il soit, qui tenait lieu de valeur — ici dev-router-admin-key-change-me. Rien dans l’arborescence de sortie ne détient alors cette chaîne comme matériel secret, mais elle est toujours là comme clé de magasin nommant une entrée qui n’existe pas.

  • Se passer du routeur. Faites plutôt pointer l’arête model de l’agent vers un composant de modèle propre à un fournisseur. L’agent détient alors lui-même des informations d’identification de fournisseur, ce qui est précisément le compromis que le routeur existe pour supprimer.

  • Atteindre un routeur que le catalogue ne modélise pas. Faites pointer l’arête model de l’agent vers un composant core/ai-model/openai-compatible et écrivez l’adresse de ce routeur dans son infra.endpoint dans la Release. Rien ne s’exécute derrière ce composant dans le cluster, donc c’est à l’opérateur d’écrire l’adresse et de la maintenir en phase avec le service qu’elle nomme.

Pour partager des informations d’identification entre les connexions de plusieurs consommateurs, voir model-api-key-sharing. Pour un socket qu’aucune entité du catalogue ne déclare, voir adhoc-uses-socket.