Envoy Gateway перед OpenAI з місячним бюджетом токенів
Команда розміщує gpt-4o-mini від OpenAI за внутрішньокластерним шлюзом, хоче встановити верхню межу
токенів, які шлюз витрачає на нього щокалендарного місяця, і спрямовує свого агента
на шлюз, а не на 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 оголошено, а не припущено
Вебхук контролера обслуговує сертифікат, який видає cert-manager: його Recipe
рендерить ресурс cert-manager Certificate і самопідписаний Issuer, що його підписує;
їх узгоджує лише запущений cert-manager. Компілятор не може зазирнути в
кластер, щоб перевірити, чи 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Перш ніж збирати release, йому потрібен lockfile, а lockfile-и генеруються, а не постачаються, тож у свіжому клоні їх немає. Спершу отримайте його або дозвольте збиранню його заповнити:
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 для OpenAI API під /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. - Secrets у
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.