Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

ИИ-шлюз, который отвечает тем, что уже сказал

Ассистенту поддержки весь день задают одни и те же вопросы немного разными словами. Шлюз перед его моделью может ответить на вопрос ответом, который он дал на более ранний, достаточно близкий по смыслу вопрос, вместо того чтобы снова вызывать модель. Это рабочее пространство компилирует такой шлюз в манифесты Kubernetes вместе с хранилищем, в котором он держит эти ответы.

Это делает сущность Feature core/semantic-caching. Какие ответы, порождённые запросом одного вызывающего, можно выдать другому, — вопрос, которому эта страница уделяет больше всего времени, потому что кэш, общий для не тех вызывающих, выдаёт одному человеку ответ, сгенерированный для другого.

Это рабочее пространство не определяет ни одной собственной сущности каталога. Три файла сущностей здесь — Aggregate, Manifest и Release — это всё, что кому-либо приходится писать.

Что собирается

экземплярсущность Component из каталогачем он является здесь
routercore/gateway/litellmAI-шлюз: псевдоним чата assistant и псевдоним эмбеддингов embedder, каждый из которых обслуживается моделью, подключённой к его сокету models
chatcore/ai-model/openaiчат-модель за assistant — собственный API OpenAI, доступный по ссылке: для неё в кластере ничего не запускается
embeddingscore/ai-model/openai-embeddingмодель эмбеддингов за embedder, доступная тем же способом
cachecore/datastore/redisхранилище, в котором шлюз хранит свои ответы

Три ребра uses: два ведут в сокет models шлюза, по одному к каждой модели, и каждое несёт в качестве credential ключ, который шлюз предъявляет этой модели, а одно ведёт в его сокет cache_store и несёт в качестве credential пароль, который кэш предъявляет хранилищу. На шлюзе два подключения сущностей Feature: api_key — его административный ключ — и answers — кэш; и одно на хранилище, password — пароль, который оно требует. Оба подключения пароля читают один параметр, cache_password, а обе учётные записи моделей — другой, openai_key; сущность Release задаёт оба. Подключение answers указывает псевдоним эмбеддингов, который превращает каждый запрос в вектор, насколько похожими должны быть два запроса — 0.9 в виде косинусного сходства, — и сколько живёт сохранённый ответ: один час. Ключ scope в нём опущен, поэтому используется значение по умолчанию, end_user.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example ai-gateway-semantic-cache

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd ai-gateway-semantic-cache

Сборка

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

Это рабочее пространство разрешает сущности каталога из реестра по умолчанию, который указывает .aggrega-config.yaml. Реализация кэша запускает один плагин, который не поставляется ни с компилятором, ни с каталогом, — шаг конфигурации шлюза pipeline-step/litellm-gateway-config, который разрешение загружает из реестра, указанного в default_registry, — hub.aggrega.ai.

Сборка выводит следующее (<workspace> обозначает папку этого примера):

[… omitted: a line reporting on the gateway configuration step's plugin, five warnings, one per credential attachment, 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 and a total build time, which differ per run, and a notice that core/referenced-secret declares origin in both of its pillars]
Build completed: 13 files written to <workspace>/dist

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки сами. Если в папке рабочего пространства ещё нет папки `ai-gateway-semantic-cache`, вызовите один раз инструмент `scaffold`, задав для `example` значение `ai-gateway-semantic-cache` и не задавая `dir`: он запишет пример в новую папку `ai-gateway-semantic-cache`. Затем вызовите инструмент `build`, задав для `workspace_root` значение `ai-gateway-semantic-cache`, для `release` — `release.yaml`, для `auto_pull` — true и для `write` — true. Сообщите мне, какие файлы записала сборка; они находятся в `ai-gateway-semantic-cache/dist/`.

Сгенерированное дерево

dist/helm/
├── cache--password--cache-secret-cache-password.yaml
├── cache-default-service.yaml
├── cache-deployment.yaml
├── chat-service.yaml
├── embeddings-service.yaml
├── router--api-zukey--router-secret-router-api-key.yaml
├── router--assistant-zdcredential--router-secret-router-assistant-credential.yaml
├── router--embedder-zdcredential--router-secret-router-embedder-credential.yaml
├── router--replies-zdcredential--router-secret-router-replies-credential.yaml
├── router-default-service.yaml
├── router-deployment.yaml
└── router/
├── litellm-gateway-config/
│ └── configmap.yaml
└── request-guard/
└── request-guard.yaml

Подключение кэша не добавляет собственных файлов. Всё, что оно делает, записывается в конфигурацию шлюза. Каждая модель порождает один файл — Service, сопоставляющий внутрикластерное имя с хостом API OpenAI, а каждые учётные данные в подключении модели порождают отдельный Secret, названный по шлюзу и псевдониму подключения.

Обслуживаемые модели

Таблица маршрутизации, с которой начинается тело конфигурации шлюза, содержит по одной записи на каждое соединение на сокете models. Запись формируется из того, что публикует каждая модель, — её конечной точки, базового URL API OpenAI и имени модели — и называет переменную, под которой Recipe шлюза передаёт ключ этого соединения:

model_list:
- model_name: "assistant"
litellm_params:
model: "openai/gpt-4o"
api_base: "https://api.openai.com/v1"
api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEY
- model_name: "embedder"
litellm_params:
model: "openai/text-embedding-3-small"
api_base: "https://api.openai.com/v1"
api_key: os.environ/LITELLM_MODEL_EMBEDDER_API_KEY

Кэш глазами шлюза

Вот тело конфигурации шлюза, ключ config.yaml файла dist/helm/router/litellm-gateway-config/configmap.yaml, начиная с litellm_settings:

[… omitted: the routing table]
litellm_settings:
callbacks:
- /etc/litellm-request-guard/request_field_filter.filter
cache: true
cache_params:
host: os.environ/SEMANTIC_CACHE_STORE_HOST
port: os.environ/SEMANTIC_CACHE_STORE_PORT
redis_semantic_cache_embedding_model: embedder
redis_semantic_cache_index_name: router-answers
semantic_cache_scope: end_user
similarity_threshold: 0.9
supported_call_types:
- acompletion
- completion
- aresponses
- responses
- aanthropic_messages
- anthropic_messages
ttl: 3600
type: redis-semantic

Из него стоит извлечь пять вещей.

Адреса хранилища в нём нет. host и port называют две переменные окружения через собственный механизм косвенной ссылки шлюза, а Recipe шлюза задаёт их по ребру cache_store. Из dist/helm/router-deployment.yaml — env контейнера шлюза:

env:
- name: LITELLM_MASTER_KEY
valueFrom:
secretKeyRef:
name: router-api-key
key: master-key
- name: REDIS_PASSWORD
valueFrom:
secretKeyRef:
name: router-replies.credential
key: password
- name: LITELLM_MODEL_ASSISTANT_API_KEY
valueFrom:
secretKeyRef:
name: router-assistant.credential
key: api-key
- name: LITELLM_MODEL_EMBEDDER_API_KEY
valueFrom:
secretKeyRef:
name: router-embedder.credential
key: api-key
- name: SEMANTIC_CACHE_STORE_HOST
value: cache-default
- name: SEMANTIC_CACHE_STORE_PORT
value: "6379"

cache-default — это Service, который выпускает собственный Recipe хранилища, взятый из того, что этот Recipe публикует, а 6379 — публикуемый им порт. Кэш читает пароль хранилища из REDIS_PASSWORD — ссылки на Secret, который формирует credential на ребре cache_store, router-replies.credential, — и никогда не читает сам пароль. Хранилище формирует собственный Secret из того же параметра, cache-password, и запускается с --requirepass, прочитанным из него, поэтому пароль, который предъявляет кэш, и пароль, который требует хранилище, — одно значение, записанное один раз. Без ребра cache_store ни одна из трёх переменных, под которыми приходят адрес и пароль хранилища, не формируется, и кэш, которому негде хранить ответы, останавливает сборку, как описано ниже. Третья и четвёртая записи — ключи моделей, каждый из которых берётся по ссылке из Secret, формируемого учётными данными его собственного соединения, под переменной, которую называет его запись в таблице маршрутизации; провайдер helm записывает все записи, читаемые из Secret, перед обычными.

Модель эмбеддингов — это псевдоним из собственной карты шлюза. Шлюз отправляет каждый запрос к embedder через ту же карту, через которую проходит запрос вызывающей стороны, поэтому у кэша нет собственного адреса или учётных данных. Если указать псевдоним, которого карта не публикует, сборка остановится и выведет список публикуемых.

Время жизни задаёт хранилище. Каждый ответ записывается с ttl в качестве срока действия, поэтому Redis удаляет его через час после сохранения. Следующий запрос с этим промптом получает ответ от модели и сохраняется заново.

Указаны только те виды запросов, промпт которых кэш читает. Кэшируются чат-запросы, потоковые и нет, а также API responses и messages. Запрос completions не кэшируется, как и запрос embeddings: если оставить значение по умолчанию, шлюз сохранял бы ответ на каждый запрос embeddings, вычисляя для этого эмбеддинг каждого входа повторно, и не отдавал бы ни один из них обратно.

Индекс назван по шлюзу и подключению, router-answers, поэтому два шлюза одного Release, использующие общее хранилище, хранят ответы в разных индексах.

Кому отдаётся одна запись кэша

Сохранённый ответ отдаётся последующему запросу, только если совпадает всё, из чего состоит его корзина, а промпт похож на тот, на который он был дан, не менее чем на 0.9:

  • ключ, который предъявляет запрос, в том виде, в каком его проверил шлюз, вместе с командой и организацией этого ключа;
  • при end_user — конечный пользователь, которого называет запрос;
  • модель, которую запрашивает запрос, и прочие параметры запроса: другая температура — это другая корзина.

Шлюз записывает ключ, его команду и организацию и конечного пользователя в сам запрос. В запросе chat он записывает их в metadata запроса поверх любого значения, которое туда отправил вызывающий; в запросе responses или messages он хранит их отдельно от metadata вызывающего, удаляет из него все поля команды, организации или конечного пользователя, записанные вызывающим, а защита запросов, которую поставляет его Recipe, отклоняет запрос, называющий там ключ, metadata.user_api_key, с ответом HTTP 400 с именем поля. Поэтому никакой запрос не может попасть в корзину чужого ключа, назвав её.

Собственные metadata запроса всё же могут перемещать его между корзинами предъявленного им ключа. В запросе responses model_group занимает в его корзине место модели, которую запрашивает запрос. В запросе responses или messages caching_groups позволяет запросам, называющим одну и ту же группу псевдонимов моделей, совместно использовать ответы между ними. В запросе responses или chat redis_namespace держит запросы, называющие пространство имён, в корзинах отдельно от запросов, не называющих никакого. Ни одно из них не ведёт в корзину чужого ключа.

Ключ этого шлюза — его административный ключ, и он есть у каждого вызывающего. К шлюзу не подключена учётная база данных, поэтому он не выдаёт собственных ключей: каждый вызывающий предъявляет ключ, подключённый к api_key, а запрос без ключа или с ключом, который шлюз не выдавал, отклоняется до какого-либо поиска. Поэтому здесь ключ не отделяет одного вызывающего от другого, и при области по умолчанию двух вызывающих разделяет конечный пользователь, которого называет каждый запрос.

При end_user, значении по умолчанию, запись отдаётся запросам, называющим того же конечного пользователя. Шлюз считывает конечного пользователя из запроса: заголовок x-litellm-end-user-id или x-litellm-customer-id либо поле тела user, metadata.user_id, litellm_metadata.user или safety_identifier. Ответ, сохранённый для alice, отдаётся на похоже сформулированный вопрос alice, но не на вопрос bob.

Из этого следуют две вещи, и обе — поведение шлюза, а не конфигурация:

  • Шлюз не проверяет ни одно из этих имён. Тот, у кого есть ключ, может назвать любого конечного пользователя и получить то, что было сохранено для него. Храните ключ в приложении, которое знает своих конечных пользователей, и позвольте ему называть их; не передавайте ключ самим конечным пользователям.
  • Запросы, не называющие конечного пользователя, используют один общий кэш. Каждый такой запрос с тем же ключом обслуживается из тех же записей, кто бы его ни отправил.

При key каждый вызывающий, предъявляющий ключ, обслуживается из одного кэша. Добавьте scope: key в значения подключения и пересоберите: semantic_cache_scope в конфигурации примет значение key, и больше ничего в отрисованном выводе не изменится. Конечный пользователь, названный в заголовке, тогда не входит в корзину, поэтому ответ, сохранённый для alice, названной в заголовке x-litellm-end-user-id, отдаётся на похоже сформулированный вопрос bob, названного тем же способом, включая вызовы инструментов в нём. Однако поле тела user — один из прочих параметров запроса, поэтому два запроса, называющие там разных конечных пользователей, всё равно попадают в разные корзины, как и две температуры. Это подходит для кэша ответов, одинаковых для всех, и ни для чего другого.

Что останавливает сборку

Каждый из этих случаев — это предложение, которое выводит сборка, называя, что нужно изменить:

  • Нет административного ключа. Удалите привязку api_key, и сборка остановится ещё до того, как что-либо будет отрисовано:

    [… omitted: a line reporting on the gateway configuration step's plugin, 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-litellm" instance "router" assertion "gateway_checks_the_caller": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: core/semantic-caching attachment "answers" on "router" needs core/gateway/litellm to check every caller's key before a cached reply is served, but its api_key credential slot is not attached, so the gateway checks no caller and a cache bucket would be made only of what each caller claims. Attach a credential to the api_key slot of "router"
  • Нет хранилища. Удалите ребро cache_store, и сборка остановится, назвав сокет, который нужно подключить.

  • Хранилище, которое не публикует vector_search. Сокет допускает хранилища «ключ — значение», и Recipe шлюза останавливает сборку на хранилище, которое не заявляет, что предоставляет векторный поиск движка запросов Redis, с помощью которого кеш ищет свои ответы: Redis версии до 8.0 или Valkey ничего бы не кешировали, хотя каждый запрос по-прежнему выполнялся бы успешно.

  • Вторая привязка core/semantic-caching на шлюзе, у которого один кеш.

  • core/data-masking на том же шлюзе. Они объявляют конфликт, потому что кеш вычисляет ключ запроса после маскирования, и два запроса, различающиеся только тем, что заменяет маскирование, получали бы один сохранённый ответ.

Когда хранилище нельзя использовать

Шлюз подключается к хранилищу при обработке первого запроса, а не при запуске. Если он не может использовать хранилище — хранилище требует пароль, который шлюзу не передан, или отвергает переданный, — каждый поиск завершается промахом и ничего не сохраняется, хотя каждый запрос по-прежнему получает ответ от модели. Об этом сообщает только собственный журнал шлюза. Именно поэтому оба конца пароля читают один параметр: слот password хранилища и credential на ребре cache_store.

Где компилятор не интерпретирует

Компилятор передаёт имя Service хранилища и его порт из Recipe хранилища в окружение шлюза в виде строк, а псевдоним и числа — в конфигурацию шлюза. Он не подключается к хранилищу, не знает, отвечает ли что-нибудь по адресу cache-default:6379, и не знает, что такое конечный пользователь. Каждая остановка, описанная выше, объявлена собственными сущностями каталога — как утверждение в реализации или в Recipe шлюза либо как конфликт, который объявляют две сущности Features, — и ни одна из них не опирается на какое-либо понимание трафика.

Адаптация примера

  • Общий кеш на ключ. Добавьте scope: key к вложению answers, если всем вызывающим сторонам следует отдавать одни и те же ответы.
  • Хранилище без пароля. Удалите вложение password хранилища и credential на ребре cache_store одновременно, вместе с параметром cache_password в сущностях Aggregate и Release; тогда REDIS_PASSWORD шлюза отрисовывается пустым, и подключение выполняется без пароля. Если удалить только одно из двух вложений, кеш не сможет использовать хранилище.
  • Больше или меньше совпадающих запросов. Повысьте similarity_threshold, чтобы отдавать только более близкие совпадения, или понизьте, чтобы отдавать больше; подходящее значение зависит от модели эмбеддингов.