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

Envoy Gateway devant OpenAI, avec un budget mensuel de tokens

Une équipe place le gpt-4o-mini d’OpenAI derrière une passerelle interne au cluster, veut un plafond sur les tokens que la passerelle dépense pour lui chaque mois calendaire, et oriente son agent vers la passerelle plutôt que vers OpenAI. Cet espace de travail compile cela en manifestes Kubernetes : Envoy Gateway servant le modèle via Envoy AI Gateway, avec core/period-budget rattaché, un Redis tenant le compteur, et un agent CrewAI envoyant ses requêtes de modèle via la passerelle.

La page montre aussi ce que cette passerelle refuse de compter : un budget en dollars américains arrête le build, tout comme un budget par appelant.

Ce workspace ne rédige aucune entité de catalogue qui lui soit propre. 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

instanceComponent du cataloguece qu’il est ici
edgecore/gateway/envoy-gatewayla passerelle, qui sert un alias, assistant, issu du modèle chat
ai-controllercore/gateway/envoy-ai-gateway-operatorle contrôleur d’Envoy AI Gateway, que la passerelle appelle comme son serveur d’extension, installé avec les six définitions de ressources d’AI Gateway
chatcore/ai-model/openaile gpt-4o-mini d’OpenAI, atteint comme référence : rien ne s’exécute pour lui dans le cluster
counterscore/datastore/redisle magasin dans lequel le service de limitation de débit de la passerelle tient le compteur du budget
assistantcore/ai-agent/crewaiun agent dont les requêtes de modèle vont à la passerelle
certscore/security/cert-managercert-manager, qui émet le certificat que sert le webhook du contrôleur

Les arêtes uses de la passerelle partent de son socket extension, vers le contrôleur ; de models, vers le modèle, en portant comme credential la clé que la passerelle présente à OpenAI ; et de cache, vers le magasin, en portant le mot de passe que le service de limitation de débit lui présente. L’arête model de l’agent pointe vers la passerelle, et non vers le modèle. Un seul rattachement de Feature sur la passerelle, budget : l’Aggregate écrit ce qui est compté, total_tokens, et le trafic de qui une limite couvre, gateway — tout ce que sert la passerelle — et la Release écrit combien et sur quelle durée : vingt millions de tokens par mois calendaire.

Le Manifest lie chaque information d’identification à k8s-existing-secret, qui oriente une charge de travail vers un Secret déjà présent dans son namespace et n’en rend aucun, si bien qu’aucune clé ni aucun mot de passe ne figure dans l’Aggregate, dans la Release ou dans la sortie rendue. Les noms des Secrets sont deux paramètres que la Release remplit, et le slot password propre au magasin lit le même paramètre que la connexion cache de la passerelle, si bien que le magasin et le service qui lui présente le mot de passe nomment un seul et même Secret.

La Release déclare où s’exécute chaque charge de travail : cert-manager dans cert-manager, le contrôleur dans envoy-ai-gateway-system, l’agent dans assistant et la passerelle dans envoy-gateway-system — le contrôleur y cherche le plan de contrôle de la passerelle, et le build s’arrête si la passerelle est placée ailleurs — avec le magasin à côté d’elle. Le modèle n’exécute rien : son unique fichier, un Service qui associe un nom interne au cluster à l’hôte d’OpenAI, ne nomme aucun namespace, et la passerelle atteint OpenAI au point de terminaison que publie le modèle plutôt que par ce Service.

cert-manager est déclaré, pas supposé

Le webhook du contrôleur sert un certificat qu’émet cert-manager : sa Recipe rend un Certificate cert-manager et l’Issuer autosigné qui le signe, que seul un cert-manager en cours d’exécution réconcilie. Le compilateur ne peut pas examiner un cluster pour voir si un cert-manager y tourne, si bien que l’espace de travail déclare cert-manager plutôt que de le supposer : certs se trouve dans l’Aggregate à côté du contrôleur, et le build rend cert-manager avec tout le reste.

Un cluster exécute un seul cert-manager. Si le vôtre en exécute déjà un, retirez certs de l’Aggregate et de la Release avant le build ; le build rend alors les mêmes fichiers, moins ceux de cert-manager.

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 envoy-ai-gateway-token-budget

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

Terminal window
cd envoy-ai-gateway-token-budget

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. Résolvez-en un d’abord, ou laissez le build le remplir :

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

La résolution épingle les trois charts que rendent les Recipes — ceux d’Envoy Gateway et d’Envoy AI Gateway depuis Docker Hub, celui de cert-manager depuis quay.io — si bien qu’elle a besoin du réseau. Cet espace de travail résout les entités du catalogue depuis le registre par défaut que nomme .aggrega-config.yaml.

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

Pull complete: release.lock (entities=26, source_artifacts=3, external_inputs=0)
[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and the total build time, which differs per run]
Build completed: 113 files written to <workspace>/dist

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 `envoy-ai-gateway-token-budget`, appelez une fois l’outil `scaffold` avec `example` défini sur `envoy-ai-gateway-token-budget` et sans `dir` : il écrit l’exemple dans un nouveau dossier `envoy-ai-gateway-token-budget`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `envoy-ai-gateway-token-budget`, `release` défini sur `release.yaml`, `auto_pull` défini sur true et `write` défini sur true. Indiquez-moi les fichiers écrits par le build ; ils se trouvent sous `envoy-ai-gateway-token-budget/dist/`.

L’arborescence rendue

dist/helm/
├── ai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yaml
[… omitted: the controller's two cluster roles and their bindings]
├── ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
├── ai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yaml
├── ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml
├── ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml
[… omitted: the controller's service account]
├── ai-controller/
│ ├── aigateway.envoyproxy.io_aigatewayroutes.yaml
[… omitted: the other five AI Gateway resource definitions]
├── assistant-deployment.yaml
[… omitted: the files cert-manager's chart renders, each named certs-…]
├── chat-service.yaml
├── counters-default-service.yaml
├── counters-deployment.yaml
[… omitted: Envoy Gateway's cluster roles and their bindings]
├── edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml
[… omitted: the resource definitions Envoy Gateway's chart installs]
├── edge-deployment-envoy-gateway-system-envoy-gateway.yaml
[… omitted: the rest of Envoy Gateway's chart — its certificate job, admission configurations, roles, bindings, Service and service accounts]
└── edge/
├── gateway.yaml
├── gatewayclass.yaml
└── models.yaml

Le budget n’apporte aucun fichier à lui. Ce qu’il fait est écrit dans deux des fichiers de la passerelle : dist/helm/edge/models.yaml, qui contient la route d’IA et les ressources atteignant le modèle, et la configuration du plan de contrôle, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.

Le budget, tel que la passerelle le lit

Depuis models.yaml, la route d’IA :

apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIGatewayRoute
metadata:
[… omitted: the labels and annotations every rendered resource carries]
name: edge-models
namespace: "envoy-gateway-system"
spec:
parentRefs:
- name: edge
kind: Gateway
group: gateway.networking.k8s.io
llmRequestCosts:
- metadataKey: llm_total_token
type: TotalToken
rules:
- matches:
- headers:
- type: Exact
name: x-ai-eg-model
value: "assistant"
backendRefs:
- name: edge-assistant
modelNameOverride: "gpt-4o-mini"

et, depuis le même fichier, la politique de trafic qui la limite, nommée comme la route qu’elle cible :

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
[… omitted: the labels and annotations every rendered resource carries]
name: edge-models
namespace: "envoy-gateway-system"
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: edge-models
rateLimit:
global:
rules:
- limit:
requests: 20000000
unit: Month
shared: true
cost:
request:
from: Number
number: 0
response:
from: Metadata
metadata:
namespace: io.envoy.ai_gateway
key: llm_total_token

Voici la clé envoy-gateway.yaml de la configuration du plan de contrôle :

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyGateway
extensionApis:
enableBackend: true
enableEnvoyPatchPolicy: true
extensionManager:
hooks:
xdsTranslator:
post:
- Translation
- Cluster
- Route
translation:
cluster:
includeAll: true
listener:
includeAll: true
route:
includeAll: true
secret:
includeAll: true
service:
fqdn:
hostname: ai-controller.envoy-ai-gateway-system.svc.cluster.local
port: 1063
gateway:
controllerName: gateway.envoyproxy.io/gatewayclass-controller
logging:
level:
default: info
provider:
kubernetes:
rateLimitDeployment:
container:
env:
- name: REDIS_AUTH
valueFrom:
secretKeyRef:
key: password
name: counter-store-password
- name: USE_CALENDAR_MONTH_RATE_LIMIT
value: "true"
image: docker.io/envoyproxy/ratelimit:8fe6ea42
patch:
type: StrategicMerge
value:
spec:
template:
spec:
containers:
- imagePullPolicy: IfNotPresent
name: envoy-ratelimit
shutdownManager:
image: docker.io/envoyproxy/gateway:v1.9.1
type: Kubernetes
rateLimit:
backend:
redis:
url: counters-default.envoy-gateway-system.svc.cluster.local:6379
type: Redis
failClosed: true

Ce qu’il faut en retenir :

Le coût se trouve sur la route d’IA, la limite sur la route qu’elle devient. Envoy AI Gateway lit les total_tokens que déclare chaque réponse du modèle et les écrit dans les métadonnées de la requête sous llm_total_token : c’est ce que déclare llmRequestCosts. Le contrôleur transforme la route d’IA en une route HTTP du même nom, edge-models, et la politique de trafic cible cette route, si bien que le budget couvre le trafic de modèle et aucune autre route attachée à la passerelle.

Une réponse est imputée lorsqu’elle se termine. cost.request n’impute rien à l’arrivée d’une requête ; cost.response impute les tokens de la réponse une fois la réponse terminée. Une requête est refusée dès que le compteur imputé jusque-là dépasse limit.

Un seul compteur pour toute la passerelle. shared: true tient un seul compteur pour toutes les règles de la route — la portée gateway que le rattachement a demandée. Avec scope: model, la Recipe écrit une règle par connexion sur le socket models, chacune correspondant au nom de modèle qu’une requête porte dans x-ai-eg-model, si bien que chaque modèle est compté à part.

La période est une unité de l’horloge. 1mo s’écrit unit: Month, et la configuration indique au service de limitation de débit d’Envoy Gateway, via USE_CALENDAR_MONTH_RATE_LIMIT, de compter un Month du premier au dernier jour d’un mois calendaire. Ce paramètre appartient au service, si bien qu’il s’applique à toute limite de débit Month que tient cette installation d’Envoy Gateway, celle du budget comme toute autre. Chaque fenêtre commence à un point fixe de l’horloge UTC plutôt qu’avec une première requête : un jour à 00:00 UTC, une semaine un jeudi.

Le compteur vit dans le magasin du socket cache. Le bloc rateLimit active le service de limitation de débit propre à Envoy Gateway, que le plan de contrôle crée dans son namespace et active pour chaque passerelle qu’il sert, et l’oriente vers le Redis qu’atteint le socket cache de la passerelle. Le magasin publie son hôte sans namespace, si bien que la passerelle le qualifie avec celui dans lequel la Release place le magasin.

Une vérification qui ne reçoit aucune réponse refuse la requête. failClosed: true fait refuser par Envoy une requête de modèle avec HTTP 500 tant que le magasin ou le service de limitation de débit est injoignable, ou qu’une vérification dure plus longtemps que le délai de limitation de débit d’Envoy, 20 ms par défaut, plutôt que de la servir sans la compter. Ce paramètre appartient au plan de contrôle, si bien qu’il vaut pour toute limite de débit que tient cette installation d’Envoy Gateway, et qu’une limite de débit appliquée à la main à l’installation échoue aussi en mode fermé. La configuration ne le porte que tant que le budget est rattaché.

Aucun mot de passe n’y figure. Le service lit le mot de passe du magasin comme REDIS_AUTH, depuis le Secret que nomme l’information d’identification de la connexion cache, counter-store-password, qu’il résout dans son propre namespace, celui de la passerelle. Le magasin, counters-deployment.yaml, démarre avec --requirepass lu depuis le même Secret.

Le chemin de l’agent au modèle

Depuis assistant-deployment.yaml, l’env du conteneur de l’agent :

env:
- name: OPENAI_BASE_URL
value: http://envoy-envoy-gateway-system-edge-06431a46.envoy-gateway-system.svc.cluster.local:80/v1
- name: MODEL
value: assistant
- name: CREWAI_ALLOW_DELEGATION
value: "false"
- name: CREWAI_BACKSTORY
value: a help-desk agent answering customers
- name: CREWAI_GOAL
value: answer questions about the product
- name: CREWAI_LOG_LEVEL
value: DEBUG
- name: CREWAI_ROLE
value: support assistant

L’agent lit les deux clés que publie la passerelle, qui sont les deux que publie un modèle, si bien que sa Recipe les lit comme elle lirait celles d’un modèle. Les variables CREWAI_ portent les valeurs propres de l’agent, sous les noms que leur donne par défaut le Component CrewAI. L’adresse est le Service qu’Envoy Gateway crée pour le plan de données de la passerelle, nommé à partir du namespace de la passerelle, de son nom et d’un hachage des deux, et qualifié avec envoy-gateway-system, si bien qu’elle se résout depuis le namespace de l’agent. Le nom du modèle est l’alias assistant ; la route envoie une requête qui le nomme au backend du modèle, en demandant gpt-4o-mini à la place.

Le backend atteint OpenAI au point de terminaison que publie le modèle : models.yaml contient un Backend Envoy Gateway pour api.openai.com sur le port 443, une politique TLS vérifiant son certificat par rapport aux ancres de confiance du système, un AIServiceBackend pour l’API OpenAI sous /v1, et la politique de sécurité présentant la clé, edge-assistant, dont la spec est :

spec:
targetRefs:
- group: aigateway.envoyproxy.io
kind: AIServiceBackend
name: edge-assistant
type: APIKey
apiKey:
secretRef:
name: "openai-api-key"

Le contrôleur lit la clé depuis ce Secret, dans le namespace de la passerelle, sous la clé de données apiKey, et l’envoie à OpenAI comme bearer token, si bien qu’aucun fichier rendu ne la contient et que l’agent ne la détient jamais. La passerelle appelle le contrôleur à l’adresse que publie le contrôleur, qualifiée avec le namespace dans lequel la Release le place — le bloc extensionManager ci-dessus. Tant qu’un modèle est câblé, la passerelle reçoit aussi la politique de trafic client d’Envoy AI Gateway, edge-client-buffer-limit dans models.yaml, qui porte à 50Mi le tampon autorisé pour chaque connexion entrante ; elle cible la passerelle, si bien qu’elle s’applique à toute route attachée à celle-ci.

Ce que fait la passerelle à l’exécution

À chaque requête de modèle, la passerelle demande au service de limitation de débit si les tokens imputés jusque-là ce mois-ci dépassent limit. Dès que c’est le cas, elle répond aux requêtes de modèle avec HTTP 429 jusqu’à la fin du mois. Les tokens d’une requête sont ajoutés une fois sa réponse terminée, si bien que la requête qui franchit la limite est servie, tout comme toute requête traitée à côté d’elle. Tant que le magasin ou le service de limitation de débit est injoignable, ou qu’une vérification dure plus longtemps que le délai de limitation de débit d’Envoy, elle refuse les requêtes de modèle avec HTTP 500, en vertu du paramètre failClosed ci-dessus, si bien qu’aucune requête de modèle n’est admise tant que son compteur ne peut pas être vérifié.

Ce qui en découle relève du comportement du produit plutôt que de la configuration :

  • Une requête admise juste avant une panne est quand même servie et non comptée. Ses tokens sont imputés après la réponse, si bien qu’une réponse qui se termine alors que le magasin ou le service est injoignable n’ajoute rien au compteur.
  • Un magasin qui tient le compteur en mémoire recommence chaque fenêtre lorsqu’il redémarre. core/datastore/redis garde ses entrées en mémoire par défaut, si bien qu’un magasin redémarré perd le compteur tenu jusque-là, et le reste du mois est compté à partir de zéro.
  • Une réponse qui ne déclare aucune utilisation n’ajoute rien. Le compteur correspond à ce que déclare chaque réponse ; Envoy AI Gateway demande au modèle de déclarer son utilisation à la fin d’une réponse en streaming aussi.

Ce qui arrête le build

Chacun de ces cas est une phrase qu’affiche le build, nommant ce qu’il faut changer :

  • Un coût en dollars américains. Définissez unit: usd dans le rattachement et le build s’arrête avant que quoi que ce soit ne soit rendu :

    [… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars]
    [CATALOG_ERROR E0033]
    Recipe/FeatureRecipe assertions
    caused by: FeatureRecipe "period-budget-envoy-gateway" instance "edge" assertion "unit_is_a_token_count": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/period-budget attachment "budget" on "edge" asks for unit usd, but core/gateway/envoy-gateway, which declares dataplane.aggrega.ai/period-budget: tokens, counts the tokens each model's reply reports and prices nothing, so it keeps no budget in US dollars; set unit to total_tokens, prompt_tokens or completion_tokens, or attach the Feature to a gateway that counts cost
  • Un budget par appelant, scope: caller. La passerelle ne distingue les appelants que par un en-tête que l’appelant écrit lui-même, et rien sur ce chemin ne vérifie qui est l’appelant, si bien qu’un appelant envoyant une nouvelle valeur démarrerait un nouveau budget et qu’un appelant n’en envoyant aucune ne serait pas compté.

  • Toute période pour laquelle la passerelle n’a pas de fenêtre. Elle tient une unité entière de sa limite de débit : 1s, 1m, 1h, 1d, 7d, 30d, 365d ou 1mo, ou la même durée écrite autrement, comme 24h. Avec 2h, 14d ou 2mo, le build s’arrête.

  • Une limite qui n’est pas un nombre entier de tokens, ou une limite supérieure à 4294967295.

  • Un second rattachement de core/period-budget sur la passerelle, qui écrit un seul budget sur la route servant ses modèles.

  • Rien de câblé au socket models, ce qui ne laisse aucune route de modèle à compter, ni au socket cache, ce qui ne laisse au compteur aucun endroit où vivre. Retirez seulement la connexion du modèle, et c’est le Component propre à la passerelle qui s’arrête en premier, parce que values.model nomme un alias que rien ne sert.

  • Un magasin sur le socket cache qui ne parle pas le protocole Redis — un magasin publiant un protocole autre que redis ou valkey.

  • La passerelle placée en dehors de envoy-gateway-system alors que le contrôleur est câblé à son socket extension.

Avant de l’appliquer

L’arborescence ne contient aucun Namespace ni aucun Secret, si bien qu’un cluster recevant dist/helm/ a besoin de :

  • Les namespaces cert-manager, envoy-ai-gateway-system, envoy-gateway-system et assistant.
  • Les Secrets, dans envoy-gateway-system : openai-api-key, contenant la clé d’OpenAI sous la clé de données apiKey, et counter-store-password, contenant le mot de passe du magasin sous password. Une charge de travail référençant un Secret qui n’existe pas ne démarre pas.
  • Un apply côté serveur pour deux des définitions d’AI Gateway, aigateway.envoyproxy.io_backendsecuritypolicies.yaml et aigateway.envoyproxy.io_mcproutes.yaml, qui sont plus grandes que la copie de l’objet appliqué qu’enregistre un apply côté client, si bien qu’un apply côté client les refuse.
  • Une image pour l’agent. La Release nomme registry.example/crew-assistant:1.0.0 ; le catalogue empaquette le runtime de l’agent, et la crew qu’il exécute est votre propre code.

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

Le compilateur achemine la limite, l’unité et le coût en tokens dans les ressources de la passerelle sous forme de chaînes, ainsi que le point de terminaison du modèle, l’adresse du magasin et l’adresse du contrôleur à partir de ce que chacun publie. Il n’atteint pas OpenAI, ne sait pas si une réponse déclare ses tokens et ne compte rien lui-même ; il ne vérifie pas que les Secrets existent ni que cert-manager s’exécute. Chaque arrêt ci-dessus est déclaré par les entités propres au catalogue, sous forme d’assertion dans la réalisation du budget ou dans le Component ou la Recipe de la passerelle, et aucun ne repose sur une quelconque compréhension du trafic.

L’adapter

  • Une limite par modèle. Câblez d’autres modèles au socket models et définissez scope: model : chacun reçoit une règle, et un compteur, qui lui sont propres.
  • Compter un seul côté. Définissez unit: prompt_tokens pour compter ce que lit le modèle, ou completion_tokens pour ce qu’il écrit.
  • Renvoyer une requête en échec. Rattachez core/retry-policy à la passerelle avec max_attempts et associez-la dans le Manifest à helm/retry-policy-envoy-gateway : la même politique de trafic, edge-models, gagne un retry à côté de la limite de débit, parce qu’Envoy Gateway attache une seule politique de trafic à une route.
  • Une fenêtre plus courte ou de longueur fixe. Définissez period dans la Release à l’une des durées ci-dessus : 1d est un jour à partir de 00:00 UTC, et 30d correspond à 30 jours comptés depuis le 1er janvier 1970 plutôt qu’à un mois calendaire. Avec toute période autre que 1mo, la configuration laisse le paramètre de mois calendaire non défini.
  • Routes MCP. Le contrôleur chiffre les identifiants de session MCP sous une clé dérivée de la graine contenue dans le Secret que nomme infra.mcp_session_seed_secret sur ai-controller ; si aucun n’est nommé, comme ici, la graine est la valeur par défaut publiée de son chart, donc nommez-en un avant de servir une route MCP par son intermédiaire.