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

Агент, маршрутизатор и две вышестоящие модели

Приложение-агент, которое обращается к двум вышестоящим моделям провайдеров через один маршрутизатор внутри кластера, скомпилированное в манифесты 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 из каталогачем он является здесь
routercore/gateway/litellmкомпонент маршрутизации: одна конечная точка, карта псевдонимов, два вышестоящих провайдера. Он публикует свой адрес и псевдоним, который запрашивает агент
agentcore/ai-agent/langgraphприложение, запускающее собственный образ графа
checkpointercore/datastore/valkeyместо, где агент хранит состояние выполнения; выбирается по категории хранилища данных

Два ребра uses, оба в сокеты, которые объявляет сущность Component агента: model (обязательный, допускает компонент модели или шлюз, обслуживающий API модели, — маршрутизатор относится ко второму) и checkpointer_db (обязательный, выбор по категории хранилища данных). Шесть подключений Feature четырёх видов Feature — пять на маршрутизаторе, одно на соединении model агента, — и каждое из них добавляет что-то в результат рендеринга; в разделе ниже показано, что даёт каждое.

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

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

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

Terminal window
aggrega scaffold --example ai-agent-and-model-router

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

Terminal window
cd ai-agent-and-model-router

Сборка

Terminal window
aggrega build --release release.yaml --auto-pull

Перед сборкой релизу нужен lock-файл, а lock-файлы генерируются, а не поставляются, поэтому в свежем клоне его нет. aggrega build по умолчанию работает только на чтение: без 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, поэтому флаг --catalog не нужен.

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

В нескольких разделах ниже предлагается изменить строку и пересобрать. Lock-файл фиксирует дайджест каждой сущности, разрешённой релизом, включая сущность Aggregate и сущность Manifest в этом каталоге, и записывает саму сущность Release по дайджесту её содержимого, — поэтому правка любого из этих трёх файлов делает lock-файл устаревшим, и следующая сборка останавливается, а не выполняет рендеринг по устаревшей фиксации. Сообщение называет, что изменилось, — Release по его файлу, Aggregate или Manifest по имени — и выводит записанный дайджест рядом с обнаруженным. Команда pull записывает изменение, сохраняя все остальные фиксации:

Terminal window
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

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

Terminal window
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: маршрутизатор записывает запись подключённой модели только через OpenAI API, а модель Anthropic отвечает на собственном API, поэтому подключение core/ai-model/anthropic останавливает сборку с указанием вписать этот upstream в карту вручную.

Цели — это строки, которые компилятор не интерпретирует. 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: metrics

Recipe составляет публикуемый им 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: /metrics

port называет порт 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 — это API OpenAI, можно вместо этого подключить к сокету 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.