Агент, маршрутизатор і дві висхідні моделі
Агентний застосунок, що звертається до двох висхідних моделей провайдерів через один маршрутизатор у кластері, скомпільований у маніфести Kubernetes.
Агент запитує модель за одним іменем. За цим іменем стоїть маршрутизатор, що тримає мапу псевдонімів, а за мапою стоять два провайдери. Агент ніколи не дізнається, який провайдер відповів, ніколи не тримає облікових даних провайдера і не змінюється, коли мапу перенаправляють, — саме тому маршрутизатор і варто там розмістити.
Цей робочий простір не створює жодної власної сутності каталогу. Кожна сутність Component, Feature і Recipe, яку він називає, постачається в каталозі стандартної бібліотеки; три файли сутностей тут — Aggregate, Manifest і Release — це все, що будь-хто пише.
Що він збирає
agent ───────────────────┐ ┌────► openai/gpt-4o │ │ │ ▼ ├────► router ──────┤ checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4 (run state) │ │ an Ingress at ───────────┘ assistant.example.internalМаршрутизатор має два входи для запитів — агент звертається до нього через своє ребро model,
а все зовнішнє — через Ingress — і по одному виходу на кожен
запис мапи. Третій порт віддає його метрики збирачеві всередині кластера.
Три компоненти, і кожен виконує окреме завдання:
| екземпляр | Component із каталогу | що це тут |
|---|---|---|
router | core/gateway/litellm | компонент маршрутизації: одна кінцева точка, мапа псевдонімів, два вищестоящі провайдери. Він публікує свою адресу й псевдонім, який запитує агент |
agent | core/ai-agent/langgraph | застосунок, що запускає власний образ графа |
checkpointer | core/datastore/valkey | місце, де агент зберігає стан виконання, вибране за категорією сховища даних |
Два ребра uses, обидва до сокетів, які оголошує сутність Component агента: model
(обов’язковий, приймає компонент моделі або шлюз, що обслуговує API моделі, — маршрутизатор
належить до другого типу) і checkpointer_db (обов’язковий, вибір за
категорією сховища даних). Шість приєднань Feature чотирьох видів Feature — п’ять на
маршрутизаторі, одне на з’єднанні model агента, — кожне з яких додає щось
до згенерованого результату; розділ нижче показує, що створює кожне з них.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
aggrega scaffold --example ai-agent-and-model-routerПотім вона виводить команди, які слід виконати далі. Перша переходить у нову теку:
cd ai-agent-and-model-routerЗбирання
aggrega build --release release.yaml --auto-pullПеред збиранням релізу потрібен lockfile, а lockfile-и генеруються, а не постачаються, тож у свіжому клоні його немає. aggrega build за замовчуванням працює лише на читання:
без 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Цей робочий простір розв’язує свої сутності з реєстру за замовчуванням, який називає .aggrega-config.yaml, тому прапорець --catalog не потрібен.
Реалізація прикріплення selection маршрутизатора запускає один плагін, який не постачається ні з компілятором, ні з каталогом, — крок конфігурації шлюзу pipeline-step/litellm-gateway-config, який розв’язання завантажує з реєстру, названого в default_registry, — hub.aggrega.ai.
Кілька розділів нижче пропонують змінити рядок і перезібрати. Lockfile фіксує дайджест кожної сутності, яку розв’язав реліз, зокрема сутностей Aggregate і Manifest у цьому каталозі, а саму сутність Release записує за дайджестом її вмісту, — тож редагування будь-якого з цих трьох файлів робить lockfile застарілим, і наступне збирання зупиняється, а не рендерить із застарілою фіксацією. Повідомлення називає, що змінилося, — Release за його файлом, Aggregate чи Manifest за назвою — і виводить записаний дайджест поруч зі знайденим. Команда pull записує зміну, зберігаючи всі інші фіксації:
aggrega pull --release release.yamlВиконайте її та зберіть знову або зберіть із --auto-pull, що спершу виконує той самий pull.
У будь-якому разі зупинка — це мета, а не перешкода: збирання не рендерить
із фіксацією, яку бачить застарілою.
Збирання виводить таке (<workspace> позначає теку цього прикладу):
verify: plugin pipeline-step/litellm-gateway-config:1.0.0 host functions match the published .wasm[… omitted: three 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]Pull complete: release.lock (entities=24, source_artifacts=0, external_inputs=0)[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 12 files written to <workspace>/distСутності перевіряються на відповідність домовленостям каталогу один раз під час
розв’язання lockfile і один раз під час збирання релізу, і кожне зауваження,
виявлене цими перевірками, виводиться рядком lint:; цей реліз не має жодного. Щоб
запустити ті самі перевірки окремо й прочитати будь-яке зауваження повністю, із файлом
сутності, з якого воно походить, і тим, що узгодило б її:
aggrega lint --release release.yamlщо тут повідомляє conventions checked: 19 entities, 0 advisory finding(s).
З ШІ-асистентом
ШІ-асистент, налаштований з інструментами Aggrega, може зробити те саме: вставте йому цей промпт.
Використовуйте лише інструменти Aggrega і не створюйте жодної теки самостійно. Якщо тека робочого простору ще не містить теки `ai-agent-and-model-router`, викличте один раз інструмент `scaffold`, задавши для `example` значення `ai-agent-and-model-router` і не задаючи `dir`: він запише приклад у нову теку `ai-agent-and-model-router`. Потім викличте інструмент `build`, задавши для `workspace_root` значення `ai-agent-and-model-router`, для `release` — `release.yaml`, для `auto_pull` — true і для `write` — true. Скажіть мені, які файли записала збірка; вони лежать у `ai-agent-and-model-router/dist/`.Згенероване дерево
dist/helm/├── agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml├── agent-deployment.yaml├── checkpointer-default-service.yaml├── checkpointer-deployment.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--metrics--router-servicemonitor-router-scrape.yaml├── router--provider-zukey--router-secret-router-provider-key.yaml├── router--published--router-ingress-router-ingress.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlУ router/ лежать файли, які генерує сам Recipe маршрутизатора. Обидва походять
із пакетів, які Recipe імпортує, а не пише сам, тож кожен лежить під ключем, під яким його
імпортовано: litellm-gateway-config і request-guard.
Усе, що принесло приєднання, лежить у тому самому каталозі, що й власні маніфести
компонента, і має у назві файлу дві координати: компонент, до якого його
приєднано, і назву, яку дано приєднанню. router--metrics-- — це приєднання
metrics на router. Що звідки походить, і далі можна прочитати з
дерева, а кожен файл лежить там, де його знайде інструмент, що читає один каталог, —
саме так і поводяться споживачі цієї цілі, якщо ви не вкажете інакше.
Дві координати закодовано, а не записано так, як ви їх увели, бо
вони ділять один рядок із власною назвою файлу. Символ, який назва файлу не може
безпечно містити, стає -z і літерою: api_key стає api-zukey;
router_model.credential — назва приєднання на з’єднанні агента
router_model: псевдонім з’єднання, крапка і слот — стає
router-zumodel-zdcredential; а feature.aggrega.ai/monitoring — назва
приєднання, яку створює власна анотація сутності Feature, — стала б
feature-zdaggrega-zdai-zsmonitoring. Власна назва файлу зберігає
усі свої крапки, тож суфікс .yaml і далі читається як суфікс.
Там, де сторінка тут показує, що створила збірка, блок скопійовано зі справжнього запуску — див. Читання виводу на цих сторінках, щоб дізнатися про домовленість і позначку, якою вона позначає пропущені рядки.
Таблиця маршрутизації
Сенс існування маршрутизатора — його мапа, і ця мапа потрапляє у відрендерений результат, а не лишається в авторському файлі. Ось увесь блок data файлу
dist/helm/router/litellm-gateway-config/configmap.yaml:
data: config.yaml: | model_list: - model_name: assistant litellm_params: model: openai/gpt-4o api_key: os.environ/LITELLM_PROVIDER_API_KEY - model_name: assistant litellm_params: model: anthropic/claude-sonnet-4 api_key: os.environ/LITELLM_PROVIDER_API_KEY litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter - prometheus router_settings: routing_strategy: latency-based-routingі блок data другого ConfigMap,
dist/helm/router/request-guard/request-guard.yaml, без тексту файлів,
які він містить:
data: request_field_filter.py: | [… omitted: the text of the router's request guard, a Python module described below] path-allowlist.conf: | [… omitted: the configuration of the router's path allowlist, described below]З них варто вичитати п’ять речей.
Обидва записи публікують той самий псевдонім. Саме це дає маршрутизатору вибір
для кожного запиту, а router_settings наприкінці тіла вказує,
як він його робить: latency-based-routing, що його записує туди
приєднання selection маршрутизатора, а не його власний Recipe, як показує розділ про це
приєднання нижче. Мапа, усі псевдоніми якої різні, маршрутизує лише за назвою,
і стратегія нічого в цьому не змінює. Спільний псевдонім — також причина, чому
обидва записи введено вручну у values.models, а не обслуговуються з компонентів моделей,
під’єднаних до сокета models маршрутизатора: під’єднана модель обслуговується під
псевдонімом власного з’єднання, який жоден інший запис не може публікувати, тож дві під’єднані
моделі ніколи не мають спільного псевдоніма. Друга причина стосується Anthropic: маршрутизатор записує
запис під’єднаної моделі лише через API OpenAI, тоді як модель Anthropic
відповідає через власний API, тож під’єднання core/ai-model/anthropic зупиняє збірку з вказівкою
ввести цю висхідну модель у мапу вручну.
Цілі — це рядки, які компілятор не інтерпретує.
openai/gpt-4o — детермінований вказівник: запущений проксі розв’язує його, коли
обслуговує запит. Компілятор ніколи не звертається до провайдера під час збирання, тому
не може сказати вам, що ціль існує, що її написано правильно чи що ваш
обліковий запис має до неї доступ. Замініть openai/gpt-4o на openai/not-a-real-model, і
збірка все одно вдасться — збій настане під час запиту, від провайдера.
У цьому файлі немає жодного значення облікових даних. Натомість кожен запис називає змінну середовища через власну непряму адресацію проксі. Значення потрапляє в контейнер зовсім іншим шляхом, показаним нижче.
Кожен запит спершу проходить через охоронця. Перший запис callbacks реєструє
модуль request_field_filter за повним шляхом його файлу: другий ConfigMap
змонтовано в контейнері маршрутизатора в /etc/litellm-request-guard, окремому
каталозі поруч із /etc/litellm, де змонтовано перший і звідки
проксі читає свою конфігурацію. Цей другий ConfigMap походить із
LiteLLMGuard#/artifacts/RequestGuard, пакета, який імпортує кожен Recipe, що запускає цей проксі,
тож охоронець і список дозволених нижче мають один текст усюди, де працює проксі.
Recipe маршрутизатора постачає цього охоронця в кожному Release, бо
маршрутизатор зберігає облікові дані провайдера. Від викликача він пересилає лише ті поля запиту,
які проксі оголошує для маршруту, яким пішов запит, а також ті, що Release
називає в infra.admitted_request_fields маршрутизатора, а на будь-яке інше
поле відповідає помилкою з його назвою, нічого не пересилаючи — тож викликач не може спрямувати
маршрутизатор на власну адресу через список моделей у тілі запиту чи надіслати
власний ключ провайдера замість ключа маршрутизатора. Не може викликач і задати
ідентичність, яку маршрутизатор сам записує в кожен запит, — хеш перевіреного ним ключа,
команду й організацію цього ключа та кінцевого користувача: у запиті responses чи
messages, де маршрутизатор тримає metadata викликача окремо від своїх,
він вилучає будь-яке поле команди, організації чи кінцевого користувача, записане туди викликачем,
а охоронець відхиляє запит, що називає там ключ, metadata.user_api_key,
а на кожному іншому маршруті значення маршрутизатора замінює будь-яке надіслане викликачем. Цей
Release більше нічого не допускає. Другий запис, prometheus, — власний
зворотний виклик метрик проксі, який вмикає значення metrics_enabled маршрутизатора;
приєднання metrics нижче збирає те, що він записує.
Досяжні лише власні маршрути маршрутизатора. Охоронець бачить лише маршрути,
які передають йому запит, тому другий файл другого ConfigMap налаштовує
другий контейнер пода, який монтує лише цей ConfigMap і запускає офіційний
образ nginx як список дозволених шляхів. Сам маршрутизатор слухає на loopback-адресі пода,
куди ніщо ззовні пода не дістається, а список дозволених
слухає на порту 4000 — порту, на який націлено Service нижче. Він пересилає запит,
лише коли його метод і шлях належать до маршрутів, які обслуговує маршрутизатор, — маршрутів
запитів до моделі, які перевіряє охоронець, у написаннях, що їх маршрутизатор обслуговує
незалежно від псевдоніма, серед них /v1/chat/completions і /v1/messages; переліку
моделей; перевірок стану; а з його
адміністративних маршрутів — керування ключами, — а на кожен інший шлях відповідає 403,
нічого не пересилаючи. Тож маршрути підрахунку токенів проксі, його наскрізні маршрути до
власних API провайдерів, інші адміністративні маршрути та адміністративна
консоль недосяжні через маршрутизатор, як і маршрут моделі,
шлях якого містить назву моделі, як у шляхах, що їх надсилає клієнт Azure:
там проксі читає слова в шляху, зокрема псевдонім, щоб вирішити, як
записати запит, і маршрутизатор відхилив би на ньому запит до власного
assistant цієї мапи. Метрики проксі також не входять до цих маршрутів: порт
4000 відповідає на /metrics кодом 403. Коли metrics_enabled маршрутизатора має значення true, як його задає
Aggregate, список дозволених також слухає на порту 9090 і пересилає там лише GET-запит до
/metrics — до слухача, який проксі тримає для своїх метрик на
loopback-адресі, — а на кожен інший запит відповідає 403. Цей порт не перевіряє
викликача, а метрики називають хешовані ключі, псевдоніми ключів та електронні адреси користувачів, яким
маршрутизатор приписує витрати.
Що публікує маршрутизатор
Recipe маршрутизатора публікує ті самі два ключі, що й кожен компонент моделі: endpoint — базову URL-адресу, яку отримує клієнтська бібліотека, і model — назву, яку запитує запит. Саме це дає змогу сокету model агента прийняти маршрутизатор замість моделі. Селектор сокета —
component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: він
допускає компонент категорії моделі або шлюзу, що має мітку
model.aggrega.ai/api, яка називає API моделі, що відповідає за адресою, опублікованою компонентом. Маршрутизатор має model.aggrega.ai/api: openai. Шлюз, що не обслуговує жодного API моделі, такої мітки не має, і ребро від агента до нього зупиняє збирання з повідомленням, яке називає сокет і селектор, якому ціль не відповідає.
Адреса — це Service, який створює власний Recipe маршрутизатора; ось увесь spec файлу
dist/helm/router-default-service.yaml:
spec: type: ClusterIP selector: app: router ports: - name: http port: 4000 targetPort: http - name: metrics port: 9090 targetPort: metricsRecipe складає endpoint, який публікує, http://router-default:4000/v1,
із тих самих двох фактів, з яких утворено назву та порт Service: власної назви компонента та його infra.port. Порт, на який спрямовано Service, http, — це той, на якому слухає список дозволених шляхів маршрутизатора; другий, metrics, є тому, що метрики маршрутизатора увімкнено, і передає лише їх. Жоден із трьох файлів не прописує
router-default явно. Перейменуйте компонент router — його ключ в Aggregate
і в Release, а також ребро агента, що його називає, — і адреса, яку отримує агент, зміниться відповідно: після перейменування на gateway значення OPENAI_BASE_URL агента буде
http://gateway-default:4000/v1.
Назва — це псевдонім, який маршрутизатор публікує як свою модель. Ця мапа публікує один псевдонім, assistant, з обох своїх записів, тож маршрутизатор публікує саме його, а його values.model не задано. Дайте другому запису власний псевдонім —
скажімо, summarizer — і збирання зупиниться ще до рендерингу, бо маршрутизатор може публікувати лише один. Ця зупинка — E0033, невдала перевірка твердження сутності Component маршрутизатора, і її повідомлення закінчується реченням самого правила:
values.model is not set, but values.models publishes 2 aliases (assistant,
summarizer), so the gateway cannot tell which one a component wired to it asks
for; set values.model to one of them (values.model не задано, але values.models публікує 2 псевдоніми (assistant, summarizer), тож шлюз не може визначити, який із них запитує під’єднаний до нього компонент; задайте values.model одним із них). Задання model: assistant поруч із
models усуває її, і агент знову отримує assistant. Викликач, якому потрібен
summarizer, запитує його в того самого endpoint за назвою.
Що отримує агент
Recipe агента читає обидва його ребра та власні значення агента й перетворює їх на змінні середовища контейнера. Ось увесь блок env файлу dist/helm/agent-deployment.yaml:
env: - name: OPENAI_API_KEY valueFrom: secretKeyRef: name: agent-router-model.credential key: api-key - name: LANGGRAPH_DEFAULT_RECURSION_LIMIT value: "25" - name: OPENAI_BASE_URL value: http://router-default:4000/v1 - name: OPENAI_MODEL value: assistant - name: LANGGRAPH_CHECKPOINTER_HOST value: checkpointer-default - name: LANGGRAPH_CHECKPOINTER_PORT value: "6379" - name: LANGGRAPH_GRAPH_ENTRYPOINT value: app.graph:graphПерший запис походить із прикріплення, яке несе ребро model, і провайдер helm записує такий запис, що читається із Secret, перед звичайними. Ліміт рекурсії — це власний recursion_limit агента під змінною, яку LangGraph читає самостійно; наступні два походять із ребра model, два після них — з ребра checkpointer_db, а останній — це власний graph_entrypoint агента під типовою назвою, яку читає код застосунку і яку замінив би блок inject на самому компоненті. Зверніть увагу на те, чого сутності Aggregate не довелося вказувати: жодне ребро не містить блоку inject, бо споживчий Recipe доставляє кожне з’єднання під типовими назвами, які замінив би блок inject на ребрі. Розробник декларує, що агент використовує модель; змінна, під якою надходить її кінцева точка, — це та, яку читає клієнтська бібліотека, і вона лишається такою, як визначає ребро.
Зверніть увагу також на LANGGRAPH_CHECKPOINTER_PORT: "6379". Сутність Release декларує
checkpointer: {} і нічого не налаштовує, тож цей порт — власне значення за
замовчуванням зі схеми кешу Component, матеріалізоване й передане через ребро.
Агент спілкується з маршрутизатором саме тим діалектом, яким спілкувався б із провайдером напряму, — базова URL-адреса, назва моделі та ключ. Саме це дає змогу вставити, перемістити або перенаправити маршрутизатор без змін у застосунку.
Шість прикріплень і що рендерить кожне з них
Прикріплення, яке нічого не змінює у вихідних даних, нічого не навчає. Кожне з цих шести щось туди додає.
api_key на маршрутизаторі — ключ, якого він вимагає від викликачів
core/referenced-secret, що заповнює слот, який декларує Component маршрутизатора;
ключ, який він зберігає, LiteLLM називає своїм майстер-ключем. Він рендерить власний Secret,
а контейнер маршрутизатора посилається на нього. З
dist/helm/router--api-zukey--router-secret-router-api-key.yaml:
stringData: master-key: "dev-router-admin-key-change-me"і в env контейнера маршрутизатора, з dist/helm/router-deployment.yaml:
- name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-keyКонтейнер містить посилання, а не значення. Назву Secret публікує прикріплення, а читає споживач, тож жодна сторона не виводить її повторно.
provider_key на маршрутизаторі — ключ, який він пред’являє вгору за потоком
Та сама Feature в іншому слоті, і різниця між двома слотами —
суть маршрутизатора. Це єдиний обліковий ключ записів, введених у
values.models, тут обох; модель, під’єднана до сокета models
маршрутизатора, натомість пред’являє ключ, який несе її власне з’єднання, і ніколи не цей. З
dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:
stringData: provider-key: "upstream-provider-key-change-me"і в тому самому env контейнера:
- name: LITELLM_PROVIDER_API_KEY valueFrom: secretKeyRef: name: router-provider-key key: provider-keyЦе прикріплення також змінює таблицю маршрутизації. Погляньте ще раз на блок
data таблиці маршрутизації вище: кожен запис мапи містить
api_key: os.environ/LITELLM_PROVIDER_API_KEY, що називає цю саму змінну.
Вилучіть прикріплення provider_key із сутності Aggregate і перезберіть. Збірка
повідомляє про одинадцять файлів замість дванадцяти — Secret зник, — а ConfigMap
таблиці маршрутизації відрізняється рівно цими двома рядками api_key і нічим іншим;
ConfigMap запобіжника не змінюється. Решта мапи зберігає авторський порядок
і форматування, маршрутизатор і далі обслуговує й маршрутизує, а маршрутизований запит тепер
завершується помилкою на боці провайдера, бо немає облікових даних для пред’явлення.
Назву змінної записано один раз у Recipe маршрутизатора, і звідти її читають і таблиця маршрутизації, і середовище контейнера, тож таблиця не може назвати змінну, яку ніщо не встановлює.
Два облікові ключі залишаються окремими, і саме це розділення дає маршрутизатор: ключ вгору за потоком залишається всередині маршрутизатора, а викликовий застосунок не має нічого, крім ключа до маршрутизатора.
credential на з’єднанні model агента — ключ, який він пред’являє маршрутизатору
Знову core/referenced-secret, на іншому боці тієї самої розмови. Сокет
model агента декларує слот credential, тож ключ прикріплюється на
з’єднанні, на якому його пред’являють, під ребром у сутності Aggregate:
uses: model: router_model: target: router features: credential: type: core/referenced-secret values: key: api-key origin: "{{ .parameters.router_admin_key }}"З
dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml:
stringData: api-key: "dev-router-admin-key-change-me"Це те саме значення, що й master-key маршрутизатора вище, і його не записано
двічі. Обидва прикріплення читають один піднятий параметр:
origin: "{{ .parameters.router_admin_key }}"Сутність Aggregate декларує параметр, а сутність Release його виконує, тож ключ має одне авторське місце, і два Secret неможливо відредагувати порізно. Змініть його один раз у сутності Release, і обидва відрендерені Secret зміняться разом.
Кожне прикріплення все одно рендерить власний Secret, названий за компонентом,
який його споживає, — а для агентового ще й за з’єднанням, на якому його прикріплено:
agent-router-model.credential. Спільний параметр поділяє значення,
а не ресурс.
published на маршрутизаторі — адреса поза кластером
core/public-ingress, що не заповнює жодного слоту: його допускає власний селектор,
component.aggrega.ai/type=server, який має маршрутизатор. Він додає
ресурс, про який Recipe маршрутизатора нічого не знає. Увесь spec файлу
dist/helm/router--published--router-ingress-router-ingress.yaml:
spec: rules: - host: assistant.example.internal http: paths: - path: / pathType: Prefix backend: service: name: router-default port: name: httpРозробник прикріплює його в сутності Aggregate з path, бо те, які
запити обслуговує застосунок, — частина того, чим є застосунок. Оператор
записує host і назву порту в записі сутності Release для того самого
прикріплення: хост — це назва маршрутизатора в середовищі, тож оператор
задає її для кожного середовища, у Release кожного середовища. Бекенд-Service не
надав ні той, ні інший: service_name не встановлено, і реалізація прикріплення
відступає до Service, який створює власний Recipe маршрутизатора. У вихідних даних немає
поля ingressClassName, бо ніщо його не встановило, а реалізація пропускає те,
чого їй не передали, залишаючи ресурс класу кластера за замовчуванням.
metrics на маршрутизаторі — ціль збирання метрик
core/prometheus-exporter, який допускає той самий селектор і який додає ще один
власний ресурс. Кожен його вхід — це операторське налаштування, а не
намір застосунку: як часто платформа збирає метрики і який порт і шлях вона
читає — властивості платформи, — тож оператор прикріплює його в сутності
Release, у записі маршрутизатора, з його типом поруч з infra. Сутність Aggregate
його не згадує:
components: router: features: metrics: type: core/prometheus-exporter infra: interval: 30s port: metrics path: /metricsУвесь spec файлу
dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml:
spec: selector: matchLabels: app.kubernetes.io/name: router endpoints: - port: metrics interval: 30s path: /metricsport називає порт Service, а не номер: metrics, який
створює Recipe маршрутизатора, бо сутність Aggregate встановлює значення metrics_enabled
маршрутизатора, і який віддає його метрики. Це також назва порту за замовчуванням
Feature, тут виписана разом з двома іншими параметрами. Порт http, на який маршрутизує
Ingress вище, відповідає на /metrics кодом 403, тож збирання, спрямоване туди, нічого
не зібрало б. Чи віддаються метрики взагалі — вибір розробника, зроблений
у сутності Aggregate; як часто і з якого порту та шляху платформа їх збирає — вибір
оператора, зроблений тут.
selection на маршрутизаторі — як він обирає між своїми цілями
core/target-selection, що прикріплюється до шлюзу з
gateway.aggrega.ai/intelligence: semantic, як-от маршрутизатор. Спосіб, у який
маршрутизатор обирає, — частина того, чого застосунок від нього вимагає, тож розробник
прикріплює його в сутності Aggregate, з strategy як значенням:
components: router: features: selection: type: core/target-selection values: strategy: latencyа сутність Manifest прив’язує його до реалізації для цього маршрутизатора:
core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0Він не рендерить власного файлу. Його реалізація записує одне налаштування в
таблицю маршрутизації, яку рендерить Recipe маршрутизатора, — останні два рядки блоку
data вище:
router_settings: routing_strategy: latency-based-routingЗ ним проксі надсилає кожен запит до assistant на той запис, чиї останні
десять відповідей забрали в середньому найменше часу, у перерахунку на вихідний токен, якщо відповідь
повідомляє свої токени, а ще не випробуваний запис вважається найшвидшим, тож кожен
випробовується, перш ніж вирішать середні. Вилучіть прикріплення
із сутності Aggregate і перезберіть: збірка й далі повідомляє про дванадцять файлів, а
ConfigMap таблиці маршрутизації відрізняється рівно цими двома рядками. Recipe
маршрутизатора не записує власної стратегії, а без неї проксі обирає між
двома записами випадково.
Запросіть натомість strategy: cost, і збірка зупиниться, нічого не записавши. Зупинка —
це E0033, невдала перевірка реалізації, і її повідомлення закінчується
власним реченням правила: core/target-selection attachment “selection” on
“router” asks for strategy cost, but core/gateway/litellm cannot choose between
the entries of its model map by cost: the proxy looks each entry’s target up,
exactly as written, in its own price table, which names OpenAI’s and Anthropic’s
models without the provider prefix a target carries (gpt-4o, not
openai/gpt-4o) and which the proxy may fetch afresh when it starts, and it
prices an entry it does not find, and that carries no price of its own, at a
fixed fallback, so the entries sharing an alias are priced alike and the choice
falls to their order. Ask for strategy latency, or remove the attachment (прикріплення core/target-selection «selection» на «router» запитує стратегію cost, але core/gateway/litellm не може обирати між записами своєї мапи моделей за вартістю: проксі шукає ціль кожного запису, точно як її записано, у власній таблиці цін, яка називає моделі OpenAI та Anthropic без префікса провайдера, що його має ціль (gpt-4o, а не openai/gpt-4o), і яку проксі може завантажити заново під час запуску, а запис, якого не знаходить і який не має власної ціни, оцінює за фіксованою резервною ціною, тож записи зі спільним псевдонімом оцінюються однаково, і вибір визначає їхній порядок. Запросіть стратегію latency або вилучіть прикріплення). Обидві
цілі тут записано саме так, тож проксі надсилав би кожен запит на
першу з них, тоді як сутність Aggregate запитувала вартість.
Де компілятор не інтерпретує
Адресу агента та назву моделі зчитано з того, що публікує маршрутизатор, тож жодну пару назв у трьох файлах не доводиться узгоджувати вручну. Збірка перевіряє лише власне правило маршрутизатора: псевдонім, який він публікує, має бути одним із тих, що публікує його мапа, — це правило оголошує його сутність Component, а збірка обчислює його, як і будь-яке інше твердження, яке несе сутність.
Решта — це рядки, що передаються з одного місця в інше. Компілятор маршрутизує адресу й псевдонім, не читаючи їх: він не знає, що одне є іменем хоста, а інше — назвою моделі, і не має доступу до запущеного кластера, щоб перевірити, чи щось відповідає за адресою router-default:4000. Мітка model.aggrega.ai/api, за якою було допущено маршрутизатор, — такий самий рядок: селектор сокета зіставляє її, і ніщо не перевіряє, який API насправді там відповідає. І кожен target у мапі — це вказівник, який розв’язує запущений проксі: змініть openai/gpt-4o на openai/not-a-real-model, і збірка все одно завершиться успішно, а збій з’явиться під час запиту.
Це та сама властивість, завдяки якій працює решта прикладу. Оскільки компілятор не інтерпретує того, що передає, маршрутизатор можна перенаправити на іншого постачальника, агента можна під’єднати до іншого маршрутизатора, а реалізацію облікових даних можна замінити на реалізацію на основі сховища — і все це без потреби компілятору щось із цього розуміти та без змін в агенті.
Адаптація прикладу
-
Перенаправте провайдера. Відредагуйте
targetу мапі маршрутизатора. Більше нічого не змінюється: ні модель, ні агент, ні відрендерений Secret. -
Додайте третього провайдера. Додайте запис до мапи. Якщо він публікує наявний псевдонім, стратегія починає вибирати між трьома. Якщо він публікує новий, мапа публікує два псевдоніми, а
values.modelмаршрутизатора називає той, який отримує агент; виклик, якому потрібен інший, запитує його за назвою. Модель, яку моделює каталог і чиїм API є OpenAI API, можна натомість під’єднати до сокетаmodelsмаршрутизатора під її власним псевдонімом, і вона пред’являтиме ключ, який несе її з’єднання; тодіvalues.modelназиває псевдонім, який отримує агент. -
Отримуйте облікові дані зі сховища. Змініть єдиний рядок у сутності Manifest, що прив’язує
core/referenced-secret, наhelm/k8s-external-secretі перезберіть. Кожен відрендеренийSecretстаєExternalSecret, що називає запис у сховищі секретів кластера, який узгоджуватиме оператор сховища, — а відрендерене посилання кожного споживача залишається побайтово ідентичним, бо локатор публікує сторона-виробник, а не узгоджують обидві сторони. Більше нічого в трьох файлах не потрібно змінювати, щоб збірка вдалася.Утім, одну річ потрібно переписати, перш ніж заміна матиме сенс:
originзмінює значення між двома реалізаціями. Реалізація цього робочого простору читає його як значення для зберігання; інша — як ключ, за яким отримують дані. Якщо замінити рядок, не переглянувши значенняorigin, відрендеренийremoteRef.keyбуде тим заповнювачем, що стояв замість значення, — тут цеdev-router-admin-key-change-me. Тоді жоден елемент вихідного дерева не містить цей рядок як секретний матеріал, але він усе ще присутній як ключ сховища, що називає запис, якого не існує. -
Приберіть маршрутизатор. Спрямуйте ребро
modelагента натомість на компонент моделі окремого провайдера. Тоді агент сам зберігає облікові дані провайдера, а саме цього компромісу маршрутизатор і покликаний уникнути. -
Під’єднайтеся до маршрутизатора, якого каталог не моделює. Спрямуйте ребро
modelагента на компонентcore/ai-model/openai-compatibleі впишіть адресу цього маршрутизатора в йогоinfra.endpointу сутності Release. За цим компонентом у кластері нічого не працює, тож вписувати адресу й підтримувати її відповідність сервісу, який вона називає, має оператор.
Про спільне використання одних облікових даних у з’єднаннях кількох споживачів див. model-api-key-sharing. Про сокет, який не оголошує жодна сутність каталогу, див. adhoc-uses-socket.