20. 网关请求、会话与根因定位
完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。
本章内容：本章面向平台管理员、运维人员与安全审计人员，说明如何检索单次网关请求、读懂请求详情的五个页签、识别调用来自哪个客户端、按会话还原多轮对话、查看 MCP 工具调用活动与策略命中，以及遇到流量突增或熔断时的处置路径。入口与可见角色见第 19.1 节；按现象排查的路径见第 21 章。
20.1 检索网关请求
「请求」页签记录经过网关的每一次模型、MCP、A2A 与 API 服务调用，包括被策略拦截的请求。排查任何运行期问题，都从这里找到目标请求开始。
前提：账号为租户管理员，或具备运营、财务、审计角色。运营角色只看到本人发起的请求。
操作步骤
- 进入「管理后台 › 观测中心 › 运行总览」，选择「请求」页签，在工具栏选择覆盖问题发生时间的时间范围。页面上方的「请求趋势」条可拖选，进一步缩小时间窗。
- 已知请求 ID、链路 ID 或成员时直接在搜索框输入。请求 ID 取自响应头
x-request-id（或x-lp-data-plane-request-id），链路 ID 取自x-trace-id。 - 需要按条件筛选时点「筛选」添加条件。条件以「字段 = 值」显示在工具栏，点「×」移除，点「清空」全部移除。
- 点击目标行打开请求详情（20.2 节）。详情左上角可用上一条、下一条在当前列表中切换。
- 常用筛选组合可通过「视图」保存；需要导出当前结果时点「导出 CSV」。
常用条件包括：结果（已完成 / 失败 / 已取消 / 已拦截）、HTTP 状态码、耗时区间、发起人、接入凭据、客户端、终端用户、模型、供应商、渠道、调用类型、MCP 工具、命中策略、责任方、该次尝试失败、网关兜住方式、用途、推理强度、标签、会话 ID、请求 ID。其中「网关兜住方式」取值为重试、故障转移、排队。列表主要列包括链路 ID、发起人 · 客户端、部门、上游端点、全周期耗时、结果、失败阶段、时间、请求造型、耗时构成、网关耗时、上游响应耗时、模型、用途、推理强度、用量与费用。
注意
- 「导出 CSV」为固定字段，导出的是当前筛选结果，没有字段选择或格式自定义入口。列表规模很大时，优先缩小时间范围或用请求 ID 精确搜索。
- 因密钥写错、伪造而认证失败的请求无法确定调用身份，按接入凭据或发起人筛选时不会出现；排查时用调用方收到的
x-request-id按请求 ID 搜索。
20.2 阅读请求详情
详情页头显示链路 ID、结果、发起人与请求造型，右上角提供「看该模型流水」「看该会话」（属于会话的请求显示）与刷新。五个页签分别回答：请求（四段报文）、概要（谁通过哪把凭据从哪个客户端发起、最终用了哪个模型和服务）、Token 与用量（用量与费用）、时延与成败（成败与耗时分布）、路由与改写（去了哪里、试了几次、改了什么、命中什么规则）。
「概要」分四组：身份归属（链路 ID、请求 ID、网关事件 ID、所属空间、发生时间、保留期）、发起人与凭据（发起方类型、发起人、发起人邮箱、客户端识别、接入凭据前缀、客户端 IP、入口 IP 异常）、调用对象与模型解析（事件类型、请求造型、对象类型、客户端声明的模型、实际路由模型、计量分组）、标签。
四段报文与差异
- 在报文区选择段落：「客户端请求」「发往上游的请求」「上游响应」「返回客户端的响应」，每段标出字节数。发生重试或故障转移时，上游各段按尝试次序分开。
- 在每段下切换「正文」「请求头」（或「响应头」）；「复制全文」复制当前段。
- 在「发往上游的请求」下选择「差异」，查看网关相对客户端请求做了哪些改动。跨协议转发时页面顶部注明入站与上游协议，例如「跨族转发：入站 Anthropic Messages → 上游 OpenAI Chat Completions」；未能转发到上游的字段在「未转发到上游」中逐项列出。
时延与路由：「时延与成败」给出状态、HTTP 状态码、失败阶段、错误类别与拦截原因，并以甘特条展示耗时分解（口径见 19.2 节），被拦截的请求各耗时字段为空。「路由与改写」的「请求去向」给出声明的模型、接管规则、最终供应商与模型及路由结论；「上游尝试」逐行给出序号、档位、供应商 / 模型、账号与选号理由、结果、原因、状态码、耗时、首字时间与参数调整；「请求改动」列出按目标能力调整的内容与规则改写；「命中记录」给出本次命中的全部策略及其处置与故障转移。
注意
- 请求头中的
authorization等凭据在采集时抹除，显示为「已抹除·长度 N」；每次读取正文或差异都写入审计记录。 - 报文不可读时页面给出原因，例如按数据留存设置未留存报文、报文已超过留存时长并已清理、报文归档中稍后可查看（第 19.5 节）。
- 被策略拦截的请求没有上游段，差异视图只在请求方向提供。
- 「请求去向」区域可能提示「本次请求未保存规则链快照」，此时以「命中记录」为准；规则已被删除时会标注并保留历史命中。
20.3 区分失败类型
同样是「调用失败」，原因可能在上游、在策略、在额度，也可能在调用方自身。按以下线索区分：
| 类型 | 结果 | 详情中的线索 | 返回给调用方 |
|---|---|---|---|
| :-- | :-- | :-- | :-- |
| 上游失败 | 失败 | 「上游尝试」结果为响应被拒、超时、流中断等，带上游状态码 | 4xx / 5xx |
| 策略拒绝 | 已拦截 | 无上游尝试；「命中记录」中处置为拒绝，规则名可点击 | 403，deniedBy: routePolicy |
| 护栏拦截 | 已拦截 | 「拦截原因」有值，「命中记录」中有内容护栏的命中 | 403，code: content_policy_violation |
| 配额或限流 | 已拦截 | 无上游尝试；「错误类别」以中文说明原因与恢复时间 | 429，reason 为 POOL_EXHAUSTED、TRAFFIC_RATE_LIMITED 等 |
| 调用方请求错误 | 失败 | 失败阶段为参数校验或上游返回 4xx | 400 / 404 / 422 |
查看故障转移与切换代价：在「筛选」中添加「网关兜住方式 = 故障转移」列出相关请求；打开一条，在「上游尝试」中逐行查看每次尝试的档位、结果与耗时。两次耗时之和即用户感受到的总时间，第一次尝试的耗时就是切换代价。代价过大时调整对应流量规则中该档位的超时时间（第 15 章）。
20.4 识别调用来自哪个客户端
网关按请求头 User-Agent 等特征自动识别常见的智能体客户端，例如 Claude Code、Codex、WorkBuddy；无法识别的显示为「自定义客户端」或「未知客户端」。识别结果显示在「请求」列表的「发起人 · 客户端」列、请求详情「概要 › 客户端识别」、会话列表与详情，以及 MCP 服务的「调用来源」列（20.6 节）。
注意
- 调用方自研程序没有可识别特征时，可在「获取 API 密钥」时为其新建并命名客户端，请求会归入该客户端。
- 客户端识别用于统计与排查，不作为访问控制依据；按客户端限制访问应使用流量规则的条件（第 15 章）。
- 模型调用的客户端识别与 MCP 调用的来源识别是两套判断。判断实际来源时两处都看。
20.5 查看会话与对话记录
多轮调用按会话串联：调用方在请求头携带 x-zenova-conversation-id: <会话标识> 时，同一标识的调用归入同一会话；未携带时网关依次按客户端自带的会话编号、Responses 续接与完整对话历史的延续关系自动归并，首条用户消息不用于识别会话（识别顺序见第 15.5 节）；客户端通过 OTLP 上报的步骤并入对应会话（第 19.3 节）。
操作步骤
- 在「运行总览」选择「会话」页签。列表列出标题（取首条用户消息）、客户端、接入、成员、来源、轮次、费用、最近活动；可按客户端、来源、诊断问题类别筛选。也可在请求详情点「看该会话」直接进入。
- 打开会话详情。页头显示最终用户、组织、调用方、密钥与活跃时段，右上角提供「查看本会话的 N 次请求」「导出 JSONL」「导出报告 PDF」。
- 切换到「对话」页签：左侧按轮列出首句、费用与耗时，可按「全部 / 失败 / 网关兜住 / 无网关记录」过滤并搜索对话内容；右侧显示所选轮的用户输入、模型回复，以及该轮耗时、模型调用次数、重试、工具调用和每次模型调用的模型、Token、耗时与结果。
其余页签：「概要」给出轮次（成功 / 失败 / 进行中）、最慢一轮、花费与网关调用计数；「客户端轨迹」把客户端上报的步骤按「轮 › 步 › 记录」分组并带时间轴，可播放回看；「网关调用」给出顶部结论、服务与渠道统计、耗时构成与按「轮 › 调用」展开的请求时间线，每次调用可点进请求详情；「诊断」列出该会话命中的诊断问题。
导出会话：「导出 JSONL」提供「Hermes 训练格式」与「轮次运维明细」两种格式，后者每行一轮，包含会话与轮次标识、起止时间、耗时、重试次数、模型调用数、子代理 / 辅助 / 压缩分道计数及该轮完整消息。「导出报告 PDF」生成含会话概览、Token 与成功率、每轮摘要、网关调用结论、故障明细、策略命中、诊断与审计事件的报告，可用于离线归档。
注意
- 调用方以同一个
x-request-id重发请求时，两次调用都会保留；平台把重发归入「客户端重发的上下文」，不计入「重试」计数。轮次的「重试」统计的是网关内部发起的重试。 - 会话列表数据量大时没有关键字搜索框。按标题定位具体会话时，从请求详情的「看该会话」进入更快。
- 「网关调用」页签显示「本会话未经平台网关调用模型」时，客户端可能直连了上游，这部分的成本、失败与策略在网关侧都看不到。
- 导出入口按会话来源显示，客户端上报型会话可能只提供「导出报告 PDF」。
20.6 查看 MCP 工具调用活动
MCP 服务的每次工具调用、配置导出、令牌签发与撤销都会留下活动记录，可用于确认谁在什么时候用哪个客户端调用了哪个工具。
操作步骤
- 进入「管理后台 › 能力 › MCP 服务」，打开目标服务，选择「调用情况」页签。
- 页面顶部显示服务状态、限流与熔断状态；「调用趋势」可在「业务调用」「协议活动」「全部活动」之间切换并选择时间范围，下方显示调用量、成功率、平均耗时、P95 耗时与当前并发。
- 在「最近调用」中查看每次调用，可用右上角「全部调用方」按用户筛选。
- 点击一行查看「调用载荷」：客户端请求、发往上游的请求、上游响应、返回客户端的响应四段正文与请求头。
「最近调用」列出时间、调用来源（客户端名称与来源入口）、用户、工具、类型（工具的副作用类型）、状态与结果（失败时给出原因，例如「上游服务错误」「参数无效」「配置快照中该接口动作未启用」）、耗时与来源 IP。需要在跨服务范围内查看时，在「运行总览 › 请求」中添加「调用类型 = MCP 调用」或「MCP 工具」筛选，可使用与模型调用相同的请求详情。
控制面事件与审计
- 成员在工作台导出 MCP 连接配置、签发令牌、撤销令牌，都会记入该服务的活动记录（「全部活动」）。
- 令牌签发与撤销同时写入「管理后台 › 审计与合规 › 操作审计」，记录操作人、对象、时间与来源 IP。
- 连接配置中的令牌只显示一次并带到期时间；活动记录与审计中只显示令牌指纹前缀，不显示全量。
20.7 会话诊断与策略命中
会话诊断：使用洞察对近期会话自动运行诊断规则，把同类现象归并为一个「问题」，给出影响范围、费用、原因分析与修复建议。
- 进入「管理后台 › 观测中心 › 使用洞察」，选择「问题」页签。
- 列表按严重度、问题、负责方、影响会话数、次数、费用、近 15 天走势与状态排列，用「筛选」按负责方或状态收窄。
- 点击问题进入详情，读「概况」中的费用、影响会话、次数、最近出现、每日发生次数与原因分析；切到「证据」查看命中的会话。
- 处理完成后在右上角「标记为」中选择处置状态，系统在观察期后自动复查。
注意：原因分析带有生成时间，其后数据仍在更新，以页面上方的关键数字为准；首屏加载较慢，等指标与列表出现后再操作；「证据」页签不提供逐条下钻到会话详情。
策略命中：「规则命中」页签按规则汇总策略在时间窗内的命中情况。
- 在「运行总览」选择「规则命中」页签，选择时间范围（默认最近 7 天）。
- 列表按规则列出策略规则、匹配判定条件、网关执行动作、命中次数与来源数、下钻查看、最近命中、7 天走势；搜索框可按规则名称或 ID 搜索。
- 点「筛选 › 处置」，按放行、拒绝、改路由、改写、降级、限速筛选。
- 点某条规则的「下钻命中请求 ➔」，页面切换到「请求」页签并自动带上「命中策略」筛选，打开其中一条即可在「路由与改写 › 命中记录」中核对处置与结果。
注意
- 列表是按规则的汇总，不是逐条命中记录；逐条记录在下钻后的请求列表或请求详情中查看。
- 脱敏类动作以「脱敏后继续处理」等描述显示在「网关执行动作」中，筛选时归入对应的处置类型；规则已删除但仍有历史命中时会标注说明。
- 个别情况下，对护栏类规则下钻后结果为空。此时改用「请求」页签按「命中策略」直接筛选该规则。
20.8 流量突增与熔断事件
适用场景：出现流量异常、上游熔断或费用突增时，需要确认发生了什么、影响多大。
操作步骤
- 在「运行总览 › 总览」查看「流量潮汐与双向承压」，对比当前 QPS 与上游生成、预填充 Token 的走势，判断是请求变多还是单请求变长。
- 用「筛选」收窄到可疑的接入凭据或模型，观察其请求量与失败率（第 18.3 节）。
- 进入「管理后台 › 运行与排障 › 告警规则」，点「新增规则」，在「指标」中选择要盯的信号：调用量看「模型调用量」，限流看「MCP 限流次数」「限流排队超时率」，成本看「单次调用成本均值」，延迟看「模型调用 P95 延迟」「网关耗时 P95（排队＋处理）」，策略事件看「策略命中」「策略拦截占比」「策略执行出错」「故障转移占比」（第 22.3 节）。
- 判断突增或突降时，「取值方式」选「相对基准的变化比例」，并填写「基准窗口」（不短于统计窗口）。比值是统计窗口读数除以基准窗口读数：「大于 3」表示涨到基准的 3 倍以上，「小于 0.3」表示降到基准的 30% 以下。
- 在「运行总览」选择「告警」页签，查看告警记录、最近取值与状态变化。
你会看到：规则列表中每条自定义规则的名称下方写出完整条件，由指标、统计窗口、取值方式、比较方式与阈值组成；设置了持续时长的，条件持续满足该时长后才触发。
注意
- 基准窗口读数很小时比值容易失真，例如空闲时段每小时一两次调用降到 0。用「基准下限」排除这类时段：计数类指标按每秒速率填写，其余指标与指标单位相同。
- 告警规则只作用于本租户；没有选择通知渠道的规则发往本租户订阅了「告警」且已确认收到测试消息的渠道，没有这样的渠道时只在平台内记录（第 19.8 节）。
能力说明
| 不提供的能力 | 替代做法 |
|---|---|
| :-- | :-- |
| 每次请求逐条规则的完整判定过程（哪些规则被评估、为何未命中） | 查看「命中记录」中实际命中的规则；规则上线前用流量规则的模拟功能验证（第 15 章） |
| 单次调用的提示词缓存命中标记 | 在「Token 与用量」及会话「概要」的缓存命中 Token 中查看（第 18.4 节） |
| 响应方向（上游响应 → 返回客户端）的差异视图 | 分别打开「上游响应」与「返回客户端的响应」正文对比（20.2 节） |
| 把请求重新发往上游的重放 | 用会话时间线与「客户端轨迹」回看；需要复现时导出报文后由调用方重新发起（20.5 节） |
| 打包为单一证据包（含原文、签名与哈希清单） | 使用会话「导出 JSONL」与「导出报告 PDF」，审计完整性见操作审计（第 19.6 节） |
| MCP 活动按事件类型（配置导出、令牌签发、撤销）筛选 | 在「调用情况」切换到「全部活动」查看，或在操作审计中按操作筛选（20.6 节） |
| 熔断次数、持续时长与恢复情况统计 | 在「请求」页签按 TRAFFIC_CIRCUIT_OPEN 筛选统计，配合「流量潮汐与双向承压」的走势判断（20.8 节） |
| 看板上的异常时段标注 | 在「请求」页签按耗时区间或结果筛选，定位异常时段的调用（20.1 节） |
| 会话列表的关键字搜索 | 从请求详情点「看该会话」进入，或按客户端、来源、诊断问题类别筛选（20.5 节） |
---