跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

共享凭据——按消费者、共享,以及两者兼用

两个 CrewAI 代理位于同一个 OpenAI 兼容网关之后。每个代理的 model socket 声明了一个 credential 槽位,因此代理向其所连接模型出示的密钥 附加在该连接上。本工作区以三种方式填充该槽位,而无需修改任何目录实体:每个连接一个密钥、所有连接都指向的一个 Secret, 以及由一个连接覆盖的共享默认值。

关键在于有两个消费者。 只有一个消费者时,这三种形式无法区分——区别在于每个消费者最终指向哪个 Secret, 而在消费者多于一个之前,这个问题没有实际内容。

生成示例

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

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

Terminal window
aggrega scaffold --example model-api-key-sharing

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd model-api-key-sharing

构建

三个 release,每种形式一个。每次运行构建一个:

Terminal window
aggrega build --release release-per-consumer.yaml --auto-pull # → dist/per-consumer/
aggrega build --release release-shared.yaml --auto-pull # → dist/shared/
aggrega build --release release-composed.yaml --auto-pull # → dist/composed/

每个 release 写入各自的目录,因此三棵渲染树可以共存, 并可以相互比较差异。

release 在构建前需要其锁文件。在全新检出的代码上,先解析一个锁文件 ——可以作为单独的步骤,也可以让构建来填充:

Terminal window
aggrega pull --release release-shared.yaml # resolve, then build normally
aggrega build --release release-shared.yaml --auto-pull # or resolve during the build

这些 release 从已配置的目录中解析其目录实体,因此无需 --catalog 标志。

三者都有意在 helm 目标上构建。区分三种形式的可观察项是每个代理的容器所引用的 Secret 的名称, 而在 helm 中,凭据是一个命名的 Kubernetes Secret,容器按名称引用它。两个 Manifests 绑定该凭据:manifest.yaml 绑定到 k8s-secret-from-parameter,它根据附件携带的值渲染一个 Secret,用于按消费者的 release; manifest-existing-secret.yaml 绑定到 k8s-existing-secret,它不渲染任何内容, 而是让每个消费者指向命名空间中已存在的 Secret,用于共享和组合的 release。

借助 AI 助手

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

只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `model-api-key-sharing` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `model-api-key-sharing`,不设 `dir`:它会把示例写入一个新的 `model-api-key-sharing` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-per-consumer.yaml`、`release-shared.yaml` 和 `release-composed.yaml`——每次都将 `workspace_root` 设为 `model-api-key-sharing`、`release` 设为该文件、`auto_pull` 设为 true、`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `model-api-key-sharing/dist/` 下。

按消费者——每个连接持有自己的密钥

aggregate-per-consumer.yaml 在每个代理的连接上填充该槽位, 每个代理使用不同的 origin:

researcher:
type: core/ai-agent/crewai
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-key-change-me

连接上的附件会成为代理自身的附件之一,以连接和槽位命名 ——此处为 gateway.credential——因此会生成两个 Secret, 每个代理一个,各自携带该代理自己的密钥材料:

dist/per-consumer/helm/researcher--gateway-zdcredential--researcher-secret-researcher-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: researcher-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "researcher-key-change-me"
# dist/per-consumer/helm/writer--gateway-zdcredential--writer-secret-writer-gateway-credential.yaml
[… omitted: the apiVersion and the Secret kind]
metadata:
name: writer-gateway.credential
[… omitted: the labels and annotations every rendered document carries]
stringData:
OPENAI_API_KEY: "writer-key-change-me"

并且每个 Deployment 引用各自的 Secret:

dist/per-consumer/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-gateway.credential
key: OPENAI_API_KEY
# dist/per-consumer/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: writer-gateway.credential
key: OPENAI_API_KEY

吊销一个代理的密钥不会影响另一个代理的运行。

共享——一个 Secret,由每个连接引用

连接上的凭据写在该连接上:其他地方附加的内容不会填充它。因此多个消费者通过编写共享一个凭据: 每个连接的凭据读取同一个值,而该值指定一个 Secret。

aggregate-shared.yaml 声明一个参数,并在两个连接上读取它:

parameters:
team_model_key:
type: string
default: team-model-key
components:
researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}"
writer: { ... } # the same credential, reading the same parameter

该 release 将凭据绑定到 k8s-existing-secret,它将 origin 读取为命名空间中已存在的 Secret 的名称。它完全不渲染 Secret——只写入网关的 Service 和两个 Deployment—— 两个 Deployment 都引用该参数所指定的那个 Secret:

dist/shared/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY
# dist/shared/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

这恰好是一个物理 Secret,由部署者在 Release 之外创建, 并被每个消费者读取。密钥材料从不经过编写的文件或渲染的制品。

参数携带的内容取决于 Manifest 绑定的实现。 在 k8s-existing-secret 下,它是 Secret 的名称。若改为绑定到 k8s-secret-from-parameter,读取同一参数的两个连接将携带密钥本身, 构建会为每个消费者渲染一个 Secret,各自持有相同的材料:渲染按组件运行, 而该实现以消费组件和连接来命名其渲染的 Secret。这一个参数使消费者不会相互偏离; 由哪个实现读取它决定了它们是否共享资源。在集群中生成的凭据也以同样方式共享——一个请求,多个 引用;参见 凭据模型。

组合——共享默认值,一个连接覆盖

aggregate-composed.yaml 保留共享参数作为默认值,并让一个 连接指定自己的 Secret:

researcher:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: researcher-model-key # this connection's own Secret
writer:
uses:
model:
gateway:
target: gateway
features:
credential:
type: core/referenced-secret
values:
key: OPENAI_API_KEY
origin: "{{ .parameters.team_model_key }}" # the shared default

覆盖是该连接自己编写的内容;不会有任何内容级联到它上面, writer 保持共享 Secret 不变:

dist/composed/helm/researcher-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: researcher-model-key
key: OPENAI_API_KEY
# dist/composed/helm/writer-deployment.yaml
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: team-model-key
key: OPENAI_API_KEY

连接的凭据是其自身的完整附件,因此覆盖需要重新声明它所需的每个字段 ——此处为 Feature 类型、key 和 origin—— 不会从默认值继承任何字段。

槽位带来了什么

core/ai-agent/crewai 在其 model socket 上声明一次该槽位, 三种形式都是在 Aggregate 中做出的选择:

usesSchema:
model:
selector: "component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api"
required: true
inject: [env, file]
featuresSchema:
credential:
selector: "feature.aggrega.ai/kind=secret"
sensitive: true
inject: [env]

该槽位是可选的,因此第四种形态是完全不附加任何内容:从两个连接中删除 features: 块,渲染树将失去所有 OPENAI_API_KEY env 条目,只剩下两个 Deployment 和网关 Service。 不会凭空生成任何内容来填补空缺。目录实体在每种情况下都相同; 由作者决定。

之所以能构建,是因为此处的网关 core/ai-model/openai-compatible 不带 component.aggrega.ai/hosting 标签。如果某个连接到达目录标记为 managed 的目标 ——例如 core/ai-model/openai——且没有凭据,代理自身的断言会使构建中止, 除非该连接在其 values 中声明目标不需要凭据,即 unauthenticated: true。

该槽位还与凭据族无关(feature.aggrega.ai/kind=secret 接受任一 凭据族),正因如此,同一个代理可以在 helm 上接受可引用的 Secret,在 compose 上接受注入值凭据。 凭据交付——secretKeyRef 端到端 演示了这种 provider 划分,其负面 release 展示了当要求不可引用的凭据满足引用时会发生什么。

确定性

三个 release 都在 --verify-determinism 下构建,它会将每个节点渲染两次 并比较生成的字节:

Terminal window
aggrega build --release release-shared.yaml --auto-pull --verify-determinism

从干净的树重新构建三者中的任何一个,都会逐字节重现其渲染输出。