Шлюз 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Перед сборкой релизу нужен lock-файл, а lock-файлы генерируются, а не поставляются, поэтому в свежем клоне его нет. Сначала разрешите его или позвольте сборке его заполнить:
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 считают одну сторону. Шлюз считает то, что сообщает ответ,
и ничего не оценивает в деньгах, поэтому он не ведёт бюджет в долларах США.
У каждой модели есть маршрут чата и нет маршрута completion. Без бюджета
каждый псевдоним также получает /<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 удерживает чарт на одной реплике.
Что шлюз делает во время выполнения
При каждом запросе к модели шлюз сравнивает счётчик с limit. Как только
счётчик его достиг, шлюз отвечает 503 Service Temporarily Unavailable
до закрытия окна, не отправляя запрос модели; ответ
содержит собственные заголовки шлюза X-AI-RateLimit-Limit-…,
X-AI-RateLimit-Remaining-… и X-AI-RateLimit-Reset-…. Токены запроса
прибавляются, когда завершается его ответ, поэтому запрос, доводящий счётчик
до лимита, обслуживается, как и любой запрос, уже выполняющийся параллельно с ним.
Из этого следуют два последствия, и оба относятся к поведению шлюза, а не к конфигурации:
- Перезапуск открывает новое окно. Счётчик хранится в памяти процесса шлюза, поэтому обновлённый или перезапущенный под начинает отсчёт с нуля.
- Ответ, не сообщающий о токенах, ничего не добавляет к счётчику. Счётчик — это то, о чём сообщает каждая модель; шлюз просит потоковый запрос чата сообщать об использовании, и модель, которая ни о чём не сообщает, ничего не добавляет.
Что останавливает сборку
Каждый из этих случаев — это предложение, которое выводит сборка, называя, что нужно изменить:
-
Стоимость в долларах США. Задайте
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]Ключей вызывающих сторон в нём нет: каждый потребитель называет переменную, которую 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,
как в разделе «A semantic cache needs callers» выше, и задайте
scope: caller: каждый вызывающий получает собственный счётчик по всем маршрутам. - Подсчёт одной стороны. Задайте
unit: prompt_tokens, чтобы считать то, что модели читают, илиcompletion_tokens— то, что они пишут. - Более короткое или длинное окно. Задайте в сущности Release для
periodчисло секунд, минут, часов или дней, например6hили30d.