Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Envoy Gateway перед OpenAI с месячным бюджетом токенов

Команда размещает модель OpenAI gpt-4o-mini за шлюзом внутри кластера, хочет ограничить число токенов, которые шлюз расходует на неё за каждый календарный месяц, и направляет своего агента на шлюз, а не напрямую в OpenAI. Это рабочее пространство компилирует всё это в манифесты Kubernetes: Envoy Gateway, обслуживающий модель через Envoy AI Gateway, с подключённой core/period-budget, Redis, хранящий счётчик, и агент CrewAI, отправляющий запросы к модели через шлюз.

На странице также показано, что этот шлюз отказывается подсчитывать: бюджет в долларах США останавливает сборку, как и бюджет на каждого вызывающего.

Это рабочее пространство не определяет ни одной собственной сущности каталога. Три файла сущностей здесь — Aggregate, Manifest и Release — это всё, что кому-либо приходится писать.

Что собирается

экземплярсущность Component из каталогачем он является здесь
edgecore/gateway/envoy-gatewayшлюз, обслуживающий один псевдоним, assistant, из модели chat
ai-controllercore/gateway/envoy-ai-gateway-operatorконтроллер Envoy AI Gateway, который шлюз вызывает как свой сервер расширений, устанавливаемый вместе с шестью определениями ресурсов AI Gateway
chatcore/ai-model/openaigpt-4o-mini от OpenAI, доступная по ссылке: в кластере для неё ничего не запускается
counterscore/datastore/redisхранилище, в котором служба ограничения частоты запросов шлюза ведёт счёт бюджета
assistantcore/ai-agent/crewaiагент, чьи запросы к модели идут на шлюз
certscore/security/cert-managercert-manager, который выпускает сертификат, обслуживаемый веб-хуком контроллера

Рёбра uses шлюза выходят из его сокета extension — к контроллеру; из models — к модели, неся в качестве credential ключ, который шлюз предъявляет OpenAI; и из cache — к хранилищу, неся пароль, который ему предъявляет служба ограничения частоты запросов. Ребро model агента указывает на шлюз, а не на модель. На шлюзе одно подключение сущности Feature, budget: сущность Aggregate задаёт, что считается, — total_tokens, и чей трафик покрывает один лимит, — gateway, то есть всё, что обслуживает шлюз, — а сущность Release задаёт, сколько и за какой срок: двадцать миллионов токенов за календарный месяц.

Сущность Manifest привязывает все учётные данные к k8s-existing-secret, который направляет рабочую нагрузку на Secret, уже существующий в её пространстве имён, и сам ничего не генерирует, поэтому ни ключа, ни пароля нет ни в сущности Aggregate, ни в сущности Release, ни в сгенерированном выводе. Имена объектов Secret — это два параметра, которые заполняет сущность Release, а собственный слот password хранилища читает тот же параметр, что и подключение cache шлюза, поэтому хранилище и служба, предъявляющая ему пароль, указывают один и тот же Secret.

Сущность Release объявляет, где работает каждая рабочая нагрузка: cert-manager — в cert-manager, контроллер — в envoy-ai-gateway-system, агент — в assistant, а шлюз — в envoy-gateway-system (контроллер ищет плоскость управления шлюза именно там, и сборка останавливается, если шлюз размещён где-либо ещё), вместе с хранилищем рядом с ним. Модель ничего не запускает: её единственный файл, Service, сопоставляющий внутрикластерное имя с хостом OpenAI, не указывает пространства имён, и шлюз обращается к OpenAI по конечной точке, которую публикует модель, а не через этот Service.

cert-manager объявлен, а не предполагается

Webhook контроллера обслуживает сертификат, который выпускает cert-manager: его Recipe рендерит Certificate для cert-manager и самоподписанный Issuer, который его подписывает, а согласовывает их только запущенный cert-manager. Компилятор не может заглянуть в кластер и проверить, запущен ли он там, поэтому рабочее пространство объявляет cert-manager, а не предполагает его наличие: certs находится в Aggregate рядом с контроллером, и сборка рендерит cert-manager вместе со всем остальным.

В кластере работает один cert-manager. Если в вашем он уже запущен, удалите certs из Aggregate и Release перед сборкой; тогда сборка рендерит те же файлы, кроме файлов самого cert-manager.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

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

Сборка

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

Перед сборкой релизу нужен lock-файл, а lock-файлы генерируются, а не поставляются, поэтому в свежем клоне его нет. Сначала разрешите его или позвольте сборке его заполнить:

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

Разрешение фиксирует версии трёх чартов, которые генерируют Recipes, — чартов Envoy Gateway и Envoy AI Gateway из Docker Hub и чарта cert-manager из quay.io, — поэтому для него нужен доступ к сети. Это рабочее пространство разрешает сущности каталога из реестра по умолчанию, который указывает .aggrega-config.yaml.

Сборка с --auto-pull выводит следующее (<workspace> обозначает папку этого примера):

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

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочей области ещё нет папки `envoy-ai-gateway-token-budget`, вызовите инструмент `scaffold` один раз, задав `example` равным `envoy-ai-gateway-token-budget` и не указывая `dir`: он запишет пример в новую папку `envoy-ai-gateway-token-budget`. Затем вызовите инструмент `build`, задав `workspace_root` равным `envoy-ai-gateway-token-budget`, `release` равным `release.yaml`, `auto_pull` равным true и `write` равным true. Сообщите мне, какие файлы записала сборка; они находятся в `envoy-ai-gateway-token-budget/dist/`.

Сгенерированное дерево

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

Бюджет не добавляет собственного файла. То, что он делает, записывается в два файла шлюза: dist/helm/edge/models.yaml, где находятся AI-маршрут и ресурсы, через которые идёт обращение к модели, и конфигурацию плоскости управления, dist/helm/edge-configmap-envoy-gateway-system-envoy-gateway-config.yaml.

Бюджет в том виде, в каком его читает шлюз

Из models.yaml — AI-маршрут:

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"

и из того же файла — политика трафика, которая его ограничивает и названа так же, как маршрут, на который она нацелена:

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

Вот ключ envoy-gateway.yaml конфигурации плоскости управления:

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

Что из них следует:

Стоимость задаётся на AI-маршруте, лимит — на маршруте, в который он превращается. Envoy AI Gateway считывает total_tokens, которые сообщает каждый ответ модели, и записывает это значение в метаданные запроса под ключом llm_total_token: именно это объявляет llmRequestCosts. Контроллер превращает AI-маршрут в HTTP-маршрут с тем же именем, edge-models, и политика трафика нацелена на этот маршрут, поэтому бюджет охватывает трафик к модели и никакой другой маршрут, подключённый к шлюзу.

Ответ учитывается по завершении. cost.request ничего не списывает при поступлении запроса; cost.response списывает токены ответа, когда ответ завершён. Запрос отклоняется, как только списанное к этому моменту количество превышает limit.

Один счётчик на весь шлюз. shared: true ведёт один счётчик для всех правил маршрута — это область gateway, запрошенная подключением. При scope: model Recipe записывает по одному правилу на каждое соединение сокета models, и каждое сопоставляется с именем модели, которое запрос передаёт в x-ai-eg-model, поэтому каждая модель учитывается отдельно.

Период — это единица на часах. 1mo записывается как unit: Month, а конфигурация через USE_CALENDAR_MONTH_RATE_LIMIT указывает службе ограничения частоты Envoy Gateway считать месяц с первого по последний день календарного месяца. Этот параметр относится к службе, поэтому он действует на все месячные ограничения частоты в этой установке Envoy Gateway — и бюджета, и любые другие. Каждое окно начинается в фиксированный момент по часам UTC, а не с первого запроса: день — в 00:00 UTC, неделя — в четверг.

Счётчик хранится в хранилище на сокете cache. Блок rateLimit включает собственную службу ограничения частоты Envoy Gateway, которую плоскость управления создаёт в своём пространстве имён и включает для каждого обслуживаемого ею шлюза, и направляет её на Redis, к которому ведёт сокет cache шлюза. Хранилище публикует свой хост без пространства имён, поэтому шлюз дополняет его тем пространством имён, в которое сущность Release помещает хранилище.

Проверка без ответа приводит к отклонению запроса. Благодаря failClosed: true Envoy отклоняет запрос к модели с HTTP 500, пока хранилище или служба ограничения частоты недоступны или проверка длится дольше тайм-аута ограничения частоты Envoy (по умолчанию 20 мс), вместо того чтобы обслужить запрос, не учтя его. Этот параметр относится к плоскости управления, поэтому он действует для всех ограничений частоты этой установки Envoy Gateway, и ограничение частоты, применённое к установке вручную, тоже отказывает в закрытом режиме. Конфигурация содержит его, только пока бюджет подключён.

Пароля в ней нет. Служба считывает пароль хранилища как REDIS_AUTH из секрета, указанного в учётных данных соединения cache, — counter-store-password, который она разрешает в своём пространстве имён, то есть в пространстве имён шлюза. Хранилище, counters-deployment.yaml, запускается с --requirepass, считанным из того же секрета.

Путь от агента к модели

Из assistant-deployment.yaml — блок env контейнера агента:

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

Агент читает два ключа, которые публикует шлюз, — те же два, что публикует модель, поэтому его Recipe читает их так же, как читал бы ключи модели. Переменные CREWAI_ несут собственные значения агента под именами, которые сущность Component CrewAI даёт им по умолчанию. Адрес — это Service, который Envoy Gateway создаёт для плоскости данных шлюза; его имя составляется из пространства имён шлюза, имени шлюза и хеша от них двух, а квалифицируется он пространством имён envoy-gateway-system, поэтому разрешается из пространства имён агента. Имя модели — псевдоним assistant; маршрут направляет запрос, в котором оно указано, на бэкенд модели и запрашивает вместо него gpt-4o-mini.

Бэкенд обращается к OpenAI по конечной точке, которую публикует модель: models.yaml содержит Backend Envoy Gateway для api.openai.com на порту 443, политику TLS, проверяющую его сертификат по системным якорям доверия, AIServiceBackend для API OpenAI по пути /v1 и политику безопасности, предъявляющую ключ, edge-assistant, у которой spec выглядит так:

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

Контроллер читает ключ из этого Secret в пространстве имён шлюза по ключу данных apiKey и передаёт его OpenAI как bearer-токен, поэтому ни один отрисованный файл его не содержит, а агент никогда его не получает. Шлюз обращается к контроллеру по адресу, который публикует контроллер, квалифицированному пространством имён, в которое его помещает Release, — это блок extensionManager выше. Пока подключена модель, шлюз также получает политику клиентского трафика Envoy AI Gateway — edge-client-buffer-limit в models.yaml, — которая увеличивает буфер, допустимый для каждого входящего соединения, до 50Mi; она нацелена на шлюз, поэтому применяется к каждому маршруту, подключённому к нему.

Что шлюз делает во время выполнения

При каждом запросе к модели шлюз спрашивает у службы ограничения частоты, превышают ли токены, учтённые с начала месяца, значение limit. Как только превышают, он отвечает на запросы к модели кодом HTTP 429 до конца месяца. Токены запроса добавляются, когда ответ на него завершён, поэтому запрос, который пересекает лимит, обслуживается, как и любой запрос, на который отвечают одновременно с ним. Пока хранилище или служба ограничения частоты недоступны либо проверка длится дольше тайм-аута ограничения частоты Envoy, шлюз отклоняет запросы к модели с кодом HTTP 500 согласно настройке failClosed выше, так что ни один запрос к модели не допускается, пока его счётчик нельзя проверить.

Из этого следует поведение самого продукта, а не конфигурации:

  • Запрос, допущенный незадолго до сбоя, всё равно обслуживается и не учитывается. Его токены учитываются после ответа, поэтому ответ, который завершается, пока хранилище или служба недоступны, ничего не добавляет к счётчику.
  • Хранилище, держащее счётчик в памяти, при перезапуске начинает каждое окно заново. core/datastore/redis по умолчанию хранит свои записи в памяти, поэтому перезапущенное хранилище теряет накопленный счётчик, и остаток месяца отсчитывается с нуля.
  • Ответ, не сообщающий об использовании, ничего не добавляет. Счётчик — это то, что сообщает каждый ответ; Envoy AI Gateway просит модель сообщать об использовании и в конце потокового ответа.

Что останавливает сборку

Каждый из этих случаев — это предложение, которое выводит сборка, называя, что нужно изменить:

  • Стоимость в долларах США. Укажите unit: usd в подключении, и сборка остановится до того, как что-либо будет отрисовано:

    [… 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
  • Бюджет на каждого вызывающего, scope: caller. Шлюз различает вызывающих только по заголовку, который вызывающий пишет сам, и ничто на этом пути не проверяет, кто вызывающий, поэтому вызывающий, отправивший новое значение, начал бы новый бюджет, а не отправивший никакого не учитывался бы.

  • Любой период, для которого у шлюза нет окна. Шлюз хранит одну целую единицу своего ограничения частоты: 1s, 1m, 1h, 1d, 7d, 30d, 365d или 1mo, либо ту же длительность, записанную иначе, например 24h. 2h, 14d или 2mo останавливает сборку.

  • Лимит, не являющийся целым числом токенов, или лимит больше 4294967295.

  • Второе подключение core/period-budget на шлюзе, которое записывает один бюджет на маршрут, обслуживающий его модели.

  • Ничего не подключено к сокету models, из-за чего не остаётся маршрута модели для подсчёта, или к сокету cache, из-за чего счётчику негде храниться. Если удалить только подключение модели, первой остановится собственная сущность Component шлюза: values.model указывает на псевдоним, который ничто не обслуживает.

  • Хранилище на сокете cache, не поддерживающее протокол Redis, — хранилище, публикующее протокол, отличный от redis или valkey.

  • Шлюз размещён вне envoy-gateway-system, когда контроллер подключён к его сокету extension.

Перед применением

Дерево не содержит ни Namespace, ни Secret, поэтому кластеру, получающему dist/helm/, нужны:

  • Пространства имён cert-manager, envoy-ai-gateway-system, envoy-gateway-system и assistant.
  • Секреты в envoy-gateway-system: openai-api-key, содержащий ключ OpenAI под ключом данных apiKey, и counter-store-password, содержащий пароль хранилища под password. Рабочая нагрузка, ссылающаяся на несуществующий Secret, не запускается.
  • Server-side apply для двух определений AI Gateway, aigateway.envoyproxy.io_backendsecuritypolicies.yaml и aigateway.envoyproxy.io_mcproutes.yaml: они больше копии применённого объекта, которую записывает client-side apply, поэтому client-side apply их отклоняет.
  • Образ для агента. Сущность Release указывает registry.example/crew-assistant:1.0.0; каталог упаковывает среду выполнения агента, а команда, которую он запускает, — ваш собственный код.

Где компилятор не интерпретирует

Компилятор передаёт лимит, единицу и стоимость токена в ресурсы шлюза в виде строк, а конечную точку модели, адрес хранилища и адрес контроллера — из того, что публикует каждый из них. Он не обращается к OpenAI, не знает, сообщает ли ответ о своих токенах, и сам ничего не подсчитывает; он не проверяет, что Secrets существуют или что cert-manager запущен. Каждая из описанных выше остановок объявлена собственными сущностями каталога — как утверждение в реализации бюджета или в сущности Component или Recipe шлюза, — и ни одна из них не опирается на какое-либо понимание трафика.

Адаптация примера

  • Лимит для каждой модели. Подключите к сокету models больше моделей и задайте scope: model: каждая получит собственное правило и собственный счётчик.
  • Подсчёт одной стороны. Задайте unit: prompt_tokens, чтобы считать то, что модель читает, или completion_tokens — то, что она пишет.
  • Повторная отправка неудавшегося запроса. Подключите к шлюзу core/retry-policy с max_attempts и сопоставьте его в Manifest с helm/retry-policy-envoy-gateway: та же политика трафика, edge-models, получает retry рядом с ограничением частоты, поскольку Envoy Gateway подключает к маршруту одну политику трафика.
  • Более короткое окно или окно фиксированной длины. Задайте period в Release равным одной из длительностей выше: 1d — это сутки от 00:00 UTC, а 30d — это 30 дней, отсчитываемых от 1 января 1970 года, а не календарный месяц. При любом периоде, кроме 1mo, настройка календарного месяца в конфигурации остаётся незаданной.
  • Маршруты MCP. Контроллер шифрует идентификаторы сеансов MCP ключом, производным от начального значения в секрете, имя которого задаёт infra.mcp_session_seed_secret в ai-controller; если имя не задано, как здесь, начальным значением служит опубликованное значение по умолчанию его чарта, поэтому задайте его, прежде чем обслуживать через контроллер маршрут MCP.