15. 流量规则与流量保护

完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。

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

本章内容：面向流量规则的管理者（租户管理员、系统管理员，以及经授予持有「流量规则」权限的成员），说明怎样用「流量规则」决定每次调用的去向，以及怎样用限额、熔断与预算保护上游与成本。读完后，你可以按业务特征编写匹配条件、在一个模型的多个上游之间分流、调整末行「默认」规则、配置故障转移与灰度切流、在保存前模拟整条规则链，并为调用量、并发与花费设置可控的上限。

「内容检测 · 对话内容」与「内容检测 · 工具调用」见第 14 章，模型分组的可用范围与配额授权见第 7 章。

15.1 规则清单与规则编排

前提：许可中包含「动态路由」或「模型护栏」模块（都未包含时侧栏不显示「流量规则」），且持有「流量规则 · 查看」权限；新建、编辑、删除规则分别需要对应的权限（见 3.5）。

操作步骤：进入「管理后台 › 流量 › 流量规则」。三个页签中，「规则清单」用于新建、导入导出、复制、排序、启停规则与进入「验证规则」，「全局限额」按调用类型维护限额，「意图集」用于试判与建规则。清单右上为「导出」「导入规则模板」「从文件导入」「新建规则」，并显示「已有条数 / 500 条」。

一条规则可读作「如果 ⟨条件⟩ 满足，就执行 ⟨动作⟩，出问题时按 ⟨异常处理⟩ 处置」。「规则编排」画布自上而下为「请求进入」（规则名 1–120 字）、「条件判断」、「处置动作」、「处理结果」与「异常处理」；其中处理结果只是配置预期，不代表请求已成功。右侧「配置检查」仍有待完善项时「保存规则」不可用。

你会看到：「命中后」列把规则分成两类。有转发目标或动作为「放行」「拒绝本次调用」的是终止规则，命中即结束匹配；只配限额、改写、检测、缓存的是增强规则，命中后继续匹配。网关先按判定阶段（全局强制 → 部门规则 → 全局默认，见 15.15），再在阶段内按优先级从小到大检查已启用规则，全部条件满足才命中；模型调用的清单末行固定为「默认」规则：在请求模型的全部启用上游之间分发。没有其他终止规则命中，或命中的规则只放行而没有指定目标时，都按「默认」规则分发；调用详情的去向依据相应显示「默认」或「按规则「X」放行 · 按默认分发」。MCP、A2A 与 API 服务调用没有规则命中时转发到主端点，「默认」规则不作用于它们。

调整「默认」规则：在清单末行打开「默认」。它不可拖动、删除或停用，在任何排序方式下都排在最后；编辑时条件、目标、护栏与请求头等区块显示为不可修改，只能修改目标选择策略、会话切换保护与故障转移，修改后同样经过「确认变更」再发布。尝试修改其他字段时，保存被拒绝并返回 409 route_default_policy_locked。

注意：终止规则一旦命中，后面的规则都不再评估，而新建规则默认排在末尾——前面若已有按模型或模型分组命中的终止规则，新规则对同样请求永远不会生效。「确认变更」能判定出新规则被上方更宽的终止规则覆盖时，会提示并提供「移到「X」之前」一键调序。编排原则：增强规则排在需要受其约束的终止规则之前，精细规则在前、兜底规则最后；保存前在「确认变更」中核对相邻规则名次，保存后在「验证规则」中确认新规则显示「命中」而非「未评估」。

15.2 匹配条件

操作步骤：在「条件判断」节点选「添加条件」，按名称搜索并添加；为每个条件选比较方式并填取值，全部填完后页脚显示「N/N 已配置」。共 19 类条件，分四组：

字符串类条件有六种比较方式：「符合」组为等于、以…开头、匹配正则；「排除」组为不等于、不以…开头、不匹配正则。

集合类条件支持「属于」「不属于」，包括模型分组、实际上游、调用类型、具体能力、数据来源、敏感信息类型、意图、MCP 方法、客户端 CIDR 与灰度 Cookie；时段也可选择排除已配置的窗口。「不属于 A、B」表示 A 和 B 都未命中。缺少请求事实、检测未完成或条件不适用于本次调用时，不会因为选择排除而自动命中；标签未设置与组织成员无法解析仍按各自的条件说明处理。

「客户端 CIDR」可直接勾选系统预置的「中国大陆」，也可填写具体网段，两者任一命中即满足正向条件。中国大陆不含港澳台，支持 IPv4 与 IPv6；内网或无法识别地区的 IP 不参与地区匹配。严格只允许大陆来源时，使用「中国大陆」放行规则加后置兜底拒绝规则，见来源访问控制。

注意：条件之间恒为「且」，只有同一条件内填多个取值才是「任一」——要表达「A 或 B」，把两个取值放进同一条件或拆成两条规则。一条规则最多 16 个条件，每个条件 1–32 个取值，每个取值最多 256 字节。未加条件的规则匹配所有请求，保存前请确认它确实是有意设置的兜底规则。结构校验不通过会被拒绝并给出可定位的提示，如「一条规则最多 16 个条件。」「每个档位的目标权重总和必须为 100%。」。

15.3 分流目标与权重

适用场景：同一模型在多个供应商之间分担流量、按比例引流到新上游、按成本或时延自动选择上游。前提：目标上游已接入并可正常调用。

操作步骤

1. 「新建规则」填规则名，加条件收窄到目标流量，如「模型」等于某模型、「调用类型」为模型调用。也可以在模型详情的「流量规则」页签选择「以此为条件新建规则」，条件已预填为该模型。
2. 选「添加处置动作」，在「其他」分组中选「转发到指定目标」，「目标方式」选「请求模型的全部上游」或逐个指定上游，选一种「目标选择策略」。新建规则默认「加权轮询」并开启会话切换保护：不同会话按比例分配到各上游，同一会话保持同一上游。

「请求模型的全部上游」按调用方请求的模型展开为它当前启用的全部上游，模型新增或停用上游后自动生效，无需修改规则；可以只限定部分供应商。展开时先按供应商过滤，再按工具、看图与上下文窗口等能力过滤；能力过滤把上游全部滤掉时退回未过滤的集合。整条规则展开为空时返回 503 model_no_backend，不会越过规则去找别的上游，配置检查与调用详情会标出这条规则。该种目标不能与指定上游或能力端点混用在同一条规则里。

1. 逐个指定上游时，在「主要目标」选第一个上游并填权重，用「添加分流目标」加第二个目标填权重，可用「平均分配权重」均分。
2. 在右侧「验证规则」页签中确认本规则显示「命中」，再「保存规则」并在「确认变更」中确认。

你会看到：转发节点注明「主档内按权重选择目标。目标失败后，按故障转移配置尝试更高档位；同档的其他目标不会自动作为后备」。五种策略：按调用方稳定分配（同一调用方总落到同一目标，需多个调用方才能观察比例）、加权轮询（同档内按权重轮流选，小样本下比例有偏差）、时延优先（抽两个目标选预计首字时延更低者，仅模型目标）、质量优先（先比质量分，容差内算打平，再比混合价格与时延）、成本优先（先比混合价格，即输入与输出价格合计，打平后再比质量分与时延）。后两者可设「容差」（默认 5%）。

注意：逐个指定上游时，加权分流本身不做容灾——被分到某个目标的请求失败后不会自动改投同档其他目标，需要容灾请配备用档位并启用故障转移（见 15.4）。用量与额度计入「计量分组」（调用方可用且包含该模型的分组中排序最靠前且仍有额度的一个，见第 6.7 节），费用按实际处理请求的上游单价结算。目标为「请求模型的全部上游」时，同档的其他上游会排在选中上游之后进入故障转移尝试链。

结果确认：规则详情选「实时流量」，逐目标给出配置权重与实际占比、调用次数、成功率、耗时与每千 Token 成本。命中规则的响应头 x-zenova-route-rule 给出决定去向的规则编号前缀。

15.4 故障转移与上游健康检查

前提：调用类型限定为模型调用，且已配至少一个备用档位——没有备用目标时无法开启故障转移。

操作步骤

1. 在「转发到」中配主要目标，选「添加备用档位」加入备用目标。
2. 开启「启用故障转移」并选触发条件（任一满足即转移）：上游连接失败或中断、上游超时、上游返回指定状态码（100–599，默认勾选 429、500、502、503、504）、响应内容命中指定条件（以 / 开头的字段位置如 /object 等于期望值，只对非流式生效）。
3. 设置「总尝试次数」（1–10，含首次调用）与「首内容前故障转移总预算（秒）」（1–600），达到任一上限即停止转移。

切换语义：主档状态码在触发集合内则转到下一档；主档返回 4xx 且不在集合内（如 400 参数错误）时不转移、不重试，原样返回上游错误；主档鉴权失败（401）返回 502 upstream_credential_rejected 且不转移，该账号进入冷却；目标派发前已不可用则跳过，全部不可用返回 503 upstream_unavailable；已向客户端输出首个内容后不再转移；流式请求不按响应内容判定。

结果确认：「实时流量」顶部给出「N 次调用 · 成功率 · 故障转移 N 次（兜住 N 次）」，主档显示「转出」、备用档显示「转入」次数。

注意：故障转移不是静默切换——它在调用记录与实时流量中可见，总耗时等于主档失败耗时加备用档耗时，客户端的超时设置应覆盖网关的尝试预算。上游可用性由「模型供应商 › 供应商详情」负责：按固定间隔主动探活，探活间隔、连续失败多少次判不健康、连续成功多少次恢复均可配置，「可用性探查」页签列出每次检查的结果与失败原因，账号可「停用」以临时摘流。

15.5 会话亲和与影子分派

会话切换保护让同一会话的后续请求继续使用上一轮的模型。前提：转发用「质量优先」或「成本优先」，主要目标至少两个。

操作步骤：在「转发到」之后选插入按钮，添加「会话切换保护」（没有转发目标时不可选），填「切换裕度」（默认 5%）、「最少用户轮次」、「空闲超时」（默认 300 秒），保存并确认应用。

网关按以下顺序识别会话，命中一项即停止：

首条用户消息不用于识别会话。前四项称为显式身份，只有带显式身份的会话才启用会话切换保护、参与按会话计数；按对话历史续接识别的会话只用于会话归并、诊断与花费统计。

注意：两个候选的价格与质量差距本身很稳定时，多轮调用会一直落在同一目标，这不能说明保护生效。要判断它是否按预期工作，请让候选排名在会话中途变化，再观察切换是否等到满足裕度与轮次条件后才发生。

影子分派把采样的请求再复制一份、异步发给影子模型。前提：规则已配转发目标，影子模型不同于转发目标。

操作步骤：在「转发到」之后插入「影子分派」，选影子模型，填「采样比例」（默认 1%）、「并发上限」、「队列上限」、「超时」与「响应读取上限」，保存后详情右上方出现「影子对比」。

你会看到：客户端只收到主目标的响应，影子内容不返回给调用方，「实时流量」只统计主流量。「影子对比」可按时间窗对比两者的请求数、成功率、延迟、Token 与成本。

注意：影子的失败、超时或丢弃不影响主响应；影子请求跳过限流但照常计费，用量按用途「影子」单独记账。它只记录响应大小、状态、耗时与 Token，不保存正文，只能对比用量与延迟，不能逐条对比输出。刚开启后立即查看可能还没有数据。

15.6 灰度发布与流量染色

按灰度 Cookie 染色：新建规则，条件中添加「灰度 Cookie」，名称从下拉选 zenova_canary、zenova_rollout 或 zenova_variant，填取值（如 beta01），动作选「转发到」灰度目标并保存。规则详情只显示名称与比较方式，不显示取值。

注意：名称只允许上述三个，需要自有名称时改用「请求头」条件。取值只能用可见的英文字母、数字和符号，不能含空格、分号或中文；取值只写不回显。用「标签」条件前先在「管理后台 › 标签」定义允许调用方声明的标签，调用方在请求头 x-zenova-tags 中声明（如 scene=code_review）；未定义的标签键会被拒绝并返回 tag_not_defined，而声明了不存在的取值时既不命中也不报错，请只使用已列出的取值。

存量接口的灰度切流与回退：前提是新旧上游已分别登记为 API 服务并发布、设置可用范围。业务方改用代理地址 https://<网关地址>/api/v1/agent-gateway/proxy/<服务ID>/<上游路径> 调用旧服务；新建规则，「调用类型」为 API 服务、「具体能力」为旧服务，加一个灰度请求头，动作「转发到」新旧两个能力端点并按权重分配。带标记的请求按权重分流，不带标记的仍走旧服务；回退时停用或删除该规则即全部回到旧服务。

注意：调用记录会标明每次请求实际落到的目标。需要旁路观察而非按比例放量时，改用「镜像复制」动作（只能用于 MCP、连接器、A2A 与 API 服务），按比例另发一份，主请求不等待镜像结果。

15.7 按时段、域名与请求内容路由

按时段生效：条件中添加「时段」，选 IANA 时区（如 Asia/Shanghai），加一个或多个 HH:MM-HH:MM 时间段，动作按需选转发、拒绝或限额。

判定按所选时区的本地时间；时间段左闭右开，12:00-14:00 含 12:00、不含 14:00；允许跨零点；多个时间段为「任一」；只支持「时:分」窗口，不支持按星期或日期。用「验证规则」的「验证时间」模拟窗口内外时刻，窗口外时该条件显示「不匹配」。

按访问域名分流：流量规则不提供域名（Host）条件，按域名分流在「网关接入」中完成——在「域名」页签「声明自定义域名」或「分配平台子域名」；于域名的「查看」里在「路由绑定」选「匹配」（路径前缀或精确路径）、填路径、把「路由目标」选为一条流量规则并「添加」；再用「路由试算」确认。

注意：域名通常是平台级共享对象，增删绑定会影响真实流量，变更前与平台管理员确认；路由试算反映的是已保存的配置，不是运行中的流量。

按请求内容路由：条件中添加「请求含敏感信息」并选类型（引用不存在的类型保存时会被拒绝），动作选「转发到」私有部署模型，需要直接拦截时选「拒绝本次调用」。

注意：内置识别器带校验位校验，校验位错误或写法不符合规范的号码不会被识别。改道只改变去向，请求内容原样发给目标；需要同时脱敏时加「内容检测 · 对话内容」并勾选「敏感信息」。该条件只在模型调用中产生。

按意图路由与兜底：前提是在「系统设置 › 全局设置」「常规」页签的「默认模型」中为「意图识别」选择模型。在「内置意图」右上方点「测试意图识别」，在弹窗中输入一句提问并点「识别」，结果给出难度、类型、场景与内容风险；在目标意图行选「用它建规则」，编辑器预填条件与规则名，补充收窄条件与转发目标；最后在所有意图规则之后放一条不带意图条件的转发规则指向通用模型作为兜底。业务专属意图可在「自定义意图集」新建。

注意：意图识别不可用（未设置模型、服务停用、调用失败或请求中没有可判断的文字）时，意图条件按不命中处理，请求由后续规则——通常就是兜底规则——或默认路由接管，因此务必配置兜底规则。每次命中意图规则都会产生一次判断模型调用，有相应的时延和成本。

15.8 规则模拟与发布确认

操作步骤：入口是「规则清单」搜索栏右侧的「验证规则」，按整套规则顺序评估。选调用类型并填写「请求的模型」（与「客户端声明的模型名」同值）；选「凭据身份」或「调用方」；按需填请求路径、请求头、「验证时间」；展开「更多请求事实」填「模型分组」「意图提示词」「客户端 IP」「查询参数」「灰度 Cookie」等；填写了调用方时，模型分组由调用方推导（API 密钥取其绑定分组，登录身份取全部可见分组），未填调用方时可多选分组。结果中显示「计量分组」。必填信息齐全后页面自动计算，也可点「运行验证」重新计算。

你会看到：结果按「选路前求值」与「选定目标后复核」两段逐条列出判定——「命中」为终止规则命中、后续不再评估；「增强规则命中，继续评估」为叠加配置、后续仍评估；「不匹配」为条件不成立；「未评估」为前序规则已结束判定。右侧「完整走向」只列实际命中的规则。

注意：模拟不调用上游模型，不能证明限额已计数、改写已执行或目标可连通；加权轮询的模拟使用独立于生产的轮询进度。真实效果仍要用一次命中调用确认。

发布：选「保存规则」后打开「确认变更」，核对「字段差异」「关联对象」与「命中顺序」，修改敏感请求头时须勾选确认，再选「确认并应用」。如遇他人同时修改，页面提示版本冲突并保留已填内容，选「重新预览并重试」即可。规则保存后无需重启组件，各副本加载新版本后对新请求生效；正在进行的请求按开始时的规则执行到结束。

15.9 请求速率限额

操作步骤（在规则中配置）

1. 新建或编辑规则，把「调用类型」限定为一种（带限额的规则必须如此）。
2. 选「添加处置动作 › 应用限额」，开启「请求速率」，选「计数维度」（如「按 API 密钥」），「额度用完时」选「直接拒绝」。
3. 为每个时间窗填「时间窗」「周期内请求数」与「即时突发量」，同一周期不能重复。
4. 在「超出限额」中选择返回给调用方的原因，保存并确认。

你会看到：额度用尽后的请求返回 429，错误码 rate_limit_exceeded、原因 TRAFFIC_RATE_LIMITED，带 Retry-After（反映真实需要等待的秒数），details 中带命中规则的编号。被拒绝的请求上游耗时为 0。

在全局限额中配置：页签右侧选调用类型后「新增限额」，依次填「限制类型」「计数对象」「限额配置」「超限处理」；右侧「试运行」可模拟未触发与触发两种情景。列表显示状态、摘要、「来源」（全局限额 / 来自路由规则 / 平台强制限额）、优先级与更新时间；「来自路由规则」的行只读，需修改时点规则名到来源规则中编辑。

操作纪律：先收窄，再扩大

新建限流、熔断或预算规则时，务必先把匹配条件收窄到单个模型分组或单个 API 密钥：加一条「模型分组」条件，或把「计数维度」与保留的匹配条款限定到一把自建密钥。用这个范围确认阈值、计数与恢复行为符合预期之后，再逐级放宽到整个分组或整个租户。

判断是否「符合预期」的基准是：先让阈值在一个你能随时观察的小范围内生效，确认第几次请求开始被拒、等待多久恢复，再扩大范围。用于收窄的密钥或分组最好只用于验证，且可用范围不含其他成员。

注意：速率限额是按时间持续补充的滚动窗口，不是到整点清零的配额；多个时间窗同时生效，请求需满足每一个时间窗。规则内限额超限时只能拒绝，排队、返回固定应答、非法尝试保护与临时豁免要到全局限额中配置。带限额的规则中，条件须是所选调用类型实际产生的信息，例如 API 服务调用的规则不能用「数据来源」条件；按 MCP 工具限流也可以用全局限额的「按 MCP 工具」计数维度。多副本部署时速率与熔断状态在各副本本地维护、不跨副本共享，规划阈值要按副本数量考虑实际放行量可能高于配置值。

15.10 并发限制与熔断

并发限制统计同时在执行的请求数。在「应用限额」中关闭「请求速率」，展开「并发、熔断与超时（可选）」开启「并发」，选「计数维度」，设置「繁忙时的优先级」（普通 / 较高 / 最高）与「并发上限」，按需填「为优先请求保留的名额」「恢复阈值」「并发硬上限」。

核心业务优先：保留名额要和优先级配合才生效。在「全局限额」中同一调用类型下新建两条并发限制：一条匹配要保护的全部请求，填并发上限和保留名额，优先级保持 0；另一条只匹配核心业务，计数维度与第一条相同，优先级填 1–3，并发上限不低于第一条。例如上限 20、保留 5 时，繁忙时普通请求最多同时执行 15 个，核心业务可以用满 20 个。两条的匹配条件和计数维度都不要用「实际上游」「路由」「端点」「依赖」或「标签」，否则两条分别在选定上游前后判定，优先级不互通。

超出的请求返回 429、原因 TRAFFIC_CONCURRENCY_LIMITED；在途请求结束后恢复放行，并发限制从不中断正在执行的请求。若保存时提示「变更预览无效」，重新打开规则并重新预览后再确认。

熔断在达到阈值后于一段时间内快速拒绝后续请求、不再打上游，到期进入半开探测。可在「应用限额 › 并发、熔断与超时」开启，也可在全局限额中新建「熔断」类型，参数一致：统计窗口、最小调用样本数、失败率阈值、慢调用阈值与慢调用率阈值、熔断持续时间、半开探测次数。同一处可开启「上游调用超时」，填连接与请求超时（连接不得大于请求），未配置时默认连接 5 秒、请求 30 秒。

你会看到：熔断打开前失败请求返回上游错误，超时记为 504 timeout、原因 LLM_TIMEOUT。熔断期间返回 503 circuit_open、原因 TRAFFIC_CIRCUIT_OPEN，带 Retry-After，请求记录中上游耗时为 0。到期进入半开，探测成功即恢复，失败则重新熔断。

注意：熔断只影响命中该规则或限额的请求，本身不切换上游，只有配了故障转移的规则才会跳过熔断中的目标。慢调用阈值只用于统计，不会中断慢请求，要中断请用「上游调用超时」。MCP 调用的熔断以整个 MCP 服务为粒度。熔断期间若看到其他拒绝原因，先确认该目标所用供应商账号是否可用、规则是否刚被修改过——修改规则会重新下发并重置熔断状态。

15.11 超限动作与临时调整

三种超限处理：在「全局限额 › 新增限额」的「超限处理」中三选一。

你会看到：选「拒绝请求」返回 429 rate_limit_exceeded、原因 TRAFFIC_RATE_LIMITED，带 Retry-After；选「排队等待」时等待超过「最大等待」返回 429 TRAFFIC_QUEUE_TIMEOUT；选「返回固定应答」返回 200，内容为配置的回复，响应头 x-zenova-default-result: true 标明降级应答，不调用上游、不计费。一个请求同时命中多条处理方式不同的限额时取最严者（拒绝 > 排队 > 固定应答）。对交互式请求，排队会表现为首字延迟变长，建议改用固定应答。

临时抬高限额：在某个时间窗下勾选「启用临时阈值」，填「临时阈值」「即时突发量」「开始时间」「结束时间」后保存。详情页「限额摘要」显示基线值、临时阈值、「生效中」及起止时刻。

注意：临时阈值只能抬高，且至少一项高于基础额度，否则提示「临时额度不得低于基础额度」；临时窗口最长 30 天，结束时间须晚于开始时间与当前时间。它只放宽流量阈值，不延长凭据有效期、不授予模型访问权，也不影响配额与密钥额度。

非法尝试保护：在全局限额中选 MCP 调用、A2A 调用或 API 服务调用类型，「新增限额」，限制类型选「非法尝试保护」，设置匹配条件（如按客户端 IP）、统计窗口、次数阈值与暂停时长。计入的是能力调用在下游凭据校验失败时产生的事件，普通 4xx 不计入；这类请求往往拿不到调用方身份，按 API 密钥收窄对它不生效，应按客户端 IP 等维度配置，出口 IP 被多人共用时阈值过低可能误伤正常用户。

临时豁免：在独立限额行的「更多操作」选「创建调用方临时豁免」，系统新建一条豁免配置，调用方条款预填为原限额的同一个调用方（原限额不受修改）；选「豁免类型」（请求次数、并发限制、熔断、非法尝试保护），填「到期时间」与「原因」，普通豁免最长 7 天；仅在确有授权的应急场景才开启「豁免平台强制限额」，有效期最长 2 小时。

注意：界面提示「豁免按类型生效：豁免适用于指定类型的所有匹配限额，并非仅适用于当前限额」，因此要选对类型。豁免不等于身份认证、模型授权或额度豁免。

15.12 计数维度

匹配条件决定哪些请求受约束，计数维度决定这些请求怎样分别累计。例如「匹配某个模型分组、按 API 密钥计数」表示每把密钥对该分组各有一份额度；「按 API 密钥 + 按模型」计数表示每把密钥对每个模型各有一份额度，同一模型的多个上游合并计数。匹配条件有两层：「本规则的匹配条件」用与流量规则相同的条件类型；「保留的匹配条款」按「匹配字段 / 匹配方式 / 匹配值」配置，可按调用方、客户端 IP、模型、模型分组、实际上游、能力、MCP 服务或工具等字段匹配。两层都为空时，限额对所选调用类型的全部请求生效。

计数维度可多选，多选时按取值组合计数，可选项随调用类型变化，包括按 API 密钥、按用户、按调用方分组、按客户端 IP、按会话、按路由、按模型、按实际上游、按模型分组（按计量分组计数，与额度口径一致）、按应用、按部门、按职能组、按 MCP 服务、按 MCP 工具、按标签等。「按会话」只对模型调用、MCP 调用和连接器调用提供，A2A 调用和 API 服务没有会话标识；MCP 调用另有「按 MCP 服务」「按 MCP 工具」。按会话计数时，带显式会话身份的请求（平台运行线程、x-zenova-conversation-id、客户端自带会话编号或 Responses 续接，见 15.5 节）按会话分别计数，不同会话互不影响；按对话历史续接识别的会话与无法识别会话的请求不计入。

注意：请求上取不到某个计数维度的值时，这条限额对该请求不生效。限额的计数维度在所选调用类型上永远取不到值时，发布会被拒绝并说明该维度在该调用面上不会产生——应更换维度，而不是反复重试保存。详情页「计数维度校验」显示「通过」才表示限额能生效。限额摘要只写限速值与超限动作，不体现计数维度，多人共用一份额度时建议在名称里写明维度。

按 MCP 工具限流：调用类型选「MCP 调用」，「计数维度」选「按 MCP 工具」（可再加「按用户」），「保留的匹配条款」选「按 MCP 服务」等于目标服务，再填时间窗阈值。MCP 侧的拒绝以 JSON-RPC 的 result.isError=true 与原因码返回（HTTP 200），客户端能拿到明确原因，不会挂起。

15.13 预算硬墙

操作步骤

1. 进入「管理后台 › 组织与权限 › 模型分组」，打开目标分组的「可用范围与配额」页签。
2. 在某个对象（成员、部门、职能组、工作空间）行选「配额编辑」。
3. 打开「启用策略」，按需填「Token 预算」与「金额预算（人民币）」，两者都按小时 / 天 / 月 / 累计填写，选「确认」。

关键取值

• Token 预算的单位是十亿（B）Token，例如 0.000003 B 即 3,000 Token。
• 金额预算按每次调用的有效单价计算。带金额预算的调用会跳过没有发布价的模型；可用模型全部未定价时返回 429、原因 POOL_MONEY_UNPRICED。设金额预算前，先到「价格」页给模型定价。
• 取消某个周期的限制请留空：留空表示该周期不限，把已填的值清空即恢复为不限。
• 填 0 是硬墙，不是不限：该周期内任何用量都会被拒绝。

注意：一个策略至少要保留一个周期的预算，把四个周期全部清空时对话框不会保存，并提示「启用的策略至少要保留一个周期预算。要取消全部周期的限制，请关闭「启用策略」。」

为单把 API 密钥设置额度：在「模型分组 › API 密钥管理」打开密钥详情，于「额度」区选「编辑配额」，字段相同。下级额度可以设得比上级大，但调用时各层都要通过，最严的一层生效。

你会看到：分组的配额列显示当前周期用量，如「本小时 · Token · 已用 9 k / 限额 3 k」，用尽时以醒目颜色标出。预算用尽后的调用返回 429 insufficient_quota、原因 POOL_EXHAUSTED、x-should-retry: false，details 中写明预算类型（token 或 money）、周期、已用、限额与窗口结束时间。

注意：用量在调用完成后记账，单个调用可能把已用量推过限额，从下一次调用起拒绝；把某个周期填 0 后，限额生效也有短暂的下发延迟。预算周期按自然周期重置，与速率限额的滚动窗口不同。单个额度池没有接近阈值的推送，需定期查看服务配额列、密钥详情的额度状态或「运行总览」的「预算」面板。

15.14 原因码与常见现象

常见现象：规则保存成功但不生效，先用「验证规则」看是否「未评估」（被前序结束匹配规则遮蔽），再检查启用状态与调用类型；429 分不清哪层限制时看原因码，TRAFFIC_* 为规则或全局限额、POOL_* 为配额或密钥额度；备用目标没收到请求，检查是否启用故障转移、触发条件是否覆盖实际错误、尝试预算是否用尽；拒绝原因看不出来时，具体原因在 details[].reason 与 deniedBy 中。

15.15 判定阶段与部门规则

适用场景：全局统一管控流量，同时允许下属部门在本部门范围内自行编写流量规则，例如分行为本行人员把某类请求转发到指定的模型分组。

15.15.1 三个判定阶段

每条规则都处于一个「判定阶段」。网关先按阶段、再按阶段内的判定顺序检查规则：

三个阶段都没有终止规则命中时，模型调用按清单末行的「默认」规则分发（见 15.1）。终止规则命中即结束匹配的规则不变，并且跨阶段生效：全局强制阶段的终止规则命中后，部门规则与全局默认规则都不再评估。因此，部门规则只能在全局强制阶段没有拦下的请求上生效，从结构上无法覆盖全局强制规则。

新建规则：在规则编辑器中选择「判定阶段」，必须选择。选择「部门规则」时再选择「归属部门」：全租户范围的管理者必须选择；部门范围的管理者只能选择其范围内的部门，不填时由系统按其授予所在的部门确定。全局的两个阶段不能指定归属部门。

修改阶段：部门规则的判定阶段与归属部门建立后不能修改；全局规则只能在「全局强制」与「全局默认」之间切换。调整顺序只能在同一判定阶段、同一归属部门的规则之间进行，跨阶段拖动会被拒绝。

规则清单：「阶段」「归属」两列显示每条规则所在的判定阶段与归属部门（全局规则显示「全局」），可按「归属」筛选。全租户范围的管理者看到全部规则，可以编辑任一部门的规则，编辑时保留其归属部门；部门范围的管理者只看到本部门及其下级部门的规则，看不到全局规则与平级部门的规则。

升级到本版本时，原有规则全部归入「全局强制」并保持原有顺序，判定结果与升级前相同。

15.15.2 部门规则能做什么

• 作用范围固定：部门规则只对归属部门及其下级部门成员发起的调用生效，这一限定由系统自动附加，不能删除。无法确定调用方所在部门的调用（例如不代表任何成员的服务调用）不会命中部门规则。
• 动作受限：部门规则只能把请求路由到目标（可带规则内限额），不能拒绝、放行、使用护栏、插件或改写请求头。需要拒绝或检测的管控由全局范围的管理者在「全局强制」阶段配置。
• 目标与条件受限：目标只能选用可用范围覆盖到归属部门或其上级部门的模型分组；附加条件只能使用范围内的部门、成员与密钥。条件在保存时校验，此后对象调出范围或规则改归上级部门时，越出范围的条件只是不再命中，不会扩大规则的作用范围。
• 归属部门被删除：规则改归最近的上级部门，没有上级部门时改归全局（见 3.3.4）。

15.15.3 委派部门之前：把可被部门覆盖的规则改为「全局默认」

升级后的规则全部处于「全局强制」。如果其中有按模型或模型分组命中的终止规则，部门规则对同样的请求永远不会被评估，部门范围的管理者会看到自己的规则「不生效」。因此，在把流量规则权限按部门授予之前，全局范围的管理者需要先区分两类规则：

操作步骤

1. 进入「管理后台 › 流量 › 流量规则」，在「规则清单」中按「阶段」核对现有规则，找出允许部门覆盖的终止规则。
2. 逐条打开这些规则，把「判定阶段」改为「全局默认」，点「保存规则」，在「确认变更」中核对「命中顺序」后点「确认并应用」。只配置限额、改写、检测等动作的增强规则命中后仍会继续匹配，不会遮蔽部门规则，可以保留在「全局强制」。
3. 在「组织与权限 › 角色管理」中按部门授予包含流量规则权限的角色（见 3.5.4）。
4. 部门编写规则后，在「验证规则」中以该部门的一名成员作为调用方模拟请求，确认部门规则显示「命中」而不是「未评估」。

注意：改为「全局默认」的规则仍对没有部门规则命中的调用生效，未委派的部门不受影响；但它从此排在全部部门规则之后，原先依赖它先于其他规则命中的编排需要在「确认变更」中一并核对。

能力说明

---

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