Envoy Gateway перед OpenAI с месячным бюджетом токенов
Команда размещает модель OpenAI gpt-4o-mini за шлюзом внутри кластера, хочет ограничить число токенов, которые шлюз расходует на неё за каждый календарный месяц, и направляет своего агента на шлюз, а не напрямую в OpenAI. Это рабочее пространство компилирует всё это в манифесты Kubernetes: Envoy Gateway, обслуживающий модель через Envoy AI Gateway, с подключённой core/period-budget, Redis, хранящий счётчик, и агент CrewAI,
отправляющий запросы к модели через шлюз.
На странице также показано, что этот шлюз отказывается подсчитывать: бюджет в долларах США останавливает сборку, как и бюджет на каждого вызывающего.
Это рабочее пространство не определяет ни одной собственной сущности каталога. Три файла сущностей здесь — Aggregate, Manifest и Release — это всё, что кому-либо приходится писать.
Что собирается
| экземпляр | сущность Component из каталога | чем он является здесь |
|---|---|---|
edge | core/gateway/envoy-gateway | шлюз, обслуживающий один псевдоним, assistant, из модели chat |
ai-controller | core/gateway/envoy-ai-gateway-operator | контроллер Envoy AI Gateway, который шлюз вызывает как свой сервер расширений, устанавливаемый вместе с шестью определениями ресурсов AI Gateway |
chat | core/ai-model/openai | gpt-4o-mini от OpenAI, доступная по ссылке: в кластере для неё ничего не запускается |
counters | core/datastore/redis | хранилище, в котором служба ограничения частоты запросов шлюза ведёт счёт бюджета |
assistant | core/ai-agent/crewai | агент, чьи запросы к модели идут на шлюз |
certs | core/security/cert-manager | cert-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.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example envoy-ai-gateway-token-budgetЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd envoy-ai-gateway-token-budgetСборка
aggrega build --release release.yaml --auto-pullПеред сборкой релизу нужен lock-файл, а lock-файлы генерируются, а не поставляются, поэтому в свежем клоне его нет. Сначала разрешите его или позвольте сборке его заполнить:
aggrega pull --release release.yaml --pin-sources # resolve once, then build with no flagaggrega 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/v1beta1kind: AIGatewayRoutemetadata: [… 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/v1alpha1kind: BackendTrafficPolicymetadata: [… 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/v1alpha1kind: EnvoyGatewayextensionApis: enableBackend: true enableEnvoyPatchPolicy: trueextensionManager: 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: 1063gateway: controllerName: gateway.envoyproxy.io/gatewayclass-controllerlogging: level: default: infoprovider: 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: KubernetesrateLimit: 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 assertionscaused 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.