跳转到内容
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

路由器有两个请求入口——agent 通过其 model 边访问它,集群外部的任何调用方则通过 Ingress 访问它——并且每个映射条目对应一个出口。第三个端口向集群内的抓取器提供其指标。

共 3 个组件,每个承担不同的职责:

实例目录中的 Component它在此处的角色
routercore/gateway/litellm路由组件:一个端点、一份别名映射、两个上游 provider。它发布自己的地址以及 agent 所请求的别名
agentcore/ai-agent/langgraph应用本身,运行它自己的 graph 镜像
checkpointercore/datastore/valkeyagent 保存运行状态的位置,按 datastore 类别选定

两条 uses 边,均指向 agent 的 Component 所声明的插槽:model(必需,接受一个模型组件或一个提供模型 API 的网关——路由器属于后者)和 checkpointer_db(必需,按 datastore 类别进行选择)。共 6 个 Feature 挂载,涉及 4 种 Feature 类型——5 个在路由器上,1 个在 agent 的 model 连接上——每一个都会在渲染输出中产生内容;下一节展示每个挂载产生的结果。

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

将示例写入一个以其命名的新文件夹:

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

release 在构建之前需要一个锁文件,而锁文件是生成的而非随附发布的,因此新克隆的仓库中没有锁文件。aggrega build 默认是只读的: 没有锁文件时,它会停止并指出两种继续的方式。先解析出一个锁文件,或者 让构建来填充它:

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 标志。

router 的 selection 附加项在实现时会运行一个既不随编译器也不随目录提供的插件,即网关配置步骤 pipeline-step/litellm-gateway-config,解析过程会从 default_registry 指定的注册表 hub.aggrega.ai 获取它。

下文的多个小节会要求你修改一行并重新构建。 锁文件为该 release 解析的每个实体固定一个摘要,其中包括本目录中的 Aggregate 和 Manifest,并按内容摘要记录 Release 本身——因此编辑这三个文件中的任何一个都会使锁文件过期,下一次构建会停止,而不是基于过期的固定版本进行渲染。该消息会指出发生了什么变化——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

这些实体会依据目录的约定接受两次检查:一次在解析 锁文件时,一次在构建 release 时。这些检查产生的每条建议 都会以 lint: 行的形式打印;此 release 没有产生任何建议。若要 单独运行同样的检查,并完整查看每条建议及其来源实体 文件和使其符合约定所需的修改:

Terminal window
aggrega lint --release release.yaml

此处会报告 conventions checked: 19 entities, 0 advisory finding(s)。

借助 AI 助手

已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。

只使用 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/ 下是 router 的 Recipe 自身输出的文件。两者都来自该 Recipe 导入而非自行编写的 bundle,因此各自位于导入时所用的键之下:litellm-gateway-config 和 request-guard。

由附件带来的所有内容都与该组件自身的 manifest 位于同一目录,并在文件名中携带两个坐标:它所附加到的组件,以及该附件被赋予的名称。router--metrics-- 即 router 上的 metrics 附件。从目录树中仍能看出哪些内容来自何处,而每个文件都位于只读取一个目录的工具能找到它的地方——除非你另行指定,该目标的使用方正是这样做的。

这两个坐标经过编码,而不是按你输入的原样写出,因为它们与文件自身的名称共用一个字符串。文件名无法安全携带的字符会变为 -z 加一个字母:api_key 变为 api-zukey;router_model.credential(agent 的 router_model 连接上的附件所取的名称,即连接的别名、一个点和槽位)变为 router-zumodel-zdcredential;而 feature.aggrega.ai/monitoring(由 Feature 自身的注解生成的附件名称)会变为 feature-zdaggrega-zdai-zsmonitoring。文件自身的名称保留其中的所有点,因此 .yaml 后缀仍可读作后缀。

本文档中凡是展示构建产出的地方,代码块都复制自一次真实运行——关于该约定以及用于标记省略行的符号,请参阅阅读这些页面上的输出。

路由表

路由器存在的意义在于它的映射,而这份映射会进入渲染输出,而不是只留在编写的文件里。下面是 dist/helm/router/litellm-gateway-config/configmap.yaml 的完整 data 块:

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

以及第二个 ConfigMap dist/helm/router/request-guard/request-guard.yaml 的 data 块,其中省略了它所携带文件的文本:

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 会中止构建,并提示改为把该上游手工写入映射。

目标是编译器不解释的字符串。 openai/gpt-4o 是一个确定性的指针:运行中的代理在处理请求时解析它。编译器在构建时从不联系 provider,因此它无法告诉你某个目标是否存在、拼写是否正确,或者你的账户能否访问它。把 openai/gpt-4o 改成 openai/not-a-real-model,构建依然成功——失败在请求时才出现,来自 provider。

此文件中没有任何凭据值。 每个条目改为通过代理自身的间接机制指定一个环境变量。值经由完全不同的途径到达容器,见下文。

每个请求都会先经过一道防护。 第一个 callbacks 条目按文件的完整路径注册模块 request_field_filter:第二个 ConfigMap 挂载在 router 容器的 /etc/litellm-request-guard,这是一个独立的目录,位于挂载第一个 ConfigMap、供代理读取其配置的 /etc/litellm 旁边。第二个 ConfigMap 来自 LiteLLMGuard#/artifacts/RequestGuard,这是每个运行该代理的 Recipe 都会导入的一个 bundle,因此无论代理在何处运行,该防护和下文的允许列表都只有一份文本。router 的 Recipe 在每个 Release 上都交付这道防护,因为 router 持有提供方凭据。它只转发调用方请求中代理为该请求所走路由声明的字段,以及 Release 在 router 的 infra.admitted_request_fields 中列出的字段;对任何其他字段,它返回一个指明该字段的错误,不转发任何内容——因此调用方无法通过请求体中的模型列表让 router 指向它自己的地址,也无法发送它自己的提供方密钥来替代 router 的密钥。调用方同样无法设置 router 自己写入每个请求的身份信息——即它所验证的密钥的哈希、该密钥的团队和组织,以及最终用户:在 responses 或 messages 请求上,router 将调用方的 metadata 与它自己的分开保存,它会删除调用方在其中写入的任何团队、组织或最终用户字段,并且防护会拒绝在其中指明密钥 metadata.user_api_key 的请求;在其他所有路由上,router 的值会替换调用方发送的任何值。本 Release 不再额外准入任何字段。第二个条目 prometheus 是代理自身的指标回调,由 router 的 metrics_enabled 值开启;下文的 metrics 附件会抓取它记录的内容。

只有路由器自己的路由可以访问。 防护只能看到把请求交给它的那些路由,因此第二个 ConfigMap 的另一个文件配置 pod 的第二个容器,该容器只挂载这个 ConfigMap,并运行官方 nginx 镜像作为路径允许列表。路由器本身监听 pod 的回环地址,pod 外部的任何东西都无法访问它,而允许列表监听端口 4000,即下文 Service 所指向的端口。只有当请求的方法和路径属于路由器所提供的路由之一时,它才转发该请求——这些路由包括防护检查的模型请求路由(采用路由器无论别名为何都提供的写法,其中包括 /v1/chat/completions 和 /v1/messages)、模型列表、健康检查,以及在其管理路由中的密钥管理——对其他所有路径返回 403,且不转发任何内容。因此,代理的 token 计数路由、通往各 provider 自有 API 的透传路由、其他管理路由以及管理控制台都无法通过路由器访问;路径中携带模型名称的模型路由也无法访问,例如 Azure 客户端发送的路径:在这类路径上,代理会读取路径中的词(包括别名)来决定如何记录请求,而路由器会拒绝在其上请求这份映射自己的 assistant。代理的指标也不在这些路由之中:端口 4000 对 /metrics 返回 403。当路由器的 metrics_enabled 为 true 时(Aggregate 正是这样设置的),允许列表还会监听端口 9090,并且在该端口上只转发对 /metrics 的 GET 请求,转发到代理在回环地址上为指标保留的监听器,对其他所有请求返回 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 的网关不带此标签,从代理指向这类网关的边会使构建中止,并指出该插座以及目标未满足的选择器。

该地址就是路由器自身的 Recipe 生成的 Service——以下是 dist/helm/router-default-service.yaml 的完整 spec:

spec:
type: ClusterIP
selector:
app: router
ports:
- name: http
port: 4000
targetPort: http
- name: metrics
port: 9090
targetPort: metrics

Recipe 所发布的端点 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 设置为其中之一)。在 models 旁设置 model: assistant 即可消除该中止,代理再次获得 assistant。需要 summarizer 的调用方可按名称向同一端点请求它。

agent 收到什么

agent 的 Recipe 读取它的两条边以及 agent 自身的值,并把它们转换为容器环境变量。以下是 dist/helm/agent-deployment.yaml 的完整 env 块:

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 provider 会把这类从 Secret 读取的条目写在普通条目之前。递归上限是 agent 自身的 recursion_limit,放在 LangGraph 会自行读取的变量下;接下来两项来自 model 边,再后两项来自 checkpointer_db 边,最后一项是 agent 自身的 graph_entrypoint,放在应用代码读取的一个默认名称下,组件自身上的 inject 块会替换这个名称。注意 Aggregate 不必说明的内容:两条边都没有 inject 块,因为消费方 Recipe 会以默认名称交付每个连接,而边上的 inject 块会替换这些名称。开发者声明 agent 使用一个模型;其端点传入时所用的变量正是客户端库读取的那个变量,并且边如何规定,它就保持如何。

还要注意 LANGGRAPH_CHECKPOINTER_PORT: "6379"。Release 声明了 checkpointer: {},没有做任何配置,因此该端口是缓存 Component 自身 schema 的默认值,经过具体化后沿边传递过来。

agent 与 router 通信所用的方式,与它直接与 provider 通信时完全相同:一个基础 URL、一个模型名称和一个密钥。正因如此, router 才可以被插入、移动或重新指向,而应用无需改动。

六个附件,以及每个附件渲染的内容

一个不改变输出的附件说明不了任何东西。这六个附件中的每一个都会在输出中留下内容。

路由器上的 api_key——它要求调用方提供的密钥

core/referenced-secret,填充路由器的 Component 声明的一个槽位;它持有的密钥就是 LiteLLM 所称的主密钥(master key)。它渲染自己的 Secret,路由器的容器引用该 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,指向的正是这个变量。 从 Aggregate 中移除 provider_key 附件并重新构建。构建报告 11 个文件而不是 12 个——Secret 没有了——路由表的 ConfigMap 恰好只差那两行 api_key,别无其他差异; 守卫的 ConfigMap 保持不变。映射的其余部分保留原有的编写顺序和格式,路由器仍然提供服务并进行路由,而被路由的请求此时会在提供方处失败,因为没有可出示的凭据。

变量名只在路由器的 Recipe 中编写一次,路由表和容器环境都从那里读取,因此路由表不可能引用一个没有任何地方设置的变量。

两个凭据彼此分离,而这种分离正是路由器带来的价值:上游密钥留在路由器内部,调用方应用只持有访问路由器的密钥。

代理的 model 连接上的 credential——它向路由器出示的密钥

又是 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 一无所知的资源。 dist/helm/router--published--router-ingress-router-ingress.yaml 的完整 spec:

spec:
rules:
- host: assistant.example.internal
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: router-default
port:
name: http

开发者在 Aggregate 中附加它并指定 path,因为应用提供哪些请求的服务,是应用本身的一部分。运维人员在 Release 中同一附件的条目上编写 host 和端口名称:host 是该环境中路由器的名称,因此运维人员按环境命名它,写在每个环境的 Release 中。后端 Service 两者都没有提供:service_name 未设置,附件的实现回退到路由器自身 Recipe 生成的 Service。输出中没有 ingressClassName 字段,因为没有任何地方设置它,而实现会省略未被提供的内容,由集群的默认类来认领该资源。

路由器上的 metrics——一个抓取目标

core/prometheus-exporter,通过同一个选择器被接纳,带来另一个属于它自己的资源。它接受的每个输入都是运维层面的规格设定,而非应用意图——平台多久抓取一次、读取哪个端口和路径,都是平台的属性——因此由运维人员在 Release 中、路由器的条目上附加它,其类型写在 infra 旁边。Aggregate 并未提及它:

components:
router:
features:
metrics:
type: core/prometheus-exporter
infra:
interval: 30s
port: metrics
path: /metrics

dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml 的完整 spec:

spec:
selector:
matchLabels:
app.kubernetes.io/name: router
endpoints:
- port: metrics
interval: 30s
path: /metrics

port 指定的是 Service 端口的名称而非端口号:metrics,路由器的 Recipe 之所以生成它,是因为 Aggregate 设置了路由器的 metrics_enabled 值,该端口提供指标。这也是该 Feature 的默认端口名,此处与另外两个参数一起显式写出。上文 Ingress 路由到的 http 端口对 /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 的请求发送到最近十次回复平均耗时最短的条目,如果回复报告了 token 数则按每个输出 token 计算;尚未尝试过的条目视为最快,因此每个条目都会先被尝试,再由平均值决定。从 Aggregate 中移除该附件并重新构建:构建仍然报告 12 个文件,而路由表的 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 要求按成本选择时,代理会把每个请求都发送给其中第一个。

编译器不做解释的地方

agent 的地址和模型名称取自 router 发布的内容,因此这三个文件中没有哪一对名称需要手动保持同步。构建确实会检查的,是 router 自身的规则:它发布的别名必须是其映射所发布的别名之一——这条规则由它的 Component 声明、由构建求值,与实体携带的任何其他断言一样。

其余的都是从一处传递到另一处的字符串。编译器传递地址和别名时并不读取它们:它不知道一个是主机名、另一个是模型名称,也无法访问运行中的集群来检查 router-default:4000 上是否有服务应答。接纳该 router 的 model.aggrega.ai/api 标签也是同类字符串——socket 的选择器匹配它,但没有任何东西检查那里实际应答的是什么 API。映射中的每个 target 都是由运行中的代理解析的指针:把 openai/gpt-4o 改为 openai/not-a-real-model,构建仍会成功,失败要到请求时才出现。

正是这一特性让示例的其余部分得以运作。由于编译器不解释它所传递的内容,router 可以重新指向另一个 provider,agent 可以连接到另一个 router,凭据的实现也可以换成基于存储的实现——这一切都不需要编译器理解其中任何内容,agent 也无需改动。

改编示例

  • 重新指向一个 provider。 编辑路由器映射中的某个 target。其他都不变:模型不变,智能体不变,渲染出的 Secret 也不变。

  • 添加第三个 provider。 添加一个映射条目。如果它发布的是已有的别名,策略就开始在三者之间选择。如果它发布一个新别名,映射就发布两个别名,而路由器的 values.model 指定交给智能体的那一个;需要另一个的调用方按名称请求它。对于目录所建模的、API 为 OpenAI API 的模型,也可以改为将其连接到路由器的 models 插槽,使用它自己的别名,并出示其连接所携带的密钥;此时 values.model 指定交给智能体的别名。

  • 改为从存储中获取凭据。 将那一行把 core/referenced-secret 绑定到 Manifest 的行改为 helm/k8s-external-secret,然后重新构建。每个渲染出的 Secret 都变成一个 ExternalSecret,指向集群密钥存储中的一个条目,由存储运维方进行协调——而每个消费方渲染出的引用都保持字节完全相同,因为定位符由生产方发布,而不是由双方约定。三个文件中无需再做其他更改,构建即可成功。

    不过,在这一替换产生意义之前,确实有一处需要重新编写:origin 在两种实现之间含义不同。本工作区的实现将其读作要存储的值;另一种则将其读作要获取的键。如果替换这一行而不重新审视 origin 的值,渲染出的 remoteRef.key 就会是原先代替该值的占位符——此处为 dev-router-admin-key-change-me。此时输出树中没有任何内容把该字符串作为密钥材料持有,但它仍作为存储键存在,指向一个并不存在的条目。

  • 去掉路由器。 改为将智能体的 model 边指向某个按 provider 划分的模型组件。这样智能体就要自己持有 provider 凭据,而这正是路由器存在所要消除的取舍。

  • 访问目录未建模的路由器。 将智能体的 model 边指向一个 core/ai-model/openai-compatible 组件,并在 Release 中把该路由器的地址写入其 infra.endpoint。该组件背后在集群内不运行任何东西,因此地址由运维人员填写,并由其负责与所指向的服务保持一致。

关于在多个消费方的连接之间共享一个凭据,请参阅 model-api-key-sharing。关于没有任何目录实体声明的插槽,请参阅 adhoc-uses-socket。