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

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

Uma equipa 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 em 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 em manifestos do Kubernetes: o Envoy Gateway a servir o modelo através do Envoy AI Gateway, com core/period-budget anexado, um Redis que mantém a contagem, e um agente CrewAI que envia os seus pedidos ao modelo através do gateway.

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

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

O que constrói

instânciaComponent do catálogoo que é aqui
edgecore/gateway/envoy-gatewayo gateway, que serve 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 onde o serviço de limitação de taxa do gateway mantém a contagem do orçamento
assistantcore/ai-agent/crewaium agente cujos pedidos ao modelo vão para o gateway
certscore/security/cert-managero cert-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, com a chave que o gateway apresenta à OpenAI como o seu credential; e de cache, para o repositório, com a palavra-passe que o serviço de limitação de taxa lhe apresenta. A aresta model do agente aponta para o gateway, não para o modelo. Um único anexo 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 cada credencial a k8s-existing-secret, que aponta uma carga de trabalho para um Secret já presente no seu namespace e não renderiza nenhum, pelo que nenhuma chave ou palavra-passe está no Aggregate, na Release ou na saída renderizada. Os nomes dos Secrets são dois parâmetros que a Release satisfaz, e o próprio slot password do repositório lê o mesmo parâmetro que a ligação cache do gateway, pelo que o repositório e o serviço que lhe apresenta a palavra-passe nomeiam um único Secret.

A Release declara onde é executada cada carga de trabalho: 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 aí o plano de controlo do gateway, e a compilação é interrompida se o gateway for colocado noutro lugar —, com o repositório ao lado dele. O modelo não executa nada: o seu único ficheiro, 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 através desse Service.

cert-manager é declarado, não pressuposto

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 consegue olhar para um cluster para ver se aí é executado um, pelo que o espaço de trabalho declara o cert-manager em vez de o pressupor: certs fica no Aggregate ao lado do controlador, e a compilação renderiza o cert-manager com tudo o resto.

Um cluster executa um único cert-manager. Se o cluster em uso já executar um, remova certs do Aggregate e da Release antes da compilação; a compilação renderiza então os mesmos ficheiros, menos os do próprio cert-manager.

Gerar o exemplo

É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.

Escreva o exemplo numa nova pasta com o nome dele:

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

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

Compilação

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

Uma release precisa de um lockfile antes de ser compilada, e os lockfiles são gerados em vez de distribuídos, pelo que um clone novo não tem nenhum. Resolva-se um primeiro, ou deixe-se que a compilação o preencha:

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 a partir do Docker Hub, o do cert-manager a partir do quay.io —, pelo que precisa da rede. Este espaço de trabalho resolve as entidades do catálogo a partir do registo predefinido que .aggrega-config.yaml nomeia.

A compilação com --auto-pull imprime, com <workspace> em vez da 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-lhe este prompt.

Utilize apenas as ferramentas do Aggrega e não crie nenhuma pasta por si. Se a pasta da área de trabalho ainda não contiver 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`: esta escreve o exemplo numa 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. Indique-me que ficheiros o build escreveu; encontram-se 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 ficheiro próprio. O que faz é escrito em dois dos ficheiros 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 controlo, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.

O orçamento, tal 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 ficheiro, a política de tráfego que a limita, com o nome da rota a que se destina:

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

Eis a chave envoy-gateway.yaml da configuração do plano de controlo:

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 retirar 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 indica e escreve-os nos metadados do pedido sob llm_total_token: é isso que llmRequestCosts declara. O controlador transforma a rota de IA numa rota HTTP com o mesmo nome, edge-models, e a política de tráfego destina-se a essa rota, pelo que o orçamento cobre o tráfego do modelo e nenhuma outra rota associada ao gateway.

Uma resposta é cobrada quando termina. cost.request não cobra nada quando chega um pedido; cost.response cobra os tokens da resposta assim que a resposta está completa. Um pedido é recusado assim que a contagem cobrada até então excede limit.

Uma única contagem para todo o gateway. shared: true mantém uma única contagem em todas as regras da rota — o âmbito gateway que o anexo pediu. Com scope: model, a Recipe escreve uma regra por ligação no socket models, cada uma correspondente ao nome do modelo que um pedido traz em x-ai-eg-model, pelo que cada modelo é contado à parte.

O período é uma unidade no relógio. 1mo é escrito como unit: Month, e a configuração indica ao serviço de limitação de taxa do Envoy Gateway, através de USE_CALENDAR_MONTH_RATE_LIMIT, que conte um Month do primeiro ao último dia de um mês de calendário. Essa definição pertence ao serviço, pelo que se aplica a todos os limites de taxa Month que esta instalação do Envoy Gateway mantém, o do orçamento e qualquer outro. Cada janela começa num ponto fixo do relógio UTC em vez de com um primeiro pedido: um dia às 00:00 UTC, uma semana numa 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 controlo cria no seu namespace e ativa para cada gateway que serve, e aponta-o para o Redis que o socket cache do gateway alcança. O repositório publica o seu host sem namespace, pelo que o gateway o qualifica com o namespace em que a Release coloca o repositório.

Uma verificação que não obtém resposta recusa o pedido. failClosed: true faz o Envoy recusar um pedido ao modelo com HTTP 500 enquanto o repositório ou o serviço de limitação de taxa não puderem ser alcançados, ou uma verificação demorar mais do que o tempo limite de limitação de taxa do Envoy, 20 ms por predefinição, em vez de o servir e não o contar. Essa definição pertence ao plano de controlo, pelo que vale para todos os limites 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 só a traz enquanto o orçamento estiver anexado.

Não contém nenhuma palavra-passe. O serviço lê a palavra-passe do repositório como REDIS_AUTH, a partir do Secret que a credencial da ligação cache nomeia, counter-store-password, que resolve no seu próprio namespace, o do gateway. O repositório, counters-deployment.yaml, arranca com --requirepass lido do mesmo Secret.

O caminho do agente até ao modelo

De assistant-deployment.yaml, o env do contentor 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, pelo que a sua Recipe as lê como leria as de um modelo. As variáveis CREWAI_ transportam os valores próprios do agente, com os nomes que o Component do CrewAI lhes atribui por predefinição. O endereço é o Service que o Envoy Gateway cria para o plano de dados do gateway, com um nome formado a partir do namespace do gateway, do seu nome e de um hash dos dois, e qualificado com envoy-gateway-system, pelo que se resolve a partir do namespace do agente. O nome do modelo é o alias assistant; a rota envia um pedido que o nomeia para o backend do modelo, pedindo em vez disso gpt-4o-mini.

O backend alcança a OpenAI no endpoint que o modelo publica: models.yaml contém um Backend do Envoy Gateway para api.openai.com na porta 443, uma política TLS que verifica o seu certificado face à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 envia-a à OpenAI como bearer token, pelo que nenhum ficheiro 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 estiver 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 aumenta para 50Mi o buffer permitido a cada ligação de entrada; destina-se ao gateway, pelo que se aplica a todas as rotas a ele associadas.

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

Em cada pedido 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, responde aos pedidos ao modelo com HTTP 429 até ao fim do mês. Os tokens de um pedido são somados assim que a sua resposta está completa, pelo que o pedido que ultrapassa o limite é servido, tal como qualquer pedido respondido ao lado dele. Enquanto o repositório ou o serviço de limitação de taxa não puderem ser alcançados, ou uma verificação demorar mais do que o tempo limite de limitação de taxa do Envoy, recusa os pedidos ao modelo com HTTP 500, de acordo com a definição failClosed acima, pelo que nenhum pedido ao modelo é admitido enquanto a sua contagem não puder ser verificada.

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

  • Um pedido admitido pouco antes de uma interrupção continua a ser servido e não é contado. Os seus tokens são cobrados depois da resposta, pelo que uma resposta que termine enquanto o repositório ou o serviço não puderem ser alcançados não acrescenta nada à contagem.
  • Um repositório que mantém a contagem em memória recomeça cada janela quando é reiniciado. core/datastore/redis mantém as suas entradas em memória por predefinição, pelo que 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 indique utilização não acrescenta nada. A contagem é aquilo que cada resposta indica; o Envoy AI Gateway pede ao modelo que indique a sua utilização também no fim de uma resposta em streaming.

O que interrompe a compilação

Cada um destes casos é uma frase que a compilação imprime, a nomear o que alterar:

  • Um custo em dólares americanos. Ao definir unit: usd no anexo, a compilação é interrompida antes de qualquer coisa ser 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, pelo que 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 tenha janela. 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, a compilação é interrompida.

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

  • Um segundo anexo 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 sítio onde viver. Ao remover apenas a ligação do modelo, é o próprio Component do gateway que é 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 o aplicar

A árvore não contém nenhum Namespace nem nenhum Secret, pelo que 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 palavra-passe do repositório sob password. Uma carga de trabalho que referencie um Secret inexistente não arranca.
  • 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 regista, pelo que 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 executa é código próprio.

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. Não contacta a OpenAI, não sabe se uma resposta indica os seus tokens e não conta nada por si; 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 assenta em qualquer compreensão do tráfego.

Adaptá-lo

  • Um limite por modelo. Ao ligar mais modelos ao socket models e definir scope: model, cada um recebe uma regra, e uma contagem, próprias.
  • Contar um único lado. Define-se unit: prompt_tokens para contar o que o modelo lê, ou completion_tokens para o que escreve.
  • Reenviar um pedido que falhou. Ao anexar core/retry-policy ao gateway com max_attempts e mapeá-la 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. Define-se 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 por definir.
  • Rotas MCP. O controlador cifra 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 predefinido publicado do seu chart, pelo que convém nomear um antes de servir uma rota MCP através dele.