Zentrix Gateway 流量规则用户手册

流量规则、全局限额、意图集、语义缓存、熔断与故障转移的配置及验证。

下载 PDF · 资料下载

2026.10 · 操作范围以当前许可、账号权限和实际部署为准。

本手册是《Zentrix Gateway 用户手册》第 15 章的流量规则专项版，按当前流量规则页面与接口补充具体字段、默认值和取值范围。规则中「内容检测」动作的检测项、模板与判断模型配置见《Zentrix Gateway 用户手册》第 14 章。

1. 入口与生效顺序

1.1 入口、许可与权限

从「管理后台 › 流量 › 流量规则」进入。页面顶部有「规则清单」「全局限额」「意图集」三个页签。「规则清单」右上方为「导出」「导入规则模板」「从文件导入」「新建规则」；下方搜索栏右侧的「验证规则」打开独立的验证页面，勾选规则后该位置换成「启用所选」「停用所选」「删除所选」。

• 许可：许可包含「动态路由」或「模型护栏」任一模块时，侧栏显示「流量规则」，页面中的意图集、判断模型状态与内置意图试判随之可用；两个模块都不包含时不显示。
• 权限：页面要求凭据管理权限，内置角色中租户管理员和安全管理员具备。看不到入口时，先核对「系统设置 → 全局设置 →「授权许可」页签」中的模块，再核对账号角色。「全局限额」页签的接口另按租户管理权限校验，只持安全管理员角色的账号可以进入页面，但该页签的加载与保存会被拒绝，需由租户管理员维护。
• 同一分组下的「网关扩展」维护「挂载插件」动作引用的插件绑定，见《Zentrix Gateway 用户手册》第 16.3 节。

「全局限额」独立于单条路由规则维护，但仍按自身的匹配条件和计数维度生效，并不表示所有请求共用一份额度。模型分组配额、API 密钥配额与这里的限额分别计数。

1.2 规则如何参与一次调用

*图 1：配置验证步骤示意。保存、下发、模拟和真实调用分别回答不同问题。*

请求通过身份认证后，网关按「优先级」数字从小到大检查已启用的规则。一条规则的全部条件都满足才算命中；不满足时跳过本条，继续检查下一条。规则清单的「命中后」列标明规则类型，悬停可查看判定原因：

• 「放行」结束规则判定，请求按网关既有路由处理，仍受身份权限、额度和目标可用性检查约束。
• 「拒绝」不向上游派发，网关返回 403，错误响应中带有配置的拒绝原因码。
• 清单为空或没有规则命中时，请求按网关既有路由处理，这不保证一定存在可用目标。平台不再内置路由规则，清单中的规则均由本租户维护。
• 多条规则同时命中时，内容检测按整条规则链合并，同一检测项冲突时取更严格的配置，整次请求只送检一次；「单次请求 Token 上限」和「请求体大小上限」取最严的值。
• 「实际上游」条件在选定目标后复核。复核时命中的规则要求的目标与已选目标不一致时，网关返回 503。

1.3 如何阅读画布

规则编辑器以「规则编排」画布展示一条规则，节点从上到下依次为：

• 「请求进入」：说明流量入口；请求路径、调用身份和模型信息作为条件判断的输入。
• 「条件判断」：本规则的匹配条件，全部条件均需满足（AND）。右侧「不满足条件 / 跳过本规则」表示按优先级检查下一条规则。
• 「处置动作 · 请求转发前」「处置动作 · 收到上游响应后」：一个动作一个节点，节点上标注「执行顺序 n / m」。展开节点后可用「上移」「下移」调整本阶段内的执行顺序；「请求体大小上限」固定在请求阶段首位。
• 「处理结果」：显示「命中后的配置预期」，不表示已有请求执行成功。
• 「异常处理」：按「系统固定行为」「命中处理」「组件不可用时」分组列出可配置的处置方式，随动作增减变化。

画布工具与面板：

• 顶部「YAML 编辑」以 YAML 编辑当前草稿，选择「应用到画布」后回到画布检查。内容不超过 256 KiB，资源引用使用资源 ID。
• 「撤销修改」「重做修改」作用于本次编辑中尚未保存的修改，最多回退 50 步。
• 「收起节点」「展开节点」只改变显示，不会停用动作；底部的「画布缩放」和「流程总览」用于定位较长的流程。
• 右侧「调试与预览」包含「验证规则」和「配置检查」两个页签。「验证规则」把当前未保存的草稿连同整套已有规则交给网关求值，填写方式与独立的验证页面相同（见第 3.2 节），页首提示「使用当前草稿，真实调用判断模型。保存并生效后，真实对话才会按此执行；模型回复阶段的流中截断无法在此验证。」；草稿仍有待完善项时会转到「配置检查」。「配置检查」列出草稿中的问题，点击问题即定位到对应配置。
• 底部依次显示保存状态（「有未保存的修改」「尚未保存」或「已保存」）、配置检查结论（「配置正常」，或「配置异常」及问题数）、「验证规则」「取消」和「保存规则」。仍有待完善的配置时「保存规则」不可用，悬停可查看原因。

2. 创建规则与配置条件

2.1 新建规则的方式

每个租户最多 500 条规则，清单右上方显示「已有条数 / 上限 条」。达到上限后新建、导入和复制不可用；导入的条数超过剩余名额时，页面提示还能创建的条数。

2.2 创建一条模型路由

1. 在「模型供应商」和「模型」中完成目标接入与调用验证，并在「模型分组」中为测试调用方准备有效凭据和模型使用权限。
2. 选择「新建规则」，在画布顶部填写能说明用途的名称，例如“客服问答主路由”。名称为 1–120 个字。
3. 在「条件判断」中选择「添加条件」，从「选择匹配条件」中添加「客户端声明的模型名」，比较方式选「等于」，填入调用方实际提交的模型名，例如 customer-support。这是请求里的名称，不是模型 ID。
4. 选择「添加处置动作」，在「其他」分组中选「转发到指定目标」，画布上显示为「转发到」节点。条件中还没有调用类型时，编辑器自动补上「调用类型」为「模型调用」。
5. 在转发节点选择「目标方式」：「请求模型的全部上游」，或「指定上游」后逐个选择上游。需要分流时在本档继续添加目标并设置权重；需要故障转移时添加备用档位并开启「启用故障转移」，见第 7 节。
6. 查看「处理结果」，修复「配置检查」中的问题后选择「保存规则」，在「确认变更」中核对后选择「确认并应用」，见第 3.1 节。
7. 用「验证规则」检查应命中和不应命中的请求，再用实际业务入口发送受控请求，见第 3 节。

本章示例名称和阈值仅用于说明操作，不代表推荐容量。不要把示例模型名直接当作已接入模型使用。

2.3 创建一条增强规则

只想给客服模型增加限速、不改变去向时，添加相同的模型名条件，再添加「限额」（画布上显示为「应用限额」）并设置请求速率、计数维度和阈值，不添加转发目标。这条规则在清单中显示为「继续匹配」。

将增强规则排在需要受它约束的终止规则之前。前面的规则已经转发、放行或拒绝时，后面的增强规则不会参与判定。要实现“允许名单 + 拒绝其他请求”，用「放行」动作放行名单内的请求，再在其后放置兜底的「拒绝」规则；没有转发目标的普通规则是增强规则，不会结束判定。

2.4 条件之间的关系与数量限制

• 同一条规则内的条件之间是“且”关系；同一条件内的多个取值满足任意一个即可。否定比较方式（如「不等于」「不以…开头」「不匹配正则」）表示与全部取值都不符合时才满足。
• 新建规则至少要有一个条件和一个动作，否则保存时提示「请至少添加一个条件」「请至少添加一个动作」。一条规则最多 16 个条件。多数条件可填 1–32 个取值，「调用方」条件可选 1–42 个对象，「组织成员」的部门与职能组合计最多 64 个。
• 取值长度：请求路径、请求头、URL 参数和客户端声明的模型名的每个取值不超过 256 字节；数据来源、具体能力等其余取值每个 1–160 字节。「模型分组」「实际上游」只接受从选择器选出的对象，不能用全零编号占位。
• 同一字段上互相矛盾的条件无法同时成立，保存时会被拒绝。“A 或 B”应写成一个条件的两个取值。
• 条件须是所选「调用类型」实际产生的信息。例如「工具名」不产生于模型调用；「MCP 方法」选了「列出工具」「资源」或「提示词」时不产生工具名。这类规则永远不会命中，保存时提示「「X」条件在「Y」中不会产生判断依据，规则永远不会命中」并列出该条件适用的调用类型。
• 正则表达式由数据面引擎执行，不支持零宽断言和反向引用。要表达“不以…开头”，改用比较方式中「排除」组的选项。
• 已有的无条件规则在清单中显示「匹配所有请求」，编辑前确认它是有意设置的兜底规则并检查其位置。

2.5 条件类型

「选择匹配条件」只列出当前调用类型可用的条件，每项带下表的分组标签，可用搜索框按名称查找：

除字符串比较外，集合、时段和灰度 Cookie 条件也可选择「属于」「不属于」；多值排除表示没有任一取值命中。缺失、不适用或尚未完成的判断不会因排除而自动命中；组织成员与标签的特殊情况按各自说明处理。

严格只允许大陆来源时，先用「客户端 CIDR 属于 中国大陆」配置「放行」，再在同一服务范围后置一条兜底「拒绝本次调用」规则；只用「不属于 中国大陆」拦截时，不会拦截未知地区或内网 IP。预置数据支持 IPv4、IPv6，随产品发布更新；判断依据是出口 IP。

请求头条件不能使用的名称（数据面在判定前剥离或改写这些请求头，用它们做条件的规则永远不会命中）：

2.6 调用身份与事实缺失

真实调用身份来自凭据认证、登录账号和受信请求上下文。在「验证规则」中填写的调用方只是判定输入，不会为真实调用授予权限；把对象 ID 复制到普通请求头也不能替代认证。

不同入口提供的匹配信息不同。模拟结果中条件显示「请求未提供该信息」时，应补齐真实请求能提供的信息；显示「此调用类型不提供该匹配信息」时，应调整条件或调用类型。配置意图条件前，先确认意图识别模型可用。模拟器中的敏感信息类型由管理员作为假设事实填写，不能据此确认真实请求已完成识别。

「请求含敏感信息」条件用于根据请求正文选规则。平台模型调用入口在规则求值前识别规则引用的类型；没有检出时条件不命中，识别不可用时请求返回 503，不把失败当作“未检出”。网关原生入口及非模型调用不产生这一事实，不能借模拟命中推断这些入口会命中。该条件只能选择可在求值前识别的类型；人名、地址和机构名等依赖敏感信息识别模型的类型应放在「敏感信息检测」动作的「检测范围」中。条件和该检测动作不能放在同一条规则里：需要按敏感信息选目标或拒绝时使用条件；需要脱敏或拦截时使用检测动作；两种处理都需要时拆成两条规则并核对顺序。

3. 验证规则与真实调用

3.1 保存与确认变更

新建和编辑规则都先打开「确认变更」：在编辑器中选择「保存规则」，或在规则详情编辑后选择「保存」。核对「字段差异」「关联对象」（变更前引用、变更后引用）和「命中顺序」；配置了故障转移时另显示「故障转移链」。本次变更修改敏感请求头时，须勾选确认后才能保存。核对无误后选择「确认并应用」；范围不符时选择「取消」返回编辑。

*图 2：确认变更。确认前核对实际变化、关联对象和命中顺序。*

• 应用成功后提示「规则「名称」已保存。」，其中「查看命中记录」打开该规则详情的「实时流量」视图。配置已提交，网关节点加载新配置可能略有延迟。
• 规则清单中的启停开关和删除在各自的确认弹窗后直接生效，拖动排序和「上移」「下移」调整后立即生效，都不打开「确认变更」；「移到最前」「移到最后」可能改变全租户的命中顺序，会先打开「确认变更」。规则详情中的启停开关也会打开「确认变更」。
• 配置发布失败时，清单顶部显示提示：「最近一次配置发布失败，本租户的流量规则仍按上一版生效。」；规则引用的词库或问答集尚未发布成功时，提示「部分规则引用的检测数据尚未发布成功，这些规则当前不会生效。」并列出缺少的对象。在相关规则中移除这些引用后重新保存，或稍后再次保存以重试发布。保存后的十几秒内页面会重新读取发布结果，失败提示可能稍后才出现。
• 规则清单、规则详情和「验证规则」都不显示各网关节点是否已加载新版本。保存后以真实调用验证生效情况。

3.2 使用「验证规则」

进入方式：「规则清单」搜索栏右侧的「验证规则」。页首提示「使用已生效的规则，按整套规则的先后顺序验证，结果与线上一致。」验证页面没有调用记录选择器，请求事实需手动填写。要验证尚未保存的修改，使用规则编辑器右侧的「验证规则」页签，见第 1.3 节。

1. 选择「调用类型」，填写「请求的模型」（与规则中「客户端声明的模型名」是同一个值）；非模型调用改选「能力」。
2. 选择「调用方」，或选择「凭据身份」（API 密钥），两者二选一。
3. 按需填写「请求路径」「验证时间」（用于时段条件）；模型调用可另填「默认路由目标（可选）」，用于查看未命中任何规则时的落点。内容检测试运行时，选择「检测方向」（「输入」或「输出」），在「消息」中为每条消息选择「角色」（「用户」「助手」）并填写「消息内容」，可选择「附图」添加图片，用「添加消息」增加多轮；「检测方向」为「输出」时另填「本轮回答」。命中的规则配置了工具调用防护时，可填写「工具名」「参数或命令」，需要检查工具返回结果时填写「返回结果」，并选择「工具调用防护」。
4. 需要时展开「更多请求事实」，填写「指定模型分组」「意图提示词」「客户端 IP」「查询参数」「灰度 Cookie」「调用标记」「数据来源」「敏感信息类型」「请求头」。这里填写的是假设值，真实流量中由平台自动判定。
5. 需要查看后备顺序时勾选「模拟主档失败」；需要按带金额预算的调用方演练时勾选「按带金额预算的调用方演练」，链上已定价但币种与调用方金额池不同的档位标为跳过，未定价的档位照常参选。
6. 必填事实齐全后页面自动计算，「运行验证」可重新计算。修改输入后等待新结果出现再读取。

「验证规则」页面字段：

结果按「选路前求值」和「选定目标后复核」两轮列出各规则的结论，并列出「本次验证命中的规则链」、「验证选定的路由目标」、计量分组、各目标的期望占比；按排名选目标的策略另显示候选目标的名次、质量分、价格、预计首字时延和是否被排除。勾选「模拟主档失败」时显示后备目标所在档位与转移链；未配置更高档位时提示主档失败后无后备目标。候选全部被硬条件排除时，结果说明请求没有被拦下，改为按权重选一个。网关节点加载新版本可能略有延迟，刚保存后仍须用真实调用核对。

模拟不会调用上游模型，也不能证明限额已计数、改写已执行或目标可连通。填写「意图提示词」「消息」或执行「工具调用防护」时，页面会调用相应的判断模型或检测服务，请使用允许送检的测试文本。加权轮询的模拟使用独立于生产的轮询进度，连续模拟不会消耗真实流量的轮询顺序。

3.3 用真实调用完成验证

使用业务实际采用的入口、凭据和请求格式。测试请求应使用脱敏数据和明确的测试对象，避免影响其他业务。

规则详情的「查看命中的请求」打开「运行总览」的「请求」视图，并按本规则筛选；也可在「规则命中」中核对命中记录并跳转到规则详情。请求详情的「路由与改写」页签列出「选路过程」「跳过的候选」「尝试」和「请求改动」，用于核对实际去向，见第 7.6 节。请求被拒绝时，保留调用方收到的完整状态码、错误码与请求标识。状态码与错误码的完整对应关系见错误参考。

部分失败请求可能缺少完整调用记录。查不到日志不能单独证明请求没有执行，应结合原始响应、上游接收记录和时间范围排查；记录缺失时提交运行管理员处理。

平台为每次调用生成独立的调用号，策略命中、护栏证据与调用详情按这个号关联。调用方传入的 X-Request-Id 单独保留为「调用方请求 ID」，可先按它搜索请求，再打开详情查看全部命中。路由策略和提示词模板中有两个请求号变量：{{request_id}} 是平台调用号，插件上下文也使用它；{{client_request_id}} 是调用方传入的 X-Request-Id，与调用方系统对账时用它，未传或格式不合法时为空，引用它的请求头照常设置、值为空。重复使用调用方编号的不同请求仍分别记录。

4. 配置全局限额

4.1 列表与来源

进入「流量规则 → 全局限额」，先在页签右侧选择调用类型（模型调用、MCP 调用、A2A 调用、API 服务），列表只显示该调用类型的限额。可按「限额类型」筛选。

调用类型为 MCP 调用时，列表顶部说明上游调用超时口径：未被已启用的超时限额覆盖的调用，使用系统默认值（连接 5000 毫秒、请求 30000 毫秒）。限额的计数维度或匹配条件不是所选调用类型实际产生的信息时，该行显示「计数维度不可用」及原因，这条限额不会生效，需改用该调用类型提供的字段。限额保存后若提示「限额已保存，尚未同步到模型网关」，系统会自动重试，同步完成前网关可能仍使用之前的配置。

4.2 新建限额

1. 选择「新增限额」，打开「创建全局限额」画布（「限额编排」）。
2. 在「请求计数入口」中选择「限制类型」：请求次数、并发限制、熔断、非法尝试保护、上游调用超时。切换类型会把阈值重置为该类型的默认值，名称和匹配条件保留。「名称」可留空，留空时使用限额摘要作为名称；限额编号由系统分配。
3. 在「计数对象」中设置匹配条件，请求次数和并发限制还需选择「计数维度」，见第 4.3 节。
4. 在「限额配置」中填写阈值，在「超限处理」中选择处理方式。
5. 在右侧「调试与预览」中，「试运行」可模拟「未触发限额」与「触发限额」两种情景（不发送请求、不读取实时计数），「配置检查」列出待完善项。条件目录或计数维度目录尚未加载完成时，发布暂停，页面提示「目录暂时无法加载，发布已暂停。」或相应的加载提示。
6. 选择「启用全局限额」发布；编辑已有限额时选择「保存全局限额」。

编辑已有限额时不能更改限制类型；需要换类型时新建一条。删除限额后无法恢复，需要时重新创建。

新建限额时各类型的预填值（均可修改）：

4.3 匹配条件与计数维度

匹配条件决定哪些请求受这条限额约束；计数维度决定这些请求如何分别累计。例如只匹配客服模型、按 API 密钥计数，表示每个 API 密钥对客服模型的请求分别计数。改变匹配条件不会自动改变计数维度，编辑时分别核对。

匹配条件有两层：

• 统一条件：与规则清单相同的条件类型，见第 2.5 节，但只列出所选调用类型实际产生的条件：「URL 参数」只用于模型调用和 API 服务；客户端声明的模型名、请求含敏感信息、意图类条件只用于模型调用；「工具名」只用于 MCP 调用、连接器调用和 API 服务；「MCP 方法」只用于 MCP 调用；「数据来源」不用于 A2A 调用和 API 服务。按网段限流使用其中的「客户端 CIDR」。
• 保留的匹配条款：按调用方身份、客户端 IP、路由、模型、模型分组、实际上游、能力、能力类型、应用、所属部门、职能组、依赖、端点、MCP 服务或工具、服务名与服务命名空间、部署环境与部署区域等字段匹配，比较方式为「等于」（只能一个值）、「属于其中之一」「不等于」。条款中的「按客户端 IP」按完整地址精确比较，不做网段包含。

已添加统一条件时，保留的匹配条款暂不参与匹配；删除全部统一条件后条款重新生效。两层都为空时，限额对所选调用类型的全部请求生效。每层最多 16 个条件，跨条件全部满足才匹配；同一字段上两条肯定条件的取值必须有交集，否则页面阻止保存。

计数维度可多选，选择多个维度时按取值组合计数。可选项以所选调用类型为准，包括按 API 密钥、按 API 密钥（直连调用）、按用户、按调用方分组、按内部服务、按客户端 IP、按会话、按路由、按模型、按实际上游、按模型分组、按应用、按所属部门（逐部门计数）、按职能组（逐组计数）、按 MCP 服务、按 MCP 工具和按标签等。会话只能作为计数维度，不在匹配条款中提供；「按会话」只对模型调用、MCP 调用和连接器调用提供，A2A 调用和 API 服务没有会话标识。按会话计数时，只有带显式会话身份的请求按会话分别计数，按对话历史续接归入的会话和无法识别会话的请求不计入此维度，Responses 续接请求沿用上一轮的识别方式；识别顺序与取值要求见《Zentrix Gateway 用户手册》第 15.5 节。选择计数维度前确认真实入口会提供该信息。

4.4 请求次数、超限处理与临时阈值

在「限额配置」中为每个时间窗填写「周期内请求数」和「即时突发量」。时间窗可选秒、分钟、小时，最多 3 个，同一周期不能重复，数值须为正整数；「周期内请求数」不能超过该时间窗的微秒数（秒 1,000,000，分钟 60,000,000，小时 3,600,000,000）。这是按时间持续补充的滚动限速，不是到整点清零的配额；多个时间窗同时生效，请求需满足每个时间窗。即时突发量用于容纳短时峰值，平时不占用额度。

「超限处理」可选：

「额度用完时」另有两个选项：「直接拒绝」，或「先占用公共额度，公共额度也不够才拒绝」。公共额度指同一调用类型下只按租户计数的请求次数限额；不存在这样的限额时仍按拒绝处理。

开启「启用临时阈值」时：

1. 为每个时间窗填写临时请求数和临时突发量。临时值都不得低于基础额度，且至少一项高于基础额度。
2. 填写开始和结束时间。结束时间须晚于开始时间且晚于当前时间，窗口最长 30 天。
3. 到期后数据面自动恢复基础额度，无需再次发布。临时阈值只放宽流量阈值，不延长凭据有效期，也不授予模型访问权。

4.5 并发限制

并发限制统计同时执行的调用数，不是一段时间内的调用总数。

• 「并发上限」：正整数，达到后新请求立即被拒绝，不进入队列。模型调用返回 429。
• 「恢复阈值（可选）」与「并发硬上限（可选）」：须同时填写，并满足“恢复阈值 < 并发硬上限 ≤ 并发上限”。达到硬上限后拒绝新请求，并发数低于恢复阈值后恢复接收。
• 「为优先请求保留的名额（可选）」：0 到并发上限减 1。繁忙时普通请求最多用到“上限减保留名额”，余下名额只放行优先请求。
• 「繁忙时的优先级」：0–3 的整数，0 为普通，3 为最高。一个请求同时命中多条带优先级的并发限额时取最高档。档位只决定繁忙时谁能用保留名额，没有保留名额的限额中优先级不起作用。

核心业务优先：繁忙时给核心业务留出名额，需要两条并发限制配合，在同一调用类型下各新建一条：

1. 池子：匹配条件覆盖要保护的全部请求（例如某个模型分组），计数维度选「按模型分组」，填写「并发上限」（例如 20）和「为优先请求保留的名额」（例如 5），「繁忙时的优先级」保持 0。
2. 授予优先级：匹配条件只圈出核心业务（例如指定调用方或请求头），计数维度与第一条相同，「繁忙时的优先级」填 1–3，不填保留名额。这一条本身也是一个并发池，「并发上限」不要低于第一条，否则核心业务会先被它挡住。

按上面的数值，繁忙时普通请求最多同时执行 15 个，核心业务可以用满 20 个。两条的匹配条件和计数维度都不要用「实际上游」「路由」「端点」「依赖」或「标签」：用到这些信息的并发限额在选定上游之后才判定，和选定上游之前判定的限额分开取优先级，核心业务拿不到保留名额。验证时让普通请求占满 15 个名额，再分别发一个普通请求和一个核心业务请求：前者返回 429，后者放行。

4.6 非法尝试保护与上游调用超时

非法尝试保护需要填写「统计窗口（秒）」「非法尝试次数阈值」和「暂停时长（秒）」，均为正整数。统计窗口内非法尝试达到阈值后，暂停该匹配对象的请求，暂停期间返回 429。当前由 MCP、A2A、API 服务等能力调用在下游凭据校验失败时计入，不统计普通的 HTTP 失败；验证时确认请求确实经过对应入口且事件被识别。

条件把「MCP 方法」限定为「列出工具」时，不支持熔断、上游调用超时和「返回固定应答」，也不提供按 MCP 工具、按应用、按实际上游、按会话等计数维度；限定为「资源」或「提示词」时不提供按 MCP 工具。相应选项置灰并提示「当前 MCP 方法不支持此配置，请选择其他配置。」

上游调用超时包含「连接超时（毫秒）」和「请求超时（毫秒）」，范围均为 50–600000，连接超时不得大于请求超时。连接超时限制建立上游连接的等待时间，请求超时限制整个上游请求（含响应体）的时长。达到超时后终止本次上游调用；配置了故障转移时，后续处理由故障转移规则决定。熔断中的「慢调用阈值」只用于熔断统计，不会中断慢请求。

4.7 创建调用方临时豁免

在独立限额行的「更多操作」中选择「创建调用方临时豁免」。系统新建一条独立的豁免配置，不修改原限额；匹配字段沿用原限额的第一个匹配字段，取值需重新确认。

1. 核对调用方、匹配范围和「豁免类型」。可选类型为请求次数、并发限制、熔断和非法尝试保护，不包含上游调用超时。
2. 填写「原因」和「到期时间」。普通豁免最长 7 天，到期时间须晚于当前时间。
3. 开启「豁免平台强制限额」时，有效期最长 2 小时。只在确有授权的应急场景使用。
4. 保存后分别用豁免范围内与范围外的调用验证；到期后再次检查原保护恢复。

豁免按类型生效：它适用于指定类型的所有匹配限额，并非仅适用于发起豁免的那条限额。豁免不等于身份认证、模型授权或其他配额的豁免。

5. 处置动作与异常处理

5.1 动作清单

在画布中选择「添加处置动作」，或在已有动作节点后选择插入按钮，从列表中选择动作。列表按「请求转发前」「收到上游响应后」「其他」三组排列：前两组是按执行阶段排在画布上的动作，「其他」组放决定请求去向的动作和对整条规则生效的设置，后者不占画布的执行顺序。不满足依赖的动作显示为不可选，悬停可查看原因；动作节点内的「动作类型」可替换为其他动作。

「放行」与「拒绝本次调用」不能与其他动作共存。一条规则中的动作须要求同一种调用类型；需要不同调用类型的动作请拆成两条规则。画布按网关固定的执行阶段排列动作，不支持任意连线。

5.2 内容检测与提示词

内容检测在规则中决定哪些请求送检、检测哪些项目以及命中后的处置。检测项、模板、判断模型和处置方式的完整说明见《Zentrix Gateway 用户手册》第 14 章。

内容检测按检查对象分为两张卡，可分别添加、删除：

• 「内容检测 · 对话内容」：检查用户提问与模型回复。「检查阶段」选「用户提问」「模型回复」或「用户提问与模型回复」，一条规则只有一个检查阶段；需要“提问查关键词、回复做模型判断”这类组合时拆成两条规则。检测方式可勾选「敏感信息」「关键词」「必答问答」「模型判断」（风险分类、提示注入与自定义类别）。
• 「内容检测 · 工具调用」：检查智能体调用工具时的参数与工具返回的结果，不检查对话内容；用于模型调用、MCP 调用和 API 服务，添加时调用类型未限定的会自动补上「模型调用」。
• 「恶意来源」：勾选「检查出站地址是否命中恶意库」，「命中后处置」选「拦截」或「仅记录」。它在代理、工具执行与影子流量的出站请求上检查目标地址，不检查对话内容和工具参数，可不配内容检测单独开启；「拒绝本次调用」规则不提供。租户尚未接入恶意库时提示「尚未接入恶意库，勾选后暂不生效。」，并提供「前往接入恶意库」。多条规则同时开启时取更严的处置。

「模型判断」需要「内容判断模型」，「敏感信息」中的人名、地址、机构名需要「敏感信息识别模型」，「必答问答」需要「问答语义匹配模型」。这三个判断模型在「系统设置 → 全局设置 →「常规」页签 → 默认模型」中设置；在规则编辑器中勾选对应项而模型尚未设置时，右侧打开「设置内容判断模型」等抽屉就地设置，选择「保存并使用」。判断模型全租户共用一个，修改后所有规则同时生效；未设置时保存会被拒绝。

「对话内容」卡勾选了「敏感信息」「模型判断」或「必答问答」时，卡内出现「判断模型不可用时」，可选「放行」或「拒绝」，新建时默认「拒绝」；「工具调用」卡配置了模型判断时也有这一项，两张卡分别设置、互不影响。高风险业务保持「拒绝」。

「对话内容」卡的「回复话术」中，「拦截回复」可选「系统默认话术」或「自定义话术」；选「自定义话术」后填写「默认回复话术」，并可为每个风险分类另填「该分类的回复话术（可选）」。话术只在内容被拦截时使用，分类话术优先；脱敏、仅记录或放行时不使用，必答问答命中时返回标准答案。取消勾选「模型判断」「必答问答」或删除整张卡时，页面先确认是否清除这项检测的设置。

检查阶段、拦截返回与引用就绪

检查阶段的作用面。 「用户提问」在请求发往目标模型之前检查，「模型回复」在模型回答返回调用方之前检查，「用户提问与模型回复」两者都检查；试运行与接口中分别对应 input、output 和双向。两种接入方式——OpenAI 兼容入口（使用模型 Key 调用 /api/v1/agent-gateway/openai/v1/*）与网关原生入口（/v1/*）——对输入、输出两个方向都执行，判定口径一致。只挂内容检测、不指定转发目标的增强规则同样检查模型回复。两种入口的差异仅在于流式放行的时机，见下文“流式输出的护栏行为”。

调用方收到的结果。

同一条命中在两种入口返回相同的 message、code 与 details 结构。调用方应按原因码区分“内容被拦截”（修改请求内容）与“检测不可用”（联系管理员恢复检测服务），不要把后者当作网络故障原样重试。各字段的示例见错误参考的“内容策略命中与检测不可用”一节。「判断模型不可用时」选择「放行」的，请求照常处理。

引用对象必须先就绪。 内容检测段引用的租户词库、问答集必须已发布成功。引用尚未发布成功的对象时，保存或配置发布会失败，并在流量规则页指出缺少的对象；已保存的规则若因引用对象失效而不可用，规则列表会标记“当前不可用”并给出原因。不会出现“保存成功但运行时不生效”的情况，也不会因此拒绝不含敏感内容的正常请求。

流式输出的护栏行为

• 区分三种检查阶段，只检查模型回复不能替代对用户提问的防护。
• 「仅记录，放行」「拦截」「脱敏后继续处理」等处置的结果不同，须分别用样例验证。
• 多条规则命中时，检测类型合并，同一类型取最严格的处置，整次请求只送检一次；应检查完整规则链。
• 「模型判断」选择的类别或提示注入不被当前内容判断模型识别时，编辑器提示「当前内容判断模型不识别：…，选择这些类别不会命中」；内容判断模型只能识别固定分类时，自定义类别不可用。
• 「检查阶段」包含模型回复时，流式响应同样受检：规则层逐段检测，模型判断逐句进行，命中拦截时网关在命中处中止并按调用协议发送终结帧，中止后按上游实际用量计费，见《Zentrix Gateway 用户手册》第 14.10 节。各协议终结帧的形态见错误参考的「流式护栏中止的终结帧」一节。

「提示词」动作引用提示词库中的提示词，字段为「选择提示词」「版本标签」（production 或 latest）和「注入位置」（「前置」或「后置」）。节点显示引用的版本；提示「当前标签为其他版本，未发布」时，应确认发布关系，不能只看提示词名称。「查看提示词」打开对应提示词详情。

内容检测 · 工具调用、MCP 工具许可与 API 服务匹配规则

• 工具调用匹配规则与自定义类别： 匹配规则只按各自填写的工具模式（精确名或 * 前后缀通配）生效，不经过“检测哪些工具”的范围筛选；按「字段」中填写的路径（点号分隔，如 args.content）取值，留空时遍历全部字符串叶子并先解开一层 JSON 转义再匹配；调用参数非合法 JSON 时对原始字符串做全文匹配并在证据中标记 argsMalformed；例外只豁免与它重叠的那一处命中，其余命中照常处置。语义注入由内容安全负责。
• 模型判断范围与提示词缓存影响： 模型判断（内置类别与租户自定义类别）只作用于模型调用（策略条件只含 MCP/连接器/API 服务时不可配置类别与分类器）；入向工具结果规则命中并改写为“该内容已被拦截”会改变历史消息内容，从而使该位置之后的上游提示词缓存失效。保存时若规则中的工具名尚未出现在目录或近 30 天调用记录中，编辑器会给出工具名核对提示，提醒核对拼写。
• MCP 工具许可与存量迁移： 原 MCP 服务详情页的独立护栏已整体并入流量规则，使用“工具名”“组织成员”“MCP 方法”条件配合拒绝动作或工具调用防护实现。升级时存量配置会自动转换为排在租户现有策略之前的流量规则，命名格式为 MCP 护栏迁移 · {服务名} · {项}（项为「工具许可」「参数内容规则」「默认处置」「请求体上限」或「需人工改写」）；含环视/反向引用正则或含通配符的精确工具名及带 argumentContains 的放行项会转为 MCP 护栏迁移 · {服务名} · 需人工改写 拒绝规则。/v1/execute 扩面后，命中含组织成员条件的拒绝规则且无触发用户（如服务账号）时按 fail-closed 拒绝。
• API 服务匹配规则： 在 API 服务调用类型下，“调用参数”位置对应检查请求体，“返回结果”位置对应检查响应体；JSON 正文按字段指针或全部字符串叶子匹配，纯文本正文按全文匹配，二进制体不检查。

工具调用联网控制

「联网控制」是工具调用防护里的一个分组，限制模型通过抓取工具、命令行或网络搜索访问外部网址。保存后，后端把这段设置编译成工具规则。「网址白名单」「网址黑名单」「调用即拦截」三种匹配方式只由联网控制生成，「匹配规则」里不能手写。

• 模式： 四选一。「不限制」不生成任何规则，其余设置隐藏；「只允许访问指定网址」只放行允许名单内的网址；「禁止访问指定网址」只拦截禁止名单内的网址，其余放行；「禁止联网」拦截所有受控抓取工具的调用，不需要填写网址。切换到后三种模式时，受控工具默认为 WebFetch、网址参数默认为 url，两个勾选项默认勾选。在两种名单模式之间切换时，只保留新模式对应的名单。
• 网址条目写法（两种名单通用）：
• 域名条目按「域名[:端口][/路径前缀]」填写，例如 www.example.com/chinese/data。域名精确匹配；*.example.com 只匹配子域名，不包括 example.com 本身。路径前缀按路径段比较：/a 匹配 /a/b，不匹配 /ab。
• IP 条目写成 10.1.2.3、10.1.2.3:8080 或网段 10.0.0.0/8；IPv6 写在方括号里，例如 [fd00::1]、[fd00::]/8。IP 条目不能带路径，网段的主机位必须为 0。
• IP 条目只匹配直接写 IP 的网址。网关不做域名解析，域名条目和 IP 条目互不换算：名单写 1.2.3.4 时，即使 evil.com 解析到该地址，访问 https://evil.com/ 也不会命中这一条。
• 写了端口只匹配该端口。不写端口时，允许名单只匹配该协议的默认端口，禁止名单匹配所有端口。
• 查询参数不参与判定。条目里不能写协议或查询参数。
• 保存时域名统一转为小写，去掉末尾的点，国际化域名按标准转换；保存后页面显示规范化后的结果。
• 只允许访问指定网址： 允许名单外的网址一律拦截。网址无法解析、协议不是 http 或 https、带账号密码、路径含歧义写法，或者是 IP 直连而名单里没有对应的 IP 或网段，都按名单外处理。主机在名单内、只是端口不在时，拦截原因显示「端口不在允许网址内」：条目不写端口时只允许该协议的默认端口。
• 禁止访问指定网址： 拦截禁止名单内的网址，其余放行。为防止换写法绕过名单，调用里找不到网址参数、网址无法解析、协议不是 http 或 https、带账号密码或路径含歧义写法时同样拦截。因此受控工具的网址参数名填错时，该工具每次调用都会被拦，命中记录的拦截原因显示「调用里没有网址」。换用镜像站、新域名或 IP 直连可以绕过禁止名单；需要严格控制出网时，使用「只允许访问指定网址」。
• 受控的抓取工具： 每行填写工具名和网址所在的参数名，默认一行是 WebFetch 与 url。客户自定义的抓取工具或 MCP 抓取工具，需要在这里另加一行。工具名旁会显示最近是否见过该工具的调用；未见过时提醒核对工具名是否写错。
• 两个勾选项（默认勾选）：
• 「同时拦截命令行里的联网命令」：只识别出现在命令开头的 curl、wget、ssh、scp、ftp、nc、telnet 等联网命令，包括经分号、&&、管道等连接的下一条命令的开头。grep curl notes.txt、cat ~/.ssh/config 这类只是提到这些词的命令不会被拦。通过脚本、改名或其他程序发起的联网识别不到；经编码、拼接变量等方式改写的命令同样可能绕过。
• 「同时禁止网络搜索」：拦截 WebSearch 的调用。
• 试一试： 输入一个网址，按表单当前的设置判定，显示「放行」或「拦截」及原因，例如「拦截 · 域名不在允许网址内」「拦截 · 在禁止访问的网址内」。试一试不保存设置。
• 命中后： 选「只记录」时只记录不拦截。该设置对本策略所有工具规则生效；同一请求命中多条策略时，与其他策略按最严格的处置执行。每条策略只有一段联网控制。多条策略的联网控制各自判定，任一条判定拦截即拦截：允许名单的效果是取交集，需要放行的网址应写入每条相关策略的允许名单；禁止名单的效果是取并集。
• 拦截后模型看到的内容： 网址白名单拦截时，模型收到说明，列出允许访问的网址（条数有上限，超出时注明总条数），并被要求不要换其他方式重试。多条策略的联网控制同时生效时，说明只列出每条策略都允许的网址，避免模型照着说明访问另一条策略不允许的网址。网址黑名单拦截时，说明只指出该网址禁止访问，不列出禁止名单。同一次请求中拦截次数达到上限后，网关停止续接并返回命中编号。
• 命中记录： 命中详情显示「来源」（联网控制或自定义规则）、「访问目标」（域名与路径，不含查询参数）和「拦截原因」。允许名单的命中可点「加入允许网址」：页面进入该策略的编辑状态，展开联网控制分组，把目标加进允许的网址：域名目标加入域名与路径前缀，IP 直连目标加入该 IP（端口不是默认端口时带上端口）。这只改表单，需管理员确认保存后才生效。若加入的是整个站点（没有路径前缀），页面会显示「将放行整个站点」。若另有已启用策略的联网控制也不允许该网址，命中详情会列出这些策略，每条都可直接跳转加入；命中记录不含判断这些策略匹配条件所需的全部信息，只有同一请求也符合它们的匹配条件时它们才会拦截，加入前应先核对匹配条件。禁止名单的命中不提供加入入口，需要放行时在策略中删去对应条目。联网控制的命中不提供「在策略中添加例外」。
• 检查范围： 「WebFetch」「WebSearch」不再视为只读工具。「检测哪些工具」选择全部时，模型判断也会检查这两个工具的调用。
• 边界：
• 网关只能看到模型经网关返回的工具调用。
• 放行后的重定向和页面脚本发出的二次请求发生在客户程序中，网关不可见。
• 网络层的最终出网控制由客户防火墙或网闸承担。本功能的作用是在模型访问未授权网址时提前拦截并留痕，不保证拦截所有外部访问。
• 客户侧建议：
• 智能体通过网关调用模型。
• 抓取工具不跟随跨主机重定向；若必须跟随，每一跳都用同一份名单检查。
• 不给智能体可联网的命令行；若必须提供，让命令行在无网络的沙箱中运行。
• 不要对共享托管域（如对象存储的公共域名）使用 *. 通配，否则同一域名下其他租户的站点也会被放行。

图文联合检测

• 检测流程与远程图片内联： 在「内容检测 · 对话内容」卡的图片检测中开启「检测图片内容」并选择「图片理解模型」（规则 YAML 为 action.guard.content.image），即选择支持视觉输入的图片理解模型（model.modelId）后，网关将输入图片（及 /v1/images/generations 生成图）转写为结构化描述、图中文字与指令标记，并以 ⟦图片 k⟧描述：…；图中文字：…⟦/图片 k⟧ 插入安全层输入，交由词库、敏感信息与内容安全统一检测（敏感信息命中图片转写且动作为打码时自动升级为拦截）。远程图片（http(s)://）由网关拉取检测后替换为内联 data: URI 再转发给目标模型，确保上游模型收到的就是被检测的那份字节。
• 数据流向、缓存与白名单： 图片数据会发往图片理解模型与目标模型；网关节点在本地保存 24 小时转写缓存（按租户、图片内容 SHA-256、模型与提示词版本索引）。远程拉取默认只允许公网地址（拒绝私网、回环、链路本地与云元数据地址），公网图片不用填写；内网图源需在「允许拉取的内网图片主机」（YAML 为 allowedFetchHosts，最多 32 项）中显式填写主机名。填在这里的主机按内网处理：所选图片理解模型是外部服务时，这些主机上的图片不会发给它，按规则「判断模型不可用时」的设置处置。
• 规格、预算与计费： 单图上限 20 MiB，单次请求最多 8 张未缓存新图（合计 40 MiB），拉取连接超时 3 秒、读取超时 10 秒，最坏额外时延约等于一次视觉模型调用。图片中若检出针对识别或审核的指令，该段转写会强制送越狱检测。图片理解调用以 guard_image_understanding 计入租户账单与用量，在模型分组用量明细中显示为「平台内部调用：图片理解」。
• 图片检测能力边界： 检测结论来自视觉模型的转写，不是确定性 OCR，可能漏识别，也可能被图片里混入的提示注入影响（含指令的转写已强制送越狱检测，见上）。以文件编号引用而不是直接携带字节的图片与文件（Anthropic source.type=file、Responses input_image.file_id/input_file.file_id/item_reference、Chat file.file_id 等形态）不做检测，照常放行，并在策略命中列表中标为「未检测」留痕；这类引用形态可能被用来绕过检测，是已知边界，不是实现缺陷。
• 附件检测能力边界： 随请求直接携带内容的 PDF、Word（.docx）、PowerPoint（.pptx）、Excel（.xlsx）、CSV、纯文本、Markdown 与 RTF 附件按敏感信息与内容安全检测，工具读取文件后在工具结果中发出的附件同样检测；附件检测没有单独开关。敏感信息配置为打码时，命中的附件改为脱敏后的文字发送（以「[附件 第 N 个附件，已由网关脱敏，原文件未发送]」开头），原文件不发出，会话详情中显示这段脱敏文字及「已由网关脱敏，原文件未发送」标注；附件中图片的命中无法打码，按拦截处置；PDF 扫描页与文档内嵌图片只在开启图片检测时检测。身份证号、手机号等按识别规则判定的类型覆盖附件全文；人名、地址、机构名等需要模型识别的类型与内容安全判断，每次请求只覆盖附件文字的前约 1 万字（32 KiB），超出部分放行并在策略命中列表中记「未检测 · 附件超出模型识别范围」。单个附件上限 20 MiB、300 页（幻灯片、工作表）、提取文字 4 MiB、解析 3 秒，超出上限、附件加密、解析失败或网关同时解析的附件过多时，按规则「判断模型不可用时」的设置处置。旧版 Office（.doc/.xls/.ppt）、其它格式与以文件编号引用的附件不做检测，照常放行，并分别记「未检测 · 旧版 Office 格式」「未检测 · 文档格式不支持」「未检测 · 文件以编号引用提交」。

多轮拼接诱导防护

在「内容检测 · 对话内容」卡的多轮对话设置中可分别开启三项（规则 YAML 为 action.guard.content.multiTurn 下的 reassembleShortMessages、cumulativeOutput、sessionEscalation），默认都不开启：

1. 拆分输入检测： 按用户撰写的消息顺序（跳过助手回答与只含工具结果的消息）滑动检查，6 条以内有至少 3 条可见字数不超过 8 个（先做兼容字符归一化，再去掉标点、表情符号、零宽字符与空白）的短消息时，把这一段的可见文字连起来，交给词库、敏感信息与内容安全检测。命中依据显示为“跨消息拼接 · 第 i–j 条用户消息”；拼接内容无法回写，敏感信息配置为打码时按拦截处置。
2. 多轮回答合并检测： 输出方向的内容安全判断带上本轮提问之前的历史对话（从末尾往前截取，最多 4096 个字符），本轮回答与历史回答合并判定，命中即中止本轮。流式输出仍按句扣留、逐句判定，每句判定多出的输入以 4096 个字符为上界；词库与敏感信息不跨轮拼接。
3. 会话多次命中限制： 同一会话在时间窗（10 分钟、30 分钟、1 小时、6 小时、24 小时）内新内容的命中（明确命中、疑似命中、越狱命中）达到设定次数（2–20 次）时，在持续时长内“拒绝该会话的后续请求”（直接返回拒答话术，不调用上游与判断模型）或“将疑似命中按明确命中处置”。同一段内容在时间窗内只计一次：历史里的旧命中随新消息反复送检不会重复累计，拆分输入检测的窗口滑动时已计过的用户消息也不再重复累计。

无论是否开启以上三项，入向检测都会补送历史助手回答。

超长对话的送检口径： 系统文本、全部用户撰写的文本与本轮新增内容（最后一次助手回答之后的消息，含本轮工具结果）一定送检，放不下时按“护栏出错时”处置；历史工具结果与历史助手回答在剩余容量内尽量送检（工具结果优先、新近优先），送不下的部分不算超限，字节数记入命中证据的 historyUncheckedBytes。因此把载荷藏进伪造的早期用户消息再用填充挤出容量的做法不能绕过检测。

会话累计口径：

• 会话累计以调用方提供的会话标识为准，更换标识即视为新会话；应由应用服务端生成不可猜测的会话标识。
• 各网关节点分别在本地累计，不跨节点共享；只有模型调用参与会话累计，MCP 调用不参与。
• 命中内容的去重摘要由各节点用节点自身的密钥计算，节点密钥轮换后，时间窗内已累计的命中按新内容重新计数（最长一个时间窗）。

处理误伤： 在“策略命中”中可按“会话状态：已限制”筛选。“标记误判”作用于触发会话限制的那条命中、且操作者有流量规则管理权限时，会同时解除该会话的限制，各网关节点在下一次配置下发后恢复。标记的不是触发命中，或操作者没有流量规则管理权限时，只记录误判标注，限制保持。“查看会话”会打开会话详情并定位、展开到命中所在的那一轮。

升级说明与试运行接口

• 滚动升级： 滚动期间，旧版本节点上本租户的 tenant_config 与 mcp_protection 两类配置段冻结在最后一次可用的版本，旧节点继续按旧规则执行，节点升级完成后自动恢复。网关节点须在控制面可达时滚动。
• 规则 YAML 的写法： 护栏写在 action.guard 下的 content（对话内容）、toolCall（工具调用）、threatIntel（恶意来源）三段中，至少写一段；不挂护栏时省略 guard。把 stage、onGuardError 等写在 guard 顶层的旧写法会被整份拒收，导入旧文件前须按三段改写。
• 试运行接口： 流量规则的试运行可经管理接口调用。JSON 形态使用 POST /api/v1/admin/route-policies/simulate：direction 为 input 或 output，messages 为 [{role, text, attachments}]，测试附件（图片或 PDF、Word、Excel 等文档）以 data:<类型>;base64, 形式放在 attachments 里，输出方向用 answer 填本轮回答。页面带图试运行使用 simulate/with-attachments（表单上传）。试运行与网关走同一条判定路径，规则里关闭的开关在试运行里同样不生效，结果给出依据与分段耗时（图片转写、内容判定）。

5.3 改写请求与响应

• 「改写请求头」「改写响应头」：操作为「设为」「追加」「删除」，头名称最多 128 个字符，同一规则内不能重复。Host、Content-Length、Content-Type、连接控制类等请求头不允许改写；网关管理的响应头不能改写。修改敏感请求头时保存前需二次确认。
• 不允许改写的请求头：host、set-cookie、content-type、content-encoding、content-length、connection、keep-alive、te、trailer、transfer-encoding、upgrade。
• 不允许改写的响应头：content-type、content-encoding、content-length、authorization、proxy-authorization、proxy-authenticate、www-authenticate、set-cookie、location 及连接控制类响应头。
• 以 x-lp-、x-zr- 开头的网关内部头，以及 x-zenova-route-rule、x-zenova-route-sample，请求头和响应头都不可改写。头字段值不超过 4096 字节，不能包含换行和空字符；删除头字段时不能填写值。
• 「改写请求字段」：用 JSON Pointer 定位字段，例如 /metadata/channel，操作为「新增」「覆盖」「删除」「复制」「搬移」；复制和搬移须填写「来源位置」，值按 JSON 格式填写，文本需带双引号。
• 「改写请求正文」：在请求体中复制、搬移字段，或把字段「转成文本」「转成数字」「转成是否」。
• 「改写响应字段」：调整最终非流式响应，可用「只保留列出的字段」保留 1–16 条路径。
• 「状态码映射」：把指定的上游状态码换成另一个状态码返回调用方，只能配在会改变目标或拒绝请求的规则上。不要把上游失败不加区分地包装为成功。

每类改写一条规则最多 16 项。路径以 / 开头、不超过 160 字节，字段名中的 / 和 ~ 按 JSON Pointer 规则转义。请求改写不能改动路由目标模型或网关保留字段，也不能通过改写 /model 或受保护请求头绕开模型选择和授权。真实密钥只在受保护的凭据入口配置，不要写进规则名、普通值或截图。

保存后分别测试正常字段、缺字段、空值、类型不符、上游失败和流式调用。模拟命中只证明规则判定，改写结果须从上游请求或调用方响应核对。

5.4 Token、请求体与推理指令

• 「单次请求 Token 上限」：填写「最大输入 Token」和「最大输出 Token」中的至少一项，范围 1–10,000,000。输入超限时在发给供应商前拒绝，并告知调用方这是平台限制；输出上限会改写请求的 max_tokens。
• 「请求体大小上限」：单位 KB，范围 1–32768（即 32 MiB 全局硬顶）。按入站原始请求体在鉴权、模型解析和正文改写之前判断，超出时返回 413。
• 「推理指令」：「推理」可选「开启」或「不开启」；开启时「推理强度」可选「默认」「低」「中」「高」，默认按中档补充。调用方已指定推理参数时以调用方为准；「不开启」只表示平台不补充，不会删除调用方已带的参数。目标模型不支持所选档位时自动折到最接近的一档。多条规则命中时取优先级最高的那条。

多条规则同时设置 Token 上限或请求体上限时取最严的值。

对外模型名

「对外模型名」决定命中本规则的模型调用在响应中向调用方返回哪个模型名，有两种方式：

• 「显示请求模型名」：返回调用方请求时填写的模型名。
• 「固定名称」：返回填写的名称。名称最多 128 个字符，首尾不能有空格，也不能包含换行等控制字符。

适用场景：上游余额耗尽或故障时，规则把请求兜底到其他模型，同时希望调用方看到的模型名与请求保持一致。这一动作只在请求的模型与实际执行的模型不一致时才有区别；流式与非流式响应都会改写，包括首段输出、中间各段与结束段。未添加这一动作的规则，响应照常返回上游实际执行的模型名。平台仍按实际执行的模型记录用量与计费。

输出节奏

「输出节奏」把命中本规则的模型调用的出字速度与首 Token 等待压到目标水准：

• 「出字速度」：「固定速度」填写每秒输出 Token 数，范围 1–2000；「按目标模型实测」按调用方请求的模型最近一次基准测速结果执行，没有基准数据时不控速。
• 「首 Token 等待」：「不等待」时首段输出随上游到达即返回；「按目标模型实测」同上；「固定时长」填写等待的毫秒数，范围 1–60000。

适用场景：兜底到更快的模型后，希望调用方感受到的出字速度与首 Token 等待接近原本请求的模型。输出节奏只减速、不加速，仅在上游快于目标时生效；上游本来就比目标慢时不追加等待。

开启这两个动作的代价：

• 并发名额的占用时间会相应变长。调用持续多久就占用并发名额多久，控速拉长了调用时长，同一并发上限下能同时服务的调用相应减少；控速调用与普通调用共用同一份并发额度。
• 非流式响应在返回前整体等待，模拟等待最多 30 秒。
• 添加了「对外模型名」或「输出节奏」的规则不参与语义缓存：缓存命中的回答不经过这两个动作，会暴露实际执行的模型与速度，见第 10.1 节。

「放行」「拒绝本次调用」规则不能添加这两个动作。多条规则同时命中时，各取优先级最高的那条规则的设置。

5.5 规则内限额

「应用限额」只对命中本规则的请求生效，并作为「来自路由规则」的派生限额出现在「全局限额」列表中。节点内先是「请求速率」开关（计数维度、「额度用完时」、时间窗和「临时阈值（可选）」），其下的「并发、熔断与超时（可选）」中有「并发」「熔断」和「上游调用超时」开关。字段含义与范围同第 4 节和第 6 节。

• 超出规则内限额时只能「拒绝本次调用」，并返回配置的原因码；排队、固定应答、非法尝试保护和临时豁免需要在「全局限额」中创建独立限额。
• 规则须将「调用类型」限定为一种，且规则中的条件须是该调用类型实际产生的信息（范围同第 4.3 节的统一条件），例如 API 服务调用的规则不能用「数据来源」条件。限定调用类型后，计数维度按该类型自动核对：已选维度仍可用则保留，都不可用时回落到第 4.2 节所述的预填维度。
• 同一请求可能同时受规则内限额和全局限额约束。
• 规则内限额的预填值：请求速率的计数维度同第 4.2 节、每分钟 100 次、突发 20；并发上限 8；熔断参数同第 6.2 节表中的默认值；上游调用超时为连接 3000 毫秒、请求 30000 毫秒。「并发」中的「繁忙时的优先级」以「最高」「较高」「普通」三档选择；使用恢复阈值与并发硬上限时，同时开启「启用软硬并发阈值与恢复机制」。

5.6 镜像复制

「镜像复制」（节点标题「流量复制测试」）只用于一种明确的 MCP、连接器、A2A 或 API 服务调用，按「复制比例」（1–100%）把请求复制到另一个能力端点。主请求不等待复制请求，复制结果也不返回调用方。复制请求不经过限流和插件，会真实发到复制目标并占用目标服务自己的配额；在请求详情中单独记为一条「镜像请求」，不计入调用方用量与费用。

开启「启用流量复制测试」后，依次选择能力与能力端点作为「复制目标」。新建时「复制比例」默认 100%，「流量去向确认」中的「我确认复制目标可能与主目标位于同一主机」「我确认复制流量可能发送到不同域名」默认已勾选，按实际拓扑核对；不满足所确认拓扑的镜像请求会被跳过。默认不复制可能产生副作用的请求；开启「允许复制可能产生副作用的请求」前，确认复制环境能安全接收创建、删除等调用。

5.7 异常处理

「异常处理」节点只列出当前动作可配置的项目：

• 「系统固定行为」：条件不满足时，不做处理，交由下一条规则判定。
• 「命中处理」：内容检测命中、超出限额、输入超出 Token 上限、请求体超限等情况的处置，在对应动作中设置或固定为拒绝。
• 「组件不可用时」：模型入口的请求字段、请求正文改写失败时，在「模型入口改写失败时」中选择「拒绝请求」（默认）或「原样放行」；MCP、A2A、API 服务入口在「能力入口改写失败时」中选择「保持原样，继续处理」或「拒绝本次调用」。这两项只在规则含请求字段或正文改写、且调用类型相符时出现。选择放行的，请求详情的「请求改动」显示该改写实际未生效、请求按原样放行。请求头、响应头与状态码改写失败时固定拒绝本次调用。
• 内容检测的失败处置不在此节点设置，在「内容检测 · 对话内容」「内容检测 · 工具调用」两张卡中分别设置「判断模型不可用时」，见第 5.2 节。
• 转发目标全部不可用时返回错误；启用故障转移后，按触发条件尝试备用目标，备用目标用尽或达到尝试上限后停止转移。

异常处理不是所有故障的统一兜底：权限不足、配额耗尽、护栏拦截、目标不可用和客户端取消可能在不同阶段结束请求。应测试实际会发生的失败路径，而不只确认异常节点存在。

6. 配置并验证熔断

6.1 熔断解决什么问题

熔断根据已完成的调用样本判断上游是否持续失败或变慢。样本数达到下限且失败率或慢调用率任一达到阈值后，在熔断持续时间内拒绝后续调用、不调用上游；到期后进入半开状态，允许有限数量的探测调用。任一探测失败重新进入熔断，全部探测成功完成后恢复正常处理。

熔断与并发、超时是不同的控制：并发限制同时执行数，超时限制等待时间，熔断依据近期结果暂停后续调用。熔断本身不切换上游；只有配置了故障转移的规则，才会跳过熔断中的候选目标并尝试转移链上的下一个目标。

*图 3：熔断状态示意。半开期间只允许有限数量的探测调用，仍可能拒绝其他请求。*

6.2 从哪里配置

可在规则的「应用限额」中展开「并发、熔断与超时（可选）」并开启「熔断」，也可在「全局限额」中新建限制类型为「熔断」的限额。两处参数含义一致，匹配范围和所属配置不同。对同一业务同时使用两处配置前，明确各自的保护对象并分别验证。

全局限额中，前五个参数位于「限额配置」，「熔断持续时间（秒）」和「半开探测次数」位于「超限处理」。规则内配置时，先将「调用类型」限定为一种。

以上均为整数。「慢调用阈值」用毫秒，其余时间参数用秒。失败类别由入口的实际调用结果归类，不能把所有业务 4xx 都当作上游故障。熔断期间，OpenAI 兼容协议的模型调用返回 503（错误码 TRAFFIC_CIRCUIT_OPEN），Anthropic 协议返回 529；实际排查以所用入口的响应为准。

6.3 用受控失败验证

准备独立的测试调用方与可控制返回结果的测试上游，不要用正常业务制造故障。以下数值只用于验证行为，不能直接当作生产容量配置。

1. 设置统计窗口 60 秒、最小样本 4、失败率 50%、慢调用阈值 30000 毫秒、慢调用率 100%、熔断 8 秒、半开探测 2 次。
2. 保存并确认应用，重新打开详情逐项核对七个字段。
3. 用同一保护对象在窗口内依次发送成功、失败、成功、失败四次请求。前 3 个样本不足 4，不应提前触发；第 4 次后失败率为 50%。
4. 紧接着继续请求，核对熔断拒绝和上游接收计数。拒绝期间被保护的上游不应再收到这些请求。
5. 等待 8 秒后发送探测。让探测失败，应重新进入熔断；再等待并让探测成功，检查普通请求恢复。
6. 保持 2 个半开探测同时执行，再发第 3 个请求，检查探测上限；释放前两个后核对恢复结果。

6.4 用慢调用验证

设置统计窗口 30 秒、最小样本 2、失败率 100%、慢调用阈值 200 毫秒、慢调用率 50%、熔断 8 秒。先发送一次快速成功请求，再发送一次耗时超过 200 毫秒的成功请求。

即使两次都是成功响应，慢调用比例达到 50% 后，下一次请求也可能被熔断。核对实际耗时、响应和上游接收次数，不要只看 HTTP 200 判断不会触发。

停用熔断配置后，等待配置同步并用实际调用确认恢复，不要把停用开关当作即时复位按钮。上线前针对实际拓扑、调用类型和流式请求补充验证。

7. 流量分配与故障转移

7.1 目标方式、档位与权重

「转发到」节点的「目标方式」有两种，切换时会清空已选目标：

• 「请求模型的全部上游」：按调用方请求的模型展开为它当前启用的全部上游，模型新增或停用上游后自动生效，无需修改规则；可以只限定部分供应商。
• 「指定上游」：逐个选择上游，按所属模型归组列出。

非模型调用的转发目标是能力端点：先选能力，再选端点。

一条规则最多 8 个转发目标。第一档为「主要目标」，之后为「备用档位 1」「备用档位 2」等。

• 主要目标按目标选择策略和权重选出一个，未选中的主要目标不会自动作为备用。
• 同一档位的权重（0–100 的整数）合计为 100%，调整一个目标时其余目标按比例分配剩余权重；「平均分配权重」把 100% 按整数尽量均分。权重为 0 的目标不参与分配，同档至少一个目标权重大于 0。
• 同一档位的转发目标不能重复。停用或不可用的目标不会因提高权重而恢复。
• 配置了备用档位但没有启用故障转移时，保存会被拒绝。

例如主要目标中 A、B 分别为 80、20，表示主要目标内的期望分配；备用档位的权重只在进入该档时使用，不与主要目标合计。

7.2 目标选择策略

「质量优先」「成本优先」可填写「容差」（0.1%–50%，不填按默认 5%）。按排名选目标时，不满足请求需要的工具调用、图片、JSON 输出、推理或上下文长度的候选会被排除；全部候选都被排除时改为按权重选一个。只有一个可选目标时，策略不影响目标分配。

7.3 配置故障转移

「上游连接失败或中断」包括连不上上游、连接被上游重置，以及连接建立后链路失去响应：发出的数据 15 秒内得不到确认即判定连接中断，不必等到首内容预算耗尽。「上游超时」只指上游在网关的时间预算内没有返回结果。

1. 将调用类型限定为「模型调用」，在转发节点配置主要目标。
2. 选择「添加备用档位」并添加备用目标。没有备用目标时「启用故障转移」不可开启。
3. 开启「启用故障转移」，选择触发条件（任一满足即转移，最多 16 个）：「上游连接失败或中断」「上游超时」「上游返回指定状态码」「响应内容命中指定条件」。默认勾选上游连接失败或中断、上游超时和状态码 429、500、502、503、504。
4. 指定状态码时每个值须在 100–599 之间；响应内容条件需填写以 / 开头的「响应内容位置」（如 /error/type）和期望值。「触发转移的上游状态码」按名称列出常见的 4xx 与 5xx 状态码，例如 401「上游鉴权失败（密钥无效或已过期）」、403「上游拒绝访问（余额不足或无权限）」、429「请求过于频繁」、503「上游暂时不可用」、504「上游网关超时」，以及 Cloudflare 的 520–526 和 529「上游过载（Anthropic）」。选择 4xx 状态码前确认这类错误换一个目标确实可能成功，否则只会增加重复调用。
5. 设置「总尝试次数」（1–10，包含首次调用，默认 3）和「首内容前故障转移总预算（秒）」（1–600，默认 120）。达到任一上限后不再尝试备用目标。
6. 保存并核对应用状态，在「验证规则」中勾选「模拟主档失败」查看转移链，再制造受控故障检查实际的备用调用。

故障转移按备用档位顺序尝试，同一备用档位内权重较高的目标优先。只有启用了故障转移，失败时才会尝试备用目标；目标排列在后面，或同档有多个目标，都不代表自动转移。

「响应内容命中指定条件」只对非流式请求生效；连接失败、超时和状态码条件也适用于流式请求。转移只发生在向调用方输出首个内容之前，已开始输出的流式响应不会被撤回后改用其他模型。用量与额度计入计量分组，费用按实际执行档位的单价结算。

7.4 会话切换保护

「会话切换保护」让同一会话的后续请求继续使用上一轮的模型。只有新候选在当前策略的首要指标上领先超过切换裕度、且用户轮次达到下限时才切换；正在续传工具调用，或提示词前缀与上一轮一致时不切换。

• 只能配在「质量优先」或「成本优先」策略上，且主要目标至少有两个转发目标。
• 字段：「切换裕度」0.1%–50%（默认 5%）、「最少用户轮次」1–100（默认 1）、「空闲超时」30–86400 秒（默认 300）。
• 会话按《Zentrix Gateway 用户手册》第 15.5 节的顺序识别。按对话历史续接归入的会话和无法识别会话的请求不启用保护。

7.5 影子分派

「影子分派」把被采样的请求（经过请求变换和脱敏之后的请求体）再复制一份，异步发给影子模型，只用于评估。影子请求的失败、超时或丢弃不影响主响应；影子跳过限流，但照常计费，用量按用途「影子」单独记账，不进入主流量统计。响应体不保存，只记录大小、状态、耗时与 Token。

• 需先配置转发目标，影子模型不能与转发目标相同。
• 字段：「采样比例」0.1%–100%（默认 1%）、「并发上限」1–64（默认 2）、「队列上限」1–256（默认 8）、「超时」1–300 秒（默认 30）、「响应读取上限」1 KiB–8 MiB（默认 1 MiB）。
• 删除该动作节点即停止影子分派。配置影子分派的规则，详情页提供「影子对比」，按请求数、成功率、延迟 p50、延迟 p95、Token（输入 / 输出）和成本对比主目标与影子目标。

7.6 实时流量与转移结果核对

设置了转发目标的规则（含能力端点目标），以及带内容检测的规则，在详情查看态提供「规则编排」和「实时流量」两个视图；编辑态只有编排。「实时流量」每 15 秒自动刷新，可暂停，按时间窗汇总为「N 次调用 · 调用成功率 · 转至其他目标 N 次（失败后转出 · 被跳过，最终成功）· 每千 Token 成本」，并按目标列出「配置权重 / 实际占比」「发送次数」「发送成功率」「耗时（中位 / 慢请求）」「转出 · 转入」和「每千 Token 成本」。能力端点目标不显示 Token 成本；备用目标带「备用」标记，实际占比显示「—」。时间窗内规则改过时，页面提示实际占比含修改前的流量。带内容检测的规则另显示「内容检测命中 N 次：拦截 · 仅记录 · 判断模型不可用」的分解与最近命中。

模型目标行中带「›」的数字可下钻：「配置权重 / 实际占比」打开该目标的「首选情况」，列出被选中后的去向（已发送、被跳过）和未被选中的原因（如会话保持到其他目标、不支持工具调用、超出上下文窗口）；「转出」「转入」打开原因表，按原因、对方目标、次数和占比列出，原因如「失败后转出 · 响应被拒（429）」「被跳过 · 目标暂停调用」。点击表中一行打开该条件下的请求列表。选路记录上线前的调用没有原因明细，页面会注明起始时间。

核对转移结果时，先在「实时流量」查看转出、转入原因分布，再下钻到具体请求，在请求详情「路由与改写」的「选路过程」「跳过的候选」「尝试」中核对选中原因、被跳过的候选及每次尝试，记录主要目标与备用目标的接收情况、最终响应、耗时和请求标识。客户端超时应覆盖网关的尝试预算；存在外部副作用的请求要评估重复调用的影响。故障转移仍受权限、额度和目标归属检查。

8. 维护、校验与故障定位

8.1 查找、排序、启停、删除与修改记录

• 搜索：按规则名、规则 ID 或目标模型搜索，至少输入 2 个字符。可按「状态」筛选，并在「筛选」中按「调用类型」多选，或按「能力」选择具体服务（MCP 服务详情的「查看适用的流量规则」即按本服务预填这两项）；结果包含显式限定了该调用类型、能力的规则和未限定的规则。
• 导出：规则清单右上方选择「导出」，把全部规则导出为 YAML 文件。认证请求头值与灰度 Cookie 值不写入文件，文件注释和提示列明被剔除的规则，导入前须补齐这些字段；规则清单未加载完整或没有规则时不可导出。
• 排序：按优先级排列且未搜索、未筛选时，可拖动行首手柄，或在「更多操作」中使用「移到最前」「上移」「下移」「移到最后」调整判定顺序。拖动和「上移」「下移」调整即生效；「移到最前」「移到最后」先打开「确认变更」。调整后验证完整规则链，尤其是增强规则和兜底拒绝规则。
• 启停：使用行内状态开关；勾选多行后可「启用所选」「停用所选」「删除所选」，确认后生效。停用后配置保留，重新启用前核对关联对象是否仍可用。
• 删除：行内「更多操作 → 删除」，在确认框中选择「删除」后立即删除；规则详情中为「删除规则」。删除无法撤销，删除前确认替代路由和保护已经就绪。
• 修改记录：规则详情的「修改记录」按时间列出每次变更的操作人和字段变化。「载入此版本」把该版本载入编辑器并提示「该版本已载入编辑器，发布后才能应用到请求。」，保存并确认应用后才作用于请求；不含可载入配置的版本提示「此版本不包含可载入的配置。」
• 未保存就关闭编辑器时，在「退出规则编辑？」中选择「继续编辑」或「放弃编辑」，放弃不会保存当前草稿。

8.2 常见校验与处理

8.3 保存冲突和运行异常

返回 403、429、502、503、504 时的错误码含义与是否可重试，见错误参考。下表按现象给出排查顺序：

问题反馈至少包括：规则或限额名称及编号、操作时间及时区、调用类型与入口、脱敏后的请求信息、响应状态和错误码、请求标识、预期结果与实际结果。错误码的含义可先查错误参考。不要提交原始 API 密钥、Cookie、个人信息或上游凭据。

9. 意图集

9.1 意图识别模型

意图条件依赖意图识别模型。在「系统设置 → 全局设置 →「常规」页签 → 默认模型」中为「意图识别」选择模型。「意图集 → 内置意图」右上方的「测试意图识别」弹窗顶部显示当前状态，例如「意图识别模型：名称」，或「还没有设置意图识别模型，意图条件不会命中」；模型不可用或所在服务停用时同样提示，意图条件不会命中。

请求命中带意图条件的规则时，网关调用一次意图识别模型，内置维度与自定义意图集合并在同一次调用中判断，单次判断超时为 8 秒。判断不可用（未设置模型、服务停用、调用失败或请求中没有可判断的文字）时意图条件不命中。意图只在模型调用中产生，MCP、A2A 和 API 服务请求不会带有意图信息。

9.2 内置意图

「意图集 → 内置意图」按三个维度列出平台内置的意图目录：

每行显示「意图」和「说明」，「用它建规则」以该意图为条件打开新规则，名称预填为「维度：意图」。

选择「测试意图识别」，在弹窗中输入一条提问后选择「识别」，显示「难度」「类型」「场景」和「内容风险」四行结果；判为难题时另附「因为：…」列出满足的判定标准，判断失败时给出原因。内容风险一行需要已设置内容判断模型，未设置时提示「还没有设置内容安全模型」并提供「去全局设置」。识别会调用判断模型，请使用允许送检的文本。

9.3 自定义意图集

在「意图集 → 自定义意图集」中选择「新建意图集」，填写：

• 「名称」：1–120 个字，不能与已有意图集重名。
• 「说明」：不超过 2000 个字。
• 「识别灵敏度」：「保守」（宁可漏判）、「均衡」（默认）、「激进」（宁可多判）。
• 「意图」：至少一个，最多 64 个。每个意图填写「显示名」（1–120 个字，不能重复）和「一句话描述」（说明什么样的提问属于这个意图，判断模型按这句描述识别）。

在规则条件中选择「意图」，将「意图维度」切换为「自定义意图集（高级）」，再选择意图集和意图。被流量规则引用的意图集不能删除，被引用的意图不能移除，页面会列出引用它的规则。

10. 语义缓存

10.1 开启方式与边界

语义缓存只对命中「开启了语义缓存」的规则的模型请求生效：在规则中添加「语义缓存」动作即开启。命中这类规则的请求先查缓存，问题足够相似时直接返回缓存答案，不再调用模型；未命中时照常调用模型，并把答案写入缓存。没有规则开启语义缓存时，请求不查也不写缓存。缓存只对 OpenAI Chat Completions 格式、消息中只有一条用户消息（可另带系统或开发者消息）且请求体不超过 256 KiB 的单轮请求生效，流式与非流式请求均适用，流式回答也会写入缓存。

• 开启前，先在「管理后台 › 系统设置 › 全局设置 ›「常规」页签 › 默认模型」中设置「语义缓存向量模型」和「语义缓存重排模型」，分别选用向量模型和重排模型。两项都已生效时，规则才能开启语义缓存。保存重排模型时，系统用内置的同义问法与非同义问法样例实际调用该模型，据此确定该模型的命中标准；不能区分两类样例的模型无法保存。没有上游或包含多个上游的模型不能选作这两项。
• 规则编辑器的「语义缓存」节点显示两个模型的状态，未设置或不可用时可在节点上直接打开设置。两个模型未就绪时，保存开启了语义缓存的规则会被拒绝，可先设置模型，或删除规则中的「语义缓存」动作。两个模型仍被开启了语义缓存的规则使用时不能清空，页面会列出这些规则。
• 每次查缓存都会调用一次所选的向量模型；找到相近的已缓存问题时，再调用一次所选的重排模型。两类调用按所选模型计费，在用量与调用记录中分别标为「语义缓存向量」「语义缓存重排」，不占用额度。当前问题，以及同一隔离范围内已缓存的相近问题，会发送给所选模型；选用外部供应商的模型前，请确认数据边界。
• 所选模型被停用、不可用或调用失败时，请求照常调用模型，请求详情写明原因，例如「未参与：语义缓存向量模型不可用」「未命中：语义缓存重排模型调用失败」。所选模型更换了上游后，默认模型页提示需要重新核对，选择「重新核对」完成核对前，缓存不参与。
• 更换语义缓存向量模型后，已有缓存条目不再命中，新条目随请求逐步积累，无需手动处理。
• 使用 OceanBase 作为平台数据库的部署不支持语义缓存。
• OpenAI 兼容入口（使用模型 Key 调用 /api/v1/agent-gateway/openai/v1/*）在网关接入层查缓存，并按本次命中的整条规则链判断能否参与。规则链中出现以下任一配置时，这次请求不查也不写缓存：
• 转发去向要到派发时才确定：多个转发目标、开启故障转移，或目标方式为「请求模型的全部上游」；
• 单次请求 Token 上限；
• 挂载插件；
• 改写请求头；
• 响应改写，包括改写响应头、改写响应字段和状态码映射；
• 检查模型回复的内容检测；
• 对外模型名或输出节奏；
• 「应用限额」之后还有内容检测、提示词、改写请求字段或改写请求正文。

最后一项按整条规则链的执行顺序判断：先按规则在清单中的先后，再按每条规则画布上的执行顺序，限额与这些动作分属不同规则时同样算。请求详情中的原因为「未参与：限额后面还有护栏或改写，要到派发时才执行」；需要缓存参与时，用「下移」把「应用限额」移到这些动作之后，或调整规则在清单中的先后。

限额排在内容检测、提示词和改写之后的规则不影响缓存。转发到单个指定上游、未开启故障转移的规则也不影响，缓存按实际转发到的模型分别记录和命中；该模型在本入口不可用时，缓存不参与。

• 网关原生入口（/v1/*）在选定转发目标之后查缓存，限额和转发规则都不影响缓存参与；重试或故障转移得到的回答不写入缓存。
• 「放行」「拒绝本次调用」规则不能开启语义缓存。
• 一条规则本身同时含有上述配置时，规则编辑器的「语义缓存」节点会提示缓存不参与；多条规则之间的组合不会提示。OpenAI 兼容入口的请求开启了语义缓存但这次没有参与时，请求详情「路由与改写」页签的「请求去向」中显示「语义缓存」一行并写明原因，例如「未参与：规则链含 Token 上限」「未参与：多轮对话不使用缓存」。上线前用同一句话调用两次，在请求详情中确认第二次显示「命中语义缓存，未请求上游」，或检查响应头 x-zenova-cache 为 hit。

10.2 缓存参数

以下参数由平台统一执行，没有可调整的设置项：

缓存始终按租户、模型和所选的语义缓存向量模型分开。修改模型、上游或供应商配置后，系统自动清除本租户的缓存条目；规则链（含规则版本）变化后，旧缓存也不会再被命中。

10.3 调用方控制与结果核对

• 调用方可在请求头 x-zenova-cache-control 中逐次控制缓存，多个指令用逗号分隔、不区分大小写：no-cache 不查缓存但仍写入，no-store 查缓存但不写入，bypass 既不查也不写。指令无法识别时，OpenAI 兼容入口本次不查也不写，网关原生入口返回 400，错误码为 cache_control_invalid。
• 响应头 x-zenova-cache 返回 hit、miss 或 bypass。向量模型、重排模型或缓存存储调用超时或失败时，按未参与或未命中继续调用模型，缓存不会导致请求失败。
• 命中缓存的调用不计费。「运行总览」的「语义缓存节省」统计命中次数和节省的 Token，并给出净节省金额：命中时按该模型当时的价格计算省下的金额，再扣除「语义缓存向量」「语义缓存重排」两类调用的费用；净节省金额只给合计，不按模型拆分。
• 命中缓存的请求不计入速率限制，也不占用租户每月 Token 上限。速率或租户每月 Token 上限用完时，能命中缓存的请求仍返回缓存答案，未命中的请求照常被拒绝。两个入口有以下差别：
• OpenAI 兼容入口：模型分组「可用范围与配额」的额度池在查缓存之前判断，额度池用满时即使能命中缓存也返回 429。
• 网关原生入口：规则链中「应用限额」排在内容检测、提示词、单次请求 Token 上限或请求改写之前时，这条规则的请求速率按执行顺序先检查，命中缓存的请求也计入次数，超限时返回 429。规则限额与全局限额的并发名额都在查缓存和全局排队等待之后才占用：命中缓存的请求、排队中的请求都不占名额；并发已满时能命中缓存的请求仍返回缓存答案。