15. 路由策略与流量保护

返回概览 · 完整版目录 · 下载完整 PDF

「流量规则」集中维护模型与能力调用的路由规则、全局限额、意图集和语义缓存，并提供「验证规则」页面模拟整套规则的判定结果。本章功能均属于动态路由许可模块。规则中「内容检测」动作的检测项、模板与判断模型配置见第 14 章，本章只说明它在规则中的位置。

15.1 入口与生效顺序

15.1.1 入口、许可与权限

从「管理控制台 → 路由策略 → 流量规则」进入。页面顶部有「规则清单」「全局限额」「意图集」「缓存」四个页签；「规则清单」页签右上方的「验证规则」按钮打开独立的验证页面。

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

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

15.1.2 规则如何参与一次调用

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

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

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

15.1.3 如何阅读画布

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

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

画布工具与面板：

• 顶部「YAML 编辑」以 YAML 编辑当前草稿，选择「应用到画布」后回到画布检查。内容不超过 256 KiB，资源引用使用资源 ID。
• 「撤销修改」「重做修改」作用于本次编辑中尚未保存的修改，最多回退 50 步。
• 「收起节点」「展开节点」只改变显示，不会停用动作；底部的「画布缩放」和「流程总览」用于定位较长的流程。
• 右侧「调试与预览」包含「试运行」和「配置检查」两个页签。「试运行」在本地按填写的请求事实预览条件与动作，需要网关求值的条件标为「需要网关验证」，应保存后用「验证规则」核对；「配置检查」列出草稿中的问题，点击问题即定位到对应配置。
• 底部依次显示保存状态（如「有未保存的修改」）、配置检查结论（「配置正常」，或「配置异常」及问题数）、「试运行」「取消」和「保存规则」。仍有待完善的配置时「保存规则」不可用。

15.2 创建规则与配置条件

15.2.1 新建规则的方式

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

15.2.2 创建一条模型路由

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

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

15.2.3 创建一条增强规则

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

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

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

• 同一条规则内的条件之间是“且”关系；同一条件内的多个取值满足任意一个即可。否定比较方式（如「不等于」「不以…开头」「不匹配正则」）表示与全部取值都不符合时才满足。
• 一条规则最多 16 个条件。多数条件可填 1–32 个取值，「调用方」条件可选 1–42 个对象。
• 同一字段上互相矛盾的条件无法同时成立，保存时会被拒绝。“A 或 B”应写成一个条件的两个取值。
• 正则表达式由数据面引擎执行，不支持零宽断言和反向引用。要表达“不以…开头”，改用比较方式中「排除」组的选项。
• 未添加条件的规则在清单中显示「匹配所有请求」，保存前确认它是有意设置的兜底规则并检查其位置。

15.2.5 条件类型

「选择匹配条件」按以下分组列出条件，可用搜索框按名称查找：

15.2.6 调用身份与事实缺失

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

不同入口提供的匹配信息不同。模拟结果中条件显示「请求未提供该信息」时，应补齐真实请求能提供的信息；显示「此调用类型不提供该匹配信息」时，应调整条件或调用类型。配置意图、个人信息类型等条件前，先确认意图识别模型或敏感信息检测已经可用。未检测、检测失败与已检测但值不匹配是不同情况，不能统一理解为“规则配置无误”。

15.3 验证规则与真实调用

15.3.1 保存与确认变更

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

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

• 应用成功后提示「规则「名称」已保存，正在下发到数据面。」，表示配置已提交，运行端可能仍在加载。
• 规则清单中的启停开关、拖动排序和删除在确认后直接生效，不再打开「确认变更」；规则详情中的启停开关仍会打开「确认变更」。
• 规则清单、规则详情和「验证规则」都不显示各网关节点是否已加载新版本。保存后以真实调用验证生效情况。

15.3.2 使用「验证规则」

进入方式：「规则清单」右上方的「验证规则」；或规则详情中的「验证这条规则」，结果默认定位到该规则。两种方式都按整套规则的先后顺序评估。验证页面没有调用记录选择器，请求事实需手动填写。

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

结果区还列出「本次模拟命中的规则链」、模拟选定的路由目标、各目标的期望占比；按排名选目标的策略另显示候选目标的名次、质量分、价格、预计首字时延和是否被排除。勾选「模拟主档失败」时显示后备目标所在档位与转移链；未配置更高档位时提示主档失败后无后备目标。验证按控制面已保存的规则计算，刚保存的规则可能尚未在网关生效。

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

15.3.3 用真实调用完成验证

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

规则详情的「查看命中的请求」打开「概览」的「网关请求」视图，并按本规则筛选；也可在「概览」的「路由策略命中」中核对命中记录并跳转到规则详情。请求被拒绝时，保留调用方收到的完整状态码、错误码与请求标识。状态码与错误码的对应关系见第 10.8 节。

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

15.4 配置全局限额

15.4.1 列表与来源

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

调用类型为 MCP 调用时，列表顶部说明上游调用超时口径：未被已启用的超时限额覆盖的调用，使用系统默认值（连接 5000 毫秒、请求 30000 毫秒）。限额的「计数维度」不被当前数据面支持时，该行显示「计数维度不可用」及原因。限额保存后若提示「限额已保存，尚未同步到模型网关」，系统会自动重试，同步完成前网关可能仍使用之前的配置。

15.4.2 新建限额

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

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

15.4.3 匹配条件与计数维度

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

匹配条件有两层：

• 统一条件：与规则清单相同的条件类型（不含灰度 Cookie），见第 15.2.5 节。按网段限流使用其中的「客户端 CIDR」。
• 保留的匹配条款：按调用方身份、客户端 IP、路由、模型服务、网关模型、能力、能力类型、应用、所属部门、职能组、依赖、端点、MCP 服务或工具、服务名与服务命名空间、部署环境与部署区域等字段匹配，比较方式为「等于」（只能一个值）、「属于其中之一」「不等于」。条款中的「按客户端 IP」按完整地址精确比较，不做网段包含。

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

计数维度可多选，选择多个维度时按取值组合计数。可选项以所选调用类型为准，包括按 API 密钥、按 API 密钥（直连调用）、按用户、按调用方分组、按内部服务、按客户端 IP、按会话、按路由、按网关模型、按模型服务、按应用、按所属部门（逐部门计数）、按职能组（逐组计数）、按 MCP 服务、按 MCP 工具和按标签等。会话只能作为计数维度，不在匹配条款中提供。按会话计数时，按首条用户消息识别会话和无法识别会话的请求不计入此维度，Responses 续接请求沿用上一轮的识别方式；识别顺序与取值要求见第 10.9 节。选择计数维度前确认真实入口会提供该信息。

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

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

「超限处理」可选：

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

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

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

15.4.5 并发限制

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

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

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

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

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

15.4.7 创建调用方临时豁免

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

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

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

15.5 处置动作与异常处理

15.5.1 动作清单

在画布中选择「添加处置动作」，或在已有动作节点后选择插入按钮，从列表中选择动作。不满足依赖的动作显示为不可选，悬停可查看原因；动作节点内的「动作类型」可替换为其他动作。

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

15.5.2 内容检测与提示词

「内容检测（护栏）」在规则中决定哪些请求送检、检测哪些项目以及命中后的处置。检测项、模板、判断模型和处置方式的配置见第 14 章。在规则层面注意：

• 区分输入、输出和双向检测，输出检测不能替代输入防护。
• 「仅记录，放行」「拦截」「脱敏后继续处理」等处置的结果不同，须分别用样例验证。
• 多条规则命中时，检测类型合并，同一类型取最严格的处置，整次请求只送检一次；应检查完整规则链。
• 风险类目和提示注入检测需要在「系统设置 → 全局设置」中选择内容安全模型，未设置时这两项不可选。

「提示词」动作引用提示词库中的提示词，字段为「选择提示词」「版本标签」（production 或 latest）和「注入位置」（「前置」或「后置」）。租户中没有提示词时该动作无可选项。

15.5.3 改写请求与响应

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

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

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

15.5.4 Token、请求体与推理指令

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

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

15.5.5 规则内限额

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

• 超出规则内限额时只能「拒绝本次调用」，并返回配置的原因码；排队、固定应答、非法尝试保护和临时豁免需要在「全局限额」中创建独立限额。
• 规则须将「调用类型」限定为一种，且不能使用限额执行时无法判断的条件（工具名、MCP 方法、意图、任务类型、任务难度、业务场景、请求含敏感信息、组织成员、灰度 Cookie、数据来源）；按 MCP 工具限流请改用全局限额的「按 MCP 工具」计数维度。
• 同一请求可能同时受规则内限额和全局限额约束。

15.5.6 镜像复制

「镜像复制」只用于一种明确的 MCP、连接器、A2A 或 API 服务调用，按「复制比例」（1–100%）把请求复制到另一个能力端点。主请求不等待复制请求，复制结果也不返回调用方；复制请求按正常调用计费与限流，会额外占用目标端点的配额。

开启前依次选择能力与能力端点作为「复制目标」，并勾选同主机和跨域名两项流量去向确认。默认不复制可能产生副作用的请求；开启「允许复制可能产生副作用的请求」前，确认复制环境能安全接收创建、删除等调用。

15.5.7 异常处理

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

• 「系统固定行为」：条件不满足时，不做处理，交由下一条规则判定。
• 「命中处理」：内容检测命中、超出限额、输入超出 Token 上限、请求体超限等情况的处置，在对应动作中设置或固定为拒绝。
• 「组件不可用时」：检测组件不可用时选择「拒绝本次调用」或「放行，继续网关路由」；模型入口的请求字段、请求正文改写失败时选择拒绝或保留原内容继续；MCP、A2A、API 服务入口的改写失败选择「阻断请求」或「保留原内容继续调用」。请求头、响应头与状态码改写失败时固定拒绝本次调用。
• 转发目标全部不可用时返回错误；启用故障转移后，按触发条件尝试备用目标，备用目标用尽或达到尝试上限后停止转移。

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

15.6 配置并验证熔断

15.6.1 熔断解决什么问题

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

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

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

15.6.2 从哪里配置

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

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

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

15.6.3 用受控失败验证

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

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

15.6.4 用慢调用验证

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

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

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

15.7 流量分配与故障转移

15.7.1 目标方式、档位与权重

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

• 「固定模型」：每个目标先选模型服务，再选该服务中的网关模型。
• 「按请求模型对应」：每个目标选一个供应商，再在「按请求模型对应」表中为条件里的每个模型名选择该供应商下承接它的模型，可用「按名称自动匹配」生成建议。要求规则恰有一条非否定的「客户端声明的模型名 等于」条件；主要目标须覆盖全部模型名，备用档位的空格表示「本档跳过」；单个供应商最多 32 个映射。不能与其他目标种类混用，也不支持「时延优先」。

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

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

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

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

15.7.2 目标选择策略

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

15.7.3 配置故障转移

1. 将调用类型限定为「模型调用」，在转发节点配置主要目标。
2. 选择「添加备用档位」并添加备用目标。没有备用目标时「启用故障转移」不可开启。
3. 开启「启用故障转移」，选择触发条件（任一满足即转移，最多 16 个）：「连不上上游」「上游超时」「上游返回指定状态码」「响应内容命中指定条件」。默认勾选连不上上游、上游超时和状态码 429、500、502、503、504。
4. 指定状态码时每个值须在 100–599 之间；响应内容条件需填写以 / 开头的「响应内容位置」（如 /error/type）和期望值。
5. 设置「总尝试次数」（1–10，包含首次调用，默认 3）和「首内容前故障转移总预算（秒）」（1–600，默认 120）。达到任一上限后不再尝试备用目标。
6. 保存并核对应用状态，在「验证规则」中勾选「模拟主档失败」查看转移链，再制造受控故障检查实际的备用调用。

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

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

15.7.4 会话切换保护

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

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

15.7.5 影子分派

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

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

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

分流规则的全部目标都经模型派发时，规则详情的查看态提供「规则编排」和「实时流量」两个视图。「实时流量」按时间窗显示调用次数、成功率、故障转移次数和每千词元成本，并按目标列出配置权重与实际占比、调用次数、成功率、耗时（中位与慢请求）和故障转移转出、转入次数。

核对转移结果时，记录主要目标与备用目标的接收情况、最终响应、耗时和请求标识。客户端超时应覆盖网关的尝试预算；存在外部副作用的请求要评估重复调用的影响。故障转移仍受权限、额度和目标归属检查。

15.8 维护、校验与故障定位

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

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

15.8.2 常见校验与处理

15.8.3 保存冲突和运行异常

错误码的含义与是否可重试见第 10.8 节。下表按现象给出排查顺序：

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

15.9 意图集

15.9.1 意图识别模型

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

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

15.9.2 内置意图

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

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

页面中的「试一句」可粘贴一句真实提问，选择「试一下」后显示「难度」「类型」「场景」和「内容风险」四行结果，难度另附命中的判定标准。内容风险一行需要已设置内容安全模型。试判会调用判断模型，请使用允许送检的文本。

15.9.3 自定义意图集

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

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

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

15.10 语义缓存

15.10.1 开启方式与边界

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

• 缓存服务与中文向量模型（bge-small-zh-v1.5）及重排模型随安装包部署在本地，Zentrix 安装默认包含该能力，不调用外部向量服务。部署未配置缓存服务时，「缓存」页签提示「本部署未配置语义缓存服务，无法清除」。
• 语义缓存只在网关接入层执行，并按本次命中的整条规则链判断能否参与。规则链中出现以下任一配置时，这次请求不查也不写缓存：转发到指定目标、应用限额、单次请求 Token 上限、挂载插件、响应改写（改写响应头、改写响应字段、状态码映射）、输出检测、改写请求头。因此语义缓存适合配在不指定转发目标的增强规则上，请求随后按网关既有路由处理。
• 「放行」「拒绝本次调用」规则不能开启语义缓存。
• 规则编辑器允许在带转发目标的规则上添加「语义缓存」，但按上述判断这类请求不会走缓存。上线前用「缓存」页签的命中占比确认缓存确实生效。

15.10.2 缓存参数与容量

「缓存」页签的设置是租户级的一份配置，留空表示使用默认值，保存后各实例最迟 5 秒内生效：

缓存始终按租户和模型分开。Zentrix 形态没有工作空间与智能体的管理入口，通常选用「按用户」或「全租户共享」。

15.10.3 命中占比与清除

• 「缓存概况」按模型列出「条目数」「占用空间」「最早写入」「最近写入」。还没有启用的规则开启语义缓存时，页面提示并提供「去规则清单添加」。
• 「命中占比」分「近 1 小时」「近 24 小时」「近 7 天」显示，计算方式为命中次数 ÷（命中次数 + 实际调用模型的次数）；另显示未开启缓存的调用占比，只按已上报的调用计算。
• 「清除缓存」中选择「清除全部」并「确认清除」，删除本租户的全部缓存条目。修改答案口径或模型后，可先清除缓存再验证。

---

上一章：14. 配置内容检测与安全围栏 · 下一章：16. 请求变换、网关扩展与开放 API