Features 与策略
本页讲解一个概念,即将一种行为附加到组件上并用策略检查结果,它不是一个可运行的工作区。在受限数据未经遮蔽到达托管模型时停止构建的策略在一个由你构建的工作区中展示了这两点;用以下命令将其写入你自己的文件夹:
aggrega scaffold --example policy-data-class-route然后它会打印接下来要运行的命令:
cd policy-data-class-routeaggrega build --release release-masked.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-unmasked.yaml --config governance-rego.yaml --auto-pull # halts; exits 1aggrega build --release release-masking-off-route.yaml --config governance-rego.yaml --auto-pull # halts; exits 1Feature 被附加,并由 FeatureRecipe 实现
Feature 是组件本身不具备的一种行为——遮蔽、备份、入口、凭据——由作者在 features: 下附加到组件上。由谁附加,取决于由谁决定其输入:行为属于应用本身组成部分的 Feature 由开发者在 Aggregate 中附加;输入全部属于运维的 Feature 由运维人员在 Release 中附加。无论哪种情况,Manifest 都会把每个 Feature 绑定到一个 FeatureRecipe,由它决定如何针对目标实现该 Feature。
在本例中,开发者将标准库的 core/data-masking 附加到一个 AI 网关上,并列出要遮蔽的内容,以下摘自 aggregate.yaml,省略了其中的注释:
masking-gateway: type: core/gateway/litellm values: model: chat features: masking: type: core/data-masking values: patterns: - name: claim_number regex: '\bCLM-[0-9]{8}\b' entities: [PERSON, EMAIL_ADDRESS]开发者不指定任何地址、防护规则或提供方设置。Manifest 将 core/data-masking 绑定到 helm/data-masking-litellm,后者通过收尾渲染的插件流水线中的步骤,将遮蔽写入网关自身 Recipe 渲染的配置中,并在旁边添加一个由网关加载的模块。构建写入的其他每个文件都与没有该附加的构建逐字节相同。
该附加不做什么,与它做什么一样被谨慎地说明:没有任何模式匹配且识别器未检测到的文本会原样通过,网关和两个识别器服务能看到原始文本,不经过网关的流量不受影响。FeatureRecipe 的注释列出了此网关拒绝的内容以及按发送时原样传递的内容。
标签决定 Feature 可以放在哪里
标签是组件的语义身份,它们驱动 Feature 的放置、插槽选择器和策略,而无需对编译器做任何改动。Feature 的 appliesTo 是作用于其所附加组件的标签选择器。core/data-masking 声明了 appliesTo: "dataplane.aggrega.ai/content-masking",这是一个单独的键,匹配带有该标签的任何组件,无论其值是什么;core/gateway/litellm 带有该标签,值为 entity-recognition。选择器还可以匹配值,如 component.aggrega.ai/type in (server, worker),或排除某个标签,如 !model.aggrega.ai/capability;同一选择器中以逗号分隔的各项要求必须全部成立,Feature 只会附加到与它们匹配的组件上。基于标签的附加给出了完整的选择器语法。
另有两种声明约束附加:
- 互操作性。 Feature 可以指明不能与其共享同一组件的 Features。
core/data-masking声明了interoperability.conflictsWith: [core/semantic-caching],因此只要某个组件最终同时带有这两者——无论是附加在组件本身上,还是附加在包含该组件的子系统或边界上——构建就会在渲染之前停止。 - 存在性强制要求。 Component 可以要求存在某种给定类型的附加。目录中的
example/compute/service带有注解features.aggrega.ai/requiredType.monitoring: core/prometheus-exporter,因此如果某个构建中它的某个实例在任何作用域上都没有带core/prometheus-exporter,构建就会停止,并指出monitoring这一要求。使用另一个后缀重复该键,即可要求第二种类型;关于强制要求与附加槽位有何不同,请参阅 entities/component.md 中的“Presence mandates”。
Feature 应附加在其行为被它改变的组件上。core/caller-allowlist 附加到模型服务器上,而不是附加到被允许调用它的网关上;只有其网关可以调用的模型服务器构建了这一场景。
策略读取构建好的图
策略由运维人员在工作区配置的 plugins.governance 下附加,每次附加对应一个角色。处于 label-transform 角色的策略为图添加标签;处于 ir-verdict 角色的策略对图作出判定,并可能停止构建。Rego 引擎运行这两者;它编译在 CLI 中,governance/rego 是它在标准库目录中的 Plugin 实体。
下面的第一条规则为每个解析其所转发模型负载的网关添加标签,将其标记为提示词发往模型提供方的出口点。在这个角色上,节点位于 input.graph.nodes:
# policies/egress-tagging.rego: attached at the label-transform rolepackage aggrega.tagging
import rego.v1
labels contains {"node": id, "key": "compliance.aggrega.ai/egress", "value": "model-provider"} if { some id, node in input.graph.nodes node.labels["gateway.aggrega.ai/intelligence"] == "semantic"}第二条规则停止任何经过此类网关且不带遮蔽的路径:
# policies/model-egress.rego: attached at the ir-verdict rolepackage aggrega.security
import rego.v1
deny contains msg if { some path in input.precalculated_paths some egress in path.nodes input.graph.spec.nodes[egress].labels["compliance.aggrega.ai/egress"] == "model-provider" not "core/data-masking" in path.attached_features
msg := sprintf( "BLOCKED: path %v sends model traffic through %v without core/data-masking attached.", [concat(" -> ", path.nodes), egress] )}节点的 id 是它在 input.graph.spec.nodes 中所在的键;attached_features 列出附加到路径上任一节点的 Feature 类型,因此用 in 测试成员关系;规则检查的是遮蔽是否已附加,而不是它列出了什么;在 deny 下收集的决策以 halt 严重级别报告,它会终止构建。针对路径的规则只在有边到达或离开某个节点时才能看到该节点,因此还必须覆盖未连接节点的策略需要读取节点本身。
运维人员按角色各附加一次引擎,每次附加都带有自己的策略文件;sources 下的相对路径相对于配置文件所在目录解析,且变换在判定之前运行:
plugins: governance: - uri: governance/rego:0.9.0 role: label-transform with: sources: - policies/egress-tagging.rego - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policies/model-egress.rego治理插槽页面是完整的编写接口:每个角色公开的负载、决策键,以及如何命名你自己的决策。塑造标签的策略在两个内置标记插件旁附加一个塑造标签的策略,并对其进行构建。