Перейти к содержимому
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

Перед сборкой релизу нужен lock-файл, а lock-файлы генерируются, а не поставляются, поэтому в свежем клоне его нет. Сначала разрешите его или позвольте сборке его заполнить:

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 считают одну сторону. Шлюз считает то, что сообщает ответ, и ничего не оценивает в деньгах, поэтому он не ведёт бюджет в долларах США.

У каждой модели есть маршрут чата и нет маршрута 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 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]

Ключей вызывающих сторон в нём нет: каждый потребитель называет переменную, которую 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.