26. 流量规则与流量保护

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

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

本章内容：本章面向流量规则的管理者（租户管理员、系统管理员，以及经授予持有「流量规则」权限的成员），说明怎样用「流量规则」决定每次调用的去向，以及怎样用限额、熔断与预算保护上游与成本。员工在「对话」中的提问、智能体运行中的模型调用与工具调用、外部客户端经 API 密钥发起的调用，都经过同一套规则。读完后，你可以按业务特征编写匹配条件、在一个模型的多个上游之间分流、调整末行「默认」规则、配置故障转移与灰度切流、理解网关怎样识别会话、在保存前模拟整条规则链，并为调用量、并发与花费设置可控的上限。

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

26.1 规则清单与规则编排

适用场景：第一次使用流量规则，或需要理解多条规则之间的先后关系。

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

操作步骤

1. 进入「管理后台 › 流量 › 流量规则」。页面有三个页签：「规则清单」用于新建、导入导出、复制、排序、启停规则与进入「验证规则」；「全局限额」按调用类型维护限额；「意图集」用于试判与建规则。
2. 清单右上方为「导出」「导入规则模板」「从文件导入」「新建规则」，并显示「已有条数 / 500 条」。
3. 点「新建规则」进入「规则编排」画布，自上而下依次为「请求进入」（规则名 1～120 字）、「条件判断」、「处置动作」、「处理结果」与「异常处理」。

一条规则可以读作「如果 ⟨条件⟩ 满足，就执行 ⟨动作⟩，出问题时按 ⟨异常处理⟩ 处置」。画布中的「处理结果」只是配置预期，不代表请求已经成功。右侧「配置检查」仍有待完善项时，「保存规则」不可用。

你会看到：「命中后」列把规则分成两类。

• 终止规则：有转发目标，或动作为「放行」「拒绝本次调用」。命中即结束匹配。
• 增强规则：只配置限额、改写、检测、缓存等动作。命中后继续匹配后面的规则。

网关先按判定阶段（全局强制 → 部门规则 → 全局默认，第 26.16 节），再在阶段内按优先级从小到大检查已启用的规则，全部条件满足才算命中；模型调用的清单末行固定为「默认」规则：在请求模型的全部启用上游之间分发。没有其他终止规则命中，或命中的规则只放行而没有指定目标时，都按「默认」规则分发；调用详情的去向依据相应显示「默认」或「按规则「X」放行 · 按默认分发」。MCP、A2A 与 API 服务调用没有规则命中时转发到主端点，「默认」规则不作用于它们。

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

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

26.2 匹配条件

适用场景：把规则收窄到某个服务、某类调用方或某类请求。

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

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

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

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

按智能体或员工收窄：只想约束某个智能体时，用「调用方」条件的「按智能体」；只想约束员工本人在平台内发起的调用时，用「按用户」。按智能体匹配时，浏览器中登录的员工会话不携带智能体身份；所选调用方类型在某些入口不会出现时，条件下方会提示「在以下入口不会生效」。

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

26.3 分流目标与权重

适用场景：同一模型在多个供应商之间分担流量、按比例引流到新上游、按成本或时延自动选择上游。

前提：目标上游已接入并可以正常调用。

操作步骤

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

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

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

你会看到：转发节点注明「主档内按权重选择目标。目标失败后，按故障转移配置尝试更高档位；同档的其他目标不会自动作为后备」。五种目标选择策略如下：

后两种策略可以设置「容差」，默认 5%。

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

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

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

适用场景：主模型不可用或返回特定错误时，自动改用备用模型。

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

操作步骤

1. 设置「总尝试次数」（1～10，含首次调用）与「首内容前故障转移总预算（秒）」（1～600），达到任一上限即停止转移。

切换规则

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

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

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

26.5 会话识别

适用场景：需要让同一场对话的多次调用归入同一个会话——用于会话诊断、单场会话花费、按会话计数的限额（26.13 节）与会话切换保护（26.6 节）；或者调用方是自建智能体平台、业务系统，希望精确指定会话归属。

网关把属于同一场对话的多次模型调用归入一个会话。会话与请求编号无关：请求编号每次调用都不同，不影响会话归属。

识别顺序

网关在请求进入时按以下顺序识别会话，命中一项即停止：

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

用请求头指定会话

能自行控制请求的调用方（例如自建智能体平台）可以在每次请求中携带：

curl https://<网关地址>/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "x-zenova-conversation-id: 3f6b2c1e-8a4d-4f7e-9b21-6c0d5e7a9f13" \
  -d '{"model":"通用对话","messages":[{"role":"user","content":"你好"}]}'

取值要求：

• 使用 UUID，或使用由字母、数字、-、_ 组成且不少于 22 个字符的编号；
• 最长 128 个字符；
• 同一场对话的全部请求携带相同的取值，不同对话使用不同的取值。

格式不合法时的返回

请求头取值不符合上述要求（字符集不对、少于 22 个字符且不是 UUID，或超过 128 个字符）时，网关直接拒绝本次请求，不转发给模型、不计费：

• HTTP 状态码 400；
• 错误类型 invalid_request_error，错误码 invalid_request，原因 VALIDATION_FAILED；
• details 中的原因为 invalid_conversation_id，提示信息说明该请求头须为 UUID 或至少 22 个 base64url 字符、且不超过 128 个字符。

调用方收到这类 400 不应重试，修正取值后再发。

Responses 续接的取值要求

• previous_response_id 必须原样回传网关下发的响应编号（以 resp_zr2. 开头）。回传无法识别的取值，或回传由其他凭据获得的响应编号时，返回 400，原因 invalid_previous_response_id。
• 续接依赖上一轮所在的供应商保存的响应。上一轮所在的供应商或供应商账号当前不可用（provider_account_continuation_unavailable），或上一轮响应经协议转换生成、上游未保存（response_continuation_unrestorable）时，无法凭 previous_response_id 续接。此时若请求的 input 已携带完整上下文（含此前的助手回复或工具调用记录），网关去掉 previous_response_id 后照常转发；否则返回 409，调用方应在 input 中携带完整上下文后重试，或开启新对话。

注意

• 按对话历史续接要求历史保持完整。调用方截断、摘要或改写早期消息后，后续请求可能被识别为新的会话；两场对话的全部可见历史逐字相同时，网关不会猜测归属，按新会话处理。对会话归属有精确要求时，请携带 x-zenova-conversation-id。
• 会话按租户、调用主体（API 密钥或平台运行主体）与终端用户隔离：共用一把 API 密钥的不同终端用户（第 28.8 节）即使带了相同的会话编号，也不会被归入同一会话。
• 员工对话与平台托管智能体无需任何配置，会话自动按运行线程识别。

26.6 会话切换保护与影子分派

会话切换保护让同一会话的后续请求继续使用上一轮选中的模型，避免多轮对话中途换模型。

前提：转发使用「质量优先」或「成本优先」策略，主要目标至少两个；请求带显式会话身份（26.5 节）。

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

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

影子分派把采样的请求再复制一份，异步发给影子模型，用于上线前比较新模型的用量与延迟。

前提：规则已配置转发目标，影子模型不同于转发目标。

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

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

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

26.7 灰度发布与流量染色

按灰度 Cookie 染色

1. 新建规则，在条件中添加「灰度 Cookie」，名称从下拉中选择 zenova_canary、zenova_rollout 或 zenova_variant，填写取值（如 beta01）。
2. 动作选「转发到」灰度目标并保存。

注意：名称只允许上述三个，需要自有名称时改用「请求头」条件。取值只能用可见的英文字母、数字和符号，不能含空格、分号或中文；取值只写不回显，规则详情只显示名称与比较方式。

按标签染色：使用「标签」条件前，先在「管理后台 › 流量 › 标签」定义允许调用方声明的标签；调用方在请求头 x-zenova-tags 中声明，如 scene=code_review。声明了未定义的标签键会被拒绝并返回 tag_not_defined；声明了不存在的取值时既不命中也不报错，请只使用已列出的取值。

存量接口的灰度切流与回退

前提：新旧上游已分别登记为 API 服务并发布，且已设置可用范围（第 22 章）。

1. 业务方改用代理地址 https://<网关地址>/api/v1/agent-gateway/proxy/<服务ID>/<上游路径> 调用旧服务。
2. 新建规则，「调用类型」为 API 服务、「具体能力」为旧服务，再加一个灰度请求头条件；动作「转发到」新旧两个能力端点，并按权重分配。
3. 带标记的请求按权重分流，不带标记的仍走旧服务；回退时停用或删除该规则，流量即全部回到旧服务。

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

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

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

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

按访问域名分流：流量规则不提供域名（Host）条件，按域名分流在「网关域名接入」页中完成。该页不在侧栏中：在「运行总览 › 会话」打开一场会话，会话详情的网关提示条显示「本会话没有经过网关的请求。……」时，点提示条上的「查看接入方式」进入。

1. 在「域名」页签「声明自定义域名」或「分配平台子域名」。
2. 打开域名的「查看」，在「路由绑定」中选择匹配方式（路径前缀或精确路径）、填写路径，把「路由目标」选为一条流量规则并「添加」。
3. 用「路由试算」确认请求会命中哪条绑定。

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

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

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

按意图路由与兜底

前提：已在「管理后台 › 系统设置 › 全局设置」「常规」页签的「默认模型」中为「意图识别」选择模型。

1. 在「意图集」页签的「内置意图」中，点右上方的「测试意图识别」，在弹窗中输入一句提问并点「识别」，结果给出难度、类型、场景与内容风险。
2. 在目标意图所在行点「用它建规则」，编辑器预填条件与规则名，补充收窄条件与转发目标。
3. 在所有意图规则之后放一条不带意图条件的转发规则，指向通用模型作为兜底。业务专属的意图可以在「自定义意图集」中新建。

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

26.9 规则模拟与发布确认

适用场景：保存或发布前，确认一个具体请求会依次命中哪些规则、最终去向是什么。

操作步骤

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

你会看到：结果分两段逐条列出判定：第一段为「选路前求值」，第二段为选定目标之后的再次判定。

右侧「完整走向」只列出实际命中的规则。

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

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

26.10 请求速率限额

适用场景：限制某把密钥、某个成员或某个服务在单位时间内的请求数，保护上游并防止意外跑量。

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

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

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

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

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

新建限流、熔断或预算规则时，先把匹配条件收窄到单个模型分组或单个 API 密钥：加一条「模型分组」条件，或把「计数维度」与保留的匹配条款限定到一把自建的测试密钥。在这个范围内确认阈值、计数与恢复行为符合预期——第几次请求开始被拒、等待多久恢复——之后，再逐级放宽到整个服务或整个租户。用于收窄的密钥或服务最好只用于验证，且可用范围不含其他成员。

注意

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

26.11 并发限制与熔断

并发限制统计同时在执行的请求数。

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

核心业务优先：保留名额要和优先级配合才生效。在「全局限额」中同一调用类型下新建两条并发限制：一条匹配要保护的全部请求，填并发上限和保留名额，优先级保持 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 服务为粒度。熔断期间看到其他拒绝原因时，先确认目标所用的供应商账号是否可用、规则是否刚被修改过——修改规则会重新下发并重置熔断状态。

26.12 超限动作与临时调整

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

你会看到

• 「拒绝请求」返回 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 小时。

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

26.13 计数维度

匹配条件决定哪些请求受约束，计数维度决定这些请求怎样分别累计。例如「匹配某个模型分组、按 API 密钥计数」表示每把密钥对该分组各有一份额度；「按 API 密钥 + 按模型」计数表示每把密钥对每个模型各有一份额度，同一模型的多个上游合并计数。

匹配条件有两层：「本规则的匹配条件」使用与流量规则相同的条件类型；「保留的匹配条款」按「匹配字段 / 匹配方式 / 匹配值」配置，可按调用方、客户端 IP、模型、模型分组、实际上游、能力、MCP 服务或工具等字段匹配。两层都为空时，限额对所选调用类型的全部请求生效。

计数维度可多选，多选时按取值组合计数，可选项随调用类型变化，包括按 API 密钥、按用户、按调用方分组、按客户端 IP、按会话、按路由、按模型、按实际上游、按模型分组（按计量分组计数，与额度口径一致）、按应用、按部门、按职能组、按 MCP 服务、按 MCP 工具、按标签等。「按会话」只对模型调用、MCP 调用和连接器调用提供，A2A 调用和 API 服务没有会话标识；MCP 调用另有「按 MCP 服务」「按 MCP 工具」。

按会话计数：只用于模型调用。带显式会话身份的请求（员工对话、平台托管智能体、带 x-zenova-conversation-id 或客户端自带会话编号的请求，见 26.5 节）按会话分别计数，不同会话互不影响；按对话历史续接识别的会话与无法识别会话的请求不计入这一维度。

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

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

26.14 预算硬墙

适用场景：为成员、部门、职能组或工作空间设置周期内的 Token 或金额上限，用尽即拒绝。

操作步骤

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

关键取值

• Token 预算的单位是十亿（B）Token，例如 0.000003 B 即 3,000 Token。
• 金额预算按每次调用的有效单价计算。调用没有发布价格的模型时不按金额计费，也就不受金额预算约束；要让金额预算真正起作用，先到「价格」页为模型定价（第 5 章）。
• 取消某个周期的限制请留空：留空表示该周期不限，把已填的值清空即恢复为不限。
• 填 0 是硬墙，不是不限：该周期内任何用量都会被拒绝。

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

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

你会看到

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

注意：用量在调用完成后记账，单次调用可能把已用量推过限额，从下一次调用起拒绝；把某个周期改为 0 后，生效也有短暂的下发延迟。预算周期按自然周期重置，与速率限额的滚动窗口不同。对象级配额本身不发预警；需要提前知道的，在「运行总览 › 总览」的「预算」面板中查看各预算池是否「接近限额」。

26.15 原因码与常见现象

常见现象

• 规则保存成功但不生效：先用「验证规则」看是否「未评估」（被前序的终止规则遮蔽），再检查启用状态与调用类型。
• 429 分不清是哪一层限制：看原因码，TRAFFIC_* 为规则或全局限额，POOL_* 为模型分组配额或密钥额度。
• 备用目标没收到请求：检查是否启用了故障转移、触发条件是否覆盖实际错误、尝试预算是否已用尽。
• 按会话计数或会话切换保护对某个客户端不起作用：确认请求是否带显式会话身份，必要时让调用方携带 x-zenova-conversation-id（26.5 节）。
• 拒绝原因看不出来：具体原因在响应的 details[].reason 与 deniedBy 中。

26.16 判定阶段与部门规则

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

26.16.1 三个判定阶段

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

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

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

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

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

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

26.16.2 部门规则能做什么

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

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

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

操作步骤

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

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

能力说明

---

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