Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Envoy Gateway delante de OpenAI, con un presupuesto mensual de tokens

Un equipo pone gpt-4o-mini de OpenAI detrás de un gateway interno del clúster, quiere un tope a los tokens que el gateway gasta en él cada mes de calendario, y dirige su agente al gateway en lugar de a OpenAI. Este espacio de trabajo compila eso a manifiestos de Kubernetes: Envoy Gateway sirviendo el modelo mediante Envoy AI Gateway, con core/period-budget vinculado, un Redis que lleva el recuento, y un agente de CrewAI que envía sus solicitudes al modelo a través del gateway.

La página también muestra lo que este gateway se niega a contar: un presupuesto en dólares estadounidenses detiene la compilación, y también un presupuesto por llamador.

Este workspace no crea ninguna entidad de catálogo propia. Los tres archivos de entidad de aquí — un Aggregate, un Manifest y una Release — son todo lo que se escribe.

Lo que construye

instanciaComponent del catálogoqué es aquí
edgecore/gateway/envoy-gatewayel gateway, que sirve un alias, assistant, del modelo chat
ai-controllercore/gateway/envoy-ai-gateway-operatorel controlador de Envoy AI Gateway, al que el gateway llama como su servidor de extensión, instalado con las seis definiciones de recursos de AI Gateway
chatcore/ai-model/openaigpt-4o-mini de OpenAI, alcanzado como referencia: nada se ejecuta para él en el clúster
counterscore/datastore/redisel almacén en el que el servicio de limitación de tasa del gateway guarda el recuento del presupuesto
assistantcore/ai-agent/crewaiun agente cuyas solicitudes al modelo van al gateway
certscore/security/cert-managercert-manager, que emite el certificado que sirve el webhook del controlador

Las aristas uses del gateway salen de su socket extension, hacia el controlador; de models, hacia el modelo, llevando como su credential la clave que el gateway presenta a OpenAI; y de cache, hacia el almacén, llevando la contraseña que el servicio de limitación de tasa le presenta. La arista model del agente apunta al gateway, no al modelo. Una sola vinculación de Feature en el gateway, budget: el Aggregate escribe qué se cuenta, total_tokens, y de quién es el tráfico que cubre un límite, gateway — todo lo que sirve el gateway —, y la Release escribe cuánto y durante cuánto tiempo: veinte millones de tokens por mes de calendario.

El Manifest enlaza cada credencial a k8s-existing-secret, que dirige una carga de trabajo a un Secret que ya está en su namespace y no renderiza ninguno, así que ninguna clave ni contraseña está en el Aggregate, en la Release ni en la salida renderizada. Los nombres de los Secrets son dos parámetros que la Release cumple, y el propio slot password del almacén lee el mismo parámetro que la conexión cache del gateway, así que el almacén y el servicio que le presenta la contraseña nombran un único Secret.

La Release declara dónde se ejecuta cada carga de trabajo: cert-manager en cert-manager, el controlador en envoy-ai-gateway-system, el agente en assistant y el gateway en envoy-gateway-system — el controlador busca allí el plano de control del gateway, y la compilación se detiene si el gateway se ubica en cualquier otro lugar —, con el almacén junto a él. El modelo no ejecuta nada: su único archivo, un Service que asigna un nombre interno del clúster al host de OpenAI, no nombra ningún namespace, y el gateway alcanza OpenAI en el endpoint que publica el modelo en lugar de a través de ese Service.

cert-manager se declara, no se presupone

El webhook del controlador sirve un certificado que emite cert-manager: su Recipe renderiza un Certificate de cert-manager y el Issuer autofirmado que lo firma, que solo un cert-manager en ejecución concilia. El compilador no puede mirar un clúster para ver si allí se ejecuta uno, así que el espacio de trabajo declara cert-manager en lugar de presuponerlo: certs está en el Aggregate junto al controlador, y la compilación renderiza cert-manager con todo lo demás.

Un clúster ejecuta un solo cert-manager. Si el tuyo ya ejecuta uno, quita certs del Aggregate y de la Release antes de compilar; la compilación renderiza entonces los mismos archivos, menos los propios de cert-manager.

Generar el ejemplo

Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.

Escribe el ejemplo en una carpeta nueva con su nombre:

Terminal window
aggrega scaffold --example envoy-ai-gateway-token-budget

Después imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:

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

Compilación

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

Una release necesita un lockfile antes de compilarse, y los lockfiles se generan en lugar de distribuirse, así que un clon recién hecho no tiene ninguno. Resuelve uno primero, o deja que la compilación lo rellene:

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 resolución fija los tres charts que renderizan las Recipes — el de Envoy Gateway y el de Envoy AI Gateway desde Docker Hub, el de cert-manager desde quay.io —, así que necesita la red. Este espacio de trabajo resuelve las entidades del catálogo desde el registro predeterminado que nombra .aggrega-config.yaml.

Compilar con --auto-pull imprime, con <workspace> en lugar de la carpeta de este ejemplo:

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

Con un asistente de IA

Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.

Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `envoy-ai-gateway-token-budget`, llama una vez a la herramienta `scaffold` con `example` establecido en `envoy-ai-gateway-token-budget` y sin `dir`: escribe el ejemplo en una nueva carpeta `envoy-ai-gateway-token-budget`. Después llama a la herramienta `build` con `workspace_root` establecido en `envoy-ai-gateway-token-budget`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `envoy-ai-gateway-token-budget/dist/`.

El árbol renderizado

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

El presupuesto no aporta ningún archivo propio. Lo que hace se escribe en dos de los archivos del gateway: dist/helm/edge/models.yaml, que contiene la ruta de IA y los recursos que alcanzan el modelo, y la configuración del plano de control, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.

El presupuesto, tal como lo lee el gateway

De models.yaml, la ruta de 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"

y, del mismo archivo, la política de tráfico que la limita, nombrada como la ruta a la que se dirige:

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

Esta es la clave envoy-gateway.yaml de la configuración del plano de control:

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

Qué leer en ellos:

El costo está en la ruta de IA, el límite en la ruta en la que se convierte. Envoy AI Gateway lee los total_tokens que informa cada respuesta del modelo y los escribe en los metadatos de la solicitud bajo llm_total_token: eso es lo que declara llmRequestCosts. El controlador convierte la ruta de IA en una ruta HTTP con el mismo nombre, edge-models, y la política de tráfico se dirige a esa ruta, así que el presupuesto cubre el tráfico del modelo y ninguna otra ruta asociada al gateway.

Una respuesta se cobra cuando se completa. cost.request no cobra nada al llegar una solicitud; cost.response cobra los tokens de la respuesta una vez que la respuesta está completa. Una solicitud se rechaza en cuanto el recuento cobrado hasta entonces supera limit.

Un solo recuento para todo el gateway. shared: true mantiene un solo recuento en todas las reglas de la ruta — el ámbito gateway que pidió la vinculación. Con scope: model, la Recipe escribe una regla por conexión en el socket models, cada una coincidente con el nombre de modelo que una solicitud lleva en x-ai-eg-model, así que cada modelo se cuenta por separado.

El periodo es una unidad del reloj. 1mo se escribe como unit: Month, y la configuración indica al servicio de limitación de tasa de Envoy Gateway, mediante USE_CALENDAR_MONTH_RATE_LIMIT, que cuente un Month desde el primer día de un mes de calendario hasta el último. Ese ajuste pertenece al servicio, así que se aplica a todo límite de tasa Month que mantiene esta instalación de Envoy Gateway, el del presupuesto y cualquier otro. Cada ventana empieza en un punto fijo del reloj UTC en lugar de con una primera solicitud: un día a las 00:00 UTC, una semana un jueves.

El recuento vive en el almacén del socket cache. El bloque rateLimit activa el propio servicio de limitación de tasa de Envoy Gateway, que el plano de control crea en su namespace y activa para cada gateway que sirve, y lo dirige al Redis que alcanza el socket cache del gateway. El almacén publica su host sin namespace, así que el gateway lo cualifica con el namespace en el que la Release ubica el almacén.

Una comprobación que no recibe respuesta rechaza la solicitud. failClosed: true hace que Envoy rechace una solicitud al modelo con HTTP 500 mientras no se puede alcanzar el almacén o el servicio de limitación de tasa, o una comprobación tarda más que el tiempo de espera de limitación de tasa de Envoy, 20 ms de forma predeterminada, en lugar de servirla y no contarla. Ese ajuste pertenece al plano de control, así que rige para todo límite de tasa que mantiene esta instalación de Envoy Gateway, y un límite de tasa aplicado a mano a la instalación también falla en modo cerrado. La configuración lo lleva solo mientras el presupuesto está vinculado.

No contiene ninguna contraseña. El servicio lee la contraseña del almacén como REDIS_AUTH, del Secret que nombra la credencial de la conexión cache, counter-store-password, que resuelve en su propio namespace, el del gateway. El almacén, counters-deployment.yaml, arranca con --requirepass leído del mismo Secret.

El camino del agente al modelo

De assistant-deployment.yaml, el env del contenedor del agente:

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

El agente lee las dos claves que publica el gateway, que son las dos que publica un modelo, así que su Recipe las lee como leería las de un modelo. Las variables CREWAI_ llevan los valores propios del agente, con los nombres que el Component de CrewAI les da por defecto. La dirección es el Service que Envoy Gateway crea para el plano de datos del gateway, nombrado a partir del namespace del gateway, su nombre y un hash de ambos, y cualificado con envoy-gateway-system, así que se resuelve desde el namespace del agente. El nombre del modelo es el alias assistant; la ruta envía una solicitud que lo nombra al backend del modelo, pidiendo en su lugar gpt-4o-mini.

El backend alcanza OpenAI en el endpoint que publica el modelo: models.yaml contiene un Backend de Envoy Gateway para api.openai.com en el puerto 443, una política TLS que comprueba su certificado frente a los anclajes de confianza del sistema, un AIServiceBackend para la API de OpenAI bajo /v1, y la política de seguridad que presenta la clave, edge-assistant, cuyo spec es:

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

El controlador lee la clave de ese Secret, en el namespace del gateway, bajo la clave de datos apiKey, y la envía a OpenAI como bearer token, así que ningún archivo renderizado la contiene y el agente nunca la tiene. El gateway llama al controlador en la dirección que publica el controlador, cualificada con el namespace en el que la Release lo ubica — el bloque extensionManager de arriba. Mientras hay un modelo conectado, el gateway recibe también la política de tráfico de cliente de Envoy AI Gateway, edge-client-buffer-limit en models.yaml, que eleva a 50Mi el búfer permitido a cada conexión entrante; se dirige al gateway, así que se aplica a todas las rutas asociadas a él.

Qué hace el gateway en tiempo de ejecución

En cada solicitud al modelo, el gateway pregunta al servicio de limitación de tasa si los tokens cobrados hasta ahora este mes superan limit. Una vez que lo hacen, responde a las solicitudes al modelo con HTTP 429 hasta que termina el mes. Los tokens de una solicitud se suman una vez que su respuesta está completa, así que la solicitud que cruza el límite se sirve, y también cualquier solicitud respondida junto a ella. Mientras no se puede alcanzar el almacén o el servicio de limitación de tasa, o una comprobación tarda más que el tiempo de espera de limitación de tasa de Envoy, rechaza las solicitudes al modelo con HTTP 500, según el ajuste failClosed de arriba, así que no se admite ninguna solicitud al modelo mientras no se puede comprobar su recuento.

Lo que se deriva de eso es comportamiento del producto y no configuración:

  • Una solicitud admitida justo antes de una interrupción se sigue sirviendo y no se cuenta. Sus tokens se cobran después de la respuesta, así que una respuesta que se completa mientras no se puede alcanzar el almacén o el servicio no suma nada al recuento.
  • Un almacén que guarda el recuento en memoria vuelve a empezar cada ventana cuando se reinicia. core/datastore/redis guarda sus entradas en memoria de forma predeterminada, así que un almacén reiniciado pierde el recuento llevado hasta entonces, y el resto del mes se cuenta desde cero.
  • Una respuesta que no informa ningún uso no suma nada. El recuento es lo que informa cada respuesta; Envoy AI Gateway pide al modelo que informe su uso también al final de una respuesta en streaming.

Qué detiene la compilación

Cada uno de estos casos es una frase que imprime la compilación, y que nombra qué cambiar:

  • Un costo en dólares estadounidenses. Establece unit: usd en la vinculación y la compilación se detiene antes de renderizar nada:

    [… 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 presupuesto por llamador, scope: caller. El gateway distingue a los llamadores solo por un encabezado que el propio llamador escribe, y nada en este camino verifica quién es el llamador, así que un llamador que envíe un valor nuevo iniciaría un presupuesto nuevo y uno que no envíe ninguno no se contaría.

  • Cualquier periodo para el que el gateway no tenga ventana. Mantiene una unidad entera de su límite de tasa: 1s, 1m, 1h, 1d, 7d, 30d, 365d o 1mo, o la misma duración escrita de otro modo, como 24h. Con 2h, 14d o 2mo la compilación se detiene.

  • Un límite que no es un número entero de tokens, o uno superior a 4294967295.

  • Una segunda vinculación de core/period-budget en el gateway, que escribe un único presupuesto en la ruta que sirve sus modelos.

  • Nada conectado al socket models, lo que no deja ninguna ruta de modelo que contar, ni al socket cache, lo que no deja al recuento ningún lugar donde vivir. Quita solo la conexión del modelo y el propio Component del gateway se detiene primero, porque values.model nombra un alias que nada sirve.

  • Un almacén en el socket cache que no habla el protocolo de Redis — uno que publica un protocolo distinto de redis o valkey.

  • El gateway colocado fuera de envoy-gateway-system mientras el controlador está conectado a su socket extension.

Antes de aplicarlo

El árbol no contiene ningún Namespace ni ningún Secret, así que un clúster que recibe dist/helm/ necesita:

  • Los namespaces cert-manager, envoy-ai-gateway-system, envoy-gateway-system y assistant.
  • Los Secrets, en envoy-gateway-system: openai-api-key, que guarda la clave de OpenAI bajo la clave de datos apiKey, y counter-store-password, que guarda la contraseña del almacén bajo password. Una carga de trabajo que hace referencia a un Secret que no existe no arranca.
  • Un apply del lado del servidor para dos de las definiciones de AI Gateway, aigateway.envoyproxy.io_backendsecuritypolicies.yaml y aigateway.envoyproxy.io_mcproutes.yaml, que son más grandes que la copia del objeto aplicado que registra un apply del lado del cliente, así que un apply del lado del cliente las rechaza.
  • Una imagen para el agente. La Release nombra registry.example/crew-assistant:1.0.0; el catálogo empaqueta el runtime del agente, y la crew que ejecuta es tu propio código.

Dónde el compilador no interpreta

El compilador canaliza el límite, la unidad y el costo en tokens a los recursos del gateway como cadenas, y el endpoint del modelo, la dirección del almacén y la dirección del controlador a partir de lo que publica cada uno. No llega a OpenAI, no sabe si una respuesta informa sus tokens y no cuenta nada por sí mismo; no comprueba que los Secrets existan ni que cert-manager se esté ejecutando. Cada detención anterior la declaran las propias entidades del catálogo, como una aserción en la realización del presupuesto o en el Component o la Recipe del gateway, y ninguna se basa en comprensión alguna del tráfico.

Adaptarlo

  • Un límite por modelo. Conecta más modelos al socket models y establece scope: model: cada uno recibe una regla, y un recuento, propios.
  • Contar un solo lado. Establece unit: prompt_tokens para contar lo que lee el modelo, o completion_tokens para lo que escribe.
  • Volver a enviar una solicitud fallida. Vincula core/retry-policy al gateway con max_attempts y asígnala en el Manifest a helm/retry-policy-envoy-gateway: la misma política de tráfico, edge-models, gana un retry junto al límite de tasa, porque Envoy Gateway asocia una sola política de tráfico a una ruta.
  • Una ventana más corta o de longitud fija. Establece period en la Release en una de las duraciones anteriores: 1d es un día desde las 00:00 UTC, y 30d son 30 días contados desde el 1 de enero de 1970 en lugar de un mes de calendario. Con cualquier periodo distinto de 1mo, la configuración deja sin establecer el ajuste del mes de calendario.
  • Rutas MCP. El controlador cifra los identificadores de sesión MCP con una clave derivada de la semilla del Secret que infra.mcp_session_seed_secret nombra en ai-controller; si no se nombra ninguno, como aquí, la semilla es el valor predeterminado publicado de su chart, así que nombra uno antes de servir una ruta MCP a través de él.