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

AI-шлюз, що відповідає тим, що вже казав

Асистентові підтримки цілий день ставлять ті самі запитання дещо різними словами. Шлюз перед його моделлю може відповісти на запитання відповіддю, яку він дав на попереднє, достатньо близьке за змістом, замість того щоб знову звертатися до моделі. Цей робочий простір компілює такий шлюз у маніфести 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

Перш ніж збирати 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

Цей робочий простір знаходить сутності каталогу в реєстрі за замовчуванням, який називає .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 — кінцевий користувач, якого називає запит;
  • модель, яку запитує запит, та інші параметри запиту — інша температура означає інший кошик.

Шлюз записує ключ, його команду й організацію та кінцевого користувача в сам запит. У чат-запиті він записує їх у metadata запиту поверх будь-якого значення, яке туди надіслав викликач; у запиті responses або messages він тримає їх окремо від metadata викликача, видаляє з нього будь-яке поле команди, організації чи кінцевого користувача, яке записав викликач, а захисник запитів, який постачає його Recipe, відхиляє запит, що називає там ключ, metadata.user_api_key, з HTTP 400 і назвою поля. Тож жоден запит не може потрапити до кошика іншого ключа, назвавши його.

Власний metadata запиту все ж може переміщувати його між кошиками ключа, який він пред’являє. У запиті responses model_group займає в кошику місце моделі, яку запитує запит. У запиті responses або messages caching_groups дає змогу запитам, що називають ту саму групу псевдонімів моделей, спільно використовувати відповіді між ними. У запиті responses або чат-запиті 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, щоб обслуговувати лише ближчі збіги, або зменште його, щоб обслуговувати більше; яке значення підходить, залежить від моделі ембедингів.