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

Шлюз APISIX, що обмежує свої моделі бюджетом токенів

Команда розміщує дві моделі OpenAI за одним шлюзом і хоче встановити верхню межу того, що шлюз витрачає на них щодня, у токенах. Цей робочий простір компілює такий шлюз у маніфести Kubernetes: Apache APISIX перед двома моделями, із підключеним core/period-budget.

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

Цей робочий простір не створює жодної власної сутності каталогу. Три файли сутностей тут — Aggregate, Manifest і Release — це все, що будь-хто пише.

Що він збирає

екземплярComponent із каталогущо це тут
gatewaycore/gateway/apisixшлюз, що обслуговує два псевдоніми: assistant — від моделі chat і summarizer — від моделі mini
chatcore/ai-model/openaigpt-4o від OpenAI, доступна як посилання: для неї в кластері нічого не запускається
minicore/ai-model/openaigpt-4o-mini від OpenAI, доступна так само

Два ребра uses у сокет models шлюзу, по одному до кожної моделі; кожне містить як свій credential ключ, який шлюз пред’являє цій моделі; обидва читають один параметр, openai_key, який задає сутність Release. Одне приєднання сутності Feature до шлюзу, budget: сутність Aggregate задає, що рахується, total_tokens, і чий трафік охоплює один ліміт, gateway — усе, що обслуговує шлюз, — а сутність Release задає, скільки і за який період: два мільйони токенів на день.

Сутність Manifest зіставляє шлюз з apisix-chart — реалізацією, яка рендерить власний чарт APISIX від самого проєкту, версії APISIX 3.18.0, і обслуговує моделі, під’єднані до шлюзу. Коли модель під’єднано, шлюз читає свої маршрути з файлу, відрендереного разом із ним, тож йому не потрібні ні з’єднання з etcd, ні ключ Admin API; сутність Aggregate не під’єднує жодного з них.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

Terminal window
aggrega scaffold --example apisix-token-budget

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:

Terminal window
cd apisix-token-budget

Збирання

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

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

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Розв’язання фіксує версію чарту APISIX, який генерує Recipe шлюзу; чарт завантажується з його власного репозиторію, тож для цього потрібна мережа. Цей робочий простір знаходить сутності каталогу в реєстрі за замовчуванням, який називає .aggrega-config.yaml.

Збирання виводить таке (<workspace> позначає теку цього прикладу):

[… omitted: two warnings, one per model connection's credential, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping, the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]
Build completed: 8 files written to <workspace>/dist

З ШІ-асистентом

ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.

Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `apisix-token-budget`, викличте один раз інструмент `scaffold`, задавши для `example` значення `apisix-token-budget` і не задаючи `dir`: він запише приклад у нову теку `apisix-token-budget`. Потім викличте інструмент `build`, задавши для `workspace_root` значення `apisix-token-budget`, для `release` — `release.yaml`, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала збірка; вони лежать у `apisix-token-budget/dist/`.

Згенероване дерево

dist/helm/
├── chat-service.yaml
├── gateway--assistant-zdcredential--gateway-secret-gateway-assistant-credential.yaml
├── gateway--summarizer-zdcredential--gateway-secret-gateway-summarizer-credential.yaml
├── gateway-configmap-default-gateway.yaml
├── gateway-deployment-default-gateway.yaml
├── gateway-service-default-gateway-gateway.yaml
├── mini-service.yaml
└── gateway/
└── model-routes.yaml

Бюджет не додає власного файлу. Те, що він робить, записано у файл маршрутів dist/helm/gateway/model-routes.yaml — ConfigMap, який шлюз монтує і з якого читає всю свою конфігурацію маршрутизації. Кожна модель генерує один файл — Service, що зіставляє внутрішньокластерне ім’я з хостом API OpenAI, а кожні облікові дані на з’єднанні з моделлю генерують окремий Secret, названий за шлюзом і псевдонімом з’єднання.

Бюджет у тому вигляді, у якому його читає шлюз

Ось ключ apisix.yaml цього ConfigMap:

services:
- id: "model-budget"
plugins:
ai-rate-limiting:
limit: 2000000
time_window: 86400
limit_strategy: "total_tokens"
routes:
- id: "model-assistant-chat"
uri: "/assistant/v1/chat/completions"
service_id: "model-budget"
methods:
- POST
plugins:
ai-proxy:
provider: openai-compatible
auth:
header:
Authorization: "$env://AI_PROXY_ASSISTANT_AUTHORIZATION"
options:
model: "gpt-4o"
override:
endpoint: "https://api.openai.com/v1/chat/completions"
- id: "model-summarizer-chat"
uri: "/summarizer/v1/chat/completions"
service_id: "model-budget"
[… omitted: the same route for gpt-4o-mini, presenting AI_PROXY_SUMMARIZER_AUTHORIZATION]
#END

З нього варто вичитати п’ять речей.

Бюджет розміщено на сервісі, який називають обидва маршрути. Обмеження швидкості за токенами в APISIX, ai-rate-limiting, веде лічильник під тим об’єктом, на якому його оголошено. Якби його записали на кожному маршруті, він вів би окремий лічильник для кожного маршруту; записаний один раз на model-budget, який кожен маршрут називає через service_id, він веде один лічильник для всього, що обслуговує шлюз, — це область gateway, якої вимагало підключення. З scope: model сутність Recipe натомість записує окремий сервіс для кожного з’єднання, model-assistant-budget і model-summarizer-budget, тож кожна модель має власний ліміт.

Період — це вікно в секундах. 1d записується як 86400. Вікно відкривається з першим запитом до моделі після закриття попереднього вікна й триває стільки часу; воно не починається опівночі. Календарний місяць не має фіксованої кількості секунд, тому 1mo відхиляється, як описано нижче.

Одиниця — це те, що підраховується. total_tokens — це токени, які, за даними відповіді кожної моделі, було прочитано й записано разом; prompt_tokens і completion_tokens підраховують лише один бік. Шлюз рахує те, що повідомляє відповідь, і нічого не оцінює в грошах, тому бюджету в доларах США він не веде.

Кожна модель має маршрут для чату й не має маршруту для completions. Без бюджету кожен псевдонім також отримує /<alias>/v1/completions. APISIX читає токени відповіді лише із запиту, протокол якого він розпізнає, а запит completion, тіло якого містить prompt, а не messages, таким не є: на нього було б відповідено, але його ніколи не було б підраховано. Тому, поки бюджет підключено, цей маршрут не записується, а на запит completion шлюз відповідає 404 Route Not Found.

Ключів у ньому немає. Кожен маршрут називає змінну, що містить bearer-токен його з’єднання, через посилання APISIX $env://. З файлу dist/helm/gateway-deployment-default-gateway.yaml — env контейнера шлюзу:

env:
- name: AI_PROXY_ASSISTANT_API_KEY
valueFrom:
secretKeyRef:
key: api-key
name: gateway-assistant.credential
- name: AI_PROXY_ASSISTANT_AUTHORIZATION
value: Bearer $(AI_PROXY_ASSISTANT_API_KEY)
[… omitted: the same two variables for summarizer]

Той самий Deployment запускає одну репліку, replicas: 1. Лічильник зберігається в пам’яті процесу шлюзу, тож друга репліка вела б власний лічильник; поки бюджет підключено, сутність Recipe утримує chart на одній репліці.

Що робить шлюз під час виконання

Під час кожного запиту до моделі шлюз порівнює лічильник із limit. Щойно лічильник його досягне, шлюз відповідає 503 Service Temporarily Unavailable до закриття вікна, і запит до моделі не надсилається; відповідь містить власні заголовки шлюзу X-AI-RateLimit-Limit-…, X-AI-RateLimit-Remaining-… і X-AI-RateLimit-Reset-…. Токени запиту додаються, коли завершується відповідь на нього, тож запит, який доводить лічильник до ліміту, обслуговується, як і будь-який запит, що вже виконується паралельно з ним.

З цього випливають два наслідки, і обидва є поведінкою шлюзу, а не конфігурацією:

  • Перезапуск відкриває нове вікно. Лічильник зберігається в пам’яті процесу шлюзу, тож оновлений або перезапущений pod починає відлік з нуля.
  • Відповідь, що не повідомляє токенів, нічого не додає. Лічильник — це те, що повідомляє кожна модель; шлюз просить потоковий запит чату повідомити про використання, а модель, яка нічого не повідомляє, нічого не додає.

Що зупиняє збірку

Кожен із цих випадків — це речення, яке друкує збірка, називаючи, що слід змінити:

  • Вартість у доларах США. Задайте 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-apisix" instance "gateway" 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 "gateway" asks for unit usd, but core/gateway/apisix, 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, тоді як сутність Release не оголошує викликачів. Шлюз розрізняє викликачів за ключем, який пред’являє кожен, а без infra.callers кожен маршрут відкритий. Коли викликачів оголошено, як у наступному розділі, кожен має власний лічильник на всіх маршрутах.

  • Календарний місяць, period: 1mo, і ліміт, що не є цілим числом токенів.

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

  • До сокета models нічого не під’єднано, і тоді не лишається маршрутів моделей, які можна рахувати. Якщо видалити лише два з’єднання, першою збирання зупинить власна сутність Component шлюзу: вона вимагатиме сховище etcd і ключ Admin API, через які шлюз без моделей зберігає свої маршрути.

  • Інша реалізація. Зіставте core/gateway/apisix з helm/apisix у сутності Manifest, і збірка зупиниться на з’єднаннях models, назвавши helm/apisix-chart: ця реалізація запускає APISIX 3.17.0 з маршрутами в etcd і не генерує жодного. Вона зупиняється й на приєднанні бюджету, оскільки не має маршруту, до якого його записати, а у версії 3.17.0 кожен процес шлюзу рахує окремо.

Семантичному кешу потрібні клієнти

APISIX 3.18.0 має семантичний кеш, і core/semantic-caching приєднується до цього шлюзу. Додайте його до features шлюзу в aggregate.yaml:

answers:
type: core/semantic-caching
values:
embedding_model: assistant
similarity_threshold: 0.9
ttl_seconds: 3600

Manifest уже спрямовує Feature до її реалізації в APISIX, і збірка зупиняється:

[… 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 "semantic-caching-apisix" instance "gateway" assertion "scope_is_one_the_gateway_keeps": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "gateway" asks for scope end_user, which keeps each end user the gateway identifies apart, but core/gateway/apisix tells its callers apart only by the key each presents, and cannot tell apart the end users behind one key: a value a request names for one is whatever the caller sent, which the gateway does not verify. Set scope to key, which keeps each caller infra.callers declares apart, or attach the Feature to a gateway that identifies end users

Кеш зберігає відповідь для будь-кого, хто пізніше запитає щось достатньо схоже, тож те, хто спільно використовує один кеш, визначає, кому може бути надано відповідь, згенеровану для когось іншого. Цей шлюз може розділяти клієнтів за ключем, який кожен із них пред’являє і який шлюз перевіряє, але не точніше: задайте scope: key, і збірка знову зупиниться, тепер через клієнтів, яких їй не надано:

[… 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 "semantic-caching-apisix" instance "gateway" assertion "callers_are_declared": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "gateway" asks for scope key, but infra.callers of "gateway" declares no caller, so the gateway authenticates no key and every request on a route would share one cache, a reply generated for one caller served to another; declare the callers in infra.callers, with their keys through the caller_keys slot

Збірку забезпечують три доповнення. Release називає клієнтів та їхні ключі:

gateway:
infra:
callers: [support-agent, billing-agent]
features:
caller_keys:
type: core/referenced-secret-set
infra:
entries:
- key: support-agent
value: support-agent-key-change-me
- key: billing-agent
value: billing-agent-key-change-me
budget:
[… omitted: the budget's size, as above]

Aggregate під’єднує модель, за допомогою якої кеш перетворює кожен запит на вектор, і сховище Redis для відповідей, а також називає модель ембедингів у приєднанні як embedding_model: embedder, разом із scope: key:

models:
[… omitted: assistant and summarizer, as above]
embedder:
target: embeddings
features:
credential:
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.openai_key }}"
cache_store:
replies:
target: cache

де компонент embeddings (core/ai-model/openai-embedding, його values.model задано як text-embedding-3-small) і компонент cache (core/datastore/redis) оголошено поруч із моделями, кожен розміщено в Release, а Manifest зіставляє обидва, а також core/referenced-secret-set з його реалізацією для Kubernetes helm/k8s-secret-set, яка записує ключі безпосередньо у згенерований Secret і тому підходить лише для цільового середовища розробки. Потім файл маршрутів оголошує кожного клієнта й перевіряє його ключ на кожному маршруті, а маршрут чату містить кеш:

consumers:
- username: "support-agent"
plugins:
key-auth:
key: "$env://CALLER_SUPPORT_AGENT_AUTHORIZATION"
[… omitted: billing-agent, the same way]
routes:
- id: "model-assistant-chat"
uri: "/assistant/v1/chat/completions"
service_id: "model-budget"
methods:
- POST
plugins:
key-auth:
header: Authorization
hide_credentials: true
ai-proxy:
[… omitted: the route to gpt-4o, as above]
ai-cache:
layers:
- exact
- semantic
exact:
ttl: 3600
cache_key:
share_across_routes: false
include_consumer: true
policy: redis
redis_host: "cache-default"
redis_port: 6379
semantic:
similarity_threshold: 0.9
ttl: 3600
embedding:
openai:
endpoint: "https://api.openai.com/v1/embeddings"
model: "text-embedding-3-small"
api_key: "$env://AI_PROXY_EMBEDDER_API_KEY"
vector_search:
redis:
index: "gateway-answers"
[… omitted: the same for the other connections]

Ключів клієнтів у ньому немає: кожен consumer називає змінну, яку Deployment заповнює із Secret, що його генерує приєднання caller_keys, під власним іменем клієнта, і складає з неї повний заголовок:

- name: CALLER_SUPPORT_AGENT_KEY
valueFrom:
secretKeyRef:
key: support-agent
name: gateway-caller-keys
- name: CALLER_SUPPORT_AGENT_AUTHORIZATION
value: Bearer $(CALLER_SUPPORT_AGENT_KEY)
[… omitted: the same two variables for billing-agent]

Під час виконання запит, що не пред’являє оголошеного ключа у вигляді Authorization: Bearer <key>, відхиляється з HTTP 401, а ключ вилучається із запиту, який шлюз пересилає далі. Відповідь зберігається за маршрутом і клієнтом, тож на переформульований запит одного клієнта видається відповідь, збережена для цього клієнта, і ніколи не збережена для іншого. Відповідь, видана з кешу, нічого не додає до бюджету й видається навіть після вичерпання ліміту. З’єднання embedder отримує власні маршрути, як і кожне з’єднання на сокеті models.

Де компілятор не інтерпретує

Компілятор передає ліміт, вікно й одиницю у файл маршрутів як рядки, а кінцеву точку й назву моделі кожної моделі — з того, що ця модель публікує. Він не звертається до OpenAI, не знає, чи повідомляє відповідь про свої токени, і сам нічого не підраховує. Кожну зупинку, описану вище, оголошують власні сутності каталогу — як твердження в реалізації бюджету чи кешу або в іншому Recipe шлюзу, — і жодна з них не спирається на будь-яке розуміння трафіку.

Адаптація прикладу

  • Ліміт для кожної моделі. Задайте scope: model: кожен псевдонім отримує власний сервіс і власний лічильник.
  • Ліміт для кожного клієнта. Оголосіть клієнтів та їхні ключі в сутності Release, як у розділі «Семантичному кешу потрібні клієнти» вище, і задайте scope: caller: кожен клієнт отримує власний лічильник для всіх маршрутів.
  • Підрахунок однієї сторони. Задайте unit: prompt_tokens, щоб рахувати те, що моделі читають, або completion_tokens — для того, що вони пишуть.
  • Коротше або довше вікно. Задайте period у сутності Release як кількість секунд, хвилин, годин або днів, наприклад 6h чи 30d.