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

连接上的凭据——每个连接一个密钥,两端共用一个密钥

一个语义记忆存储连接两个模型,并向每个模型出示不同的密钥,编译为 Kubernetes manifests。它使用一个托管模型读取摄取的材料,并使用在集群中与它并行运行的嵌入服务器对材料进行编码。它向托管模型出示的密钥从集群 secret store 中获取。嵌入服务器校验它自己的一个密钥,而该存储出示的正是同一个密钥——两端从同一个参数读取它,因此两者不可能写得不一致。

此工作区不编写任何自己的目录实体。它引用的每个 Component、 Feature 和 Recipe 都随标准库目录提供;这里的文件——三个 Aggregates、一个 Manifest 和三个 Releases——就是任何人需要编写的全部内容。

它构建了什么

┌── extraction_model ──► llm a hosted model API
│ key on the connection, fetched from a secret store
memory ───┤
│
└── embedding_model ──► embeddings an embedding server that checks a key
key on the connection ═══ the server's own api_key
(both read one parameter)
实例目录中的 Component它在此处的角色
memorycore/datastore/cognee调用方:一个语义记忆存储,它的两个模型插槽各自声明一个 credential 槽位,用于存放它在该连接上出示的密钥
llmcore/ai-model/openai一个托管模型,标签为 component.aggrega.ai/hosting: managed;以引用方式访问,因此集群中不会为它运行任何内容
embeddingscore/ai-model/tei集群中的 Text Embeddings Inference,标签为 self-hosted;它要求每个调用方提供密钥,并将其保存在自己的 api_key 槽位中

三个 release 共享一个 Manifest,即 manifest.yaml,每个 release 各有自己的 Aggregate:

releaseAggregate它展示的内容
release-matched.yamlaggregate-matched.yaml两个连接均由开发者编写,嵌入连接的两端读取同一个参数
release-mismatched.yamlaggregate-mismatched.yaml与上一个相同,但两端读取两个参数:构建成功,约定检查给出建议
release-operator-wired.yamlaggregate-operator-wired.yaml提取连接留给运维人员:由 Release 完成连接,并在 infra 中指定其密钥

生成示例

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

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

Terminal window
aggrega scaffold --example connection-credentials

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

Terminal window
cd connection-credentials

构建

每次运行构建一个 release:

Terminal window
aggrega build --release release-matched.yaml --auto-pull # → dist/matched/
aggrega build --release release-mismatched.yaml --auto-pull # → dist/mismatched/
aggrega build --release release-operator-wired.yaml --auto-pull # → dist/operator-wired/

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

release 在构建之前需要其锁文件,而锁文件是生成的, 而不是随附提供的。请先解析一个锁文件,或让构建来填充它:

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

工作区从 .aggrega-config.yaml 指定的默认注册表解析其实体,因此不需要 --catalog 标志。

拉取输出:

[… omitted: a warning that the declared-sensitive origin of llm.credential reaches the target with no per-key sensitivity marking, because its realization maps it through a valuesMapping]
Pull complete: release-matched.lock (entities=15, source_artifacts=0, external_inputs=0)

构建输出如下,其中 <workspace> 代表本示例的文件夹:

[… omitted: the same warning about llm.credential the pull printed]
notice: LINT: Feature "core/referenced-secret" at core/referenced-secret:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 8 files written to <workspace>/dist

另外两个 release 输出相同的行,每次拉取指明各自的 锁文件,每次构建写入八个文件。notice: 行涉及此处每个附件所使用的凭据 Feature: core/referenced-secret 接受其密钥的名称 origin,该名称既可来自 开发者的 values,也可来自运维人员的 infra,而该提示报告 有一个叶节点在两个支柱中都有声明。它不改变任何判定,也不改变任何 渲染出的字节;Credential Features 解释了该叶节点为何同时位于两者之中。

本页凡是输出构建产物之处,其代码块均复制自一次真实 运行——有关该约定以及用于标记省略行的符号,请参阅阅读这些页面上的输出。

借助 AI 助手

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

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

渲染出的目录树

dist/matched/helm/
├── embeddings-default-service.yaml
├── embeddings-headless-service.yaml
├── embeddings-statefulset.yaml
├── llm-service.yaml
├── memory--llm-zdcredential--memory-externalsecret-memory-memory-llm-credential.yaml
├── memory-default-service.yaml
├── memory-headless-service.yaml
└── memory-statefulset.yaml

有一个文件是由一个 attachment 带来的,而不是由某个 component 自身的 Recipe 带来的: 即获取存储向托管模型出示的密钥的 ExternalSecret。它的文件名包含它所附加到的 component memory,以及该 attachment 的名称 llm.credential,写作 llm-zdcredential,因为这个点与文件自身的名称共用一个字符串;参见 为渲染出的资源命名。 没有任何文件包含 embedding 密钥:它位于命名空间中已有的一个 Secret 里,如下文各节所示。

哪份文档写了什么

  • 目录(catalog) 声明绑定点。存储的 Component 在其两个模型套接字上各声明一个 credential 槽;嵌入服务器的 Component 在自身上声明 api_key;每个 Recipe 决定密钥以哪个变量交付。
  • Aggregate(开发者)写明存储连接哪些模型、每个连接上的凭据、服务器校验的密钥,以及嵌入连接两端都读取的那个参数。
  • Manifest(运维人员针对此目标的路由)决定每个凭据在 Kubernetes 上变成什么:对每个 core/referenced-secret 附件,它是对命名空间中已有 Secret 的引用;唯一的例外是连接托管模型的那个连接上的附件,它从集群密钥存储中获取。
  • Release(运维人员针对某个环境的文档)填充参数,将边界放入一个命名空间,并在由运维人员连接的 release 中连接抽取连接、指定在其上提供的密钥。

每个连接一个密钥

存储通过其目录实体声明的两个插槽 extraction_model 和 embedding_model 访问两个模型,每个插槽都声明了一个 credential 槽位。因此,存储出示的密钥位于出示它的那个连接上,每个连接各自携带自己的密钥。摘自 aggregate-matched.yaml:

memory:
type: core/datastore/cognee
values:
# The width of the vectors the embedding model above returns.
embedding_dimensions: 384
uses:
extraction_model:
llm:
target: llm
features:
credential: # the key presented to the hosted model
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.provider_key_entry }}"
embedding_model:
embeddings:
target: embeddings
features:
credential: # the key presented to the embedding server
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.embedding_key_secret }}"

写在连接上的附件会成为存储自身的附件之一,以连接的别名、一个点和槽位命名: llm.credential 和 embeddings.credential。下面是存储容器 env 的前两项和最后四项,摘自 dist/matched/helm/memory-statefulset.yaml:

- name: LLM_API_KEY
valueFrom:
secretKeyRef:
name: memory-llm.credential
key: api-key
- name: EMBEDDING_API_KEY
valueFrom:
secretKeyRef:
name: embedding-server-key
key: api-key
[… omitted: the store's own settings, HTTP_PORT to EMBEDDING_DIMENSIONS]
- name: EMBEDDING_ENDPOINT
value: http://embeddings-default:8080/v1
- name: EMBEDDING_MODEL
value: BAAI/bge-small-en-v1.5
- name: LLM_ENDPOINT
value: https://api.openai.com/v1
- name: LLM_MODEL
value: gpt-4o-mini

前两项是密钥,各自来自其所在连接上的凭据,使用存储的 Recipe 为该侧指定的变量——提取使用 LLM_API_KEY,嵌入使用 EMBEDDING_API_KEY。两者都是引用而非值,helm provider 会把从 Secret 读取的条目写在普通条目之前。最后四项来自两个连接:每个模型发布其地址和模型名称,存储的 Recipe 按插槽读取它们。

存储的 Component 还在自身上声明了一个密钥槽位 model_api_key。其 Recipe 只在插槽未连线时才读取该槽位:此时存储在 provider 自己的地址访问该 provider,没有连接来携带密钥。这里两个插槽都已连线,因此不会读取它。

两端共用一个密钥

嵌入服务器会校验密钥。它将该密钥保存在自身 Component 的一个槽位 api_key 中,其 Recipe 将填入该槽位的任何内容以 API_KEY 交付,这是 Text Embeddings Inference 启动时读取的变量。摘自 aggregate-matched.yaml:

embeddings:
type: core/ai-model/tei
values:
model: BAAI/bge-small-en-v1.5
features:
api_key: # the key the server verifies
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.embedding_key_secret }}"

这是服务器上的一个附件。存储所出示的密钥是另一个附件,位于存储的连接上,如上所示。填充一端的槽位不会填充另一端的任何内容,因此在两端都声明密钥是最低要求,而不是重复。让两者保持为同一个密钥的,是它们都读取同一个参数 embedding_key_secret,该参数由 Aggregate 声明、由 Release 满足:

parameters:
provider_key_entry: ai/openai-api-key
embedding_key_secret: embedding-server-key

Manifest 将 core/referenced-secret 绑定到 k8s-existing-secret,后者将 origin 读作命名空间中已有的 Secret 的名称,且不渲染任何内容。因此两端都引用这同一个 Secret。在服务器容器的 env 中,摘自 dist/matched/helm/embeddings-statefulset.yaml:

- name: API_KEY
valueFrom:
secretKeyRef:
name: embedding-server-key
key: api-key

以及在存储的容器中,摘自 dist/matched/helm/memory-statefulset.yaml:

- name: EMBEDDING_API_KEY
valueFrom:
secretKeyRef:
name: embedding-server-key
key: api-key

该 Secret 在 Release 之外由部署者创建,因此密钥的内容从不经过任何编写的文件或渲染出的制品。

为什么服务器永远看不到调用方的密钥

连接上的附件只落在调用方一侧。存储的两个 凭据是存储的附件:它们渲染出的内容位于 存储旁边,并由存储的容器引用。它们的任何内容都不会到达 连接所指向的组件,因此无论到达目标的连接携带什么, 目标的渲染结果都相同。

托管模型清楚地体现了这一点。它只渲染一个文件:一个将 集群内名称映射到提供方主机的 Service,即 dist/matched/helm/llm-service.yaml 的完整 spec:

spec:
type: ExternalName
externalName: api.openai.com
ports:
- port: 443

存储向它出示的密钥在存储旁边获取,如下一 节所示。嵌入服务器则通过对比体现这一点:下面的不匹配 release 更改了存储的嵌入连接上的密钥,而保持 服务器的密钥不变,服务器在 dist/mismatched/ 中的三个文件 与 dist/matched/ 中的文件相比,只有 aggrega.ai/aggregate-name 标签不同, 该标签指明了各文件构建所依据的 Aggregate。

因此,服务器的配置中没有任何内容指明调用方持有的密钥。在运行 时,请求携带调用方的密钥,服务器将其与自身持有的 密钥进行比较;而调用方只读取服务器发布的内容: 一个地址和一个模型名称。

每个服务器一个密钥

Text Embeddings Inference 只校验一个密钥。每个调用方出示同一个密钥, 出示其他密钥的调用方会被拒绝,而且服务器无法区分不同的调用方,因此撤销某个调用方的访问权限就意味着更改 所有调用方出示的密钥。无论有多少连接到达它,它的 api_key 槽位都 只保存一个密钥。这一限制属于服务器本身,目录中的 core/ai-model/vllm 和 core/ai-model/tgi 也有同样的限制。它并不是 连接的限制:连接多个服务器的调用方为每个连接持有一个密钥,正如 这里的存储持有两个密钥。

从密钥存储获取单个连接的密钥

Manifest 按类型绑定每个 core/referenced-secret 附件,并按名称绑定其中一个。摘自 manifest.yaml:

features:
# One realization for every core/referenced-secret attachment: the Secret
# already exists in the namespace, and origin is its name.
type:
core/referenced-secret:1.0.0: helm/k8s-existing-secret:1.0.0
# One attachment bound differently, by its name. An attachment written on
# a connection is named for the connection's alias, a dot and the slot,
# so the memory store's credential on its llm connection is
# llm.credential. That key is fetched from the store, and origin is the
# store entry to fetch.
name:
llm.credential: helm/k8s-external-secret:1.0.0

k8s-external-secret 将 origin 读作要获取的存储条目。该连接的 origin 是参数 provider_key_entry,其取值为 ai/openai-api-key,因此该附件渲染出一个 ExternalSecret,由集群中的密钥存储 operator 将其调和为一个 Secret。 dist/matched/helm/memory--llm-zdcredential--memory-externalsecret-memory-memory-llm-credential.yaml 的完整 spec:

spec:
refreshInterval: "1h"
secretStoreRef:
name: platform-secret-store
kind: ClusterSecretStore
target:
name: memory-llm.credential
creationPolicy: Owner
data:
- secretKey: api-key
remoteRef:
key: "ai/openai-api-key"

它所填充的 Secret memory-llm.credential 以存储和连接命名,也正是上文中存储的 LLM_API_KEY 所引用的名称。该实现从名为 platform-secret-store 的 ClusterSecretStore 读取。

参数承载什么,取决于读取它的实现:对托管模型的密钥而言是存储条目,对嵌入密钥而言是 Secret 的名称。单个连接的密钥可以采用自己的实现,而同一类型的其他所有附件仍沿用该类型的实现。

连接两端在何处解析密钥

目标平台在密钥作用域内按引用解析密钥:密钥作用域是一个资源能够命名另一个资源的边界。若连接两端位于同一作用域,两端引用同一个密钥资源。若位于不同作用域,每一端各自持有一个密钥资源,均从同一个存储条目实现。Manifest 为每一端选择实现方式——按 Feature 类型作用于该类型的每个附件,或按名称作用于某一个附件。

每个目标以自身的方式划定作用域。在本工作区所构建的目标 Kubernetes 上,作用域是命名空间:workload 只能引用其所在命名空间中的 Secret。这里的每个 release 都将其唯一的边界放在一个命名空间中,即 aggrega.ai/namespace: memory,且每个渲染出的文档都带有它——两个 StatefulSet 的头部:

dist/matched/helm/memory-statefulset.yaml
metadata:
name: memory
namespace: memory
# dist/matched/helm/embeddings-statefulset.yaml
metadata:
name: embeddings
namespace: memory

因此两端引用上面那一个 Secret。若嵌入服务器位于单独的命名空间中,Manifest 会按名称将两端的凭据—— api_key 和 embeddings.credential——绑定到 k8s-external-secret,Release 用存储条目满足该参数,每一端在各自的命名空间中持有一个 ExternalSecret,二者都获取同一个条目。此时 store 需要跨命名空间访问服务器,这部分内容见 cross-boundary-networking。在其他目标上,作用域分别是 Compose 项目、Terraform 根配置和 CloudFormation 栈;凭据模型 对每一种都有说明。

由运维人员接线一个连接

aggregate-operator-wired.yaml 写出了嵌入连接,并让存储的 extraction_model 插槽保持未绑定:存储的目录实体声明了它,开发者将其留给运维人员。Release 将它接到该 Aggregate 声明的托管模型上。摘自 release-operator-wired.yaml:

memory:
uses:
# A connection the Aggregate does not write, into a socket the
# store's catalog entity declares, to a component the Aggregate
# declares. A Release writes no values, so the credential on it
# names its secret in infra.
extraction_model:
llm:
target: llm
features:
credential:
type: core/referenced-secret
infra:
origin: ai/openai-api-key

Release 可以将一个连接接入目录实体声明、而 Aggregate 未绑定的插槽,连接到 Aggregate 声明的某个组件。它不添加任何组件,也从不重新指定 Aggregate 已写出的连接的目标。它不写 values,因此该连接上的凭据在 infra 中指明其密钥:core/referenced-secret 从开发者的 values 或运维人员的 infra 中取得 origin,二者恰取其一;若某个附加项同时带有两者或两者都没有,构建就会停止。

该附加项的名称是 llm.credential,与匹配的 release 中完全相同,因此 Manifest 的名称层级以相同方式绑定它。除了指明 Aggregate 的标签之外,dist/operator-wired/ 与 dist/matched/ 之间有两行不同。ExternalSecret 的 data:

data:
- secretKey: value
remoteRef:
key: "ai/openai-api-key"

以及存储对其所填充的 Secret 的引用,位于 dist/operator-wired/helm/memory-statefulset.yaml:

- name: LLM_API_KEY
valueFrom:
secretKeyRef:
name: memory-llm.credential
key: value

数据键是 value 而不是 api-key,因为 key 是一个 values 叶子,只有 Aggregate 会写它,所以仅由 Release 创建的附加项读取的是该 Feature 的默认值。实现会发布该键,存储则从已发布的内容中读取它,因此两端依然一致。

托管模型带有 managed 标签,因此到达它的连接要么带有凭据,要么在自己的 values 中声明该模型不需要凭据,即 unauthenticated: true。无论哪个文档写出该连接,这一点都成立。从 Release 的连接中删除 features: 块,构建就会停止。该停止是 E0033,即存储的 Component 的一个断言失败,其消息以该规则本身的语句结尾:the extraction_model connection llm of “memory” reaches “llm”, whose component.aggrega.ai/hosting label is managed, with no credential: attach one under credential on that connection, or set unauthenticated: true in its values(“memory”的 extraction_model 连接 llm 到达“llm”,其 component.aggrega.ai/hosting 标签为 managed,但没有凭据:请在该连接的 credential 下附加一个凭据,或在其 values 中设置 unauthenticated: true)。

两端不一致时

aggregate-mismatched.yaml 为服务器的密钥和存储的密钥分别指定了两个 参数:

parameters:
provider_key_entry:
type: string
description: >
The store entry holding the key the memory store presents to the hosted
model provider.
embedding_key_secret:
type: string
description: The Secret holding the key the embedding server verifies.
# The fault: a second parameter for what is meant to be the same key.
memory_embedding_key_secret:
type: string
description: The Secret holding the key the memory store presents to the embedding server.

服务器的 api_key 读取 embedding_key_secret,存储的连接读取 memory_embedding_key_secret,而该 Release 用两个不同的 Secret 来满足它们。构建成功并写出八个文件:编译器对给定的每个附件分别求值,不在两端之间进行任何比较。服务器仍然引用 embedding-server-key,而存储现在提供的是另一个,见 dist/mismatched/helm/memory-statefulset.yaml:

- name: EMBEDDING_API_KEY
valueFrom:
secretKeyRef:
name: embedding-client-key
key: api-key

部署后,只有当这两个 Secret 恰好持有相同的密钥时,服务器才会接受存储的请求。

这种情况由 Release 的发布约定检查发现:

Terminal window
aggrega lint --release release-mismatched.yaml
release-mismatched.yaml:
warn: E0329 connection-credential-matches-target-key: connection "embeddings" on socket "embedding_model" of component "memory" carries a credential in its credential slot and its target "embeddings" holds a key in its api_key slot, but the two ends write their secret's locator differently, so they may name different secrets and the target would refuse the key this caller presents. The locators are compared as written, and neither is shown here. Reading one parameter at both ends keeps them one key; that agreement is the standard-catalog convention, and the build does not check it.
conventions checked: 10 entities, 1 advisory finding(s)

对匹配的 release 执行同样的检查,不会报告任何问题:

Terminal window
aggrega lint --release release-matched.yaml
conventions checked: 10 entities, 0 advisory finding(s)

对由运维人员连接的 release 执行检查,同样不会报告任何问题。

该规则按照标准目录为两端指定的名称找到它们——目标的 api_key 和连接的 credential——并按原样比较每一端写入的 origin:两端读取同一个参数即视为相等,且不解析任何内容。它从不引用其中任何一端的内容,因为写在那里的可能就是秘密本身。它不评判标记为 managed 的目标,这类目标的 api_key(如果声明了)是向其供应商提供的密钥,而不是其调用方提供的密钥;因此在这三个 release 中,到 llm 的连接都不会产生任何发现。该发现只是建议:aggrega lint 以 0 退出,两端有意不同的工作区可以通过 allow_connection_credential_mismatches 选择退出。编辑器向守护进程提出同样的问题,即以 aggrega/lint 指定该 Release,会收到相同的发现,代码为 connection-credential-matches-target-key,短代码为 E0329。该规则及其读取的内容在 纪律规则中说明。

确定性

三个 release 都能在 --verify-determinism 下构建,该选项会将每个节点渲染两次并比较输出的字节:

Terminal window
aggrega build --release release-matched.yaml --verify-determinism

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

改编示例

  • 为嵌入服务器添加第二个调用方。 其连接的凭据同样读取 embedding_key_secret。服务器为所有调用方持有同一个密钥, 因此第二个调用方出示的是同一个密钥。
  • 同样从存储中获取嵌入密钥。 按名称将 api_key 和 embeddings.credential 绑定到 k8s-external-secret,并用存储条目而非 Secret 的名称来满足 embedding_key_secret。两端 会一起改变,因为两端都读取该参数。
  • 访问不检查密钥的模型。 不在连接上设置凭据。若目标标记为 managed,则在连接的 values 中 用 unauthenticated: true 加以说明。

关于在多个调用方的连接之间共享一个密钥,参见 model-api-key-sharing。关于代表调用方持有 provider 密钥的路由器,参见 ai-agent-and-model-router。这一切背后的模型 是凭据模型。