Zentrix Gateway 流量规则配置教程

下载 PDF · 资料下载

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

本教程按场景给出从新建规则到真实调用验证的完整步骤，适合第一次配置流量规则的管理员。各场景可以单独阅读；字段的完整取值范围、默认值与限制见《Zentrix Gateway 流量规则用户手册》。示例中的规则名、模型名、密钥和阈值仅用于说明，请按实际业务替换。

1. 开始之前

1.1 准备工作

本教程中的真实调用示例统一使用下面的格式，只替换 model 与消息内容：

curl https://<网关地址>/api/v1/agent-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer <测试 API 密钥>" \
  -H "Content-Type: application/json" \
  -d '{"model":"customer-support","messages":[{"role":"user","content":"你好"}]}'

1.2 先理解三条规则

1. 自上而下判定。 网关按「优先级」数字从小到大检查已启用的规则，一条规则的全部条件都满足才算命中，不满足就跳过，继续检查下一条。
2. 两类规则。 设置了转发目标、动作为「放行」或「拒绝本次调用」的规则，命中后结束匹配，后面的规则不再判定；只做检测、限额、改写的规则，命中后继续匹配。规则清单的「命中后」列分别显示「结束匹配」「继续匹配」，悬停可查看原因。因此，限额、内容检测这类规则要排在转发规则之前。
3. 没有规则命中时，模型调用按清单末行「默认」处理，即在请求模型的全部上游之间分发。

1.3 每条规则的通用步骤

后面的每个场景都按这七步完成，场景中只写各步的具体内容：

1. 进入「管理后台 › 流量 › 流量规则」，在「规则清单」右上方选择「新建规则」，打开「规则编排」画布。
2. 在画布顶部的「请求进入」节点中填写规则名称（1–120 个字），名称应说明用途，例如“客服模型主路由”。
3. 在「条件判断」节点选择「添加条件」，在「选择匹配条件」中搜索并添加条件，选择比较方式并填写取值。条件之间是“且”，同一条件中的多个取值是“或”。
4. 选择「添加处置动作」，列表按「请求转发前」「收到上游响应后」「其他」分组，选中动作后在节点中填写字段。
5. 在右侧「调试与预览」的「验证规则」页签填写一次请求的信息，确认本规则显示「命中」或「增强规则命中，继续评估」；「配置检查」页签没有待完善项。
6. 选择底部的「保存规则」，在「确认变更」中核对「字段差异」「关联对象」和「命中顺序」，确认无误后选择「确认并应用」。页面提示「规则「名称」已保存。」
7. 用测试密钥真实调用一次，在「运行总览」的「请求」视图中打开这次请求，在「路由与改写」页签核对实际去向和命中的规则。

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

保存后网关节点加载新配置可能有几秒延迟。清单顶部出现「最近一次配置发布失败」提示时，规则尚未生效，按提示处理后重新保存。

先窄后宽。 第一次上线某类规则时，先用条件把范围收窄到一个模型分组或一把测试密钥，确认行为符合预期后再放宽到整个分组或整个租户。

2. 场景一：把请求的模型名转到指定模型

适用场景：业务系统统一请求 customer-support 这个模型名，由网关决定实际使用哪个模型；以后更换模型只改规则，不改业务代码。

示例目标：model 为 customer-support 的请求，转发到指定的一个上游。

操作步骤

1. 在「管理后台 › 模型 › 模型」中新建模型，调用名称填 customer-support，不添加上游，由流量规则供给；再把它加入调用方可用的模型分组。
2. 新建规则，名称填“客服模型主路由”。
3. 添加条件「客户端声明的模型名」，比较方式选「等于」，取值填 customer-support。这里填调用方请求里的模型名，不是模型 ID。
4. 选择「添加处置动作」，在「其他」分组中选「转发到指定目标」。编辑器自动补上条件「调用类型」为「模型调用」。
5. 在「转发到」节点中，「目标方式」选「指定上游」，在「主要目标」中选择承接请求的上游（上游按所属模型归组列出）。
6. 在右侧「验证规则」中，「调用类型」选「模型调用」，「请求的模型」填 customer-support，选择「调用方」或填写「凭据身份」，确认本规则显示「命中」，结果区「验证选定的路由目标」是刚选的上游。
7. 保存规则并确认应用。

验证

• 用测试密钥发送 model 为 customer-support 的请求，请求详情的「路由与改写」显示实际目标为所选上游。
• 再发送一个其他模型名的请求，确认它不受本规则影响。
• 规则详情的「实时流量」视图显示本规则的调用次数与成功率。

常见问题

• 验证结果显示本规则「未评估」：前面有结束匹配的规则先命中了。在规则清单中把本规则调到它前面，或收窄前面规则的条件。
• 只需在某个模型已有的全部上游之间分发时，不必新建规则：模型调用默认在请求模型的全部上游之间分发；需要限定供应商或调整分配方式时，「目标方式」选「请求模型的全部上游」，见《Zentrix Gateway 流量规则用户手册》第 7.1 节。

3. 场景二：主模型故障时自动切换到备用模型

适用场景：主模型限流、超时或不可用时，请求自动改发到另一家供应商的模型，调用方无感知。

示例目标：在场景一的规则上加一个备用模型。

操作步骤

1. 打开“客服模型主路由”的规则详情，选择「编辑」。
2. 在「转发到」节点中，主要目标保持不变，选择「添加备用档位」，在「备用档位 1」中选择备用模型。
3. 开启「启用故障转移」。触发条件默认勾选「上游连接失败或中断」「上游超时」和「上游返回指定状态码」中的 429、500、502、503、504，一般场景保持默认即可。
4. 「总尝试次数」保持 3（含首次调用），「首内容前故障转移总预算（秒）」保持 120。达到任一上限后不再尝试备用模型。
5. 在右侧「验证规则」中勾选「模拟主档失败」，结果区显示主档失败后的转移链和备用目标。
6. 保存规则并确认应用。

验证

• 主模型正常时，请求只发往主模型。
• 主模型出现限流或不可用时，规则详情「实时流量」中主模型的「转出」和备用模型的「转入」次数增加；点击带「›」的数字可查看转出原因，例如「失败后转出 · 响应被拒（429）」。
• 请求详情「路由与改写」的「尝试」列出每一次尝试的目标和结果。

常见问题

• 备用模型没有收到请求：确认已开启「启用故障转移」、实际错误在触发条件中、尝试次数和总预算没有用尽，以及失败发生在向调用方输出首个内容之前。流式回答一旦开始输出，就不会改用其他模型。
• 400 这类请求本身有误的错误不在默认触发条件中，换一个模型也会失败，不要随意加入。
• 调用方的超时时间应长于故障转移总预算，否则调用方会先放弃。
• 同一档位中的多个目标只用于分流，不互为备用；需要容灾时必须配置备用档位。

4. 场景三：新模型按比例逐步放量

适用场景：新模型上线前，先把一小部分流量分给它，观察质量和成功率后逐步提高比例。

示例目标：customer-support 的请求 90% 发往旧模型、10% 发往新模型。

4.1 按比例分流

1. 编辑“客服模型主路由”。在「转发到」节点中，「目标选择策略」选「加权轮询」。
2. 主要目标中保留旧模型，选择「添加分流目标」加入新模型。
3. 把旧模型的权重改为 90，新模型改为 10。同一档位的权重合计为 100%，调整一个目标时，其余目标按比例分配剩余权重。
4. 在右侧「验证规则」中查看各目标的期望占比，保存规则并确认应用。

4.2 观察与放量

• 规则详情的「实时流量」按目标列出「配置权重 / 实际占比」「发送次数」「发送成功率」和「耗时（中位 / 慢请求）」。点击「配置权重 / 实际占比」中带「›」的数字，可查看该目标的首选情况。
• 新模型稳定后，按 10% → 30% → 50% → 100% 逐步调高权重；全部切换后删除旧模型目标。
• 样本较少时实际占比会偏离配置值，判断时以足够多的调用为准。每个网关副本独立轮询，多副本部署时整体占比同样需要足够样本。

4.3 只让测试人员先用新模型

需要先由少数人试用、而不是按比例随机分配时，在“客服模型主路由”前面新建一条规则：

1. 新建规则，名称填“客服模型灰度”。
2. 添加条件「客户端声明的模型名」等于 customer-support，再添加条件「灰度 Cookie」：名称选 zenova_canary，取值填 beta01。需要使用自定义名称时，改用「请求头」条件，例如 x-canary 等于 beta01。
3. 添加「转发到指定目标」，主要目标选新模型。
4. 保存后，在规则清单中确认“客服模型灰度”排在“客服模型主路由”之前。

带有该 Cookie 或请求头的请求发往新模型，其余请求仍走主路由。回退时停用或删除这条灰度规则即可。

常见问题

• 加权分流本身不做容灾：被分到新模型的请求失败后不会改投同档的旧模型。需要容灾时同时配置备用档位，见场景二。
• 灰度 Cookie 的取值只写不回显；编辑规则时，Cookie 名称不变且取值留空即沿用原值。

5. 场景四：给每把 API 密钥限流

适用场景：防止单个调用方占满模型额度，例如每把密钥每分钟最多调用 60 次。

示例目标：对模型分组「客服问答」，每把 API 密钥每分钟 60 次，允许瞬时多出 10 次。

操作步骤

1. 新建规则，名称填“客服问答按密钥限流”。
2. 添加条件「模型分组」，选「客服问答」；再添加条件「调用类型」，选「模型调用」。带限额的规则必须把调用类型限定为一种。
3. 选择「添加处置动作」，在「请求转发前」分组中选「限额」，画布上显示为「应用限额」节点。
4. 保持「请求速率」开启：
   • 「计数维度」选「按 API 密钥」（模型调用的默认值），表示每把密钥分别计数。
   • 「额度用完时」选「直接拒绝」。
   • 「时间窗」选分钟，「周期内请求数」填 60，「即时突发量」填 10。
5. 不要添加转发目标。这条规则在清单中显示「继续匹配」，命中后请求仍按后续规则转发。
6. 保存时在「确认变更」的「命中顺序」中确认它排在“客服模型主路由”之前；排在后面时，在规则清单中用「移到最前」调整。

验证

1. 先把阈值临时改小（例如每分钟 3 次、突发 1），用测试密钥连续发送 6 次请求：

   for i in $(seq 1 6); do
     curl -s -o /dev/null -w "%{http_code}\n" \
       https://<网关地址>/api/v1/agent-gateway/openai/v1/chat/completions \
       -H "Authorization: Bearer <测试 API 密钥>" \
       -H "Content-Type: application/json" \
       -d '{"model":"customer-support","messages":[{"role":"user","content":"你好"}]}'
   done

2. 超出额度的请求返回 429，错误中带原因 TRAFFIC_RATE_LIMITED 和 Retry-After。

3. 换另一把测试密钥调用，确认它有自己独立的额度。

4. 确认无误后，把阈值改回正式值。

常见问题

• 这是按时间持续补充的滚动限速，不是到整点清零的配额；多个网关副本各自计数，实际放行量可能高于配置值。
• 规则内的限额超出时只能拒绝。需要排队等待或返回固定应答时，改在「流量规则 → 全局限额」中新建限额，见《Zentrix Gateway 用户手册》第 15.11 节。
• 按月或按天的总量控制使用模型分组配额或密钥额度，不使用速率限额。

6. 场景五：用并发上限和熔断保护上游

适用场景：上游模型容量有限，需要限制同时执行的请求数；上游持续失败时暂停调用，避免把问题放大。

示例目标：对模型分组「客服问答」，同时执行的请求不超过 20 个；近 30 秒失败率达到 50% 时暂停调用 30 秒。

操作步骤

1. 新建规则，名称填“客服问答上游保护”，条件同场景四：「模型分组」为「客服问答」，「调用类型」为「模型调用」。
2. 添加「限额」，在「应用限额」节点中关闭「请求速率」（只需要并发和熔断时）。
3. 展开「并发、熔断与超时（可选）」：
   • 开启「并发」，「计数维度」选「按模型分组」，「并发上限」填 20。
   • 开启「熔断」，参数保持默认：统计窗口 30 秒、最小调用样本数 10、失败率阈值 50%、慢调用阈值 2000 毫秒、慢调用率阈值 50%、熔断持续时间 30 秒、半开探测 5 次。
   • 需要限制等待时间时开启「上游调用超时」，例如连接 3000 毫秒、请求 60000 毫秒。
4. 保存并确认应用，确认规则排在转发规则之前。

验证

• 同时在途的请求超过 20 个时，新请求立即返回 429，原因 TRAFFIC_CONCURRENCY_LIMITED；在途请求结束后恢复。
• 熔断期间请求返回 503，原因 TRAFFIC_CIRCUIT_OPEN，上游不再收到这些请求；30 秒后进入半开状态，探测成功即恢复。
• 用受控失败验证熔断的完整步骤见《Zentrix Gateway 流量规则用户手册》第 6 节。

常见问题

• 熔断本身不切换模型。需要在熔断时改用备用模型，在转发规则中配置故障转移（场景二），网关会跳过熔断中的目标。
• 「慢调用阈值」只用于熔断统计，不会中断慢请求；需要中断时使用「上游调用超时」。
• 修改规则会重新下发配置，并重置熔断状态。

7. 场景六：对话中的手机号、身份证号自动脱敏

适用场景：用户提问或模型回答中出现手机号、身份证号、银行卡号时，替换为占位符后再继续处理，避免敏感信息发给外部模型或返回给调用方。

示例目标：模型分组「客服问答」的提问和回答都做敏感信息脱敏。

操作步骤

1. 新建规则，名称填“客服问答敏感信息脱敏”，添加条件「模型分组」为「客服问答」。
2. 选择「添加处置动作」，在「请求转发前」分组中选「内容检测 · 对话内容」。
3. 「检查阶段」选「用户提问与模型回复」。
4. 「检查方式」勾选「敏感信息」，在「检测范围」中选择行业模板，或单独选择「手机号」「身份证号」「银行卡号」等类型。
5. 「命中后的处理」选「脱敏后继续处理」。上线初期不确定误报情况时，可以先选「仅记录，放行」观察一段时间。
6. 在右侧「验证规则」中，「检测方向」选「输入」，「消息」中填“我的手机号是 13812345678”，在「内容检测结果」中确认命中「手机号」。
7. 保存并确认应用。

验证

• 用测试密钥发送一句带手机号的提问，请求详情中发往上游的内容里，手机号已替换为占位符，调用方仍收到正常回答。
• 在「规则命中」中可以看到这次命中及其处置。

常见问题

• 人名、地址、机构名需要先设置「敏感信息识别模型」，见《Zentrix Gateway 用户手册》第 13.6 节；未设置时勾选会打开设置抽屉。
• 身份证号、银行卡号等带校验位的类型，写法不规范或校验位错误时不会被识别，测试时使用格式正确的样例。
• 从图片中识别出的敏感信息无法打码，会按拦截处理。
• 一条规则只有一个检查阶段；多条规则同时命中时，同一类型取更严格的处理（拦截高于脱敏，脱敏高于仅记录）。

8. 场景七：提问中出现违禁词时拦截并回复固定话术

适用场景：用户提问包含受控词时，不调用模型，直接回复一段固定说明。

示例目标：提问中出现词库“客服禁用词”里的词语时拦截，并回复“该问题暂不支持，请联系人工客服。”

准备词库

1. 进入「管理后台 › 护栏 › 护栏规则」，切到「词库」页签，选择「新建词库」。
2. 「名称」填“客服禁用词”，「类型」选「自定义黑名单」，「分类」选最接近的类别。
3. 打开词库，选择「添加词条」逐条添加；词条较多时用「导入」上传 UTF-8 编码的 .txt 文件，每行一条。

操作步骤

1. 在「规则清单」右上方选择「导入规则模板」，切到「内容检测」分组，选择「关键词拦截并回复话术」，填写高亮的必填项后选择「导入这条」；也可以选择「新建规则」从空白开始。
2. 添加条件「模型分组」为「客服问答」。
3. 在「内容检测 · 对话内容」节点中，「检查阶段」选「用户提问」，「检查方式」勾选「关键词」，在「引用词库」中选择“客服禁用词”。
4. 在「回复话术」中，「拦截回复」选「自定义话术」，在「默认回复话术」中填“该问题暂不支持，请联系人工客服。”
5. 在右侧「验证规则」的「消息」中填一句包含禁用词的话，确认「内容检测结果」显示拦截。
6. 保存并确认应用。

验证

• 用测试密钥发送一句包含禁用词的提问，返回 403，error.code 为 content_policy_violation，error.message 为配置的话术；上游没有收到这次请求。
• 发送一句正常提问，确认正常回答。

常见问题

• 全角、繁体、同形字、零宽字符等改写写法会自动归一化后再匹配，无需为它们单独添加词条；拼音写法只记录不拦截，需要拦截时把拼音作为词条的别名添加。
• 话术应说明无法继续的原因和求助渠道，不要透露规则、阈值或绕过方法。
• 需要按话题、风险类别判断而不是按固定词语时，使用模板「自定义话题拦截」或「风险内容拦截」，需要先设置内容判断模型，见《Zentrix Gateway 用户手册》第 14.3 节。

9. 场景八：含敏感信息的请求只发给私有部署模型

适用场景：请求中含身份证号、银行卡号等敏感数据时，只交给本地部署的模型处理；其余请求仍按原路由发往外部模型。

示例目标：customer-support 的请求中含身份证号或银行卡号时，转发到私有部署模型。

操作步骤

1. 新建规则，名称填“敏感请求走私有模型”。
2. 添加条件「客户端声明的模型名」等于 customer-support。
3. 添加条件「请求含敏感信息」，选择「身份证号」「银行卡号」。
4. 添加「转发到指定目标」，主要目标选私有部署模型。
5. 保存时确认本规则排在“客服模型主路由”之前。

验证

• 在右侧「验证规则」的「更多请求事实」中，「敏感信息类型」填所选类型，确认本规则命中。这里填写的是假设值，只用于检查规则逻辑。
• 用测试密钥经 OpenAI 兼容入口发送一句含格式正确的身份证号的提问，请求详情显示实际目标为私有部署模型。

常见问题

• 这个条件只在平台模型调用入口（例如 OpenAI 兼容入口 /api/v1/agent-gateway/openai/v1/*）上于规则判定前识别；网关原生入口 /v1/* 以及 MCP、A2A、API 服务调用不产生这一信息，规则不会命中。
• 识别服务不可用时请求返回 503，不会按“未检出”放行到外部模型。
• 改道只改变去向，请求内容原样发给私有模型。需要同时脱敏时另建一条场景六的规则；同一条规则中不能同时使用「请求含敏感信息」条件和「敏感信息」检测。
• 人名、地址、机构名不能作为本条件，只能在内容检测的「检测范围」中使用。

10. 场景九：只允许指定调用方使用某个模型

适用场景：某个高成本模型只开放给少数 API 密钥，其他调用方请求这个模型名时直接拒绝。

示例目标：premium-chat 只允许“研发组密钥”和“数据组密钥”使用。

这个场景需要两条规则配合，第一条放行名单内的调用方，第二条拒绝其余请求。

第一条：名单放行

1. 新建规则，名称填“高端模型名单放行”。
2. 添加条件「客户端声明的模型名」等于 premium-chat。
3. 添加条件「调用方」：「调用方类型」选「API 密钥」，比较方式选「属于」，选中“研发组密钥”和“数据组密钥”。
4. 选择「添加处置动作」，在「其他」分组中选「放行」。
5. 保存并确认应用。

第二条：兜底拒绝

1. 新建规则，名称填“高端模型兜底拒绝”。
2. 添加条件「客户端声明的模型名」等于 premium-chat。
3. 在「其他」分组中选「拒绝」，「拒绝原因码」填 premium_model_not_allowed（小写字母、数字和下划线）。
4. 保存时在「确认变更」中确认它排在“高端模型名单放行”之后。

验证

• 在「验证规则」中，「凭据身份」选“研发组密钥”，第一条显示「命中」；改选其他密钥，第一条显示「不匹配」、第二条显示「命中」。
• 用名单外的密钥真实调用，返回 403，错误中带 deniedBy: routePolicy 和原因码 premium_model_not_allowed。

常见问题

• 「放行」只结束规则判定，请求随后按网关既有路由处理，premium-chat 必须能被默认路由找到；需要指定去向时，把第一条的动作改为「转发到指定目标」。
• 「调用方类型」为「API 密钥」的条件不约束平台内发起的调用；平台用户或智能体的调用需要另选对应的调用方类型，或使用「组织成员」条件按部门和职能组限定。
• 长期的模型使用权限应在模型分组的可用范围中配置；本场景适合按模型名在网关入口统一收口。

11. 场景十：工作时间和夜间使用不同模型

适用场景：工作时间使用响应更快的模型，夜间改用成本更低的模型。

示例目标：北京时间 09:00–18:00 使用模型 A，其余时间使用模型 B。

操作步骤

1. 新建规则“客服白天路由”：添加条件「客户端声明的模型名」等于 customer-support；添加条件「时段」，时区选 Asia/Shanghai，时间段填 09:00-18:00；动作「转发到指定目标」选模型 A。
2. 新建规则“客服夜间路由”：只添加条件「客户端声明的模型名」等于 customer-support，动作转发到模型 B。
3. 在规则清单中确认“客服白天路由”排在“客服夜间路由”之前。

验证

在右侧「验证规则」中修改「验证时间」，分别填工作时间内和工作时间外的时刻，确认命中的规则不同。不需要等到实际时段再测试。

常见问题

• 时段按所选时区判定，与管理员电脑的时区无关。时间段左闭右开，09:00-18:00 包含 09:00、不包含 18:00；允许跨零点，例如 22:00-06:00。
• 只支持每日的时:分窗口，不支持按星期或日期。
• 第二条规则没有时段条件，作为兜底，必须排在后面。

12. 场景十一：按问题难度选择模型

适用场景：困难问题交给能力更强的模型，普通问题交给成本更低的模型，由网关自动判断。

示例目标：调用方请求 auto 时，难题发往强模型，其余发往经济模型。

前提

在「系统设置 → 全局设置 →「常规」页签」的默认模型中，为「意图识别」选择模型。

操作步骤

1. 进入「流量规则 → 意图集 → 内置意图」，选择右上方的「测试意图识别」，输入几句业务中的真实提问并选择「识别」，确认「难度」的判断符合预期。
2. 在维度「任务难度」中找到「难题」，选择该行的「用它建规则」。编辑器预填意图条件和规则名「任务难度：难题」。
3. 补充条件「客户端声明的模型名」等于 auto，添加「转发到指定目标」，主要目标选强模型，保存。
4. 新建兜底规则“自动路由兜底”：条件「客户端声明的模型名」等于 auto，转发到经济模型，排在难题规则之后。

验证

在右侧「验证规则」的「更多请求事实」中填写「意图提示词」，分别输入一句难题和一句简单问题，确认命中的规则不同。验证会调用意图识别模型，请使用允许送检的文本。

常见问题

• 意图识别不可用（未设置模型、服务停用、调用失败）时，意图条件按不命中处理，请求由兜底规则接管，因此兜底规则不能省略。
• 每次判断都会调用一次意图识别模型，增加时延和费用；只对需要的模型名启用。
• 业务专属的分类可以在「意图集 → 自定义意图集」中新建，见《Zentrix Gateway 流量规则用户手册》第 9 节。

13. 场景十二：禁止调用危险的 MCP 工具

适用场景：某个 MCP 服务提供删除、清空类工具，不允许智能体或调用方直接调用。

示例目标：禁止调用 MCP 服务“工单系统”中名称以 delete_ 开头的工具。

操作步骤

1. 新建规则，名称填“禁止工单删除工具”。
2. 添加条件「调用类型」，选「MCP 调用」。
3. 添加条件「具体能力」，选择 MCP 服务“工单系统”。
4. 添加条件「工具名」，比较方式选「属于」，填写 delete_*。已选 MCP 服务时也可以从已登记的工具中选择。
5. 添加条件「MCP 方法」，保持默认的「调用工具」。
6. 在「其他」分组中选「拒绝」，「拒绝原因码」填 mcp_tool_blocked。
7. 保存并确认应用。

验证

用测试客户端调用一次 delete_ticket，调用被拒绝；在「规则命中」中可以看到本规则的命中记录。再调用一个普通工具，确认不受影响。

常见问题

• 「MCP 方法」选了「列出工具」「资源」或「提示词」时不产生工具名，不能再配「工具名」条件。
• 需要检查工具参数内容（例如命令中是否含 rm -rf）而不是按工具名一刀切时，使用「内容检测 · 工具调用」，见《Zentrix Gateway 流量规则用户手册》第 5.2 节。

14. 场景十三：限制单次请求的 Token 和请求体大小

适用场景：防止超长上下文或超大请求体消耗过多费用、拖慢上游。

示例目标：模型分组「客服问答」的单次请求输入不超过 32000 Token、输出不超过 4096 Token，请求体不超过 2048 KB。

操作步骤

1. 新建规则“客服问答请求上限”，添加条件「模型分组」为「客服问答」。
2. 在「请求转发前」分组中添加「单次请求 Token 上限」，「最大输入 Token」填 32000，「最大输出 Token」填 4096。
3. 再添加「请求体大小上限」，填 2048。
4. 不添加转发目标，保存后这条规则显示「继续匹配」，确认它排在转发规则之前。

验证

• 发送超长输入的请求，在发给供应商之前被拒绝，错误说明这是平台限制。
• 请求体超过上限时返回 413。
• 输出上限会改写请求中的 max_tokens，在请求详情发往上游的请求中可以看到。

常见问题

• 多条规则同时设置上限时取最严的值。
• 请求体上限按入站原始请求体判断，范围 1–32768 KB。

15. 场景十四：给一类请求统一加系统提示词

适用场景：为某个模型分组的所有调用统一加上身份说明、输出格式或安全要求，并且可以按版本切换和回滚。

准备提示词

进入「管理后台 › 能力 › 提示词库」新建提示词，见《Zentrix Gateway 用户手册》第 6.9 节。正文中只能使用网关系统变量，例如 {{tenant}}、{{principal.user}}、{{request_id}}（平台调用号）、{{client_request_id}}（调用方传入的 X-Request-Id）；工作空间级提示词不能被流量规则引用。

操作步骤

1. 新建规则“客服问答统一提示词”，添加条件「模型分组」为「客服问答」。
2. 在「请求转发前」分组中添加「提示词」：「选择提示词」选刚建的提示词，「版本标签」选「正式」，「注入位置」选「前置」。
3. 保存并确认应用，确认规则排在转发规则之前。

验证

用测试密钥调用一次，在请求详情中查看发往上游的请求：第一条是注入的系统消息，变量已替换为实际值；调用方原始请求中没有这条消息。

常见问题

• 节点提示「当前标签为其他版本，未发布」时，先确认提示词的版本与标签关系。
• 把「正式」标签移到新版本后，引用它的规则需要重新保存才会使用新版本。

16. 场景十五：相似问题直接返回缓存答案

适用场景：常见问题、知识问答等重复提问多的服务。问题足够相似时直接返回之前的回答，不再调用模型，减少费用和等待时间。

示例目标：模型分组「常见问题解答」的单轮问答开启语义缓存。

开始前确认

本场景使用 1.1 节的 OpenAI 兼容入口。语义缓存按一次请求命中的全部规则整体判断，只要其中任一条规则含有以下配置，这次请求就既不查也不写缓存：

• 多个转发目标、开启故障转移，或目标方式为「请求模型的全部上游」；
• 单次请求 Token 上限；
• 挂载插件；
• 改写请求头；
• 响应改写，包括改写响应头、改写响应字段和状态码映射；
• 检查模型回复的内容检测；
• 「应用限额」之后还有内容检测、提示词、改写请求字段或改写请求正文。

缓存答案不会再经过这些改写和检查；去向不确定时，还可能把其他模型的回答返回给调用方，所以这些情况下缓存不参与。最后一项按整条规则链的执行顺序判断：先按规则在清单中的先后，再按每条规则画布上的执行顺序。限额排在内容检测、提示词和改写之后的规则，以及转发到单个指定上游的规则，不影响缓存。按前面的场景对照「客服问答」：

• 场景一的转发规则不影响缓存。
• 场景四、五的限额规则在清单中排在场景七（违禁词）、场景十四（提示词）的规则之后时，不影响缓存；排在它们前面时，限额之后还有内容检测或提示词，缓存不参与。
• 场景二（故障转移）、场景三（按比例分流）的规则，以及场景六（检查模型回复）、场景十三（Token 上限）的规则，会让命中它们的请求不走缓存。

因此本场景用另一个模型分组「常见问题解答」作为示例。编辑器只在同一条规则内有冲突时提示，多条规则之间的组合不会提示，上线前务必按下面的「验证」实测一次。

语义缓存使用租户自选的向量模型和重排模型。开始前，在「管理后台 › 系统设置 › 全局设置 ›「常规」页签 › 默认模型」中设置「语义缓存向量模型」和「语义缓存重排模型」：

• 向量模型用于找出相近的已缓存问题，重排模型用于判断是否足够相似。保存重排模型时，系统用内置的同义与非同义问法样例实际调用该模型并确定命中标准，不能区分两类样例的模型无法保存，需换用其他重排模型。
• 两类调用按所选模型计费，在用量与调用记录中分别标为「语义缓存向量」「语义缓存重排」。当前问题和同一范围内已缓存的相近问题会发送给所选模型，选用外部供应商的模型前请确认数据边界。
• 使用 OceanBase 作为平台数据库的部署不支持语义缓存。

操作步骤

1. 新建规则，名称填“常见问题语义缓存”，添加条件「模型分组」为「常见问题解答」。
2. 选择「添加处置动作」，在「其他」分组中选「语义缓存」。如果还没有条件「调用类型」，编辑器会自动补上「模型调用」。节点中没有要填写的字段，节点上显示两个语义缓存模型的状态；命中标准由所选重排模型决定，有效期和隔离范围由平台统一设定。两个模型未设置或不可用时，「语义缓存」不可选，或节点上提示设置模型，可在节点上直接打开设置。
3. 这条规则不需要其他动作。在已有规则上添加「语义缓存」时，节点中出现「语义缓存在这条规则上永远不会参与」的警告，说明这条规则本身含有上述配置：如果是「应用限额」排在内容检测、提示词或改写前面，展开「应用限额」节点，用「下移」把它移到这些动作之后；其他配置需要删除相应动作，或改为单独建一条规则。
4. 保存并确认应用。规则显示「继续匹配」，请求随后按「默认」行在请求模型的全部上游之间分发。两个语义缓存模型未就绪时保存会被拒绝，先设置模型再保存。

验证

在 1.1 节的调用命令中加上 -i 参数以显示响应头，model 换成「常见问题解答」对应的模型名。

1. 用测试密钥发送一句单轮提问，例如“如何修改登录密码？”，确认响应头 x-zenova-cache: miss：已查缓存但没有命中，这次回答会写入缓存。
2. 等第一次回答完整返回后，用同一把密钥再发一次同样的问题。确认响应头为 hit，请求详情显示「命中语义缓存，未请求上游」。换一种意思相同的问法也可能命中，取决于重排得分是否达到所选重排模型的命中标准。
3. 换另一把 API 密钥发送同一问题，结果为 miss。缓存按密钥隔离，同一所有者的不同密钥也互不命中。
4. 「运行总览」的「语义缓存节省」统计命中次数、节省的 Token 和净节省金额（命中省下的金额扣除「语义缓存向量」「语义缓存重排」两类调用的费用）。命中缓存的调用不计费，也不计入速率限制和租户每月 Token 上限。

常见问题

• 响应中没有 x-zenova-cache 头：这次请求没有查缓存。打开请求详情的「路由与改写」页签，查看「请求去向」中的「语义缓存」一行：

  • 有这一行时，它写明了原因，例如「未参与：规则链含 Token 上限」「未参与：限额后面还有护栏或改写，要到派发时才执行」「未参与：多轮对话不使用缓存」「未参与：调用方要求跳过缓存」，按原因调整规则或请求。缓存只对 Chat Completions 格式、只有一条用户消息（可另带系统消息）、请求体不超过 256 KiB 的请求生效；语义缓存模型未设置、不可用或调用失败时，请求照常调用模型，不会失败，原因例如「未参与：未设置语义缓存向量模型」「未参与：语义缓存重排模型不可用」。
  • 没有这一行时，说明请求没有命中开启了语义缓存的规则，检查本规则的条件和启用状态。

• 第二次仍是 miss：以下几种回答不会写入缓存，下次仍会调用模型：

  • 第一次调用失败或中途断开；
  • 回答中含工具调用；
  • 回答超过 512 KiB。

  另外，修改模型、上游、供应商或规则后，旧缓存不再命中；更换语义缓存向量模型后，已有缓存条目也不再命中，新条目随请求逐步积累。

• 额度用满后，能命中缓存的请求也返回 429：模型分组「可用范围与配额」的额度池在查缓存之前判断，额度池用满后请求直接被拒绝。速率限制和租户每月 Token 上限在查缓存之后判断，用满时能命中缓存的请求仍返回缓存答案。

• 响应头为 bypass：调用方在请求头 x-zenova-cache-control 中带了 no-cache。这次请求不查缓存，但仍会写入。

• 需要让某次请求跳过缓存，例如调试或要求实时结果时，在请求头中带 x-zenova-cache-control: bypass。其他指令和缓存参数见《Zentrix Gateway 流量规则用户手册》第 10 节。

17. 上线前检查与排查速查

17.1 上线前检查清单

• 规则名称能说明用途，条件已收窄到预期范围，没有误建“匹配所有请求”的规则。
• 限额、内容检测、提示词等继续匹配的规则排在转发规则之前；兜底规则排在最后。
• 右侧「验证规则」中，应命中和不应命中的请求结果都符合预期。
• 用测试密钥完成至少一次真实调用，并在请求详情中核对了实际去向。
• 限流、熔断阈值先在测试密钥或单个模型分组上验证过，再扩大范围。
• 内容检测先用「仅记录，放行」观察过误报，再改为拦截或脱敏。
• 清单顶部没有「最近一次配置发布失败」提示。

17.2 常见现象速查

错误码的完整含义见错误参考；各字段的取值范围与更多排查方法见《Zentrix Gateway 流量规则用户手册》第 8 节。