Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Envoy Gateway na frente da OpenAI, com um orçamento mensal de tokens

Uma equipe coloca o gpt-4o-mini da OpenAI atrás de um gateway interno ao cluster, quer um teto para os tokens que o gateway gasta com ele a cada mês de calendário, e aponta o seu agente para o gateway em vez de para a OpenAI. Este espaço de trabalho compila isso para manifestos do Kubernetes: o Envoy Gateway servindo o modelo por meio do Envoy AI Gateway, com core/period-budget vinculado, um Redis mantendo a contagem, e um agente CrewAI enviando as suas requisições ao modelo por meio do gateway.

A página também mostra o que este gateway se recusa a contar: um orçamento em dólares americanos interrompe o build, assim como um orçamento por chamador.

Este workspace não cria nenhuma entidade de catálogo própria. Os três arquivos de entidade daqui — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.

O que ele constrói

instânciaComponent do catálogoo que é aqui
edgecore/gateway/envoy-gatewayo gateway, servindo um alias, assistant, a partir do modelo chat
ai-controllercore/gateway/envoy-ai-gateway-operatoro controlador do Envoy AI Gateway, que o gateway chama como seu servidor de extensão, instalado com as seis definições de recursos do AI Gateway
chatcore/ai-model/openaio gpt-4o-mini da OpenAI, alcançado como referência: nada é executado para ele no cluster
counterscore/datastore/rediso repositório no qual o serviço de limitação de taxa do gateway mantém a contagem do orçamento
assistantcore/ai-agent/crewaium agente cujas requisições ao modelo vão para o gateway
certscore/security/cert-managercert-manager, que emite o certificado que o webhook do controlador serve

As arestas uses do gateway partem do seu socket extension, para o controlador; de models, para o modelo, trazendo como seu credential a chave que o gateway apresenta à OpenAI; e de cache, para o repositório, trazendo a senha que o serviço de limitação de taxa apresenta a ele. A aresta model do agente aponta para o gateway, não para o modelo. Uma única vinculação de Feature no gateway, budget: o Aggregate escreve o que é contado, total_tokens, e de quem é o tráfego que um limite cobre, gateway — tudo o que o gateway serve —, e a Release escreve quanto e ao longo de quanto tempo: vinte milhões de tokens por mês de calendário.

O Manifest vincula toda credencial a k8s-existing-secret, que aponta uma carga de trabalho para um Secret já presente no seu namespace e não renderiza nenhum, de modo que nenhuma chave ou senha está no Aggregate, na Release ou na saída renderizada. Os nomes dos Secrets são dois parâmetros que a Release preenche, e o próprio slot password do repositório lê o mesmo parâmetro que a conexão cache do gateway, de modo que o repositório e o serviço que apresenta a senha a ele nomeiam um único Secret.

A Release declara onde cada carga de trabalho é executada: o cert-manager em cert-manager, o controlador em envoy-ai-gateway-system, o agente em assistant e o gateway em envoy-gateway-system — o controlador procura ali o plano de controle do gateway, e o build é interrompido se o gateway for colocado em qualquer outro lugar —, com o repositório ao lado dele. O modelo não executa nada: o seu único arquivo, um Service que mapeia um nome interno ao cluster para o host da OpenAI, não nomeia nenhum namespace, e o gateway alcança a OpenAI no endpoint que o modelo publica em vez de por meio desse Service.

cert-manager é declarado, não presumido

O webhook do controlador serve um certificado que o cert-manager emite: a sua Recipe renderiza um Certificate do cert-manager e o Issuer autoassinado que o assina, que só um cert-manager em execução reconcilia. O compilador não pode olhar um cluster para ver se há um em execução ali, então o espaço de trabalho declara o cert-manager em vez de presumi-lo: certs fica no Aggregate ao lado do controlador, e o build renderiza o cert-manager com todo o resto.

Um cluster executa um único cert-manager. Se o seu já executa um, remova certs do Aggregate e da Release antes do build; o build então renderiza os mesmos arquivos, menos os do próprio cert-manager.

Gerar o exemplo

Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.

Escreva o exemplo em uma nova pasta com o nome dele:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

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

Build

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

Uma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. Resolva um primeiro, ou deixe o build preenchê-lo:

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

A resolução fixa os três charts que as Recipes renderizam — o do Envoy Gateway e o do Envoy AI Gateway do Docker Hub, o do cert-manager do quay.io —, então precisa da rede. Este espaço de trabalho resolve as entidades do catálogo a partir do registro padrão que .aggrega-config.yaml nomeia.

O build com --auto-pull imprime, com <workspace> representando a pasta deste exemplo:

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

Com um assistente de IA

Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.

Use somente as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta do espaço de trabalho ainda não contém uma pasta `envoy-ai-gateway-token-budget`, chame uma vez a ferramenta `scaffold` com `example` definido como `envoy-ai-gateway-token-budget` e sem `dir`: ela grava o exemplo em uma nova pasta `envoy-ai-gateway-token-budget`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `envoy-ai-gateway-token-budget`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build gravou; eles ficam em `envoy-ai-gateway-token-budget/dist/`.

A árvore renderizada

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

O orçamento não traz nenhum arquivo próprio. O que ele faz é escrito em dois dos arquivos do gateway: dist/helm/edge/models.yaml, que contém a rota de IA e os recursos que alcançam o modelo, e a configuração do plano de controle, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.

O orçamento, como o gateway o lê

De models.yaml, a rota 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"

e, do mesmo arquivo, a política de tráfego que a limita, nomeada como a rota que ela tem como alvo:

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

Aqui está a chave envoy-gateway.yaml da configuração do plano de controle:

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

O que tirar deles:

O custo fica na rota de IA, o limite na rota em que ela se transforma. O Envoy AI Gateway lê os total_tokens que cada resposta do modelo informa e os escreve nos metadados da requisição sob llm_total_token: é isso que llmRequestCosts declara. O controlador transforma a rota de IA em uma rota HTTP com o mesmo nome, edge-models, e a política de tráfego tem essa rota como alvo, de modo que o orçamento cobre o tráfego do modelo e nenhuma outra rota anexada ao gateway.

Uma resposta é cobrada quando é concluída. cost.request não cobra nada quando uma requisição chega; cost.response cobra os tokens da resposta assim que a resposta está completa. Uma requisição é recusada assim que a contagem cobrada até então excede limit.

Uma única contagem para o gateway inteiro. shared: true mantém uma única contagem em todas as regras da rota — o escopo gateway que a vinculação pediu. Com scope: model, a Recipe escreve uma regra por conexão no socket models, cada uma correspondendo ao nome do modelo que uma requisição traz em x-ai-eg-model, de modo que cada modelo é contado separadamente.

O período é uma unidade no relógio. 1mo é escrito como unit: Month, e a configuração instrui o serviço de limitação de taxa do Envoy Gateway, por meio de USE_CALENDAR_MONTH_RATE_LIMIT, a contar um Month do primeiro ao último dia de um mês de calendário. Essa configuração pertence ao serviço, então se aplica a todo limite de taxa Month que esta instalação do Envoy Gateway mantém, o do orçamento e qualquer outro. Toda janela começa em um ponto fixo do relógio UTC em vez de com uma primeira requisição: um dia às 00:00 UTC, uma semana em uma quinta-feira.

A contagem vive no repositório do socket cache. O bloco rateLimit ativa o próprio serviço de limitação de taxa do Envoy Gateway, que o plano de controle cria no seu namespace e ativa para todo gateway que serve, e o aponta para o Redis que o socket cache do gateway alcança. O repositório publica o seu host sem namespace, então o gateway o qualifica com o namespace em que a Release coloca o repositório.

Uma verificação que não recebe resposta recusa a requisição. failClosed: true faz o Envoy recusar uma requisição ao modelo com HTTP 500 enquanto o repositório ou o serviço de limitação de taxa não podem ser alcançados, ou uma verificação demora mais que o timeout de limitação de taxa do Envoy, 20 ms por padrão, em vez de servi-la e não contá-la. Essa configuração pertence ao plano de controle, então vale para todo limite de taxa que esta instalação do Envoy Gateway mantém, e um limite de taxa aplicado manualmente à instalação também falha fechado. A configuração a traz apenas enquanto o orçamento está vinculado.

Nenhuma senha está nela. O serviço lê a senha do repositório como REDIS_AUTH, do Secret que a credencial da conexão cache nomeia, counter-store-password, que ele resolve no seu próprio namespace, o do gateway. O repositório, counters-deployment.yaml, inicia com --requirepass lido do mesmo Secret.

O caminho do agente até o modelo

De assistant-deployment.yaml, o env do contêiner do 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

O agente lê as duas chaves que o gateway publica, que são as duas que um modelo publica, então a sua Recipe as lê como leria as de um modelo. As variáveis CREWAI_ levam os valores próprios do agente, com os nomes que o Component do CrewAI dá a elas por padrão. O endereço é o Service que o Envoy Gateway cria para o plano de dados do gateway, nomeado a partir do namespace do gateway, do seu nome e de um hash dos dois, e qualificado com envoy-gateway-system, de modo que é resolvido a partir do namespace do agente. O nome do modelo é o alias assistant; a rota envia uma requisição que o nomeia para o backend do modelo, pedindo gpt-4o-mini em vez disso.

O backend alcança a OpenAI no endpoint que o modelo publica: models.yaml traz um Backend do Envoy Gateway para api.openai.com na porta 443, uma política TLS que verifica o seu certificado em relação às âncoras de confiança do sistema, um AIServiceBackend para a API da OpenAI sob /v1, e a política de segurança que apresenta a chave, edge-assistant, cujo spec é:

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

O controlador lê a chave desse Secret, no namespace do gateway, sob a chave de dados apiKey, e a envia à OpenAI como bearer token, de modo que nenhum arquivo renderizado a contém e o agente nunca a detém. O gateway chama o controlador no endereço que o controlador publica, qualificado com o namespace em que a Release o coloca — o bloco extensionManager acima. Enquanto um modelo está ligado, o gateway recebe também a política de tráfego de cliente do Envoy AI Gateway, edge-client-buffer-limit em models.yaml, que eleva para 50Mi o buffer permitido a cada conexão de entrada; ela tem o gateway como alvo, então se aplica a toda rota anexada a ele.

O que o gateway faz em tempo de execução

A cada requisição ao modelo, o gateway pergunta ao serviço de limitação de taxa se os tokens cobrados até agora neste mês excedem limit. Assim que excedem, ele responde às requisições ao modelo com HTTP 429 até o mês terminar. Os tokens de uma requisição são somados assim que a sua resposta está completa, então a requisição que ultrapassa o limite é servida, assim como qualquer requisição respondida ao lado dela. Enquanto o repositório ou o serviço de limitação de taxa não podem ser alcançados, ou uma verificação demora mais que o timeout de limitação de taxa do Envoy, ele recusa as requisições ao modelo com HTTP 500, conforme a configuração failClosed acima, de modo que nenhuma requisição ao modelo é admitida enquanto a sua contagem não pode ser verificada.

O que decorre disso é comportamento do produto, e não configuração:

  • Uma requisição admitida pouco antes de uma interrupção ainda é servida e não é contada. Os seus tokens são cobrados depois da resposta, então uma resposta concluída enquanto o repositório ou o serviço não podem ser alcançados não acrescenta nada à contagem.
  • Um repositório que mantém a contagem em memória recomeça toda janela quando é reiniciado. core/datastore/redis mantém as suas entradas em memória por padrão, então um repositório reiniciado perde a contagem mantida até então, e o resto do mês é contado a partir do zero.
  • Uma resposta que não informa uso não acrescenta nada. A contagem é o que cada resposta informa; o Envoy AI Gateway pede ao modelo que informe o seu uso também no final de uma resposta em streaming.

O que interrompe o build

Cada um destes casos é uma frase que o build imprime, nomeando o que mudar:

  • Um custo em dólares americanos. Defina unit: usd na vinculação e o build é interrompido antes que qualquer coisa seja renderizada:

    [… 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
  • Um orçamento por chamador, scope: caller. O gateway distingue os chamadores apenas por um cabeçalho que o próprio chamador escreve, e nada neste caminho verifica quem é o chamador, então um chamador que envie um novo valor iniciaria um orçamento novo e um que não envie nenhum não seria contado.

  • Qualquer período para o qual o gateway não tem janela. Ele mantém uma unidade inteira do seu limite de taxa: 1s, 1m, 1h, 1d, 7d, 30d, 365d ou 1mo, ou a mesma duração escrita de outra forma, como 24h. Com 2h, 14d ou 2mo, o build é interrompido.

  • Um limite que não é um número inteiro de tokens, ou um acima de 4294967295.

  • Uma segunda vinculação de core/period-budget no gateway, que escreve um único orçamento na rota que serve os seus modelos.

  • Nada ligado ao socket models, o que não deixa nenhuma rota de modelo para contar, ou ao socket cache, o que não deixa à contagem nenhum lugar onde viver. Remova apenas a conexão do modelo e o próprio Component do gateway é interrompido primeiro, porque values.model nomeia um alias que nada serve.

  • Um repositório no socket cache que não fala o protocolo do Redis — um que publica um protocolo diferente de redis ou valkey.

  • O gateway colocado fora de envoy-gateway-system enquanto o controlador está ligado ao seu socket extension.

Antes de aplicá-lo

A árvore não contém nenhum Namespace nem nenhum Secret, então um cluster que recebe dist/helm/ precisa de:

  • Os namespaces cert-manager, envoy-ai-gateway-system, envoy-gateway-system e assistant.
  • Os Secrets, em envoy-gateway-system: openai-api-key, que guarda a chave da OpenAI sob a chave de dados apiKey, e counter-store-password, que guarda a senha do repositório sob password. Uma carga de trabalho que referencia um Secret inexistente não inicia.
  • Um apply do lado do servidor para duas das definições do AI Gateway, aigateway.envoyproxy.io_backendsecuritypolicies.yaml e aigateway.envoyproxy.io_mcproutes.yaml, que são maiores do que a cópia do objeto aplicado que um apply do lado do cliente registra, então um apply do lado do cliente as recusa.
  • Uma imagem para o agente. A Release nomeia registry.example/crew-assistant:1.0.0; o catálogo empacota o runtime do agente, e a crew que ele executa é o seu próprio código.

Onde o compilador não interpreta

O compilador canaliza o limite, a unidade e o custo em tokens para os recursos do gateway como strings, e o endpoint do modelo, o endereço do repositório e o endereço do controlador a partir do que cada um publica. Ele não acessa a OpenAI, não sabe se uma resposta informa os seus tokens e não conta nada por si mesmo; não verifica se os Secrets existem nem se o cert-manager está em execução. Cada interrupção acima é declarada pelas próprias entidades do catálogo, como uma asserção na realização do orçamento ou no Component ou na Recipe do gateway, e nenhuma delas se apoia em qualquer compreensão do tráfego.

Adaptando-o

  • Um limite por modelo. Ligue mais modelos ao socket models e defina scope: model: cada um recebe uma regra, e uma contagem, próprias.
  • Contar um único lado. Defina unit: prompt_tokens para contar o que o modelo lê, ou completion_tokens para o que ele escreve.
  • Reenviar uma requisição que falhou. Vincule core/retry-policy ao gateway com max_attempts e mapeie-a no Manifest para helm/retry-policy-envoy-gateway: a mesma política de tráfego, edge-models, ganha um retry ao lado do limite de taxa, porque o Envoy Gateway associa uma única política de tráfego a uma rota.
  • Uma janela mais curta ou de duração fixa. Defina period na Release como uma das durações acima: 1d é um dia a partir das 00:00 UTC, e 30d são 30 dias contados a partir de 1º de janeiro de 1970, e não um mês de calendário. Com qualquer período que não seja 1mo, a configuração deixa a definição de mês de calendário sem valor.
  • Rotas MCP. O controlador criptografa os identificadores de sessão MCP com uma chave derivada da semente no Secret que infra.mcp_session_seed_secret nomeia em ai-controller; sem nenhum nomeado, como aqui, a semente é o valor padrão publicado do seu chart, então nomeie um antes de servir uma rota MCP por meio dele.