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

AI Features

Aggrega AI Feature 集

为了应对现代 AI 系统的独特需求、易变性和安全威胁,Aggrega 将专门的智能直接嵌入其开源的 AI 标准库(目录)。它确保通用的云原生脚手架与高度专业化的 AI 原生推理引擎能够安全共存。

核心 Go 编译器是一个对内容保持中立的通用路由器;所有 AI 专用的智能都位于可插拔的 WebAssembly(Wasm)策略,以及平台架构师在目录实体上编写的 JSON Schema 2020-12 声明中。

1. 运维云本体与 AI 鸭子类型

为了将通用的开放应用模型(OAM)与现代基础设施的严格现实衔接起来,component.aggrega.ai/type 标签只映射到一个封闭的通用云原生原语集合。套接字选择器、Feature 的 appliesTo 和治理策略正是读取这一语义身份,来了解组件如何处理状态、网络入口和生命周期;编译器将其作为不透明字符串进行匹配,不据此分支,而组件如何渲染由 Manifest 为其映射的 Recipe 决定。

云原生类型(基础设施基础):

  • server:长期运行、无状态的计算,需要接收入站应用流量(例如 AI 网关或聊天 UI)。
  • worker:长期运行、无状态的计算,从队列拉取任务或运行后台循环,没有任何入站应用端口(例如 LangGraph 智能体或 Celery worker)。
  • task:运行至完成后即终止的临时计算(例如数据库迁移脚本)。
  • function:可缩容至零的事件驱动计算(例如 AWS Lambda)。
  • stateful-server:需要稳定网络标识和持久磁盘的集群内计算(例如 Qdrant 向量数据库、Kafka broker)。
  • resource:由平台托管的外部基础设施(例如 AWS RDS PostgreSQL、S3 存储桶、托管事件总线)。

该集合属于 Aggrega 自身,并且是封闭的。 已发布的 Component schema 枚举了这些值,携带其他任何值的文档在加载时即被拒绝——E0215 会指出该标签并列出其可接受的值。这正是这一维度带来的好处:针对 stateful-server 编写的 Feature 或插槽选择器,在它遇到的每个目录中含义都相同。

一个组件在你自己的词汇中是什么,应放在你自己的键上。 层级、数据区、服务等级、对原语的更细划分——每一项都是你在保留键旁边编写的标签键,因为 Component schema 接受任何其他带字符串值的标签键,而每个选择器界面都以相同方式读取它。下文的 AI 鸭子类型标签使用的也是同一机制;保留键是共享的基础,其上的一切都归你所有。

运维类型不是浏览类别,二者是有意分开的两个维度。 Kafka broker 位于 messaging 类别中——这是用户查找它的地方——并以 stateful-server 作为其类型,因为这是基础设施必须为它做的事。针对一个维度编写的选择器永远不会匹配另一个维度。

语义标签分类表参见 entities/component——即通用云层、专用 AI 层、横切关注点和动态业务上下文标签,架构师用它们在基础类型之上叠加认知身份。


1.1 开源目录标准:“裸基础,调味边缘”

应用这些标签时,Aggrega 官方开源目录(core/*)与企业私有目录(acme/*)之间存在一个关键区别。

官方开源目录要保持普遍可用,就必须严格区分不可变的技术物理属性与主观的认知意图。如果通用的 core/datastore/postgres 被硬编码为 engine: relational,那么当开发者在其 values 中启用 pgvector 扩展、并尝试连接一个需要 vector 数据存储的 AI Agent 时,配置为强制数据存储类型匹配的治理裁决插件将中止构建。

为保持核心目录不预设立场,官方组件遵循以下标准:保持基础赤裸,为边缘调味。

  1. **裸基础:**根级开源 Component 只硬编码产品客观为真、且作者的任何配置都无法改变的内容——首先且始终是运维原语(component.aggrega.ai/type)。Postgres 数据库客观上是 stateful-server;这一事实无法改变。同样的检验也允许在产品身份就是某种能力时添加能力标签:core/datastore/qdrant 和 core/datastore/weaviate 是向量搜索引擎,作者写什么都不会让它们变成别的东西,因此二者都在基础上携带 datastore.aggrega.ai/engine: vector,正如 core/datastore/redis 携带 kv。裸基础拒绝的是相反的情况——取决于组件如何配置或使用的特性,这正是下文第三种机制存在的原因。
  2. 调味接口(Schema 继承):一个 Component 可以声明 extends,指定另一个 Component 作为其基础,而它组合的是结构:标签、注解、附加槽、自注入允许列表、拓扑插座和命名的 assertions。三大数据支柱不参与组合——进行扩展的 Component 写入字面标记 schema: inherited,且不编写任何自己的 values、infra 或 provides 内容,因此其契约与基础的完全相同。这就是该机制收窄而非变化的原因:由于契约不变,为基础编写的每个 Recipe 已经可以服务于该特化,而特化的代价只是一个目录实体和一行 Manifest 映射。因此,特化所添加的是供选择器或策略读取的身份——审计层级、数据区域、治理联系人,或其选择器比基础的接纳范围更小的插座。它无法添加不同的契约,因为它没有可编写契约的位置。有一个后果容易被忽略:映射行仍然是必需的。Recipe 的选择依据精确的映射键,因此特化即使不需要自己的 Recipe,也需要自己的 mappings.components.type 条目。请参阅 examples/extends-wrapper,其中有一个已发布的包装器,它添加了一个已审核层级标签并在其上收窄了一个插座,同时还展示了当接入该插座的边离开该层级时中止的构建。取决于组件配置方式的特性不是该机制的对象:特化固定其基础的制品并继承其契约,因此对特化为真的特性对基础也已为真,而裸基础规则会把它放在基础上。这样的特性属于下文的动态变更器。
  3. **动态变更器(Wasm 提升):**如果某个特性由开发者的负载决定(例如 enable_vector: true),企业会在拓扑构建时使用治理插座的 label-transform 角色,动态读取不透明的 values,并在策略运行之前自动将 datastore.aggrega.ai/engine: vector 标签注入 IR 图。依赖配置的特性正是在这里变得可供严格的策略评估使用——提升它的是开发者声明的 values,且该转换在任何策略读取标签之前运行。

**企业例外:**由于编译器不预设立场,编写内部目录的企业可以自由打破这条规则。如果公司安全策略规定所有内部数据库都高度敏感,平台架构师可以并且应该将 compliance.aggrega.ai/data-class: restricted(或公司规定的类似标签)直接硬编码到其 acme/postgres 基础组件上,使它的每个实例都携带该类别,企业附加的策略也会在每个实例上读取它。标签本身不强制执行任何内容:编译器将其作为字符串携带,中止构建的是附加的策略。如果某产品在整个环境中只有部分用途持有此类数据,则改由通过 extends 的特化携带该类别——请参阅 examples/policy-data-class-route,其中的理赔助手就是标准库的 LangGraph agent 加上一个类别标签,旁边是读取该标签的策略。

1.2 语义标签如何驱动编译器流水线

为将标签保留在平台架构师的领域内,开发者不能在 Aggregate 内的 Component 实例上编写标签:Aggregate schema 不为组件实例提供 labels 键。节点的标签来自其目录实体,再加上运维人员配置的 label-transform 治理挂载在拓扑构建期间添加的任何标签。以下准确说明这些标签如何在不需要自定义 Go 代码的情况下驱动编译流水线:

1. component.aggrega.ai/type(基础原语)

  • **谁编写?**平台架构师(领域 2)。目录中的每个组件都必须有此标签。
  • 谁使用它? 静态分析器和 Wasm 渲染 Plugins。
  • **编译器用例:**这是核心的运维云本体。静态分析器在 Go 中原生评估 usesSchema 选择器字符串,以保证当插座要求特定 AI 能力时,开发者无法将 Agent 连接到标准数据库。此外,DevOps 使用此标签将有状态原语(stateful-server、resource)显式路由到支持持久磁盘的物理集群边界,而治理裁决角色可以强制有状态组件永远不被放入仅支持临时存储的边界。

2. model.aggrega.ai/capability

  • **谁编写?**平台架构师。
  • **谁使用?**静态分析器(通过 usesSchema 套接字的 Kubernetes 风格标签选择器)。
  • **编译器用例:**当架构师编写一个指定所需能力标签的 usesSchema 选择器时,编译器原生的标签匹配引擎会在生成制品之前拒绝不满足该选择器的连接。编译器将这些标签视为不透明字符串;“text-generation”与“embedding”的语义含义存在于架构师编写的选择器中。

3. component.aggrega.ai/hosting

  • **谁编写?**平台架构师。
  • 谁使用它? 策略引擎(一个治理裁决角色)、Wasm 渲染 Plugins,以及标准库中自身调用模型或智能体的组件:其智能体,其断言在每个 model 连接上读取它;core/ai-tool/agent-invocation,其断言在其 target_agent 连接上读取它,其 Kubernetes 实现也会读取它,拒绝向通过 http 访问的 external 智能体提供凭据;AI 网关,其断言在连接到其 models 和 cache_store 插槽的每个连接上读取它;以及 core/gateway/kong、core/gateway/kong-enterprise、core/gateway/apisix、core/gateway/envoy-gateway、core/gateway/traefik-hub、core/gateway/agentgateway 和 core/gateway/higress,其断言在连接到其 models 插槽的每个连接上读取它,并在连接到两个 Kong 的 backend、APISIX 和 Traefik Hub 的 cache_store 插槽,以及 Envoy Gateway、Higress 和 Traefik Hub 的 cache 插槽的每个连接上读取它——参见下文的“调用方出示的密钥”。
  • 编译器用例: 它记录由谁运营该组件的底层资源,使运营者附加的策略能够判断数据外泄风险;编译器将该值作为字符串读取,不做任何判断。当一个类别标签表明其持有 internal 数据的 Agent 连接到标记为 managed 的 Model(即在该 Release 自身边界之外运营的服务)时,这样的策略可以读出数据离开了该边界,并让构建停止,除非该连接经由携带 core/data-masking 的 AI 网关路由,该网关会对其转发的聊天和补全文本进行脱敏。agent 的 model 插槽可以接收这样的网关来代替模型,因此该路由是策略所读取的图中的一条边;网关从其 models 插槽提供的模型也是一条独立的边,从网关指向模型组件,策略会读取该模型组件的标签——因此从 agent 经网关到达 managed 模型的路径在图中是端到端完整的。手动写入网关模型映射的上游则不然:它是编译器不解析的字符串,因此读取图的策略只能看到网关,看不到其背后的任何东西。examples/policy-data-class-route 就是这样的策略:其设置将 managed 模型归类为 public,当持有 restricted 数据的助手在路由上没有脱敏网关的情况下到达这样的模型时,它会让构建停止。这是一个横切特性:同样的 self-hosted | managed | external 值既可描述模型,也可描述托管数据库或自行运行的推理服务器,因此该标签位于共享的 component.aggrega.ai/ 命名空间下,而不是模型专用的命名空间下。

4. agent.aggrega.ai/autonomy

  • **谁编写?**平台架构师。
  • 谁使用它? 策略引擎(治理裁决角色)。
  • 编译器用例: 它标识认知循环的执行风险。如果某个 agent 被标记为 autonomous(意味着它在没有用户提示的情况下运行后台循环)并连接到高度敏感的数据库,策略引擎可以中止构建,除非作者挂载了企业自身规则所要求的审批或隔离 Feature,从而使无人值守的循环无法在未经审查的情况下访问这些数据。
  • 未加标签的组件在这一维度上意味着什么,因为这种缺失是有意为之。 该标签描述认知循环的执行风险,因此自身不含循环的组件在这里不携带任何值,而不是携带两者中较低的那个。agent 类别中有相当多的组件正是出于这个原因而未加标签:agent 平台随其服务器一起提供的辅助部件——浏览器控制台、schema 迁移任务、任务 worker、代码沙箱、出口代理——之所以归入该类别,是因为你会在那里找它们,而它们所支持的循环位于平台的服务器中,标签也正是放在那里。最清楚的例子是同一产品分成两种处理:平台的服务器携带 copilot,而随之提供的代码沙箱什么也不携带。判断依据是循环位于何处,而非部件的形态,因此承载你所提供的 agent 代码的运行时同样不加标签——那里的循环是你部署进去的任何东西,而不是产品所声明的。因此,指定任一值的选择器只匹配持有循环的组件,而为匹配任意自主程度而编写的选择器会跳过辅助部件,而不是把它们当作部署中自主程度最低的东西。

5. gateway.aggrega.ai/intelligence

  • **谁编写?**平台架构师。
  • 谁使用它? 静态分析器,以及企业编写的 linter Wasm 插件。
  • 编译器用例: 它决定路由器在物理上能支持哪些功能。AI fallback-chain Feature 声明了 appliesTo: gateway.aggrega.ai/intelligence=semantic,静态分析器会在渲染任何产物之前,针对目标组件的标签评估该选择器。如果开发者将它挂载到标准的 l4-mesh 网关上,构建会因选择器违规而中止,并指出该 Feature 及其未满足的选择器,因为架构师编写该选择器时就知道,标准 TCP 网格无法解析 LLM JSON 负载来读取请求所指定的模型。该拒绝依据的是 semantic 的缺失,而非 l4-mesh 的存在,因此它同样适用于完全不携带 intelligence 标签的路由器。与上文完全一样,编译器将该标签视为不透明字符串:semantic 的含义在于架构师所编写的选择器。在确实携带 semantic 的路由器上,挂载会通过选择器,接下来发生什么取决于其实现:标准库的实现会将该链写入 AI 网关的路由配置。
  • 标准库携带的内容。 以下组件携带 semantic:core/gateway/litellm,其实现渲染代理的路由表:一个覆盖多个上游提供方的模型映射;core/gateway/cloudflare-ai-gateway,Cloudflare 的托管网关,它读取其转发的每个模型请求——请求指定的模型、计费的 token,以及在网关自身检查开启时的内容;core/gateway/azure-api-management,Azure API Management 的 AI 网关,一种托管服务,它读取提供模型的 API 上的每个模型请求——其语义缓存所比较的提示、回复所报告的 token,以及其安全检查送去审查的内容;core/gateway/apisix,其 AI 代理读取提供模型的路由上每个请求的正文以及模型回复所报告的 token;core/gateway/envoy-gateway,其 Envoy AI Gateway 扩展读取为接入它的模型提供服务的路由上每个请求的正文,以找到请求指定的模型,以及每个回复所报告的 token;core/gateway/kong-enterprise,即 Kong Gateway Enterprise,其 AI 代理读取提供已接入模型的路由上每个请求的正文——请求指定的模型及其携带的消息——以及每个回复所报告的 token;core/gateway/traefik-hub,即 Traefik Hub,其 Chat Completion 中间件读取提供已接入模型的路由上每个请求的正文,根据 chat completion schema 进行检查,并读取每个回复所报告的 token;core/gateway/agentgateway,即 agentgateway,它读取其模型服务路径上每个请求的正文,以找到请求指定的模型(它借此选择请求发往的已接入模型),以及每个回复所报告的 token;以及 core/gateway/higress,即 Higress,其 AI 代理读取提供已接入模型的路由上每个请求的正文——请求指定的模型以及是否流式传输——其插件读取每个回复所报告的 token——因此需要该值的 AI Features 可以针对其中任何一个解析,每个实现会说明其网关支持哪些内容,或在其网关完全不支持时中止构建;对某个网关没有实现的 Feature 会在那里中止构建,并指出其类型。没有组件携带 l4-mesh,标准库中的其他网关组件完全不携带 intelligence 标签:其中负责路由流量的组件终止 HTTP 并在第 7 层路由,另有一个是完全不路由任何内容的控制平面,因此两个值都不适用于它。第 4 层 TCP 网格又是另一类产品。这使上述拒绝完全有效,因为它依据的是 semantic 的缺失:需要该值的挂载在其中任何一个上都会中止。如果架构师的目录确实运行第 4 层网格,就在该组件上携带 l4-mesh,从而使这一区分在两个方向上都可被选择。
  • 此轴命名的是产品层级,这与组件能对流量做什么是不同的问题,而把它理解为后者正是它容易引发的错误。semantic 表示路由器会解析请求体,这正是作用于请求所指定模型的控制所需要的——因此它是该用途的正确轴。它并不说明路由器能否复制流量、携带调用方身份、校验上游证书、拒绝匹配某个模式列表的提示词,或在一段时期内维护预算;需要这些能力之一的 Feature 不应去询问层级:提供这些能力的组件大多是普通的七层代理,根本不带任何 intelligence 值;而当某个 semantic 路由器确实提供其中一项时,其原因也不是层级所记录的。因此层级在两个方向上都会命中错误的集合——它完全排除了普通代理,而对于它所命中的 AI 网关实际具备哪些能力,它也只字未提。这个问题属于下文的数据路径轴,并且两者可以组合——一个 Feature 可以通过同时指定两者,要求一个同时支持镜像的 semantic 路由器。

6. tool.aggrega.ai/impact

  • **谁编写?**平台架构师。
  • 谁使用它? 策略引擎和 Wasm 渲染 Plugins。
  • 编译器用例: 将这一信息从开发者可变的 values 块移入不可变的标签身份后,策略引擎就能评估严格的最小权限配置。渲染插件可以为 read-only 的网页搜索工具生成标准的 invoke 权限,而调用 mutating 的 SQL 删除工具则要求严格的加密签名配置。

7. compliance.aggrega.ai/data-class

  • 谁编写它? 某个资产环境自有目录的平台架构师(或通过治理 label-transform 角色动态注入)。
  • 谁使用它? 策略引擎(治理裁决角色)。
  • 编译器用例: 它为组件所持有的数据赋予一个策略可以沿图追踪的治理身份。编译器将该标签作为字符串带入 IR 图,不做任何排序:它不知道 restricted 比 public 更敏感,也不知道这两个词有任何含义。挂接在 ir-verdict 角色上的策略在其自身设置中提供这种含义——存在哪些类别以及它们如何排序——并读取编译器沿 uses 边枚举出的路由上各组件的标签,因此当持有 restricted 数据的组件沿某条路由到达另一类别的组件,而该路由上没有挂接策略视为降密的 Feature(例如路由所经过的 AI 网关上的 core/data-masking)时,它可以中止构建。枚举按每个起始组件设有上限,超出上限的部分不会列出,因此策略读到的路由是真实存在的,而未读到某条路由并不能证明它不存在。examples/policy-data-class-route 就是这样的策略,针对编译进 CLI 的 Rego 和 CEL 引擎以及 OPA 编写,并将中止的构建与成功完成的构建并列展示。
  • 标准库携带的内容。 没有任何 core/ Component 携带此标签。组件数据属于哪个类别,是关于某个资产环境如何使用该组件的陈述,而非产品在每个 Release 中都成立的属性,因此按照 Naked Base 规则,它不放在基础组件上:资产环境将其携带在自己的 Component 上——可以是通过 extends 的特化(如示例中的理赔助手),也可以是依据上文企业例外而建立的自有基础组件。

8. hardware.aggrega.ai/accelerator

  • 谁编写它? 平台架构师。在打包本地模型组件时,他们清楚该组件从根本上需要 GPU 才能运行。
  • 谁使用它? DevOps(领域 4)。
  • 编译器用例: DevOps 在 Release 中通过 components: {} 映射,显式地将带 GPU 标签的组件路由到物理硬件池边界中。开发者只需在其 Aggregate 中请求认知模型,DevOps 则将其放入昂贵的 GPU 集群边界,完整保留关注点分离。治理裁决角色还可以额外强制:任何携带此标签的组件都不会被放入缺少 GPU 基础设施的边界。

9. datastore.aggrega.ai/engine

  • 谁编写它? 平台架构师,写在数据存储类别的组件上(静态写在带风味的特化上,或在开发者 values 提升该角色时由 label-transform 角色注入)。整个目录中使用的值为:relational、document、kv、vector、graph、semantic-memory、search。每个值命名的是某个产品本身就是的存储引擎——search 指同时也索引向量的搜索与分析引擎——因此存在于应用自身 schema 和访问模式中、而不在任何可部署存储中的特性,不是此轴上的值。
  • 谁使用它? 静态分析器(通过选择器字符串)和策略引擎。
  • 编译器用例: 选择器针对的是存储语义而非产品——智能体的知识库 socket 选择 datastore.aggrega.ai/engine in (vector, semantic-memory, search),策略引擎可以拒绝将 SQL 负载路由到向量引擎。双用途数据存储的 AI 相关性从此标签推导,从不作为单独的布尔值存储。
  • 标准库携带的内容。 core/datastore/qdrant、core/datastore/weaviate、core/datastore/chroma、core/datastore/pgvector 和 core/datastore/milvus 携带 vector,core/datastore/cognee 携带 semantic-memory,core/datastore/opensearch 和 core/datastore/elasticsearch 携带 search,因此上文的知识库选择器可以解析到其中每一个。core/datastore/redis、core/datastore/valkey 和 core/datastore/memcached 携带 kv。这些标签都位于组件自身的基础组件上,因为产品的身份就是该引擎。对 core/datastore/pgvector 而言,这一身份就是它所固定的制品:它运行 pgvector 项目自己的 PostgreSQL 镜像,其中包含该扩展,并且每个 Recipe 都会在组件创建的数据库中启用该扩展——因此它的向量特性不依赖于某项设置,这正是它与上文“Naked Base, Flavored Edges”中所述配置情形的区别:在那种情形下,通用 PostgreSQL 只有在开发者开启扩展后才获得该特性。relational、document 和 graph 没有标准库组件,因此仅指定其中值的选择器在这里不匹配任何组件,而由携带此类组件的目录来满足。

10. pipeline.aggrega.ai/mode

  • 谁编写它? 平台架构师,写在流水线类别的组件上。每个值命名的是产品运行多步骤作业的方式,这些值跟随携带它们的组件而定,而不是预先列出的清单。标准库携带两个值:core/ai-pipeline/temporal 上的 durable,其引擎将每个步骤的结果记录为事件历史并重放,因此工作进程崩溃的作业会从停止处继续;以及 core/ai-pipeline/argo-workflows 上的 reconciled,其控制器依据保存在集群自身 API 中的工作流资源,将每个步骤作为一个 pod 运行。
  • 谁使用它? 策略引擎和 Wasm 渲染 Plugins。
  • 编译器用例: 让策略和渲染器按照一次运行如何在故障中存活——重放的事件历史或协调的集群资源——而非按产品名称来区分流水线引擎。

11. dataplane.aggrega.ai/*(数据路径能力)

  • 谁编写它? 平台架构师,写在任何位于流量路径中的组件上——反向代理、入口网关、服务网格、AI 网关。
  • 谁使用它? 静态分析器,通过 Feature 的 appliesTo 和 socket 的 usesSchema 选择器。
  • **编译器用例:**它回答的是该组件能对流量做什么,这正是运行时控制真正需要知道、而产品层级标签无法表达的内容。core/traffic-shadowing 会将实时请求复制到第二个服务以供评估,它声明 appliesTo: dataplane.aggrega.ai/request-mirroring(仅键本身),Static Analyzer 会在任何渲染之前根据目标的标签对其求值,因此将它附加到完全无法镜像的组件上时,构建会以选择器违规中止,并指出该 Feature 及其未满足的选择器。编译器将这些字符串都视为不透明的,与对待其余字符串完全相同。
  • **为什么前缀命名的是流量路径而不是组件类型。**镜像、调用方身份和上游验证并不是网关的属性,而是任何位于请求路径中的事物的属性,添加到目录中的服务网格三者兼备。如果按最先承载它们的组件类型来命名这一族标签,就会迫使之后的每种类型在自己的前缀下重述同一套词汇,导致同一能力有多个名称,且没有任何选择器能够跨越它们。
  • **为什么保真度放在值中。**两个组件可能都能镜像请求,却仍在 Feature 所关心的方面有所不同:一个复制每个匹配的请求,另一个复制其中可设置的一部分。只说明组件是否镜像的键会同时接纳二者,而把差异留到渲染之后才被发现。将保真度放在值中,便可按适合该 Feature 的两种方式之一来请求它。离开某种保真度就完全无法工作的 Feature,在其选择器中指定该值。在较低保真度下仍能工作的 Feature 只按键选择,并由其实现拒绝组件无法满足的设置:复制整个流量在每个能镜像的组件上都可行,因此 core/traffic-shadowing 可附加到所有这些组件上,而针对声明 full-rate 的组件的实现会拒绝低于 100 的比例,并在消息中指出所请求的比例和组件声明的保真度——这两点是选择器违规不会说明的。因此,这些值源自已发布产品实际实现的功能,而不是作为分类法编排出来的:request-mirroring 带有 full-rate 和 sampled,因为真实的代理正是这样划分的,一种提供复制比例设置,另一种则不提供。
  • **值声明的是能力,而不是配置状态。**这两者在开发者看来读起来一样,但只有其中之一是组件的属性。能够验证上游证书的代理带有 upstream-tls: trust-anchor,无论是否有任何部署启用该检查——标签是 Feature 在任何配置之前据以选择的依据,因此若在其中加载配置,它在被使用的那一刻就无法读取。
  • 标准库包含的内容。core/gateway/nginx 带有 request-mirroring: full-rate、upstream-tls: trust-anchor 和 concurrency-cap: total,即对其转发的所有请求设一个上限。core/gateway/contour 带有 request-mirroring: sampled、caller-identity: client-certificate 和 upstream-tls: trust-anchor。core/gateway/envoy-gateway 带有与 core/gateway/contour 相同的三个值,以及 period-budget: tokens(统计其通过 Envoy AI Gateway 提供的模型每次回复所报告的 token 数)和 concurrency-cap: per-target(对发往其提供的每个模型的在途请求设上限)。core/gateway/kong 带有 upstream-tls: trust-anchor 和 prompt-guard: pattern-list,其 AI Prompt Guard 将模型请求的消息与其路由中保存的列表进行匹配。core/gateway/tyk 带有 upstream-pinning: public-key,core/upstream-key-pinning 据此进行选择。core/gateway/litellm 带有 caller-identity: injected-header、content-masking: entity-recognition、period-budget: cost、prompt-guard: pattern-list、upstream-tls: trust-anchor 和 concurrency-cap: per-target,即对发往其模型映射中每个条目的在途请求设上限。core/gateway/cloudflare-ai-gateway 带有 period-budget: cost。core/gateway/apisix 带有 period-budget: tokens(统计每个模型回复所报告的 token 数,不计价格)和 prompt-guard: pattern-list。core/gateway/kong-enterprise 带有 period-budget: tokens(统计每个模型回复所报告的 token 数)和 content-masking: entity-recognition。core/gateway/traefik-hub 带有 content-masking: entity-recognition 和 prompt-guard: pattern-list,其 Content Guard 中间件会屏蔽其配置中所保存模式的匹配项或其调用的 Presidio 分析器检测到的实体类型,或拒绝与某个模式匹配的请求;它还带有 period-budget: cost,按其配额中间件自带的按模型价格表计价,该中间件也可改为统计每次回复所报告的 token 数。core/gateway/agentgateway 带有 content-masking: pattern-list 和 prompt-guard: pattern-list,其正则表达式防护会屏蔽或拒绝其配置中所保存模式的匹配项,且不识别任何实体类型;它还带有 period-budget: cost,即它按 API 密钥维护的预算,以美元计(按其模型成本目录计价)或以 token 计。core/gateway/higress 带有 content-masking: pattern-list,其 ai-data-masking 插件会在聊天请求消息的文本中屏蔽其配置中所保存模式的匹配项,且不识别任何实体类型;它还带有 period-budget: tokens,将每次回复所报告的提示 token 和补全 token 合并统计,不计价格。core/gateway/azure-api-management 带有 period-budget: tokens,将每次回复所报告的提示 token 和补全 token 合并统计,在实例的每个网关处分别计数,不计价格。core/security/nemo-guardrails 和 core/security/trustyai-guardrails-gateway 是两个位于模型路径上、用训练好的分类器判断请求的防护组件,带有 prompt-guard: classifier,AI 网关和 NGINX 网关的 guard 套接字会选择该值。其中的 AI 网关——core/gateway/litellm、core/gateway/cloudflare-ai-gateway、core/gateway/apisix、core/gateway/envoy-gateway、core/gateway/kong-enterprise、core/gateway/traefik-hub、core/gateway/agentgateway、core/gateway/higress 和 core/gateway/azure-api-management——带有 semantic,其余的则不带任何 gateway.aggrega.ai/intelligence 值,这正是分离在发挥作用,而不是它的例外:需要镜像的 Feature 会触达具备镜像能力的三个组件,而产品层级选择器在其中只会触达 Envoy Gateway,且其理由与镜像毫无关系;需要提示防护、内容屏蔽或周期预算的 Feature 依据 AI 网关能做什么而不是其所处层级来触达它;限制在途请求的 Feature 会触达不带任何层级值的 NGINX 网关,正如它触达 Envoy Gateway 和 AI 网关一样;按模式列表拒绝请求的 Feature 会触达同样不带层级值的开源 Kong,正如它触达 APISIX 一样。在这些轴之一上没有可描述内容的组件,在该轴上不带任何值,而不是带一个最弱的值,因此指定该轴上任何值的选择器都正确地不会附加到它上面。

12. security.aggrega.ai/text-anonymization

  • **谁编写它?**Platform Architect,写在参与屏蔽敏感文本的服务上。当这项工作分由两个服务完成时,analyzer 放在负责在文本中查找敏感片段并报告它们的服务上,anonymizer 放在负责改写交给它的片段的服务上;sanitizer 放在一次调用中完成两者的服务上,它在收到的文本中查找敏感片段并自行改写,然后返回改写后的文本。
  • **谁使用它?**Static Analyzer,通过套接字的 usesSchema 选择器。
  • **编译器用例:**它是将正确地址交给消费方的方式。core/gateway/litellm 声明了一个选择 security.aggrega.ai/text-anonymization=analyzer 的 pii_analyzer 插槽,以及一个选择 anonymizer 值的 pii_anonymizer 插槽,因此把任一服务连接到另一个服务的插槽,都会因选择器违规而中止,并指出该插槽。core/gateway/kong-enterprise 声明一个插槽 pii_sanitizer,选择 sanitizer 值;core/gateway/traefik-hub 声明一个插槽 pii_analyzer,只选择 analyzer 值,因为其 chart Recipe 为 core/data-masking 编写的 Content Guard 会自行替换分析器找到的内容。编译器路由所选组件发布的地址,而不检查在该地址应答的是什么。
  • 标准库提供的内容。core/security/presidio-analyzer 带有 analyzer,core/security/presidio-anonymizer 带有 anonymizer。两者都使用 Presidio HTTP API:当 core/data-masking 附加项或网关自身的 values.log_masking 列出实体类型时,AI 网关会调用它;当该网关上的 core/data-masking 附加项列出实体类型时,Traefik Hub 的 Content Guard 只调用分析器。core/security/kong-ai-pii-service 带有 sanitizer,使用 Kong 的 AI PII 服务 API;当该网关上有 core/data-masking 附加项时,Kong Gateway Enterprise 的 AI PII Sanitizer 会用它所掩码的每段文本(包括其正则表达式)调用该 API。清洗器不向它出示任何凭据,且每段文本都以未掩码形式到达它,因此其地址是集群内地址,不应暴露到集群之外。

13. model.aggrega.ai/api

  • **谁来编写?**平台架构师,写在模型类别中的每个组件上,以及提供模型 API 的网关上。该值指明在组件发布的地址上应答的是哪种模型 API:是 OpenAI API(厂商自身的,或某个服务器对它的实现)时为 openai,是 Anthropic 的 Messages API 时为 anthropic,是 Google 的 Gemini API 时为 gemini,是产品自身的 API 且不属于上述任何一种时为 native,消费方通过该产品的客户端访问它。每个值都取自产品自身的参考文档,无论某个 Release 如何配置,组件都带有该值。
  • **谁来消费?**静态分析器(通过插槽的 usesSchema 选择器),以及 AI 网关、core/gateway/kong、core/gateway/kong-enterprise、core/gateway/apisix、core/gateway/envoy-gateway、core/gateway/traefik-hub、core/gateway/agentgateway 和 core/gateway/higress 的断言,作用于其 models 插槽上的每个连接。
  • **编译器用例:**它让一个插槽既能接受模型,也能接受提供模型的网关。除下文列出的五个运行时之外,每个智能体的 model 插槽、core/ai-tool/model-invocation 的 target_model 插槽以及 core/datastore/cognee 的两个模型插槽都选择 component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api:类别要求接纳这两个类别,键要求只接纳其中带有该标签的组件,因此把这样的插槽连接到不提供任何模型 API 的网关,会因选择器违规而中止,并指出该插槽。选择器的所有要求都必须成立,而其备选项只存在于一个键的集合之内,所以两类组件都要响应的那个键必须既在每个模型组件上,也在网关上——这就是该标签指明 API 而非只标记网关的原因。带有该标签的网关发布与模型相同的 endpoint 和 model 键,因此消费方的 Recipe 能以相同方式读取两者。Recipes 只交付某一种模型 API 变量的智能体则直接指明其值:core/ai-agent/openai-agents-sdk、core/ai-agent/agent-framework 和 core/ai-agent/mastra 的 model 插槽选择 model.aggrega.ai/api=openai,core/ai-agent/claude-agent-sdk 的选择 model.aggrega.ai/api=anthropic,core/ai-agent/google-adk 的选择 model.aggrega.ai/api=gemini,因此把其中之一连接到提供另一种 API 的模型或网关,会因选择器违规而中止,并指出该插槽。core/ai-agent/google-adk 的插槽还把类别收窄为 ai-model,拒绝所有网关,因为 ADK 的客户端不读取任何地址,会把网关的凭据发送到 Google 自己的地址。AI 网关读取该值而不是以它为选择条件:其 models 插槽选择 component.aggrega.ai/category=ai-model,接纳所有模型;由于网关只通过 OpenAI API 向其代理描述连接在此的模型,其 Component 的断言会在目标带有 openai 以外任何值的连接上中止构建,指出该连接,并提示改为将该上游手动填入网关的手写模型映射。core/gateway/kong、core/gateway/kong-enterprise、core/gateway/apisix、core/gateway/envoy-gateway、core/gateway/traefik-hub、core/gateway/agentgateway 和 core/gateway/higress 在各自的 models 插槽上以同样方式读取该值,因为它们各自只为 OpenAI API 编写所连接模型的路由(在 agentgateway 上是其模型条目)。编译器将该值视为不透明字符串,不检查在该地址应答的是什么。
  • 标准库提供的内容。core/gateway/litellm、core/gateway/kong、core/gateway/kong-enterprise、core/gateway/apisix、core/gateway/envoy-gateway、core/gateway/traefik-hub、core/gateway/agentgateway 和 core/gateway/higress 带有 openai;自托管服务器 core/ai-model/vllm、ollama、docker-model-runner、tgi、tei、nvidia-nim 和 litellm,托管 API core/ai-model/openai、openai-embedding 和 nvidia-api,以及指向使用该 API 的服务的代理 core/ai-model/openai-compatible 也是如此。core/ai-model/anthropic 带有 anthropic,core/ai-model/gemini 带有 gemini。其他所有模型组件都带有 native。

14. tool.aggrega.ai/transport

  • **谁来编写?**平台架构师,写在消费方必须通过某种传输协议访问的工具上。该值指明这种传输协议。
  • **谁来消费?**静态分析器,通过消费方的工具插槽。
  • **编译器用例:**它确保消费方只被交付它能与之通信的工具。工具插槽选择 component.aggrega.ai/category=ai-tool, tool.aggrega.ai/transport=http:类别要求只接纳工具,传输要求只接纳通过 HTTP 访问的工具,因此把这样的插槽连接到不带此标签的工具,会因选择器违规而中止,并指出该插槽。工具的访问方式必须是标签而非发布的值,因为选择器读取标签,从不读取值的内容。编译器将该值视为不透明字符串,不检查在该地址应答的是什么。
  • 标准库的承载情况。 core/ai-tool/mcp 带有 http。它将一个 Model Context Protocol 服务器挂接到智能体上,由 Manifest 决定该服务器如何实现:helm/mcp 和 compose/mcp 运行一个通过 HTTP 提供该协议的镜像;helm/mcp-stdio-bridge 和 compose/mcp-stdio-bridge 运行一个只支持 stdio 的软件包,并在其前面放置一个固定版本的桥接器,通过 HTTP 对外提供服务;helm/mcp-remote 和 compose/mcp-remote 访问由他人运行的服务器,自身不运行任何内容。每种实现都发布相同的 host、port、endpoint、protocol 和 credential_header,因此消费者的连线不随实现方式而改变。服务器自身的凭据是环境变量,保存在该工具的 server_env 槽位中:在 Kubernetes 上以引用方式传递给桥接器,在 Docker Compose 上则按传递时的原样写入服务的环境,其中 Compose 变量引用可使凭据不出现在文件中;远程服务器的凭据由消费者保存在其自身到该工具的连接上,并在 credential_header 指定的请求头下出示,除非 Release 指定了其他请求头,否则为 Authorization。如果远程服务器从自身地址中读取密钥,消费者也在该连接上保存完整地址,放在一个 endpoint 槽位中:在 Kubernetes 上由对 Secret 的引用填充,在 Docker Compose 上由 Compose 变量引用填充,因此密钥不会出现在任何渲染文件中,而该工具的 infra.endpoint 保存不含密钥部分的地址;examples/mcp-address-from-secret 同时构建了这两者。core/ai-agent/openai-agents-sdk、core/ai-agent/claude-agent-sdk、core/ai-agent/agent-framework、core/ai-agent/google-adk 和 core/ai-agent/mastra,以及流程平台 core/ai-agent/flowise 和 core/ai-agent/n8n,都声明了这种形式的工具 socket tools,并以按连接别名命名的变量传递每个已连接工具的地址,以及以引用方式传递该连接的凭据,而写有 inject: 块的连接则接收该块所规定的内容,取代由工具发布的内容派生出的变量,其 credential 和 endpoint 槽位中保存的内容仍沿用别名的名称;自定义的消费者也以同样方式声明。这三个流程平台都会在部署时将 Aggregate 中编写的流程带入平台,两种目标上均是如此:Langflow 在每次启动时从其 flows 目录加载所携带的定义,Flowise 的 chatflow 由一个一次性步骤写入,该步骤以 Release 指定的所有者账户登录,n8n 的 workflow 则由平台启动前的一个 init 步骤导入。core/ai-agent/langflow 声明了相同形式的 tools socket(该 socket 不接受 inject: 块),但改为通过该流程传递每个连接,因为 Langflow 的 MCP Tools 组件只从 Langflow 自身的设置或流程中获取服务器地址,从不从变量中获取:其 Recipes 将工具地址写入服务器名称与连接别名相同的 MCP Tools 节点,以引用方式将连接的凭据作为该节点请求头所指定的变量传递——在 Authorization 下,变量中保存 Bearer 和凭据——并让已连接的工具和存储的主机通过 Langflow 针对私有地址的防护。这三个平台还都声明了一个选择 datastore.aggrega.ai/engine in (vector, semantic-memory, search) 的 vector_store socket,以同样方式传递每个已连接存储的地址——即其发布的 endpoint(对于 core/datastore/pgvector,是一个不含密码的连接 URI),或由其协议、主机和端口组合而成的地址——以及以引用方式传递连接的凭据;如果某个存储还发布了其数据库和用户(如 core/datastore/pgvector),这些部分也会分别传递给 Flowise 和 n8n,因为这两个平台的 PostgreSQL 向量节点都不接受连接字符串;Langflow 的 PGVector 组件接受单个字符串,因此它以 AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING 接收这样的存储,连接的凭据即其密码,在 Kubernetes 上以引用方式传递,在 Docker Compose 上按传递方式提供。Flowise chatflow 通过在 Flowise 的 Variables 页面上创建的同名 Runtime 变量读取传递的变量;n8n workflow 只有在 Aggregate 设置了平台的 allow_env_access_in_nodes 值时才能通过 $env 读取变量,因为其 Recipes 默认保留 n8n 对节点内访问环境变量的限制。

2. 端口抽象(零端口约定)

开源的 Aggrega 标准库目录建议在 Components 的认知层中省略物理端口声明,改由 Ops Recipe 负责端口选择。遵循这一建议的作者可以避免跨部署目标的端口冲突,防止绕过注入 契约的后门 API,并在不同提供方之间保持网络拓扑的灵活性。编译器本身与端口无关——它传递解析后的 JSON Schema 所允许的任何值。该 约定为物理端口无法变更的遗留系统提供了明确的逃生舱口。

  • 云原生默认方式(动态注入): 对于现代工作负载,Components 在其 schema: 声明中完全省略物理端口(没有 ports 或 expose 数组)。平台 Ops Recipes 选择内部 TCP/UDP 端口,并将其作为命名的 provides 键发布,下游消费者通过 .context.uses 注入契约读取该键。
  • 遗留系统逃生舱口(显式声明): 当遗留组件具有不可更改的硬编码端口时,平台架构师在该 Component 的 schema: 声明中显式暴露 一个 port 字段。这为开发者提供了一种经过校验的方式来声明该物理约束。编译器将该 值原样传递通过整个管道;Recipe 通过 {{ .values.port }} 使用它。
  • 运维端口(带外): 仅供集群基础设施使用的端口(例如 Prometheus 抓取、Envoy sidecar 指标)对开发者的认知层保持隐藏。它们由平台运维通过 Features 以带外方式注入(例如挂接 core/prometheus-exporter Feature,其抓取端口是由运维方设置的 infra)。

3. 领域特定的 Schema(配置智能)

开发者的 values 块(对 Go 编译器不透明,但由 Component 的 schema: 声明进行严格类型约束)经过校验,以支持明确的 AI 工作流:

  • 智能体链接(依赖数组): 标准库共享的智能体参数 schema 以 values 数组的形式携带 tools_allowed 和 agents_allowed,列出智能体可以调用或委派的目录 Components——这是一项有文档记载的约定,编译器不会对其求值。编译器作为拓扑边连接的链接,是智能体的 Component 在其 usesSchema 中声明的 uses socket,而构建检查的正是该 socket 的选择器。
  • 深度认知记忆分区(CoALA): 架构师可以不使用单一的扁平记忆存储桶,而是声明一个 cognitive_memory socket,其连接将语义记忆、情景记忆和程序性记忆作为显式拓扑边映射到不同的基础设施目标,使策略引擎可以评估并强制实施细粒度的访问防护(例如,确保智能体可以读取语义记忆,但在被劫持时无法覆盖它)。标准库没有声明这样的 socket。
  • 多模态管道: Component 的 schema: 可以将 document_chunking、embedding_generation 和 storage_routing 等显式执行阶段声明为带类型的 values,使声明式数据流在任何内容渲染之前得到验证。标准库没有声明这样的阶段。

4. 网关智能与路由

标准库的 AI 网关承载将请求路由到 LLM API 的控制:core/gateway/litellm 在集群内运行;另有两个托管服务:core/gateway/cloudflare-ai-gateway 是 Cloudflare 的托管网关,由其 terraform Recipe 在 Cloudflare 账户中创建;core/gateway/azure-api-management 是 Azure API Management 的 AI 网关,其 terraform Recipe 向一个已存在的 API Management 实例添加一个提供模型服务的 API,连同其后端和策略。每个托管网关的 helm 和 compose Recipes 在其已配置之处引用它。有些控制是网关自身的值,有些是附加到网关上的 Features,下文每个 Feature 都会说明标准库在哪个网关上实现它。在托管网关上,每项控制都写入网关自身的配置——Cloudflare 网关资源的一项设置,或 Azure API Management 上 API 策略的一个元素——因此只有其 terraform Recipe 能承载控制,而其 helm 和 compose Recipes 在有任何附加时都会使构建中止。下文中,“AI 网关”指 core/gateway/litellm,“托管网关”指 core/gateway/cloudflare-ai-gateway,Azure API Management 的网关则使用全称。

Aggrega 之外,运行时

代理

其 model 插槽连接到网关

AI 网关

附带挂接到它的控制项

令牌预算

语义缓存

提示注入防护

模型

网关后面的提供方

代理的请求会经过其 model 插槽所连接的网关,因此挂接到网关上的每个控制项都位于代理和模型之间。这里画出的三个是 Features core/period-budget、core/semantic-caching 和 core/prompt-injection-shield,并排显示是为了说明它们所处的位置,而不是作为某一个网关的配置:下面的条目说明哪个网关实现每个控制项,以及什么会使构建停止。

  • 其背后的模型: AI 网关的模型映射——它提供的别名,以及每个别名的请求所发往的上游——由两部分组成。连接到网关 models 插槽的模型组件(无论是托管的还是自托管的)以该连接的别名提供服务,其条目根据该模型发布的 endpoint 和 model 写成;这些字符串由编译器传入网关配置,编译器从不解析它们;因此该模型是图中的一个组件,通过其自身的一条边到达。网关仅通过 OpenAI API 向其代理描述此类模型,所以如果某个连接到达的模型的 model.aggrega.ai/api 不是 openai,构建会中止,并指明该连接。另一部分是网关的 values.models,即以代理自身的 provider/model 表示法手工填写的条目:用于目录未建模的上游、自身 API 不是 OpenAI API 的 provider,以及多个条目共用一个别名的情况——连接的模型无法做到这一点,因为每个模型都以其自身连接的别名提供服务。连接的条目出示其自身连接所携带的凭据(如下文“The key a caller presents”所述),而从不使用网关的 provider_key;每个手工填写的条目都出示该插槽中的那一个凭据。两部分都发布的别名会中止构建并指明该别名;两部分都没有为其提供模型的网关同样会中止构建。

  • 位于智能体的路径中: 网关发布 endpoint 和 model,即模型组件所发布的键,并带有 model.aggrega.ai/api: openai,因此智能体的 model 插槽可以直接接入该网关,附加到网关上的每个控制项都位于该智能体与其背后的 provider 之间。它发布的 model 是其 values.model 所指定的别名,若映射的两部分都未发布该别名,构建会中止;只有当网关只提供一个别名且由 values.models 的某个条目发布时,才可以省略它,此时发布的就是该别名。需要映射所发布的其他别名的调用方,可以按名称向同一端点请求。core/gateway/cloudflare-ai-gateway 发布同样的两个键——网关某个端点的地址(由 Cloudflare 账户和网关 id 组合而成),以及调用方请求的模型(网关不加检查地转发)——但不带 model.aggrega.ai/api,因此智能体的 model 插槽不接受它。core/gateway/azure-api-management 同样发布这两个键——其 API 的地址(由实例主机和 API 路径组合而成),以及调用方请求的模型(不加检查地转发)——同样不带 model.aggrega.ai/api:该 API 响应 OpenAI 的 chat completions 请求,但默认情况下调用方要在其专用请求头中出示 API Management 订阅密钥,而不是 OpenAI 的 bearer token,所以仅靠普通的 OpenAI 客户端不足以调用它。

  • 位于模型前的 Kong: core/gateway/kong,即开源的 Kong 网关,通过 Kong 的 AI 代理为连接到其自身 models 插槽的模型提供服务;在下述控制项中,它只实现提示词拒绝模式,形式是在每个连接模型的每条路由上启用 Kong 的 AI Prompt Guard。每个连接的模型在 /<alias>/v1 下获得一条 chat 路由和一条 completion 路由,根据该模型发布的 endpoint 和 model 写成,其 Recipes 会在网关启动前将这些路由导入网关的 PostgreSQL 后端。路由决定模型,因此无论请求携带什么模型名称,都会发往其路径所指定的模型。网关将每个连接自身的凭据作为 bearer token 出示,该 token 由其配置按名称从网关的环境变量中读取;如果某个连接到达的模型的 model.aggrega.ai/api 不是 openai,构建会中止。它将其 values.model 所指定别名的路由发布为其 endpoint,将该别名发布为其 model,并带有 model.aggrega.ai/api: openai,因此智能体的 model 插槽可以像接入 AI 网关一样接入它。若该插槽上没有连接任何模型,网关不提供任何模型,发布的两个键均为空,连接到它的智能体此时读不到地址,也读不到模型名称。导入只添加和更新路由,从不删除,因此连接被移除的路由会继续响应,core/prompt-deny-patterns 附加所写入的提示词防护在附加移除后也会继续拒绝请求,直到通过 Kong 的 Admin API 逐一删除。出于同样的原因,该网关不声明调用方,其模型路由也不检查任何调用方的密钥:Kong 只能将调用方区分为某个认证插件所指定的 consumer,而一个 consumer 及其密钥一旦导入,在该调用方从 Release 中移除后仍能通过认证,密钥轮换后旧密钥也仍然有效;而且 key-auth 密钥无法通过引用持有,因此调用方的密钥只能以字面值的形式出现在渲染出的文件中才能到达 Kong。

  • 模型前端的 Kong Gateway Enterprise:core/gateway/kong-enterprise 是 Kong 推出的同一款数据库支撑网关的付费版本。它在 core/gateway/kong 所服务的路由上,为连接到自身 models 插槽的模型提供服务;这些路由由相同的配置写出,并在网关启动前,由网关自身 pod 中的一个步骤导入其 PostgreSQL 后端。它发布 endpoint 和 model 的方式与 Kong 相同。它唯一的实现是基于 Kong 官方 Helm chart 的 chart Recipe,没有 compose 实现。它运行 Release 在 infra.image 中指定的镜像(包括版本标签),因为 Kong 按其自有条款分发企业版镜像,catalog 因此不指定任何镜像;当该键未设置或其标签不含版本时,构建会中止。许可证通过引用绑定到其必需 license 插槽的 Secret 送达网关,从不作为值传入;当该插槽未绑定任何内容时,构建会中止。编译器不验证任何许可证,也不联系任何供应商,因此一个构建成功的 Release 并不能说明许可证的任何情况:Kong 在节点启动时读取许可证,没有有效许可证的节点表现得与许可证过期时相同,其实体配置变为只读,代理流量则按已有的配置提供服务。Kong 将其 AI 插件作为 AI Gateway Enterprise 产品出售,这是许可证内的一项授权,任何构建都无法看到;当许可证缺少该授权时,Kong 会跳过此类插件而不是拒绝它,因此附加 core/semantic-caching、core/period-budget、core/data-masking、core/fallback-chain、core/retry-policy 或 core/target-selection 会中止构建,直到 Release 将 infra.ai_gateway_entitled 设为 true,以确认许可证包含该授权。在下列控制中,它实现周期预算和回退链,二者都写入网关导入的路由;它按下文“Data Exfiltration & Payload Interception”所述实现 core/data-masking;它对语义缓存、重试策略和目标选择的实现会在每次附加时中止构建,并各自说明原因;并发限制、审计日志、提示注入筛查、响应验证和提示拒绝模式在其上没有实现,因此附加其中任何一个都会中止构建。路由集合发生变化会滚动更新网关,而导入只添加和更新路由、从不删除路由,因此连接已移除的路由,以及 AI Feature 写入的插件(在该 Feature 移除后),都会保留在数据库中,直到通过 Kong 的 Admin API 删除为止;出于上一条所述的原因,它同样不声明任何调用方,其模型路由也不检查任何调用方的密钥。运行中的网关是否执行了这些控制中的任何一项,任何构建都无法观察到。

  • 模型前端的 APISIX:core/gateway/apisix 即开源的 Apache APISIX 网关,在 Manifest 绑定其 chart Recipe(运行 APISIX 3.18.0)时,通过 APISIX 的 AI 代理为连接到自身 models 插槽的模型提供服务。每个连接的模型在 /<alias>/v1 下获得一个 chat 路由和一个 completion 路由——当附加了周期预算或提示拒绝模式时只有 chat 路由,因为 APISIX 不对 completion 请求计算 token,其提示防护也不读取 completion 请求——这些路由由模型发布的 endpoint 和 model 写入一个与网关一同渲染的路由文件,网关在启动时读取该文件,并在文件每次变化时重新读取。从该文件读取路由的网关不读取 etcd,也不运行 Admin API,因此在已连接模型时,etcd 连接或 admin_key 附加会中止构建;而在未连接任何模型时,二者都是必需的。路由决定模型。网关将每个连接自己的凭据作为 bearer token 提供,路由按名称从网关的环境中读取该凭据;连接到 model.aggrega.ai/api 不为 openai 的模型会中止构建。它将其 values.model 所指别名的路由发布为 endpoint,将该别名发布为 model,并带有 model.aggrega.ai/api: openai,因此 agent 的 model 插槽可以像接受 AI 网关那样接受它;未连接任何模型时,它发布的两个键均为空。连接已移除的路由会在下一次渲染中消失。Release 可以在 infra.callers 中指定网关的调用方,并通过 caller_keys 插槽指定其密钥,即一个为每个调用方名称保存一个数据键的 Secret:此时每个调用方都是路由文件中的一个 consumer,其密钥按名称从该 Secret 读取;每个路由都会以 HTTP 401 拒绝未以 Authorization: Bearer <key>(OpenAI 客户端提供密钥的方式)提供已声明密钥的请求,并从转发的请求中移除该密钥。没有调用方时,路由是开放的。其 workload Recipe 使用 APISIX 3.17.0,将路由保存在 etcd 中,不渲染任何路由文件,并会在连接到该插槽以及设置 infra.callers 时中止构建。在下列控制中,它实现周期预算、针对其所声明调用方的语义缓存,以及提示拒绝模式。

  • 模型前端的 Envoy Gateway:core/gateway/envoy-gateway 即开源的 Envoy Gateway,通过 Envoy AI Gateway 为连接到自身 models 插槽的模型提供服务;Envoy AI Gateway 的控制器 core/gateway/envoy-ai-gateway-operator 由网关通过其 extension 插槽作为扩展服务器调用。已连接模型而该插槽上没有任何连接时,构建会中止;连接了控制器时,Release 必须将网关置于 envoy-gateway-system 中,否则构建会中止。每个连接的模型都成为附加到网关的同一个 AI 路由中的一条规则,按请求携带的模型名称选择,其后端由模型发布的 endpoint 和 model 写出,因此每个连接的模型都在网关自身地址的 /v1 下提供服务。网关将每个连接自己的凭据作为 bearer token 提供,Envoy AI Gateway 的控制器从该凭据所指的 Secret 中读取它;连接到 model.aggrega.ai/api 不为 openai 的模型会中止构建。只要连接了模型,网关上的每个路由都会采用 Envoy AI Gateway 配置的每连接 50Mi 请求缓冲区。它将以 envoy-gateway-system 限定的地址(以便从任何命名空间解析)发布为 endpoint,将其 values.model 所指的别名发布为 model,并带有 model.aggrega.ai/api: openai,因此 agent 的 model 插槽可以像接受 AI 网关那样接受它;未连接任何模型时,它发布的两个键均为空。控制器的 webhook 使用 cert-manager 签发的证书,因此 cert-manager 必须已在集群中运行,除非 Release 在控制器的 infra.webhook_tls_secret 中指定一个保存运维人员所提供证书的 Secret,webhook 随后使用该证书。在下列控制中,它实现周期预算、重试策略和并发限制,均写入为其模型提供服务的路由的那一个流量策略中。它不实现语义缓存或响应验证,因为 Envoy AI Gateway 不保留用于回答后续请求的回复,也不按 schema 检查回复;它也不实现回退链:Envoy AI Gateway 通过在模型规则的其他后端上重试来实现回退,而网关会将其唯一流量策略的重试次数写入为其模型提供服务的路由的每条规则,因此只有当每个连接模型的回退列表长度相同时,回退列表才能恰好得到其应有的发送次数。它按下文“Audit logging”所述,将 core/audit-logging 实现为其访问日志,并按名称拒绝该日志无法保存的内容:请求的成本,因为 Envoy AI Gateway 能计算的每请求成本没有单位,且网关不保存价格;网关验证过的调用方,因为该路径上没有任何组件验证调用方;以及保留期,因为该日志没有存储,也没有保留期设置。examples/envoy-ai-gateway-token-budget 构建了完整路径,其中一个 agent 通过该网关访问 OpenAI 的托管模型。

  • 模型前置的 agentgateway:core/gateway/agentgateway 即开源的 agentgateway,它通过其 Recipes 渲染的一个配置文件,为连接到其自身 models 插槽的模型提供服务。每个已连接的模型都是该文件中的一个条目,以连接的别名命名,并根据模型发布的 endpoint 和 model 写为一个兼容 OpenAI 的聊天补全提供方,因此每个已连接的模型都在网关自身地址的 /v1 下提供服务,并由请求携带的模型名称来选择:请求到达模型时,请求的是该模型发布的模型名称;没有任何连接携带的名称会得到 HTTP 404 响应。网关以 bearer 令牌的形式出示每个连接自身的凭据,文件将其命名为一个变量,网关在读取文件时从其环境中读取该变量;环境中缺少该变量会使网关无法启动。连接到 model.aggrega.ai/api 不为 openai 的模型的连接会使构建中止。它将该 /v1 基础 URL 发布为其 endpoint,将其 values.model 指定的别名发布为其 model,并带有 model.aggrega.ai/api: openai,因此智能体的 model 插槽会像接受 AI 网关一样接受它;未连接任何模型时,它发布的这两个键均为空。两个 Recipes 运行同一个按摘要固定的镜像:agentgateway-chart 渲染该项目的独立 Helm chart(从项目的镜像仓库获取),并实现下文的各项控制;agentgateway 将镜像作为一个 Docker Compose 服务运行,不实现其中任何一项,也不支持调用方,因此在其上的挂载会使构建中止并指出其类型。在 Kubernetes 上请使用 chart,因为构建可以访问该镜像仓库。在 chart 上,Release 可以像在 APISIX 上一样,在 infra.callers 中指定网关的调用方,并通过 caller_keys 插槽提供其密钥:每个调用方都是该文件中的一个 API 密钥,以严格模式检查,并按名称从该 Secret 中读取,因此未以 Authorization: Bearer <key> 形式出示已声明密钥的模型请求会被 HTTP 401 拒绝,且转发的请求中会移除该密钥;没有调用方时,模型路由是开放的。agentgateway 会将文件以这种方式指定的每个密钥(任一 Recipe 上已连接模型的密钥,以及 chart 上调用方的密钥)先放入文件文本,然后再将文件作为 YAML 读取,因此密钥必须是纯令牌——字母、数字以及 -、.、_、~、+、/ 和 =——其他字符可能被加载为另一个密钥,或使网关停止。网关会在文件变更时重新读取,因此从 Release 中移除的调用方会在挂载的文件更新后被拒绝。当挂载了 core/audit-logging,或作用域为 caller 的 core/period-budget 时,chart Recipe 会为网关提供一个存储,即位于其专属卷上的一个 SQLite 文件,并只运行一个副本。在下文的各项控制中,它实现数据脱敏、提示词拒绝模式、周期预算、审计日志和重试策略,每项都写入该文件,并按名称拒绝它无法保持的每个值。数据脱敏会将挂载所列模式的每个匹配替换为 <masked>,或在 refuse 下以 HTTP 403 响应请求或回复;其作用范围是请求的系统提示词和开发者提示词、其他消息以及工具调用的参数和结果,以及整体到达的回复的消息文本;它不识别实体类型,也不恢复任何内容。agentgateway 不对流式回复脱敏,因此在回复被脱敏期间,要求流式回复的模型请求会在转发前被 HTTP 403 拒绝;任何正文大于网关为该检查所读取的 2 MiB 的模型请求也同样如此,无论是否为流式。守卫(包括拒绝模式)的拒绝是 HTTP 403,正文为 “The request was rejected due to inappropriate content”。预算、记录和重试见下文“Period budget”“Audit logging”和“Resilience”。它对回退链、目标选择、语义缓存、响应校验和提示词注入筛查的实现会中止每一次挂载,并各自说明原因;并发限制不会挂载到它上面,因为它不带有 dataplane.aggrega.ai/concurrency-cap 值。

  • 模型前置的 Traefik Hub:core/gateway/traefik-hub 即 Traefik 的付费网关,它通过 Traefik Hub 的 Chat Completion 中间件,为连接到其自身 models 插槽的模型提供服务。它唯一的实现是基于 Traefik 自身 Helm chart 的 chart Recipe;没有 compose 实现。它运行 Release 在 infra.image 中指定的镜像(包括标签),因为 Traefik 按其自身条款分发 Traefik Hub,所以目录不指定任何镜像;当该键未设置或未指定标签时,构建会中止。许可证令牌通过引用绑定到其必需的 license 插槽的 Secret(数据键为 token)到达网关,而从不作为值传递;当该插槽未绑定任何内容或其发布的是其他数据键时,构建会中止。Traefik 需要到 api.traefik.io 的出站 HTTPS,网关在该处校验其令牌;从 Traefik Hub v3.21 起,该主机无法访问时网关仍会提供服务并在后台重试;令牌默认有效期为一年,过期后网关停止。chart Recipe 会关闭 chart 将网关错误日志导出到 Traefik 平台的功能及其新版本检查。编译器不校验令牌,也不联系任何供应商,因此一个构建无误的 Release 并不能说明网关能否启动。每个已连接的模型在 /<alias>/v1/chat/completions 获得一条路由,通过类型为 ExternalName 的 Service 发送到模型发布的 endpoint,并且无论请求携带何种模型名称,都请求模型发布的 model,因此由路径选择模型;它只提供聊天补全。网关以 bearer 令牌的形式出示每个连接自身的凭据,Traefik Hub 从该连接的 Chat Completion 中间件所指定的 Secret 中读取它;连接到 model.aggrega.ai/api 不为 openai 的模型,或其端点指定的是地址而非主机名的连接,会使构建中止。它将其 values.model 指定的别名的路由发布为其 endpoint,将该别名发布为其 model,并带有 model.aggrega.ai/api: openai,因此智能体的 model 插槽会像接受 AI 网关一样接受它;未连接任何模型时,它发布的这两个键均为空。Release 可以在 infra.callers 中指定网关的调用方,并通过 caller_keys 插槽提供其密钥的 htpasswd 哈希:此时 Traefik Hub 的 API Key 中间件位于每条模型路由之首,拒绝未以 Authorization: Bearer <key> 形式出示已声明密钥的请求,且转发的请求中会移除该密钥;没有调用方时,路由是开放的。对于指定了不存在的 Secret 或数据键的调用方条目,Traefik Hub 如何处理,其参考文档并未说明,因此在最坏情况下,路由会像没有调用方时一样开放。在下文的各项控制中,它通过 Traefik Hub AI 网关的中间件实现周期预算、针对其所声明调用方的语义缓存、提示词拒绝模式和数据脱敏,并通过 Traefik 自身的故障转移和重试实现回退链和重试策略,每项都写入其 chart Recipe 渲染的路由中。AI 网关是许可证内含的一项授权,任何构建都无法看到;对于许可证缺少该授权的有效令牌,Traefik Hub 如何处理并无文档说明,因此挂载前四项中的任何一项都会使构建中止,直到 Release 将 infra.ai_gateway_entitled 设为 true。它对提示词注入筛查、审计日志、目标选择和响应校验的实现会中止每一次挂载,并各自说明原因;并发限制不会挂载到它上面,因为它不带有 dataplane.aggrega.ai/concurrency-cap 值。运行中的网关是否执行了这些控制中的任何一项,任何构建都无法观察到。

  • 模型前置 Higress:core/gateway/higress 是开源的 Higress 网关,基于 Envoy 构建并通过 Kubernetes 资源配置,它通过 Higress 的 AI 代理为接入其自身 models 插槽的模型提供服务。它唯一的实现是基于该项目自身 higress-core Helm chart 的 chart Recipe,该 chart 运行 Higress 的控制器(含其发现服务)和网关;没有 compose 实现,因为该项目的 compose 发行版主要面向本地测试,且该发行版运行多个协作服务,并通过它们自己的存储进行配置。该 Recipe 固定 chart、镜像及其写入的每个插件模块的版本,并且 infra.source_version 只接受其配置已验证过的 chart 版本;网关在运行时从 Higress 插件仓库拉取这些模块,集群必须能访问该仓库,而构建无法检查这一点。控制器只监视该 Release 的命名空间,使用以网关和该命名空间命名的 IngressClass,因此同一命名空间中的两个 Higress 网关会发生冲突。每个别名在 /<alias>/v1 获得一条路由,通过网关自身注册表中的一个条目发送到该别名的模型所发布的 endpoint,并且无论请求携带什么模型名,都请求该模型发布的 model,因此由路径选择模型;在 serves 值中指定同一别名的多个连接平均分担其请求。网关将每个连接自身的凭据作为 bearer token 出示,Higress 控制器从 AI 代理配置所指定的 Secret(位于网关的命名空间)中读取该凭据并交给网关,因此密钥不会出现在任何渲染出的文件中;Secret 名称包含点号会使构建中止,因为 Higress 只读取名称中第一个点号之前的部分;不携带凭据的连接会传递请求所出示的密钥。Higress 的 AI 代理还会把客户端发送的 Authorization 头复制到 X-HI-ORIGINAL-AUTH 头中,每条模型路由都会在请求到达模型之前移除该副本,因此客户端出示的密钥绝不会与连接自身的凭据一同传输。在 https 下,网关会检查模型的证书是否链接到系统的信任锚并包含模型的主机名(无论客户端发送的是什么主机),否则不向模型发送任何内容:该 Recipe 会为所有连接均为 https 的每个别名的路由加上 Higress 的 higress.io/backend-protocol: HTTPS 注解,使网关从 AI 代理写入每个请求的主机名中获取服务器名称——即模型的主机名,若其不含点号则以模型的命名空间加以限定——并据此检查证书。该注解作用于一个别名的所有连接,因此混合 http 与 https 连接的别名会使构建中止,并指出两者;将它们放在两个别名下即可解决。连接到 model.aggrega.ai/api 不为 openai 的模型,或其端点指定的是地址而非主机名的连接,会使构建中止。它将其 values.model 所指定别名的路由发布为其 endpoint,并将该别名发布为其 model,且带有 model.aggrega.ai/api: openai,因此代理的 model 插槽会像接收 AI 网关一样接收它;未接入任何模型时,这两个键均发布为空。它不声明调用方,因此其模型路由不检查任何调用方的密钥,需要经网关验证的调用方的值会被按名拒绝。在下文的控制项中,它实现周期预算、审计日志和重试策略,均写入模型路由,并按下文“Data Exfiltration & Payload Interception”所述实现 core/data-masking。它对响应校验、回退链、语义缓存、提示注入筛查和目标选择的实现会使每次附加中止,并分别说明原因;提示拒绝模式和并发限制都不会附加到它,因为它不带有 dataplane.aggrega.ai/prompt-guard 或 dataplane.aggrega.ai/concurrency-cap 值。运行中的网关是否执行这些控制项,任何构建都无法观察到。

  • 模型前置 Azure API Management:core/gateway/azure-api-management 是托管服务 Azure API Management 的 AI 网关,它通过一个已存在的 API Management 实例上的 API 为一个模型 API 提供服务。它的 terraform Recipe 读取该实例,并添加该 API、其聊天补全操作、其转发目标后端以及该 API 的策略;该策略会从转发内容中移除调用方的订阅密钥,并按 infra.backend_authentication 的设定向模型 API 进行身份验证:使用实例的托管标识、使用保存在 Key Vault 中的提供方密钥,或不进行身份验证。它的 helm 和 compose Recipes 引用在该 Release 之外配置的 API,任何附加都会使构建中止。在下文的控制项中,它的 terraform Recipe 实现语义缓存、周期预算、提示注入筛查和重试策略,均写入该 API 的策略。它不实现并发限制,因为 Microsoft 表示其并发策略所执行的上限从来不完全准确,并且当一个区域中运行多个容量单元时会更低;它也不实现回退链,因为该 API 只转发到一个后端,而 Azure 自身的回退机制(后端池的优先级组)是将后续请求从断路器已跳闸的后端移走,而不是把失败的请求转发给另一个模型。它对 core/audit-logging 的实现会使每次附加中止,并指出其能力范围之外的内容:日志本身,需由实例上的诊断设置开启;启用 require_cost 时请求的成本,因为 Azure 的模型请求日志只记录 token 数和模型,不记录价格;以及给出 retention_days 时的保留期,因为一行记录的保留时长取决于它所写入的 Log Analytics 工作区。这些策略是否按 Microsoft 文档所述生效并执行,任何构建都无法观察到。

  • 调用方出示的密钥: 检查其调用方所出示密钥的服务器,将该密钥保存在它自己的一个槽位中,在每个进行检查的模型服务目标上该槽位名为 api_key——core/ai-model/vllm、tei 和 tgi、LiteLLM 模型,以及 AI 网关(在 AI 网关上它就是 LiteLLM 所称的 master key)——它的每个 Recipes 都将该密钥作为服务器读取的变量交付。core/gateway/apisix 和 core/gateway/agentgateway 各自在其 caller_keys 槽位中,为其 Release 在 infra.callers 中列出的每个调用方保存一个密钥:一个 Secret,以每个调用方的名称保存该调用方的密钥。core/gateway/traefik-hub 以相同方式保存其调用方,不同之处在于它的 Secret 保存的是每个调用方密钥的 htpasswd 哈希,其密钥检查将出示的密钥与之比较,因此它并不是调用方出示密钥所用的 Secret。调用方将它出示的密钥保存在自己一侧、出示该密钥的连接上、其 socket 声明的一个槽位中:标准库中的 agent 在其 model socket 上声明一个槽位 credential;AI 网关在其 models socket 和 cache_store socket 上声明,后者中它是网关的语义缓存向其存储出示的密码;core/gateway/kong 和 core/gateway/kong-enterprise 在其 models socket 上声明;core/gateway/apisix 在其 models socket 和 cache_store socket 上声明,后者中它同样是其语义缓存向其存储出示的密码;core/gateway/agentgateway 在其 models socket 上声明;core/gateway/envoy-gateway 在其 models socket 和 cache socket 上声明,后者中它是网关的限流服务向保存周期预算计数的存储出示的密码;core/gateway/higress 在其 models socket 和 cache socket 上声明,后者中它是其 token 限制向保存周期预算计数的存储出示的密码;core/gateway/traefik-hub 在其 models socket、cache socket(其中它是其配额向保存周期预算计数的存储出示的密码)以及 cache_store socket(其中它是其语义缓存向其存储出示的密码)上声明——因此,访问模型的 agent,或访问其所服务模型的网关,都在那里保存该连接的密钥。AI 网关、两个 Kong、APISIX 和 agentgateway 将每个已连接模型的密钥以各自的变量交付,该变量由其配置中该模型的条目或路由指明;Envoy Gateway 在模型后端的安全策略中指明该 Secret,Envoy AI Gateway 的控制器从中读取密钥;Traefik Hub 在模型路由的 Chat Completion 中间件中指明该 Secret 及数据键,并从中读取密钥。访问标记为 component.aggrega.ai/hosting: managed 的模型的连接要携带一个密钥,或在其自身的 values 中声明该模型不需要密钥,即 unauthenticated: true;两者都没有时,调用方的断言会使构建中止,并指明该连接及其目标;标记为其他值的模型不会引发此类中止。调用方的 Component 改为在自己的槽位中声明的密钥,是其建立的每个连接共用的一个密钥。两端都看不到对方的附件,因此服务器对调用方的密钥一无所知,两者之所以匹配,是因为 Aggregate 从同一个参数为两端提供值:两端在同一作用域(一个 Kubernetes 命名空间、一个 Compose 项目)中解析 secret 时,它们引用同一个 secret,否则各自保存自己的 secret,由同一存储条目实现。vLLM、TEI 和 TGI 各自只检查一个密钥,因此每个调用方出示相同的密钥,服务器无法区分其调用方,且 TGI 匹配密钥时不区分大小写;APISIX、agentgateway 和 Traefik Hub 各自检查每个已声明调用方的密钥,并据此区分调用方;两个 Kong 不声明调用方,也不检查任何调用方的密钥,原因见上文“Kong 位于模型前端”;LiteLLM 模型和 AI 网关在附加了其记账数据库时,还接受它们签发的密钥。Credential Model 在一个 Aggregate 中完整演示了这一结构。

  • 在目标之间选择:core/target-selection 声明网关如何在能够处理同一请求的多个目标之间进行选择,其 strategy 为 latency(观测到响应最快的目标)或 cost(调用成本最低的目标)。该策略是应用对其网关的要求的一部分,因此由开发者在 Aggregate 中附加。在 AI 网关上,这些目标是其 values.models 中发布同一别名的条目——已连接的模型以其连接的别名提供服务,其他条目不得发布该别名——标准库通过将代理的 latency-based-routing 写入网关的 Recipe 所渲染的路由配置来实现 latency:代理将每个请求发送到最近十次回复平均耗时最少的条目,若回复报告了令牌数则按每个输出令牌计算,流式请求则按到达首个令牌的时间计算,尚未尝试过的条目视为最快。未附加时,配置不指定策略,代理在这些条目中随机选择。cost 在此处会被按名称拒绝:代理按条目的目标原样在价格表中查找来定价,而该价格表列出的 OpenAI 和 Anthropic 模型不带网关目标所携带的 provider 前缀,且对查不到的条目使用固定的后备价格,因此共享同一别名的条目会被定为相同价格,并按其顺序被选中。在 core/gateway/kong-enterprise 上,每次附加都会中止,因为连接到它的每个模型都在各自独立的路由上提供服务,每条路由只承载该模型,因此没有可供选择的对象。在 core/gateway/agentgateway 上,每次附加同样会中止并说明原因:agentgateway 从一个模型名称的目标中随机抽取两个,取健康度除以响应耗时得分更高的那个,因此只有在最快的目标被抽中时才会选用它,而且它不按成本选择目标。在 core/gateway/higress 上,每次附加同样会中止并说明原因:Higress 能够测量服务的延迟,但其负载均衡插件在 AI 代理之后运行——此时 AI 代理已为路由解析出的候选目标设置了请求的模型、地址和凭据——并将其选择写入一个请求头,而若没有本目录不渲染的 Envoy 过滤器,就没有任何路由依据该请求头,因此该选择不会生效,而且它不按成本选择目标。在 core/gateway/traefik-hub 上,每次附加同样会中止并说明原因:Traefik 仅在一个 Service 的服务器之间按最低响应时间选择,而一个 Service 只覆盖一个模型名称和一个凭据;在 Service 之间则按权重或客户端地址的哈希进行均衡,从不按延迟,它的任何策略都不按成本选择目标;并且连接到该网关的每个模型都在各自独立的路由上提供服务,每条路由只承载该模型,因此没有可供选择的对象。在任何其他网关上,附加会中止构建。

  • 弹性: core/fallback-chain 将模型调用失败的请求转交给其他模型:chains 为每个需要回退的模型别名列出依次尝试的别名,直到其中一个应答为止;失败的回退项会继续沿用它自己的条目,max_hops 限定请求沿该链可传递的距离。标准库在 AI 网关上实现它的方式,是将这两项写入网关的 Recipe 所渲染的路由配置;遇到网关模型映射未发布的名称时,构建会中止。只有当网关放弃了请求所指定的别名后,请求才会回退:若某个别名被发布了多次,失败的调用会先作为重试转到该别名的另一个条目,重试次数受网关重试计数限制。core/retry-policy 设置该计数——对于再次发送即可能成功的失败(如连接被拒绝、触发速率限制或超时),网关可发送请求的次数,包括首次发送(max_attempts)——标准库在 AI 网关上将其写入网关的 Recipe 所渲染的路由配置来实现它。在 core/gateway/envoy-gateway 上,它实现为服务已连接模型的路由上流量策略的重试,与承载周期预算速率限制的是同一个策略,因为 Envoy Gateway 对一条路由只附加一个流量策略:在连接或流被拒绝、被重置,或收到 429、503 或 504 应答后,请求会再次发送,最多发送 max_attempts 次;在路由的请求超时内毫无应答的模型不会被再次发送,因为该超时涵盖所有发送。在 core/gateway/azure-api-management 上,它实现为 Azure 在转发外层的重试,位于 API 策略的 backend 部分:收到 HTTP 429 或 5xx 状态应答的请求会被再次发送,其请求体会被保留以便重发,在上一次发送后一秒重发,最多发送 max_attempts 次。连接被拒绝或断开,以及在转发超时内毫无应答的模型,不会被再次发送,因为 Azure 遇到此类错误会结束重试,并将其交给策略的 on-error 部分。Azure 在首次发送后可重试 1 到 50 次,因此 max_attempts 为 1 时不写入重试,大于 51 时按名称拒绝。该重试会取代 API 原本继承的转发,因此附加期间,在实例更宽范围上设置的转发配置(如超时)不适用于该 API,API 将以 Azure 的默认值转发。在托管网关上,core/retry-policy 通过向网关资源写入其重试计数来实现,该计数指首次之后的发送次数,范围为 1 到 5,因此 max_attempts 为 2 到 6 时会被采纳,其他值会被拒绝;core/fallback-chain 在那里不实现,因为该网关只在请求以路由代替模型指定时才在模型之间回退,所以指定模型的请求永远不会回退。在 core/gateway/kong-enterprise 上,core/fallback-chain 在其 chart Recipe 上实现:chains 为其提供条目的每个别名,其 chat 和 completion 路由用 Kong 的 AI Proxy Advanced 代替其 AI proxy,以该别名的模型及其回退路径上的模型作为按优先级排列的目标——先是该别名,然后依次是其条目的回退项,仅当计数少于 max_hops 时才继续沿用回退项自己的条目。均衡器按顺序向路径上的每个目标各发送一次请求,直到其中一个应答为止;遇到连接错误或超时、无效的应答头,或 429、500、502、503 或 504 应答时转向下一个,其他应答则原样返回。以下情况构建会中止:models socket 未承载的名称、路径两次到达同一别名、与 core/retry-policy 同时附加(因为 Kong 对整条路径只保留一个重试计数,无法在回退前再次发送给同一模型),以及早于 3.12 的网关镜像。core/retry-policy 在那里不实现,其实现会中止每个附加并说明原因:每个已连接模型都在仅承载该模型的专属路由上提供服务,因此重试必须再次将请求发送给同一目标,而 Kong 的参考文档对其均衡器是否这样做两种解读皆可。在 core/gateway/agentgateway 上,core/retry-policy 在 chart Recipe 上实现为网关自身配置中的重试策略,附加到模型请求到达的监听器上:在收到 429、500、502、503 或 504 应答、连接被拒绝或重置、连接建立超过 11 秒或名称解析失败后,请求会立即再次发送给同一模型,最多发送 max_attempts 次。agentgateway 发送请求的次数比其策略的尝试次数多一次,因此策略写为 max_attempts 减一,max_attempts 为 1 时不写入,大于 256 时按名称拒绝。请求体大于 64 KiB 的请求只发送一次,且配置未设置超时,因此接受连接却毫无应答的模型会被一直等待,而不会被再次发送。core/fallback-chain 在那里不实现,其实现会中止每个附加并说明原因:agentgateway 在模型之间故障转移的方式是为后续请求剔除失败的模型,而失败的那个请求会以其失败作答,因此没有请求会沿链传递。在 core/gateway/higress 上,core/retry-policy 实现为路由自身的重试,以 Ingress 注解写入每条模型路由:在连接被拒绝或重置、收到 5xx 应答或 429 后,请求会再次发送(包括 POST),最多发送 max_attempts 次;max_attempts 为 1 时关闭重试,覆盖 Higress 控制平面为未带注解的路由提供的重试,大于 2147483648 时按名称拒绝。接受连接后毫无应答或应答缓慢的模型不会被再次发送,因为路由未设置每次尝试的截止时间;流式请求仅在其应答开始之前才会被再次发送。core/fallback-chain 在那里同样不实现,其实现会中止每个附加并说明原因:Higress 最多只将失败的请求转交一次,且只交给另一个目的地——路由的默认后端,或其控制台为 AI 路由写入的唯一回退路由——因此没有请求会沿链传递。在 core/gateway/traefik-hub 上,两者都在 chart Recipe 上实现,并且在 Traefik Hub 镜像早于 v3.20 时各自中止构建,因为这些版本的故障转移不接受其所尝试服务上的中间件,其重试也无法根据应答状态再次发送 POST——只发送一次的重试策略除外。core/fallback-chain 将 chains 为其提供条目的每个别名的路由送入 Traefik 自身的嵌套故障转移,依次尝试该别名路径上的模型——先是该别名,然后依次是其条目的回退项,仅当计数少于 max_hops 时才继续沿用回退项自己的条目——每个模型都有自己的模型名称、凭据、配额和重试。模型在其自身的任何重试之后应答 429 或 500 到 504 时,请求会转到下一个;其他应答原样返回,最后一个模型的应答无论是什么都会返回,请求体超过 1 MiB 的请求会以 HTTP 413 拒绝而不发送。以下情况构建会中止:models socket 未承载的名称,以及路径两次到达同一别名。core/retry-policy 是 Traefik 的重试中间件,位于每条模型路由的最后,或位于路径所尝试的每个模型上:在连接未向模型传送任何内容后,以及在收到 429 或 500 到 504 应答后,请求会立即再次发送(包括 POST),最多发送 max_attempts 次(包括首次),max_attempts 为 1 时不写入任何内容。网关自己形成的应答——其密钥检查的拒绝、守卫、脱敏或配额——永远不会被再次发送,已开始的流式应答也不会。

  • 周期预算:core/period-budget 限定经过某个网关的流量在一个周期内可以消耗的量:一个 limit、它覆盖的 period、一个 scope(网关服务的全部流量、每个调用方或每个模型)以及一个 unit(以美元计的费用或 token);一旦网关在该周期内的计数超过限额,后续的模型请求即被拒绝。它可以附加到任何声明了 dataplane.aggrega.ai/period-budget 的组件。标准库在 AI 网关上实现它,该网关的预算覆盖网关服务的全部流量,以美元计数,并在每个周期开始时重新计数(周期为从 UTC 午夜起算的若干天,或从当月第一天起算的一个日历月):该实现将限额和周期写入网关的 Recipe 渲染的配置,按名称拒绝任何其他单位、范围或周期(其中包括 30d,网关会将其按日历月计数),并且除非网关的 database_url 和 api_key 凭据槽都已附加,否则会停止构建,因为没有记账数据库,网关就不保留计数;没有管理密钥,网关就不会按预算检查任何调用方。一旦计数超过限额,网关既拒绝每个调用方的模型请求,也拒绝管理密钥的模型请求;但其模型列表和密钥管理仍会响应该密钥。在托管网关上,它实现为网关资源上的一条支出限额规则,以美元计数,计数窗口随时间向前移动(最近一个 period,仅针对网关知道定价的模型),覆盖网关服务的全部流量:按调用方或按模型的预算、token 以及日历月都会被按名称拒绝。在 core/gateway/apisix 上,它在 chart Recipe 上实现,作为 APISIX 的 token 限流写入所连接模型的路由:按每个模型回复报告的 token(total_tokens、prompt_tokens 或 completion_tokens)计数,窗口为固定的 period,在上一个窗口关闭后的第一个模型请求到来时开启,而不是按时钟开启;计数范围可以是网关服务的全部流量、每个所连接的模型分别计数,或其 Release 在 infra.callers 中声明的每个调用方分别计数,网关按各调用方出示的密钥区分它们。一旦计数达到限额,网关在窗口关闭之前以 HTTP 503 响应模型请求;请求的 token 在其回复完成后才累加,因此达到限额的那个请求仍会得到服务,而由语义缓存提供的回复不计数,并且在超过限额后仍会提供。APISIX 不对 completion 请求计数 token,因此在附加预算期间,每个所连接的模型只获得其 chat 路由;APISIX 把计数保存在网关进程的内存中,因此 chart 只运行一个副本,重启会开启一个新窗口。以美元计的预算、在 infra.callers 未声明任何调用方时按调用方的预算、日历月以及同一网关上的第二个预算都会被按名称拒绝,附加到其 workload Recipe 上同样会被拒绝,因为该 Recipe 不渲染任何路由。在 core/gateway/envoy-gateway 上,它实现为 Envoy Gateway 基于用量的限流,作用于服务所连接模型的 AI 路由:该路由将 unit 指定的 token 计数(total_tokens、prompt_tokens 或 completion_tokens)声明为 Envoy AI Gateway 从每个回复中读取的成本,该路由上的流量策略在回复完成时扣除该成本,额度为每个 Envoy Gateway 限流单位 limit 个 token,范围是网关服务的全部流量或每个所连接的模型分别计数。每个窗口按 UTC 时钟固定:一秒、一分钟、一小时、从午夜起的一天、从星期四起的一周,或从 1970 年 1 月 1 日起算的 30 天或 365 天;1mo 是一个日历月,这依赖 Envoy Gateway 限流服务的一项设置,该设置随后对该安装保留的每个按月限流都生效。计数由 Envoy Gateway 控制平面为其服务的每个网关创建并开启的限流服务保存,存放在连接到网关 cache 插槽的 Redis 协议存储中。一旦计数超过限额,网关在窗口结束之前以 HTTP 429 响应模型请求;请求的 token 在其回复完成后才累加,因此越过限额的那个请求仍会得到服务。当存储或限流服务无法访问,或某次检查耗时超过 Envoy 的限流超时时,模型请求会以 HTTP 500 被拒绝,这依赖 Envoy Gateway 控制平面的一项设置,该设置随后对该安装保留的每个限流都生效,因此手动施加的限流同样会失败即关闭;在故障前刚被放行的请求仍会得到服务且不计数,因为其 token 在回复之后才扣除,而把计数保存在内存中的存储在重启时会重新开始每个窗口。以美元计的预算、按调用方的预算(网关只能通过调用方自行写入的请求头区分调用方,而该路径上没有任何东西验证它)、任何其他周期以及同一网关上的第二个预算都会被按名称拒绝,models 或 cache 插槽未连接任何东西的附加同样会被拒绝。在 core/gateway/azure-api-management 上,它实现为 Azure 的 token 限制,写入 API 的策略:按每个回复报告的 prompt 和 completion token 合计计数,范围是 API 服务的全部流量或每个 API Management 订阅(网关会验证其密钥);形式为按 UTC 时钟固定窗口的配额,即一小时、一天、一周、一个日历月或一个日历年(1h、1d、7d、1mo 或 12mo;Microsoft 未说明一周从哪一天开始),超出后以 HTTP 403 响应;或为一分钟(1m)内的速率,以 HTTP 429 响应,在经典层级上按滑动窗口计数,在 v2 层级上按令牌桶计数。计数依据每个回复报告的用量,因此并发请求可能越过限额,并且实例的每个网关各自保留计数。以美元计或仅以 prompt 或 completion token 计的预算、按模型的预算(请求指定的模型由调用方写入,且多个名称可以指向同一个模型)、在不要求订阅密钥的 API 上按订阅的预算、任何其他周期以及非整数的限额都会被按名称拒绝。Consumption 层级不运行 token 限制。在 core/gateway/kong-enterprise 上,它在 chart Recipe 上实现,作为 Kong 的 AI Rate Limiting Advanced 写入网关导入的路由:按每个模型回复报告的 token(total_tokens、prompt_tokens 或 completion_tokens)计数,窗口为固定的 period(若干秒、分钟、小时或天),每个请求计入其时间所在的那个窗口,范围是网关服务的全部流量或每个所连接的模型分别计数;在范围 model 下,请求计入它所指定的别名,而不论实际由哪个模型响应。一旦计数达到限额,下一个模型请求在窗口结束之前以 HTTP 429 响应,因此越过限额的那个请求仍会得到服务;Kong 也可以根据自己对请求所携带 prompt token 的估算提前拒绝请求。计数保存在网关的 PostgreSQL 后端中,由所有副本共享,并在重启后保留。以美元计的预算(Kong 只能根据其配置为每个模型给出的价格计算费用,而目录不提供任何价格)、按调用方的预算(Kong 只能把调用方区分为身份验证插件所指定的 consumer,而网关不声明任何调用方,原因见上文“Kong in front of models”)、日历月、同一网关上的第二个预算以及早于 3.15 的网关镜像都会被按名称拒绝,models 插槽未连接任何东西的附加同样会被拒绝。在 core/gateway/agentgateway 上,它在 chart Recipe 上实现,写入网关的配置,按每个回复报告的总 token 数计数:在范围 caller 下,作为其 Release 在 infra.callers 中声明的每个调用方的 API 密钥上的预算,窗口为与 Unix 纪元对齐的固定 period,一天从 UTC 午夜开始,保存在 Recipe 渲染的卷上的 SQLite 存储中,只运行一个副本;在范围 gateway 或 model 下,作为令牌桶,覆盖网关服务的全部流量或请求所要求的每个模型名称,从网关读取其配置时起每个 period 填满至限额,并保存在其内存中,因此重启或配置变更会重新填满。一旦计数达到限额,模型请求在窗口结束或令牌桶被填满之前以 HTTP 429 响应;达到限额的那个请求仍会得到服务。以美元计的预算(网关的模型成本目录没有为所连接的任何模型定价,因此预算不会计入任何东西)、仅以 prompt 或 completion token 计的预算、在 infra.callers 未声明任何调用方时按调用方的预算、日历月、非整数的限额以及同一网关上的第二个预算都会被按名称拒绝,models 插槽未连接任何东西的附加同样会被拒绝;其 compose Recipe 没有它的实现。在 core/gateway/traefik-hub 上,它在 chart Recipe 上实现为每个所连接模型路由上的 Traefik Hub 配额中间件,计数保存在连接到网关 cache 插槽的 Redis 协议存储中:它按每个回复报告的 token(total_tokens、prompt_tokens 或 completion_tokens)计数,或在 usd 下按其美元费用计数,价格取自该中间件自带的模型列表,没有价格的模型会以 HTTP 422 被拒绝;窗口随时间滑动,某一时刻计入的量在一个周期后重新释放;范围是每个所连接的模型分别计数,或在只连接一个模型时覆盖网关服务的全部流量。一旦计数达到限额,模型请求以 HTTP 429 被拒绝;请求的计数在其回复完成后才累加,因此越过限额的那个请求以及与之同时提供的任何请求都会得到服务,而由语义缓存提供的回复不计数。Traefik 的参考文档称,存储无法访问时,配额会放行请求而不计数。按调用方的预算(配额按客户端地址、请求头或请求的主机区分请求,而这些都不是网关密钥检查所验证的调用方)、连接了多个模型时覆盖整个网关的预算(因为 Traefik 的参考文档未说明指定同一配额的路由是否共享计数)、日历月以及除小时、天或构成整小时的分钟或秒以外的任何周期都会被按名称拒绝,非整数 token 的限额以及 models 或 cache 插槽未连接任何东西的附加同样会被拒绝。在 core/gateway/higress 上,它在 chart Recipe 上实现为每个所连接模型路由上的 Higress token 限制插件,计数保存在连接到网关 cache 插槽的 Redis 协议存储中:它在回复完成后合计每个回复报告的 prompt 和 completion token,窗口为固定的 period(一秒、一分钟、一小时或一天),在窗口内第一个回复被计数时开启,范围是网关服务的全部流量或每个别名分别计数。当计数超过限额时,模型请求在窗口结束之前以 HTTP 429 响应,因此越过限额的那个请求仍会得到服务。未报告用量的回复不计数,因此 Recipe 会要求流式请求的模型报告其用量,并以 HTTP 403 拒绝关闭该报告的流式请求、内容类型既不包含 application/json 也不以 multipart/form-data 开头的请求(AI 代理会转发此类请求而不要求报告),以及网关插件不读取其请求体的请求(压缩的请求体、包含 octet-stream 或 grpc 的内容类型、协议升级);客户端故意发送网关校验无法解码的请求体即可绕过这些拒绝,这样的流式请求不会被计数。在未附加脱敏时,请求体超过网关 32 KiB 缓冲区的请求可能会以 HTTP 413 被拒绝,取决于存储何时响应。存储无法访问时,模型请求会得到服务且不计数:该插件没有在这种情况下拒绝请求的设置。以美元计或仅以 prompt 或 completion token 计的预算、按调用方的预算(网关不声明任何调用方,因此不验证任何调用方)、任何其他周期、非整数的限额以及同一网关上的第二个预算都会被按名称拒绝,models 或 cache 插槽未连接任何东西的附加同样会被拒绝。

  • 并发:core/concurrency-limit 限制网关同时承载的请求数(max_in_flight),以防一批突发的调用方在其后端模型处形成队列。scope 说明一个上限计数的对象:默认值 gateway 将网关转发的所有请求合并计数;model 为网关发送请求的每个目标单独计数,目标是网关路由到的每个上游条目,因此当一个模型名称有多个条目时,每个条目分别计数。上限及其范围属于运维人员决定的容量规划,在附加的 infra 中设置,因此由运维人员在 Release 中附加它。上限按每个运行中的代理计数,因此运行多个副本时,每个副本都会放行这么多请求。它可以附加到任何声明了 dataplane.aggrega.ai/concurrency-cap 的组件,实现会按名称拒绝其网关不计数的范围。在 core/gateway/nginx 上,范围 gateway 实现为 NGINX 的 limit_conn,以对每个请求都相同的一个词为键,因此 NGINX 将其正在处理的所有请求计为一个总数,保存在其工作进程共享的内存中,并以 HTTP 503 响应超过上限的请求;范围 model 会被拒绝,因为 NGINX 不为每个上游目标保留计数,大于 65535(limit_conn 接受的最大值)的 max_in_flight 同样会被拒绝。在 core/gateway/envoy-gateway 上,范围 model 实现为服务所连接模型的路由上流量策略的熔断器,该策略同时承载周期预算的限流和重试策略的重试:Envoy Gateway 将其应用于该路由每条规则的后端,而每个所连接的模型都有自己的规则,因此同时发送到每个所连接模型的请求至多为 max_in_flight 个,超过上限的请求以 HTTP 503 响应且不会重发;重试策略重复的发送与首次发送一样计入上限。Envoy 的工作线程先检查计数再累加,因此同时到达的请求可能使计数短暂超过上限。范围 gateway 会被拒绝,因为 Envoy Gateway 为每个后端保留上限,而不对其总数设上限,models 插槽未连接任何东西的附加同样会被拒绝。在 AI 网关上,范围 model 实现为其模型映射中每个条目(无论是手动输入的还是连接的)的 max_parallel_requests:同时发往每个条目的请求至多为 max_in_flight 个,发现其条目已满的请求以 HTTP 429 响应(若其别名只有一个条目,则在网关重试之后;若有多个条目,则立即响应,即使其中另一个条目仍有余量,因为代理先选择条目再计数),除非 core/fallback-chain 为其别名列出了回退项,此时请求会被转发到回退项。代理将每个计数保存在内存中,默认情况下一条记录在创建十分钟后失效,随后新计数从零开始,因此该附加还会把这一有效期设为一个世纪,使每个计数在代理运行期间一直保留。由于这一有效期,附加上限期间网关会拒绝携带 priority 的请求,即使 Release 允许该字段,因为代理会为每个此类请求保留一个队列条目,直到其记录失效;并且模型映射超过 100 个条目时构建会停止,超过这个数量后,保存计数的存储(容纳 200 条记录,存满时会丢弃一条)可能丢弃某个计数。范围 gateway 在此会被拒绝,因为代理的总数只由一个通过环境变量开启的请求限制器读取,而该限制器只在请求的第一秒内计数。托管网关也不实现它:其 terraform Recipe 写入网关资源的请求限制是一个速率,即一段时间间隔内的请求数,而不是对进行中请求的上限。

  • 审计日志:core/audit-logging 让网关为它所服务的每个模型请求保留一条记录,写明作答的模型以及回复所报告的 token 数,每种实现各自说明记录落在何处。它可挂接到任何带有 gateway.aggrega.ai/intelligence: semantic 的组件上,它的三个值属于运维人员,在其 infra 中设置,因此由运维人员在 Release 中挂接它。require_cost 默认开启,让记录同时写明每个请求的费用,币种由实现指定。require_verified_caller 默认开启,让记录写明网关验证过的调用方,即网关签发或校验过的密钥。retention_days 默认不设置,让网关在记录达到该天数时将其删除;不设置时网关自身不删除任何记录,记录的保留时长取决于其落地之处保留它多久。无法满足某个值的网关会在构建时拒绝该挂接,并指明该值,因此将 require_cost 和 require_verified_caller 保持默认的挂接,要么得到费用和经验证的调用方,要么构建中止。关闭 require_verified_caller 即接受调用方为请求自身所声称的任何值、或根本没有调用方的记录:任何发送请求的人都可以让请求记在另一个调用方名下,因此这样的记录并不能说明请求是谁发送的。在 AI 网关上,记录是网关记账数据库中的一行,每个值都会被满足:该行写明请求以美元计的费用,按网关为每个模型维护的价格表计价——价格表未定价的模型记为零费用——并写明网关验证过的密钥,以及该密钥所属的用户和团队,而行中写明的最终用户是请求自己写入的任意值,不经校验。没有记账数据库时网关不写任何行;没有管理密钥时网关不校验任何调用方,对既未出示密钥也未写明最终用户的请求不写行,因此除非网关的 database_url 和 api_key 凭据槽都已挂接,否则构建中止;当网关的 values.log_masking 列出了要掩码的内容时,它只记录已作答的请求。在 core/gateway/envoy-gateway 上,记录是网关访问日志中的一行,由其 Recipe 在挂接存在时写入:每个请求在数据平面的标准输出上一行 JSON,包含 Envoy Gateway 默认写出的字段、请求指定的模型、作答的模型,以及回复所报告的提示、补全和总 token 数,服务这些模型的路由声明了这些计数,以便 Envoy AI Gateway 记录它们。模型未作答的请求不含作答模型和 token 数,而访问日志自身不保留任何内容,因此一行日志保留多久取决于收集该输出的系统。没有字段写明网关验证过的调用方:客户端地址和它发送的请求头按原样写入。网关不维护价格,其 Recipe 渲染的路由上没有任何东西验证调用方,访问日志也不保留可供删除的记录,因此其实现只构建关闭了 require_cost 和 require_verified_caller 且未给出 retention_days 的挂接,否则中止,并在同一次失败中指明每个无法满足的值;models 插槽上没有任何连接时它同样中止。在 core/gateway/agentgateway 上,记录是网关写入 SQLite 存储的一行,该存储位于其 chart Recipe 在挂接存在时渲染的卷上,且只有一个副本;每个通过其密钥、预算和授权检查的模型请求(包括被防护规则拒绝的请求)各写一行:网关向模型服务器请求的模型——即所连接模型发布的名称,而非调用方发送的别名——和作答的模型、回复所报告的输入、输出和总 token 数、其状态和耗时,以及对其 Release 在 infra.callers 中声明的每个调用方,取自网关所验证 API 密钥的该调用方名称。因密钥、授权规则或调用方预算而被拒绝的请求不留下任何行。不保留任何提示或回复文本,这些行通过网关的管理接口读取,该接口在其 pod 内监听。声明了调用方时 require_verified_caller 会被满足;require_cost 会被按名称拒绝,因为网关的模型费用目录不为连接到它的任何模型定价,未声明调用方时的 require_verified_caller 以及 retention_days 同样会被拒绝,因为网关不删除任何记录;其 compose Recipe 不提供它的实现。在 core/gateway/higress 上,记录是网关访问日志行中的 ai_log 字段,由 Higress 的统计插件在挂接存在时填写:作答的模型以及回复所报告的输入、输出和总 token 数,输出到网关的标准输出,不含提示或回复文本。该网关不声明调用方、不定价,也不保留可供删除的记录,因此其实现只构建关闭了 require_cost 和 require_verified_caller 且未给出 retention_days 的挂接,否则中止,并在同一次失败中指明每个无法满足的值;models 插槽上没有任何连接时它同样中止。在 core/gateway/traefik-hub 上,每个挂接都会中止并说明原因:Traefik Hub 只以其 AI 中间件导出到追踪后端的 OpenTelemetry span 的形式记录模型请求——写明模型,并在其详细级别下写明 token 数及其美元费用——而其实现不连接任何追踪后端,因此记录将无处落地;span 也不写明调用方,因此无法写明网关密钥检查所验证的调用方。在 core/gateway/azure-api-management 上,正如上文该网关的条目所述,每个挂接都会中止,标准库中也没有其他网关实现它,因此任何其他网关上的挂接都会中止并指明该类型。

  • 语义缓存:core/semantic-caching 声明一个缓存:对于某个提示,如果先前有一个在语义上足够接近的提示,就用为它存储的回复作答,而不再调用模型。embedding_model 指定把每个提示转换为向量的模型,名称与网关发布的一致;两个提示的相似度至少达到 similarity_threshold 时提供已存储的回复,该回复在 ttl_seconds 内保持可用。scope 决定谁共享一个缓存:默认值 end_user 将网关识别出的每个终端用户彼此隔开,而 key 让出示同一个密钥的所有调用方共用一个缓存,因此该密钥背后的某个终端用户可能收到为另一个终端用户生成的回复。core/data-masking 声明与它冲突,因此同时带有两者的组件会使构建中止。标准库在 AI 网关上实现它:网关把回复保存在连接到其 cache_store 插槽的 core/datastore/redis 中,在存储要求密码时向其出示该连接上凭据所持有的密码,存储在 ttl_seconds 过后删除每条回复;网关缓存 chat、responses 和 messages 请求,不缓存 completions 或 embeddings 请求。在以下情况下该实现会使构建中止:网关的 api_key 插槽未挂接,因为没有管理密钥时网关不检查任何调用方;embedding_model 不在网关模型映射所发布的模型中;以及 cache_store 上未连接任何内容。已存储的回复只提供给与其存储依据相匹配的请求:请求出示的密钥(由网关验证)及该密钥的团队和组织;在 end_user 下,还包括请求指明的终端用户;以及请求所要求的模型及其其他参数。网关把密钥、团队、组织和终端用户写入请求本身,在 chat 请求上覆盖调用方为它们发送的任何值;在 responses 或 messages 请求上,它从请求自身的元数据中删除团队、组织或终端用户字段,并拒绝在其中指明密钥的请求,因此任何请求都无法通过指明名称进入另一个密钥的回复。请求自身的元数据仍可使其在所出示密钥的回复之间移动:在 responses 请求上,model_group 在其回复的存储依据中替换所要求的模型;在 responses 或 messages 请求上,caching_groups 让指明同一组模型别名的请求跨这些别名共享回复;在 responses 或 chat 请求上,redis_namespace 将指明某个命名空间的请求与未指明命名空间的请求隔开。网关从请求自己指定的请求头或请求体字段中读取终端用户,且不验证其中任何一个:在 end_user 下,指明另一个终端用户的调用方会收到该终端用户的回复,而未指明终端用户的请求与其所出示密钥下所有其他此类请求共享一个缓存。托管网关不实现它:其缓存只回答与先前请求完全相同的请求。在 core/gateway/azure-api-management 上,它实现为 Azure 的语义缓存查找与存储,写入 API 的策略中:embedding_model 指定 API Management 实例已持有的、用于嵌入模型的后端,实例通过其托管标识访问该后端;实例还需要一个配置了 RediSearch 的 Redis 缓存作为其外部缓存,这两者构建都无法看到,因此在运维人员通过设置网关的 infra.cache_serves_vector_search 确认缓存提供 RediSearch 之前,构建会中止;存储将回复保留 ttl_seconds;similarity_threshold 写为 Azure 的分数阈值,即 1 减去该阈值,并将该分数理解为余弦距离,因为 Microsoft 给出了其范围和方向(越低要求提示越接近),但未给出其度量方式。回复按 API 以及按 API Management 订阅分别存储和提供,订阅的密钥由网关验证,因此该实现保留 key,在不要求订阅密钥的 API 上拒绝它,并拒绝 end_user:其 Recipe 渲染的 API 不验证任何终端用户的令牌,因此网关没有可供隔离的已验证终端用户。core/gateway/contour 和 core/gateway/nginx 也不实现它,因为它们不提供语义缓存。在 core/gateway/agentgateway 上,其实现会中止每个挂接并说明原因:agentgateway 不缓存回复,其提示缓存只标记自身缓存提示的提供方可以在何处这样做。在 core/gateway/kong-enterprise 上,其实现会中止每个挂接,并指明所请求的 scope:Kong 的 AI Semantic Cache 没有能将一个调用方存储的回复与另一个调用方隔开的设置,而网关只能按身份验证插件所指明的 consumer 区分调用方,且出于上文“Kong in front of models”所述原因不声明任何调用方,因此无论在 end_user 还是 key 下,所有请求都会共享一个缓存。在 core/gateway/higress 上,其实现会中止每个挂接,并指明所请求的 scope:Higress 的语义缓存把每条回复存储在一个键前缀加提示文本组成的键下,该键中没有任何部分指明调用方或终端用户,而网关不声明任何调用方,因此所有请求都会共享一个缓存。在 core/gateway/apisix 上,它在 chart Recipe 上实现,作为 APISIX 3.18.0 的语义缓存写入每个已连接模型的 chat 路由,面向其 Release 在 infra.callers 中声明的调用方:回复按路由和按调用方存储,依据调用方出示并由网关验证的密钥,因此任何调用方都不会收到为另一个调用方存储的回复;该实现保留 key 并按名称拒绝 end_user,因为网关无法区分同一个密钥背后的终端用户。embedding_model 指定网关 models 插槽上的一个连接,缓存使用其端点、模型和凭据进行嵌入。缓存对请求的最后一条用户消息进行嵌入,并在某条已存储回复的消息相似度至少为 similarity_threshold 且其先前消息(系统提示、先前轮次)相同时提供该回复。回复在连接到网关 cache_store 插槽的 core/datastore/redis 中保存 ttl_seconds,缓存向其出示该连接上凭据所持有的密码;按语义提供的回复会以该请求为依据再存储 ttl_seconds。completion 请求不缓存,存储或嵌入失败视为未命中:请求仍会得到回答。在以下情况下该实现会中止:未声明任何调用方;cache_store 或 models 插槽上未连接任何内容;以及 embedding_model 不是那里的任何连接所承载的。APISIX 按路由和调用方而非按网关为已存储回复建立键,因此连接到同一存储的两个 APISIX 网关,或同一 Aggregate 的两个 Releases 将其网关指向同一个外部存储时,可能把缓存的回复提供给同一别名和模型上同名的调用方。其 workload Recipe 使用 APISIX 3.17.0,完全不带语义缓存。在 core/gateway/traefik-hub 上,它在 chart Recipe 上实现为每个已连接模型路由上的 Traefik Hub 语义缓存,面向其 Release 在 infra.callers 中声明的调用方:回复按已连接模型和按调用方存储,依据网关密钥检查所验证的调用方,各自使用自己的密钥,因此任何调用方都不会收到为另一个调用方存储的回复;该实现保留 key 并按名称拒绝 end_user,因为网关无法区分同一个密钥背后的终端用户。embedding_model 指定网关 models 插槽上的一个连接,缓存使用其端点、模型和凭据对请求文本进行嵌入。similarity_threshold 写为缓存的距离上限,即 1 减去该阈值,并理解为余弦距离,因为 Traefik 的参考文档给出了该上限的方向,但未给出其度量方式。回复在连接到网关 cache_store 插槽的 core/datastore/redis 中保存 ttl_seconds,过大而无法嵌入的请求不经缓存直接回答。在以下情况下该实现会中止:未声明任何调用方;cache_store 或 models 插槽上未连接任何内容;embedding_model 不是那里的任何连接所承载的;以及 Traefik Hub 镜像的标签所指的版本既不是 3.19 中 v3.19.11 及以后的版本,也不是 v3.20.6 及以后的版本,因为更早的版本让一个路由的所有调用方共享一个缓存。

  • 提示注入筛查: core/prompt-injection-shield 声明:网关转发的模型请求在调用模型之前会接受检查,查看其中是否有试图覆盖模型所获指令的企图,检查的 sensitivity 为 standard 或 strict,strict 会拒绝更多此类企图,同时也会拒绝更多合法请求。该检查是一个概率分类器的判定:它会漏掉部分攻击(其中包括改写、编码或换拼写的攻击),会拒绝部分合法请求,并且已知可被规避,因此它只是与其他控制措施并列的一种控制,并且不评判模型的回复、工具调用参数或图像。它可附加到任何网关,其实现要么将网关的请求发送经过连接到其 guard 插槽的守卫(这对网关的唯一要求是它能转发到所配置的地址),要么开启网关自身运行的检查。经由守卫时,守卫检查每个请求,并将其放行的请求转发给模型;在该插槽上没有任何连接时附加该 Feature,构建会停止并指出该插槽。标准库在 AI 网关和 NGINX 网关上实现它,两者都以 core/security/nemo-guardrails 作为守卫:这是一个使用 OpenAI chat-completions API 的服务,其 rail 将请求中最新的用户消息发送给连接到它的 core/security/trustyai-huggingface-detector 的分类器,并在该分类器的分数达到守卫阈值时拒绝请求。被拒绝的请求由守卫自己以一个普通的 completion 作答,其任何内容都不会到达模型;守卫或其检测器无法访问时,请求同样被拒绝。这两者都会停止构建,除非守卫正是该守卫,且运行该灵敏度所对应的阈值:standard 为 0.5,strict 为 0.001,这两个值是针对检测器默认分类器测得的;网关只看得到守卫而看不到其后的检测器,因此无法检查其模型。在 AI 网关上,模型映射的每个别名都发送到守卫,每个目标写作 openai/<model>,因此该映射是手工填写的映射:连接到网关 models 插槽的模型会以其自身连接的凭据发送到它自己的端点,绕过守卫,因此只要该插槽上有连接,实现就会停止构建并指出该连接。AI 网关拒绝除 chat completion 以外的所有请求,chat completion 是守卫唯一检查的类型;在 NGINX 网关上,其唯一的 location 转发到守卫而非上游,而守卫不响应其他模型路由。在 core/gateway/azure-api-management 上,它实现为 Azure 自身的 prompt shield,通过 infra.content_safety_backend_id 所指定实例的 Azure AI Content Safety 后端在 API 的策略中开启;该键未设置时构建会停止:Azure AI Content Safety 在调用模型之前、在语义缓存查找之前检查每个请求中是否有用户攻击,网关对检测到的请求以 HTTP 403 作答,与它对超出该服务可接受长度的请求的作答方式相同。该 shield 只有开和关两种状态,因此保留 standard,并按名称拒绝 strict;它以 Microsoft 自身的灵敏度运行,未依照守卫上 standard 所对应的阈值进行测量。实例以其托管标识访问该后端,该标识需要该服务上的 Cognitive Services User 角色;这两者构建都看不到。标准库中除这三个网关外,没有其他网关实现它,将它附加到其他网关会停止构建并指出该类型:大多数网关不渲染可让实现经由守卫转发的路由,它们将路由保存在自己的存储中、从其后的服务获取路由,或者是标准库不会在其上开启此类检查的托管服务;而 core/gateway/apisix(其 chart Recipe 渲染连接到它的模型的路由)和 core/gateway/envoy-gateway(其 Recipe 渲染连接到它的模型的 AI 路由)没有它的实现。在 core/gateway/agentgateway 上(其 Recipes 为连接到它的每个模型渲染一个条目),实现会停止每一次附加并说明原因:agentgateway 只能通过它调用的服务来判断请求中是否有此类企图,即运维人员运行的 webhook,或 Azure AI Content Safety、Google Model Armor、AWS Bedrock Guardrails,而实现不连接其中任何一个。在 core/gateway/higress 上,实现同样会停止每一次附加并说明原因:Higress 只能通过它调用的服务来判断此类企图,即阿里云的内容安全服务,或者通过其源码中包含但其 2.2.5 插件发布未发布的插件调用运维人员运行的 Qwen3Guard 模型服务;两者在调用失败时都会放行请求,而实现不连接其中任何一个。在 core/gateway/traefik-hub 上,实现同样会停止每一次附加并说明原因:Traefik Hub 只能通过它调用的服务来判断此类企图,即其 LLM Guard 和 Parallel LLM Guard 中间件(它们以实现必须编写的请求和条件调用守卫服务或模型,且其与提示攻击检测器配合的效果未经测量,因此没有任何灵敏度可映射到那里的检查),或其 Azure Prompt Shield、Amazon Bedrock Guardrails 和 GCP Model Armor 中间件(它们调用实现不连接的托管服务)。守卫只读取最新的用户消息,因此系统消息、较早的轮次或工具结果会未经读取地到达模型;而且只有经过网关的流量会被筛查:直接调用模型地址的工作负载会绕过它。

  • 响应验证与评估: core/response-validation 声明在模型回复到达调用方之前,按 JSON Schema 对其进行检查:schema 承载 schema 本身,不匹配的回复会被拒绝而不是被传递;若开启 invert,则拒绝匹配的回复。该 schema 属于附加本身,对每个请求都相同,而不是调用方随其请求发送的 schema,因此由开发者在 Aggregate 中附加它,并在其 values 中编写 schema。标准库中没有任何实现保留它:在 core/gateway/agentgateway 上,其实现会停止每一次附加并说明原因:agentgateway 的响应守卫只匹配模式或调用内容安全服务或 webhook 服务,其中没有一个接受 schema;它在 core/gateway/higress 上的实现也是如此,Higress 的回复检查对通过检查的回复返回它在回复消息中找到的纯 JSON,而不是其 OpenAI 路由返回的 chat completion,任何发送请求头 X-HIGRESS-AI-JSON-RESP: true 的客户端都会跳过该检查,并且嵌套超过六层的 schema 不会被检查;它在 core/gateway/traefik-hub 上的实现同样如此,因为 Traefik Hub 参考文档中没有任何中间件按 schema 检查回复:其 Chat Completion 中间件按 chat completion schema 检查请求,其 API 管理按 OpenAPI 文档检查请求体,其 LLM Guard 将回复发送给外部服务,而实现不连接该服务;在其他任何网关上,附加会停止构建并指出该类型。core/traffic-shadowing 将实时请求复制到第二个服务并丢弃该服务的应答,因此可以在真实流量下评估候选模型或服务,而不让任何调用方看到其输出。它可附加到任何声明了 dataplane.aggrega.ai/request-mirroring 的组件,AI 网关未声明该项;标准库在 NGINX 网关上实现它,该网关复制整个流而不是其中一部分,并在要求的比例较小时停止并指出该比例。

5. 异步执行与 HITL 基础设施

Aggrega 将人机交互框架(如 AutoGen 和 LangGraph)视为工作节点。为支持在等待人工输入时“休眠”且不丢失状态的智能体,平台架构师可以在这些智能体的 Components 上声明 usesSchema 插槽,严格要求将 datastore 类别的组件显式绑定到这些智能体,并按 datastore 引擎标签进行选择:对于智能体按相似度检索的存储,使用 datastore.aggrega.ai/engine in (vector, semantic-memory, search);对于智能体将运行状态写入检查点的存储,使用 datastore.aggrega.ai/engine=kv。该插槽按引擎标签而非产品名称绑定,因此作者可以选择接入哪种存储,而声明依然成立。此外,对于人与智能体之间的反馈回路(例如 Slack 集成),可以配置一个治理裁决角色,除非挂接了显式声明的 Gateway 组件,否则拒绝该架构,从而使回调 webhook 经由已声明的入口边界进入。

基于某个框架或 SDK 构建、应用程序围绕其编写而非作为独立产品交付的智能体,在标准库中采用同一种形态。Release 指定应用程序镜像,目录不固定该镜像。model 套接字把框架所读取的已连接模型信息——框架读取时包括其地址和模型名称,以及以引用方式传递的连接凭据——传递到该框架读取的变量中。若框架未定义自己的服务器,该组件为 worker,不开放端口:core/ai-agent/crewai 和 core/ai-agent/langgraph 采用这种形态,core/ai-agent/openai-agents-sdk(其 model 套接字只接受带有 model.aggrega.ai/api: openai 的模型或网关)、core/ai-agent/claude-agent-sdk(其套接字只接受带有 model.aggrega.ai/api: anthropic 的模型或网关)以及 core/ai-agent/agent-framework(用于基于 Microsoft Agent Framework 构建的应用程序,自身不提供任何服务,其套接字只接受带有 model.aggrega.ai/api: openai 的模型或网关,并传递 Agent Framework 的 Python OpenAI 客户端读取的变量)也是如此;在 Release 设置之前,这三者会使构建中止,并指出 infra.image。OpenAI Agents SDK 默认将每次运行的追踪上传到 OpenAI,因此除非 Aggregate 将其 upload_traces_to_openai 值设为 true,core/ai-agent/openai-agents-sdk 会关闭该上传。若框架自身提供 HTTP 服务,该组件为 server,使用框架自己的端口,并以 host、port、endpoint 和 protocol 发布调用方访问的地址;在 Release 设置之前,它同样会使构建中止,并指出 infra.image:core/ai-agent/google-adk 在 8000 端口提供 ADK 的 REST API,并传递 ADK 的 Gemini 客户端发送给 Gemini API 的密钥,其 model 套接字只接受带有 model.aggrega.ai/api: gemini 的模型(例如 core/ai-model/gemini),绝不接受网关,因为 ADK 的客户端不会读取网关的地址;core/ai-agent/mastra 在 4111 端口提供 Mastra 构建的服务器,在 Kubernetes 上于其 /health 路由响应后即就绪,接受带有 model.aggrega.ai/api: openai 的模型或网关,并且当 Aggregate 在其 agent_id 值中指定应用程序的某个智能体时,发布该智能体的 Agent2Agent 卡片地址,使 core/ai-tool/agent-invocation 可以委托给它。除非应用程序对这两种服务器的路由进行身份验证,否则这些路由会响应任何调用方,因此在 Release 将其 infra.routes_authenticated 设为 true、确认应用程序对其路由接收的每个请求都进行身份验证之前,任一服务器上的 core/public-ingress 或 core/http-route 附加都会使构建中止。SDK 和服务器运行时以及 core/ai-agent/agent-framework 还声明了一个可选的 tools 套接字,它以按连接别名命名的变量传递每个已连接工具的地址,以及以引用方式传递的连接凭据。由于应用程序是 Release 自身的代码,这些智能体为该代码传递的变量只是默认值:它们的每个套接字都接受一个 inject: 块,Aggregate 可以通过它指定应用程序改为读取的变量或文件,而框架自行读取的变量以及连接上的附加所传递的内容保持不变。智能体自身的值也是如此:每个组件都接受在其自身上声明一个由 env 和 file 条目组成的 inject: 块;如果某个条目的模板只读取组件的一个自身值、不读取组件的其他任何内容——既不读取其他值,也不读取其 infra、元数据或身份——该条目就会替换 Recipe 传递该值时所用的默认名称,例如 CrewAI 智能体的 role 所对应的 CREWAI_ROLE。导入 CrewAI 项目的智能体声明、LangGraph 应用程序的 langgraph.json、Google ADK 应用程序的智能体配置或 Agent Framework 声明式智能体,会起草这些智能体——core/ai-agent/crewai、core/ai-agent/langgraph、core/ai-agent/google-adk 和 core/ai-agent/agent-framework——并连接到配置所指定的数据存储,以及在智能体的 model 套接字接受时连接到配置所指定的模型,同时附带一个草稿 Release,其中程序运行所用的镜像留待操作员指定;导入只读取配置,从不读取程序,如 Importer Plugins 所述。

6. 拓扑安全验证与运行时执行

由于 AI 工作负载引入了新型攻击向量(如提示注入和自主数据外泄),保护它们需要将静态架构治理与主动的运行时执行衔接起来。作为一个预先(AOT)编译器,Aggrega 不拦截实时网络流量,也不评估 AI 提示。它通过两部分的架构握手来解决复杂的安全需求:静态架构编译(编译时)和执行交接(部署时)。

A. 编译时:策略验证与制品生成

编译器构建一个扁平的中间表示(IR)图,其中包含所有节点、边和挂接的 Features。在生成任何物理基础设施之前,企业的安全态势通过在治理裁决角色处使用业界标准的策略引擎评估这一静态 JSON 图来执行。

由于该插槽评估的是通用 JSON 数据,它不绑定于单一的策略语言。企业可以使用最适合其生态系统的标准来编译和执行其架构规则:

  • **Open Policy Agent(OPA/Rego):**一种广泛使用的语言,用于评估复杂的多跳图关系、计算分布式拓扑中的最小权限访问。编译进 CLI 的 Rego 引擎按原样运行 .rego 文件;需要 OPA 完整内置函数集的策略则使用 OPA 自己的工具链编译,并在一个适配器 guest 之后运行。
  • **Common Expression Language(CEL):**编译进 CLI 的 CEL 引擎运行以单个表达式针对文档编写的规则,写法与 Kubernetes validating-admission 策略相同。
  • **Kyverno:**评估静态 JSON/YAML 清单,使团队可以用原生 YAML 编写策略,而无需学习 Rego。编译器不附带任何 Kyverno guest,它只以 WebAssembly guest 的形式运行策略,从不调用 Kyverno CLI,因此 Kyverno 规则在一个封装该引擎的 guest 之后运行。
  • **自定义 Rust/TypeScript 验证:**安全团队可以用标准语言编写定制的组织策略,并将其编译为 Wasm,作为验证关卡。

策略引擎验证该图后,编译器将这些抽象的安全需求转换为物理配置。当开发者挂接一个安全 Feature(例如 AI 网关上的 core/data-masking)时,编译器运行其实现所指定的流水线步骤,即一个隔离的 WebAssembly(Wasm)插件,该步骤将控制所需的设置写入网关自身 Recipe 已渲染的配置中。实现也可以将写入工作交给网关自身的 Recipe,由它读取挂接并自行写入设置,core/gateway/kong-enterprise 上的 core/data-masking 即是如此;针对另一类控制的实现则可能输出一个独立的资源。无论哪种方式,输出都是根据开发者所挂接内容写出的静态制品。

B. 部署时与运行时:执行交接与强制执行

Aggrega 的职责在它处理完输入、将配置好的静态产物写入输出目录的那一刻即告结束。它是一个纯粹的编译器:它写出配置,随后控制权完全交还给调用它的系统。

这些配置如何执行非常灵活,完全由企业决定:

  • 产物交接(部署时): 由外部部署控制器接手,将产物付诸实际。这可以是一个严格的 GitOps 控制器(如 ArgoCD 或 Flux),将文件同步到 Kubernetes 集群中;但同样也可以是执行 terraform apply 的标准 CI/CD 流水线,或是开发者针对 Docker Compose 运行的本地 shell 脚本。
  • 运行时强制执行: 配置应用到目标环境后,由物理基础设施接手。由 Aggrega 配置的专用工具(例如护栏 sidecar、活动的服务网格或原生云防火墙)启动并开始其实际工作:在物理层面拦截载荷、验证 JWT,或丢弃恶意的提示注入。

7. Aggrega 如何应对 AI 安全挑战

通过将架构验证与运行时执行解耦,平台团队可以使用 Aggrega 显式地建模、验证并生成配置方案,以应对下列 AI 漏洞。

A. 数据外泄与载荷拦截

  • 问题: 自主智能体可能试图将受限的企业数据泄露给未经授权的外部 API。
  • Aggrega 的方案:
    1. 编译时(验证与生成): 平台团队编写一条在治理裁决角色处评估的策略(例如 Rego),规定:“每条经过 AI 网关的路径都必须带有 core/data-masking。” 若缺失,编译器停止。若存在,Manifest 绑定的实现会将脱敏写入网关已渲染的配置中:在 core/gateway/litellm 上,写入护栏条目,这些条目匹配附件列出的正则表达式,并针对附件列出的实体类型,将文本发送给连接到网关 pii_analyzer 和 pii_anonymizer 插槽的 Presidio 分析器和匿名化器;在 core/gateway/kong-enterprise 上,在每个已连接模型的 chat 和 completion 路由上写入 Kong 的 AI PII Sanitizer,由网关的 chart Recipe 写入,它将其脱敏的文本连同附件列出的正则表达式和实体类型,发送给连接到网关 pii_sanitizer 插槽的 Kong AI PII 服务;在 core/gateway/agentgateway 上,写入网关自身的正则表达式防护,由其 chart Recipe 写入其配置,这些防护将附件所列模式的每个匹配替换为 <masked>,或在 refuse 下以 HTTP 403 应答请求或回复,且不识别任何实体类型;这些防护不会对流式回复脱敏,因此在回复被脱敏期间,同一 Recipe 会写入一条规则,在请求被转发之前,以 HTTP 403 拒绝要求流式回复的请求,以及任何请求体大于网关为该规则读取的 2 MiB 的请求,无论是否为流式;在 core/gateway/traefik-hub 上,在每个已连接模型的路由上写入 Traefik Hub AI 网关的 Content Guard,由其 chart Recipe 写入,它通过其正则表达式引擎对附件所列模式的匹配进行脱敏,或通过连接到网关 pii_analyzer 插槽的 Presidio 分析器对附件所列实体类型进行脱敏,每个附件使用一个引擎;在 core/gateway/higress 上,在每个已连接模型的路由上写入 Higress 的 ai-data-masking 插件,由其 chart Recipe 写入,它将 chat 请求消息中附件所列模式的每个匹配替换为方括号括起的模式名称,且不识别任何实体类型。策略还可以提出更窄的问题——脱敏是否位于受限数据与 provider 之间——方法是沿路由读取每个组件的附件,而不是将路由的附件作为整体读取,正如 examples/policy-data-class-route 所做的那样。
    2. 运行时(物理执行): 编排器部署生成的产物后,网关在转发请求之前,将其所掩码的请求文本中的每个匹配项替换为占位符,因此模型提供方收到的是占位符;使用 action: refuse 时,该附加项不会转发携带匹配项的请求的任何内容,而是以错误响应该请求。无法访问或出错的识别器会使请求失败,因此其文本不会被传递出去。掩码未覆盖的内容由两个值决定,其默认值即为保护措施。在 AI 网关上,当该附加项同时掩码回复时,网关会掩码回复的文本,以及模型或其提供方在其旁边添加的部分——拒绝内容、引用和注释、网页搜索的查询和结果、提供方自有名称下的字段——或者在 refuse 下,不发送携带匹配项的回复的任何内容;按模式掩码的流式回复会在最后完整地到达调用方。默认情况下,对于请求中掩码未覆盖的内容——例如图像生成这样的路由、safety_identifier 这样的字段、对话中的图像或文件、由提供方自行运行的工具——AI 网关会在转发任何内容之前以 HTTP 400 拒绝;接受此类文本未经掩码到达提供方的运维人员,在 Release 中的附加项上设置 allow_unmasked_text,由实现准确列出此时放行的内容,而非文本内容仍由 allow_non_text_content 控制。默认情况下,被掩码的回复中掩码无法读取的内容——语音音频及其转录文本、图像、模型所选 token 的概率——会被扣留,失败的调用会以固定消息代替提供方返回的消息到达调用方;allow_unmasked_reply_parts 允许这些内容未经掩码到达调用方。回复本身的文本从不会因此被放行,但它放行的部分可能携带回复的内容:语音回复的转录文本、token 概率背后的 token、引用回复的提供方错误消息。在 core/gateway/kong-enterprise 上,每个匹配项被替换为带编号的占位符,因此在 redact 下列出模式的附加项需设置 placeholder_shows_name: false;refuse 仅作用于请求,自 Kong 3.12 起可用,它以 HTTP 400 响应携带匹配项的请求;回复自 3.12 起被掩码,此时请求流式回复的请求会在转发前被拒绝,并且 allow_streamed_replies 会被拒绝。Kong 的清理器读取用户轮次的文本、补全的提示词以及回复的消息文本,而 Kong 的参考文档没有提供任何设置,用于拒绝清理器未读取内容的请求或扣留回复的其余部分,因此在该网关上,每项保护在保持默认值时都会在构建时被按名称拒绝;一旦 Release 放宽这些保护——在掩码请求时为 allow_unmasked_text 和 allow_non_text_content,在掩码回复时为 allow_unmasked_reply_parts 和 mask_reasoning: false——附加项即可构建,并由 data-masking-kong-enterprise 列出每项设置此时放行的内容。在该网关上,文本未以 OpenAI API 返回的单个字符串形式到达的回复会未经读取地通过,其自身文本未经掩码到达调用方;对此的防护是构建对连接到该网关的每个模型所做的检查,遇到 model.aggrega.ai/api 不为 openai 的模型时会终止构建。在 core/gateway/traefik-hub 上,每个匹配项被替换为与匹配项等长的一串 *,因此在 redact 下列出模式的附加项需设置 placeholder_shows_name: false;refuse 以 HTTP 403 代替请求或回复;被掩码的回复会被完整保留并在最后发送,包括流式回复,因此在回复中掩码实体类型的附加项需设置 allow_streamed_replies。Traefik 的参考文档没有说明 Content Guard 读取聊天请求或回复的哪些字段,也没有提供任何设置,用于拒绝其未读取内容的请求或扣留回复的部分内容,因此在该网关上,每项保护在保持默认值时都会在构建时被按名称拒绝;一旦 Release 放宽这些保护——在掩码请求时为 allow_unmasked_text 和 allow_non_text_content,在掩码回复时为 allow_unmasked_reply_parts 和 mask_reasoning: false——附加项即可构建,并由 data-masking-traefik-hub 列出每项设置此时放行的内容。同时列出模式和实体类型的附加项,以及同一网关上的第二个掩码附加项,都会被拒绝,因为 Traefik 的参考文档没有说明路由上的第二个 Content Guard 读取的是第一个已掩码的文本,还是调用方发送的原始请求。在 core/gateway/higress 上,Higress 的 ai-data-masking 插件将聊天请求中每条消息的内容和推理里,附加项所列模式的每个匹配项替换为方括号括起的模式名称;它仅掩码请求,因此 scope 为 response 和 both 时会被拒绝,且它不识别任何实体类型。该插件不读取请求的其他任何部分,因此当保护保持默认值时,网关的 chart Recipe 还会写入 Higress 的请求校验插件,在转发任何内容之前以 HTTP 403 拒绝携带掩码未读取内容的请求——未以 JSON 发送或不是聊天补全的请求体、内容为列表或 null 的消息、工具调用或工具轮次、消息的名称、除聊天补全的非文本参数以及开发者自有的工具、响应格式和停止序列之外的任何参数——并且无论附加项放宽了什么,都会拒绝 Higress 插件会跳过其请求体的请求——压缩的请求体、包含 octet-stream 或 grpc 的内容类型、协议升级——以及包含 Unicode 替换字符 U+FFFD 的请求体,这是该校验读取非有效 UTF-8 字节的方式,因为掩码插件会将非有效 UTF-8 的请求体未经掩码地转发。请求体超过网关 32 KiB 缓冲区的请求会以 HTTP 413 被拒绝。该校验只读取其 JSON 解码器接受的请求体,因此客户端故意发送解码器拒绝的有效 JSON——例如超出 double 所能表示范围的数字——即可通过针对其请求体的所有拒绝:此时掩码插件只掩码每条消息的纯内容和推理,因此请求体中其他任何位置的所列值——工具调用的参数、名称、任何其他字段——都会未经掩码地转发,使用 JSON 转义序列编写的内容也是如此;如果此类请求体同时不是有效的 UTF-8,则其全部内容都会未经掩码地转发。客户端故意在校验允许的字段(例如 tools)中将请求体嵌套超过 127 层,所发送的有效 JSON 会被校验解码并放行,但掩码插件的 JSON 读取器在该深度处停止,因此该请求体中使用 JSON 转义序列编写的内容同样会未经掩码地转发。仅靠掩码是不够的:没有模式匹配、也没有识别器检测到的文本会原样通过;在 AI 网关上,工具调用参数和工具结果按值逐一掩码,但其键名不会被掩码;开发者自有的工具定义、响应格式和停止序列按发送时的原样通过;网关和识别器服务能看到原始文本;网关记录的调用信息——在其自身日志中,或在其交给日志集成的内容中——仍可能包含该文本;不经过网关的流量不受影响。

B. 防御 MCP 投毒(信任与隔离)

  • **问题:**如果智能体通过被投毒的 Model Context Protocol(MCP)工具遭到入侵,它可能会自主执行破坏性操作(例如删除数据库或授权转账)。
  • Aggrega 的方案:
    1. **编译时(验证与生成):**开发者在其 Aggregate.yaml 中将一个审批关卡 Feature 附加到敏感工具上。标准库不提供此类 Feature,因此它需要在企业自己的目录中编写,连同渲染它的 FeatureRecipe 一起。编译器验证图,并将该附加转换为 L7 代理或 webhook 网关的配置。
    2. **运行时(物理执行):**当被劫持的智能体尝试调用该工具时,已部署的代理会暂停请求,并在收到人工操作员经过加密签名的批准之前,从物理上阻止执行。

C. 解决“混淆代理人”问题(上下文传播)

  • **问题:**在多智能体链中,面向公众的智能体可能被劫持,并命令一个内部的高权限智能体获取敏感数据。标准防火墙只能看到“智能体 A 正在与智能体 B 通信”并放行流量,完全丢失了原始恶意用户的上下文。
  • **Aggrega 的解决方案:**企业可以叠加两种特定模式:
    1. 调用方身份传播,跨两个跳点:原始调用方的身份必须在两个不同的跳点上得以保留,每个跳点在不同的位置受到保护。在网关跳点,开发者将 core/context-propagation 附加到请求进入时经过的网关上,该网关在 dataplane.aggrega.ai/caller-identity 上进行选择。在编译时,该附加在该网关自身的配置中实现——在 Envoy Gateway 上,是一条客户端流量策略,它根据 Release 指定的证书颁发机构验证每个客户端的证书,并转发证书的详细信息;在 LiteLLM AI 网关上,是一个请求钩子,对发往附加在 destinations 中列出的模型别名的请求,它会移除调用方提供的任何身份标头,并添加网关所验证的虚拟密钥的用户和团队,以及该密钥指定组织时的组织。在运行时,网关后面的服务接收到的是谁发起了调用,而不仅仅是网关发起了调用。在工作负载跳点,一个智能体直接发往另一个智能体的请求从不经过该网关,因此它在接收方智能体自身的入口处接受检查,由服务网格拒绝任何缺少能证明原始用户意图的签名令牌的请求(例如 Istio JWT AuthorizationPolicy)。标准库提供网关跳点 Feature,不提供工作负载跳点 Feature,因此附加 core/context-propagation 保护的是经过网关的流量,而智能体之间的调用则交由企业自行提供的网格配置处理。由另一方运行的智能体——core/ai-tool/agent-invocation 通过 A2A 以 core/ai-agent/a2a-remote 的形式访问它——完全位于 Release 之外:该方根据该智能体的 Agent Card 声明的安全方案检查每次调用,而工具则在该智能体公布的请求标头下,出示其连接上持有的凭据,该凭据通过引用从 Secret 中读取。当卡片要求 OAuth 2.0 客户端凭据或 OpenID Connect 时,连接改为持有(或同时持有)一个客户端密钥,以及操作员写在连接上的客户端 ID,智能体则公布令牌或发现地址以及其卡片声明的作用域;工具自身的容器使用这些信息获取令牌、刷新令牌并在每次调用时出示;目录只交付这些输入,任何构建都无法检查容器如何使用它们。当卡片要求双向 TLS 时,连接持有一个客户端证书,并且当智能体的服务器证书由镜像尚未信任的证书颁发机构签发时,还持有该颁发机构的证书;每一项都以文件形式从连接指定的 Secret 挂载到工具的容器中,由容器自己在 TLS 握手中出示证书。因此,工具能够访问的智能体,其卡片声明的是:标头或 cookie 中的 API 密钥;值固定的 HTTP 认证方案,例如 Bearer 或 Basic,由 Secret 持有完整的标头值;采用客户端凭据授权的 OAuth 2.0 或 OpenID Connect;或双向 TLS。它无法访问卡片要求以下方案的智能体:查询字符串中的密钥、需要应答智能体质询的 HTTP 方案(例如 Digest),或客户端凭据以外的 OAuth 2.0 流程。它也不会向通过明文 HTTP 运行的另一方智能体出示凭据:当该智能体的地址为 http 时,连接上的凭据或客户端密钥会使构建停止,并指出该连接,因为凭据或用该密钥获取的令牌将以未加密的方式传输给它。在 Release 内部运行的智能体在使用两者中的任一种时仍可通过 http 访问,此时凭据以未加密的方式穿过集群网络。
    2. 智能体之间的负载检查:一个智能体直接发往另一个智能体的请求从不经过 AI 网关,因此它在接收方智能体自身的入口处接受检查,由在该智能体旁运行的护栏引擎执行(例如 NeMo Guardrails)。在编译时,实现附加到接收方智能体上的 Feature 的 FeatureRecipe 渲染该引擎的配置。在运行时,引擎根据企业编写的规则评估每个请求,并拒绝这些规则否决的请求;它区分被劫持请求与合法请求的能力取决于引擎和规则,因为 Aggrega 只编译配置,从不评估提示词。标准库不提供部署此类引擎的 Feature,因此该模式需要在企业自己的目录中编写。网关自身的模式防护 dataplane.aggrega.ai/prompt-guard: pattern-list 范围更窄,由 core/prompt-deny-patterns 开启——在 AI 网关上,读取请求的每条消息并忽略大小写;在 core/gateway/apisix 和 core/gateway/kong 上,将所有角色的每条消息作为一段文本读取,区分大小写,并遵循请求还必须匹配的模式列表;在 core/gateway/agentgateway 上,分别读取每条消息、工具调用参数和工具结果,区分大小写;在 core/gateway/traefik-hub 上,将请求作为聊天补全读取(Traefik 的参考文档未列出读取哪些字段),区分大小写:它拒绝文本在字面上匹配附加所列表达式之一的模型请求——改写、换一种语言或编码即可绕过——并且只作用于经过网关的流量,因此智能体之间直接发送的请求永远不会遇到它。core/prompt-injection-shield 是它在同一跳点上的分类器对应项,它将网关转发的每个模型请求发送到连接至该网关 guard 插槽的 NeMo Guardrails 防护,或在 Azure API Management 上发送到 Azure AI Content Safety 的提示词防护,它同样只覆盖经过网关的流量。

D. 拓扑风险分析

  • **问题:**包含数十个相互连接的模型、向量和工具的复杂 AI 架构过于庞大,人工无法手动审计其中的传递性漏洞(例如:“智能体 A 能否与工具 B 通信,而工具 B 与智能体 C 通信,智能体 C 又能访问数据库 D?”)。
  • **Aggrega 的解决方案:**此检查提前运行。由于 Aggrega 在内存中构建了预期拓扑的完整 IR 图,治理裁决角色可以在整个架构上运行高级路径查找规则。如果策略检测到一条从公共节点出发、终止于高度敏感数据库的连续传递边链,且沿途任何位置都没有附加企业要求的控制措施,它会立即停止构建。不安全的架构在生成任何一行基础设施代码之前就被阻止。

8. 可观测性与合规

为满足严格的监管要求(例如欧盟《人工智能法案》),平台架构师可以利用 Aggrega 的 feature 系统,将 AI 可观测性作为结构性的基础设施要求来强制执行,而不是依赖应用代码:

  • **审计日志:**由企业编写的 Wasm 插件可以配置网关 sidecar,将未经脱敏的原始提示词和响应异步流式传输到安全的 WORM(Write Once, Read Many,一次写入、多次读取)存储桶,绕过标准应用日志。
  • **LLM 追踪:**代理 feature 可以配置数据平面,提取并转发 AI 专用的 OpenTelemetry span 头,确保复杂的智能体推理循环可以在外部工具中可视化。

9. Feature 兼容性与拓扑安全

由于核心编译器与物理基础设施机制无关,它完全依赖目录中的显式声明来防止生成不兼容的配置。

  • **conflictsWith:**在 Feature 的目录实体中 interoperability 下声明的列表,列出不能与其同时附加的 Features。在所有作用域都已贡献之后——即组件自身的附加项、写在包含它的子系统或边界上的附加项、其 Release 组件条目上的附加项,以及由注解驱动的展开所产生的附加项——编译器将该列表与每个组件最终携带的 Features 进行比较;当某个组件同时携带两者时(即作者直接或通过某个作用域附加了某个 Feature 的作者明确声明为不兼容的两个 Features),编译器会在渲染任何物理制品之前停止。只需一处声明即可,且 Features 按名称匹配,与其版本无关。编译器不会从名称中解读任何含义:不兼容性是作者的声明,而检查只是名称的比较。Feature 的原子性和纯粹性本身仍是一种社会契约——没有任何机制检查一个 Feature 是否只做一件事。

10. 动态拓扑映射(依赖解析)

为了在没有硬编码规则的情况下构建 IR 图,编译器从三种显式声明中读取它:

  • **uses 边:**开发者在每个实例的 uses 块中链接组件,在插槽中写明目标组件,图中的每条边都来自这样的声明。恰好写有另一个组件名称的 values 条目不会绘制任何边:编译器不会从值中解读任何含义。
  • **边目标:**每个 uses 目标都必须指向构建中存在的组件;不存在的目标会使构建中止,并指出它所连接的插槽。
  • 跨节点类型安全:usesSchema 选择器字符串充当显式的带外指令,在静态分析期间由 Go 编译器的标签匹配引擎原生求值。它们保证开发者不会意外地将标准组件接入需要特定 AI 原生能力或合规标签的已声明插槽。这一保证在构造上仅限于已声明的插槽:选择器位于 usesSchema 条目中,因此临时插槽没有可供求值的选择器。每条边都会记录其插槽是否由目录声明,因此需要全面保证的运维人员可以将其作为治理裁决来要求。

11. 智能体系统的自动化设计(ADAS)

高级 AI 系统具有元智能体(Meta-Agent),它们编写代码来即时发明和部署新的智能体。由于 Aggrega 要求预先(AOT)确定的静态架构,它通过两个明确的边界来解决运行时基础设施演进问题:

  • **预置沙箱边界:**对于运行时发明的临时工具,架构师定义一个 feature(例如 dynamic-execution-environment)。附加后,Wasm 渲染插件会生成配置,以预置一个受严格锁定的计算池(如 WebAssembly 运行时)。元智能体将新代码注入该沙箱,但其影响范围受生成的静态网络策略约束。
  • **元智能体作为“开发者”角色(GitOps 循环):**如果元智能体需要真正新的物理基础设施,它就以开发者的身份行事。它编写新的 Aggregate.yaml 并提交到 Git,从而触发标准 CI/CD 流水线。治理裁决角色对 AI 请求的拓扑进行静态分析,如果 AI 幻觉出了漏洞,就安全地停止构建。

12. 模型序列化与供应链安全

部署开源模型通常意味着下载不透明的 .pkl 或 .gguf 文件,其中可能包含恶意代码载荷。企业可以将模型供应链安全视为目标平台的配置问题。通过在目录中定义 model_provenance feature,企业的 Wasm 渲染插件可以对配置求值,并将其转换为运行时制品(如 Kubernetes Kyverno 策略),从而使目标集群被配置为阻止编排器拉取未签名或未经验证的模型权重。