31. 问题诊断与处理

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

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

本章内容：本章面向值班管理员与替成员、调用方排查问题的技术支持人员，按「现象」组织：先给出常见现象的速查表，再说明调用失败、请求不返回、被限流、被熔断、被护栏拦截、上游报错时分别从哪里看、由谁处理；然后说明如何用「使用洞察」把零散的单次失败归纳成系统性问题，并比较成员、任务场景、模型与客户端；最后说明如何追溯配置变更，以及常见错误码与处理建议。

31.1 按现象速查

适用场景：收到问题反馈，需要先判断该去哪个页面、看哪一章。

31.2 排查的第一步：拿到三个信息

适用场景：成员或调用方报告「调不通」，但说不清原因。

动手看页面之前，先索取三样东西，后面每一步都依赖它们：

1. HTTP 状态码：401、403、404、429、502、503、504 分别落在不同环节。
2. 响应体中的 reason：平台给出的稳定原因码，比状态码更精确。同为 429，TRAFFIC_RATE_LIMITED 是本地限额，LLM_RATE_LIMITED 是上游限流，处理人不同。
3. 响应头中的 x-request-id：用它可以直接定位这一次调用。

员工在「对话」中使用智能体时拿不到响应头，可改为记录发生时间、所用智能体与会话标题。

操作步骤

1. 进入「管理后台 › 观测中心 › 运行总览 › 请求」，在搜索框粘贴 x-request-id。
2. 没有请求标识时，改按「发起人」「接入凭据」与时间范围筛选，并把「结果」设为「失败」；智能体会话可在「会话」页签按成员与时间找到会话后，从「网关调用」页签进入具体请求。
3. 打开记录，进入请求详情。

你会看到

• 「时延与成败」：状态、HTTP 状态码、失败发生在哪个环节、错误类别。
• 「路由与改写 › 命中记录」：命中了哪条规则、做了什么处置。
• 「路由与改写 › 上游尝试」：有尝试记录说明请求已发到上游；没有说明它在网关内部就被拦下了。这一条立刻把「调不通」分成两半：要么改规则，要么查上游。

31.3 调用失败：认证、授权与模型不存在

适用场景：调用方收到 401、403、404，请求根本没发到上游。

操作步骤

1. 在「管理后台 › 组织与权限 › 模型分组」打开目标分组的「可用范围」，核对调用方或其部门、职能组是否在内。
2. 在「管理后台 › 组织与权限 › 模型分组 › API 密钥管理」中按名称或前缀搜索该密钥，核对是否「已禁用」。
3. 若为 403，在请求详情「命中记录」中确认是否由流量规则拒绝。

你会看到

• 三种协议各自返回原生错误结构，但携带同一个 reason。同样的认证失败，OpenAI 返回 invalid_api_key，Anthropic 返回 authentication_error，Gemini 返回 UNAUTHENTICATED。
• 400、401、404、413 这类请求侧错误的响应头带 x-should-retry: false，表示原样重试不会改变结果。

注意：403 有两个来源，可用范围未授权，或被流量规则拒绝。前者改「可用范围」，后者改规则。处理前先在「命中记录」确认是哪一种，否则会在错误的地方改配置。

31.4 请求一直不返回：超时

适用场景：调用方等待很久后收到 504，或客户端先于平台超时断开。

超时由两层构成：网关等待上游的时间（在流量规则里配置），以及调用方客户端自己的超时。先分清是哪一层先到。

操作步骤

1. 在「管理后台 › 流量 › 流量规则」中新建规则并限定条件，例如「调用类型 = 模型调用」加一个专属请求头，避免影响其他调用方。
2. 添加处置动作「应用限额」，展开「并发、熔断与超时（可选）」。
3. 打开「上游调用超时」，填写「连接超时」与「请求超时」（毫秒）。
4. 保存，在「确认变更」中核对后点「确认并应用」。

你会看到

• 上游未按时响应时，客户端收到 504：

  {"error":{"message":"The upstream model service timed out.","type":"server_error","code":"timeout","reason":"LLM_TIMEOUT"}}

• 这类请求有上游尝试记录，上游耗时接近或超过配置的请求超时值。

注意

• 请求超时按上游真实响应时间设置。过小会把正常的长回答判成超时；过大则客户端已断开而网关还在等，白白占用连接。智能体执行长任务时，模型单次回答可能较长，设置前先在「时延与成败」中观察实际耗时分布。
• 上游确实慢时，应同时考虑增加供应商账号、配置备用档位（31.8 节）或换更快的模型。

31.5 被限流：请求速率、并发与排队

适用场景：调用方收到 429，或需要为某个调用方设定调用上限。

操作步骤

1. 在「流量规则 › 全局限额」点「新增限额」，填写名称。
2. 选择「计数维度」（如「按 API 密钥」），填写「匹配条件」选定调用方。
3. 选择「时间窗」（如「分钟」），填写「周期内请求数」与「即时突发量」。
4. 在「超限处理」中选择动作，按需填写附加参数，保存。

你会看到：三种超限动作表现各不相同。

• 选「返回固定应答」时，响应体带 zenova_degraded: true、reason_code（如 quota_exceeded）与 retry_after_seconds，usage 各项为 0，该次调用不计费。

注意

• 「返回固定应答」返回 200 而非错误码。调用方只看状态码会把降级应答当成正常回答，应以 zenova_degraded 或 reason_code 判断。员工在「对话」中看到的是这段固定回复。
• 限额在调用结束后记账，单次调用可能把用量推过限额，从下一次调用起才被拒绝；不要在临界点上依赖「一次都不超」。

31.6 熔断：目标连续失败时快速拒绝

适用场景：上游持续超时或连续报错，希望后续请求立即失败，而不是每个请求都等满超时。

操作步骤

1. 在流量规则中添加处置动作「应用限额」，展开「并发、熔断与超时（可选）」。
2. 打开「熔断」，填写「统计窗口」（如 30 秒）、「最小调用样本数」、「失败率阈值」、「慢调用阈值」与「慢调用率阈值」、「熔断持续时间」、「半开探测次数」。
3. 保存并在「确认变更」中应用。

你会看到

• 熔断打开后，客户端收到 503：

  {"error":{"code":"circuit_open","reason":"TRAFFIC_CIRCUIT_OPEN","retry_delay_seconds":29}}

• 熔断期间的请求上游耗时为 0 毫秒，说明确实被快速拒绝、没有再去打扰上游。
• 熔断持续时间到期后，平台按「半开探测次数」放少量请求试探，探测成功即恢复。

注意

• 熔断是规则级配置，只作用于命中该规则的请求；停用规则即恢复原状。
• 修改并重新下发规则会重置该规则的熔断状态。核对是否真的自动恢复时，应在不改配置的前提下等待熔断持续时间到期再观察。
• 熔断解决的是「不要继续等」，不是「上游已经好了」。频繁触发时根因仍在供应商侧。

31.7 被护栏拦截

适用场景：调用返回 403，但既不是可用范围问题，也不是限流。

操作步骤

1. 打开请求详情，看「命中记录」中命中的规则、类别与处置。
2. 把请求内容与规则条件对照，判断是否误拦。
3. 确认误拦时调整规则的条件或处置（例如把「拒绝」改为「仅记录，放行」观察一段时间）；确认违规时通知调用方修改请求内容。

你会看到：护栏拦截表现为 403，与「可用范围未授权」状态码相同，区别在于命中记录里能看到具体的护栏类别与处置。

注意

• 护栏的检测与处置都写在流量规则里，没有独立的护栏配置页（第 24、25 章）。
• 出向护栏拦截的是模型返回的正文，因此同一请求可能已经产生上游费用，而调用方拿到 403。核对费用以请求详情中的用量为准。
• 需要系统性地核对护栏判定是否正确时，在「运行总览 › 规则命中」中按规则下钻到命中的请求，逐条打开请求详情核对（第 30.9 节）。

31.8 上游报错与故障转移

适用场景：请求已到达上游，但上游返回错误、连不上或超时。

前提：模型至少有两个可用上游，或规则中配置了两个以上可用目标。

操作步骤

1. 打开流量规则详情，在「规则编排」中把转发动作设为「转发到」，启用「故障转移（高可用）」。
2. 按优先级排列目标：第 1 档主用，第 2 档起备用。
3. 勾选触发条件：上游连接失败或中断、上游超时，以及上游返回的状态码（400、429、500、502、503、504）。
4. 填写最多尝试次数与时间上限（如最多 3 次、120 秒），保存并应用。

你会看到

• 主用失败、备用成功时，客户端拿到 200，响应头带 x-zenova-route-rule，响应体 model 字段为实际提供服务的备用模型。
• 失败状态码不在触发集合内时，客户端原样收到该状态码，错误体带 details.upstream_status 与 upstream_message；这说明平台既没有重试，也没有切换目标。
• 「规则编排」把故障转移表达为一条链路（第 1 档 → 第 2 档），并说明「备用目标用尽或达到尝试上限后，停止转移；已收到响应则按响应处理，无可用响应时返回错误」。
• 「实时流量」显示每条规则的调用次数、成功率，以及「故障转移 N 次（兜住 N 次）」；各目标分行给出转出、转入次数与费用。

注意

• 400 这类参数错误的请求，重试到备用目标同样会失败。是否把它放进触发集合，取决于备用目标的参数约束；不确定时不要勾选 400。
• 上游错误原文可能通过 details.upstream_message 透传给调用方，其中含上游侧的请求标识。对外分享请求记录时应留意。

31.9 用使用洞察发现系统性问题

适用场景：单次失败已处理完，但同类问题反复出现，或需要回答「这段时间员工用 AI 哪里不顺」。

前提：账号为租户管理员；已有经过网关或客户端上报的会话数据。

操作步骤

1. 进入「管理后台 › 观测中心 › 使用洞察」，默认打开「总览」，在「统计周期」中选择周期。
2. 查看五组指标：采用（覆盖率）、效果（任务达成率、一次达成）、效率（每次达成费用、无效消耗）、用法（需求清晰度、验证习惯）、平台因素（因平台原因未达成，含外部服务与工具失败），以及「需要关注」清单与「趋势」。
3. 切到「问题」页签，按严重度、影响或费用浏览，可用「筛选」按负责方或状态收窄。
4. 打开一个问题，在「概况」中阅读费用、影响会话、次数、最近出现、每日发生次数、分布特征与原因分析、修复建议；切到「证据」查看命中的会话；「处理记录」列出此前的处置。
5. 处理后点右上角「标记为」：选「已处理，开始观察」并写一句做了什么，系统在第 7 天自动复查是否好转；或选「忽略」并选择原因「判定错误」或「接受不修」。

你会看到

• 问题状态分为未处理、观察中、已解决、已忽略。复查后页面给出「已改善，问题已解决」「未改善，问题已回到未处理」或「复查期内相关会话太少，继续观察」。
• 「判定错误」的问题不会再提醒；「接受不修」的问题在发生率翻倍时会再次提醒。
• 问题列表的列：严重度、问题、负责方、影响、费用、近 15 天走势、状态。常见问题包括上游服务报错（含被限流）、请求被本企业额度拒绝、会话内上下文反复压缩、提示词缓存反复失效等。
• 页面右上角可能提示「正在按最新规则重新分析历史会话，完成前部分指标可能变动」，或「正在分析近 N 天数据」，指标在完成前可能偏低。
• 原因分析末尾注明生成时间，其后数据仍在更新，次数与会话数以上方关键数字为准。

注意

• 诊断以「问题」为单位跨会话聚合，单次失败的调用不会单独成为问题；排查单次调用请用 31.2 至 31.8 的方法。
• 「效果」「效率」「用法」等指标依赖会话评审，需要在诊断设置中选好会话评审模型（31.11 节）；未开启时卡片显示「未开启评审」。会话中员工有效输入过少时判为内容不足，不计入任何比率。
• 「标记为」会改变他人可见的处置状态，多人共用一个租户时先与同事确认。
• 单个会话的诊断结果也显示在会话详情的「诊断」页签中（第 30.5 节）。

31.10 按成员、任务场景、模型与客户端比较

适用场景：需要找出达成率偏低的部门或成员、某类任务的主要短板，或比较不同模型、客户端的实际效果。

操作步骤

1. 在「使用洞察」切到「成员」页签：按成员列出部门、主要任务、会话/已评审（后一个数是抽样评审并计入评价的会话数，评审按每人每天抽样）、活跃天、达成率、一次达成、需求清晰度、无效消耗、最大短板与综合分；点击成员查看个人画像，点「导出表格」导出当前列表。
2. 切到「任务场景」页签：按任务类型（编码开发、缺陷排查、代码评审、文档写作、数据分析、调研分析、日常办公、其他任务）查看达成率与未达成原因，下方给出「达成率最低的部门」「做法差异」（达成会话比未达成会话多做到的做法）与「典型会话」。
3. 切到「模型与客户端」页签：在「比较维度」中选择按模型或按客户端比较，查看场次、达成率与每次达成费用（均有已按任务类型与难度校正、未校正两列）、一次达成率、换过模型的会话占比与总花费；样本不足的行标「样本不足，暂不比较」。页面上方的「达成率与费用」散点图把每个模型或客户端画成一个点，下方「换模型之后」列出会话中途换模型的组合（换前模型、换后模型、场次、换后达成率），点击某一行可查看用到该模型或客户端的会话。
4. 切到「最佳实践」页签：列出由模型从达成会话中归纳并自动发布的实践，给出名称、发布对象、做到 / 未做到达成率、状态与发布时间。打开一条可查看「实践方法」与「变更记录」；不再适用时点「撤下」，员工端立即不再显示。

你会看到

• 「做到 / 未做到达成率」注明仅供参考，不代表因果。
• 有计入评价的已评审会话的成员都有综合分、名次、「完成率比同类」与「费用比同类」，不论团队人数多少（只有一人时名次为第 1/1）。每场会话都与同类型、同难度的会话比较；同类会话较少时参考同难度的整体水平，分数更接近 50，可信度标为低、仅供参考。员工端只看到本人的结果，同类会话的其他成员不足 3 人时不显示该类的同类平均。
• 最佳实践不需要手动创建；员工在工作台「洞察 › 最佳实践」中看到推荐给自己的实践，「洞察 › 诊断」中看到本人与团队平均的对比（优于、持平或弱于团队平均）。

注意

• 「成员」页签与个人画像向租户管理员展示个人明细，开通前请确认符合本企业的员工信息管理要求。
• 比较结论依赖评审样本量；样本不足的部门、模型或客户端不参与排序。成员综合分不设人数门槛，可信度低的结果请结合会话清单查看。

31.11 诊断设置

适用场景：首次启用会话评审，或需要控制评审花费、调整周报推送。

操作步骤

1. 在「使用洞察」右上角点「诊断设置」（「总览」卡片上的「前往诊断设置」进入同一处）。
2. 在「评审范围」中设置「抽样比例」：异常会话全部评审，其余会话按每人每天的比例抽样评审。按需开启「采集助手回复正文」，用于判断智能体该不该停、员工是否在纠正。
3. 选择「会话评审模型」。每场会话最多评审一次，量大，建议选本租户可用的最便宜的对话模型；下拉中显示各模型的输入、输出单价（每百万 Token）。
4. 设置「评审并发数」（1～128）、「运行时段」与「月预算」（留空表示不限）。「运行时段」默认「不限」；评审模型与业务共用算力时，可选「每天只在指定时段评审」并填写开始、结束时间（按租户时区，可跨零点，如 22:00–07:00）。页面给出「预计月度费用」与上线补评审的一次性估算，以及「本月已用」。
5. 在「周报推送渠道」中选择已订阅「会话诊断周报」事件的通知渠道，或选「不推送」。周报每周一 09:00 推送四段判断句与简报链接，不含成员和会话内容。
6. 点「保存设置」，下一轮诊断起生效，已评审的会话不重评。

注意

• 模型必须是本租户网关里已启用的对话模型；没有可用模型时，按页面提示到模型供应商中启用上游。
• 达到月预算后，本月新会话只做规则检查，次月 1 日恢复；调高预算后下一轮即恢复。
• 设置了运行时段后，时段外不发起新的会话评审、问题分析、最佳实践与技能候选生成；规则检查与排队照常，进入时段后自动继续。时段外「使用洞察」页头提示「当前不在评审运行时段」。
• 客户端上报的费用以美元计时，需要在全局设置中填写美元汇率，否则这部分费用不计入。

31.12 追溯配置变更与合规决策

适用场景：配置变更后出现资源不可用或行为变化，或需要解释一次请求为何被允许、拦截、脱敏或改路由。

操作步骤

1. 进入「管理后台 › 审计与合规 › 操作审计」，选择覆盖问题发生时间的时间范围。
2. 在「搜索操作人、动作或资源...」中输入操作人员、动作或资源名称；需要时点「筛选」按操作、结果、数据等级、策略来源、策略动作、应用或模型收窄。
3. 打开目标记录，核对操作人员、对象、变更时间、结果与变更内容。
4. 把记录时间与「运行总览 › 请求」、会话或「智能体运营」中的异常时间对齐。
5. 确认误操作后回到对应管理页面恢复配置，再用一条正常请求和一条预期被拒的请求验证。
6. 在操作审计中确认恢复操作已经记录。

追溯一次请求的治理决策

1. 从「运行总览 › 请求」定位目标请求，记录请求 ID、模型、调用方、状态与发生时间。
2. 在「路由与改写 › 命中记录」中核对命中的流量规则、护栏类别与处置；在「差异」中核对网关对请求做了哪些改写或脱敏。
3. 涉及智能体时，从「看该会话」进入会话，查看该轮的工具调用与智能体内部上下文（第 30.6 节）。
4. 近期有配置调整时，回到操作审计查询模型、流量规则、可用范围或护栏的变更记录。
5. 把请求、命中、执行与配置变更按时间顺序整理到同一事件记录中，区分请求失败、策略拒绝和外部工具失败。

注意：审计记录说明平台实际执行了什么，不替代业务系统中的结果核对。页面只显示脱敏内容或原文已过留存期时，应以可见记录完成判断，不通过其他渠道索取或传播敏感原文。操作审计的导出与完整性校验见第 32 章。

31.13 常见错误码与处理

同一状态码下，reason 决定责任人。

通用规则

• 所有响应都带 x-request-id；OpenAI 与 Gemini 的错误体中另有 request_id，Anthropic 的在 details 中。
• x-should-retry: false 表示重试无意义；429 带 Retry-After，按其中秒数退避。
• 错误体不含上游地址、上游密钥或堆栈，可直接转给调用方或外部协作方。
• 400、413 这类由请求内容引起的错误，改网关配置无济于事，必须先修调用方的请求。完整错误码表见附录 C。

能力说明

---

上一章：30. 网关请求、会话与根因定位 · 下一章：32. 告警、通知、留存、导出与操作审计