Шлюз APISIX, що обмежує свої моделі бюджетом токенів
Команда розміщує дві моделі OpenAI за одним шлюзом і хоче встановити верхню межу того, що
шлюз витрачає на них щодня, у токенах. Цей робочий простір компілює такий
шлюз у маніфести Kubernetes: Apache APISIX перед двома моделями,
із підключеним core/period-budget.
Сторінка також показує, що потрібно семантичному кешу від цього шлюзу, перш ніж він збереться: клієнти, яких він може розрізнити, кожного за ключем, який той надає, і сховище для відповідей.
Цей робочий простір не створює жодної власної сутності каталогу. Три файли сутностей тут — Aggregate, Manifest і Release — це все, що будь-хто пише.
Що він збирає
| екземпляр | Component із каталогу | що це тут |
|---|---|---|
gateway | core/gateway/apisix | шлюз, що обслуговує два псевдоніми: assistant — від моделі chat і summarizer — від моделі mini |
chat | core/ai-model/openai | gpt-4o від OpenAI, доступна як посилання: для неї в кластері нічого не запускається |
mini | core/ai-model/openai | gpt-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 не під’єднує жодного з них.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example apisix-token-budgetПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd apisix-token-budgetЗбирання
aggrega build --release release.yaml --auto-pullПерш ніж збирати release, йому потрібен lockfile, а lockfile-и генеруються, а не постачаються, тож у свіжому клоні їх немає. Спершу отримайте його або дозвольте збиранню його заповнити:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega 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 assertionscaused 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: 3600Manifest уже спрямовує 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.