Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

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

Команда розміщує gpt-4o-mini від OpenAI за внутрішньокластерним шлюзом, хоче встановити верхню межу токенів, які шлюз витрачає на нього щокалендарного місяця, і спрямовує свого агента на шлюз, а не на 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 оголошено, а не припущено

Вебхук контролера обслуговує сертифікат, який видає cert-manager: його Recipe рендерить ресурс cert-manager Certificate і самопідписаний Issuer, що його підписує; їх узгоджує лише запущений cert-manager. Компілятор не може зазирнути в кластер, щоб перевірити, чи 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

Перш ніж збирати release, йому потрібен lockfile, а lockfile-и генеруються, а не постачаються, тож у свіжому клоні їх немає. Спершу отримайте його або дозвольте збиранню його заповнити:

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 для 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 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.
  • 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.