# 解释请求延迟诊断

## 已确认与未确认

固定模型与跟随当前模型都使用 `ctx.modelRegistry.streamSimple()`。扩展没有为固定模型启动子 agent、切换主会话模型、增加等待、追加翻译请求或自动重试。用户配置的 timeout 是取消上限，不是先等待对应时长再请求。

这只能排除代码中显式的额外流程，不能单凭源码证明扩展绝无性能问题，也不能断定责任在 Magpie 或模型中转供应商。整条链可能包括本地配置/认证、Pi adapter、网络、Magpie 排队/路由、上游中转排队/限流、模型推理和流式响应缓冲。

已通过离线测试复现一个推理适配边界：Pi 1.4.0 的 OpenAI Completions adapter 在模型没有明确 off 映射时，可能不发送任何 `reasoning_effort`。所以本扩展配置 off 不一定等于上游真正关闭推理。这是需要观察的候选因素，不是本次真实延迟的已证明原因。

现默认复用 Pi 会话层的等级校正，而不是把配置 off 无条件转成省略参数；例如元数据只支持 low/high/max 时，off 会采用 low。按模型发送 `reasoning_effort=none` 仅保留为实验项，用户对 qoder/dfmodel 的实测仍返回推理。说明见 [思考等级](reasoning-off.md)。

## 使用诊断命令

1. 在加载本项目的 Pi 中 `/reload`，或退出后重新用 `pi -e` 加载。
2. 若你同意该次模型费用，在新的审批上按解释键；让请求完成或超时。不要用同一已完成审批的重复按键做测速。
3. 回到正常输入后执行 `/permission-explain-diagnostics`。该命令只读取已存在的计时，不会再次请求模型。
4. 保存或反馈这条诊断即可，不需要提供 API key、完整命令、对话或认证文件。

没有历史计时的旧版本请求不能补测。新版本尚未请求时，命令仅显示当前选定模型的安全元数据和“尚无计时”提示。API 及端点来源来自 Pi 的运行时模型注册表，不自行读取 `auth.json` 或 `models.json`。端点仅显示 origin，删除用户名、密码、路径和 query。

## 字段含义

| 字段 | 范围 / 含义 |
| --- | --- |
| 开始时间 | UTC，用于与供应商自行提供的服务端记录对应 |
| 本地准备 | 配置检查、选择模型、语言、脱敏、提示词和缓存 key 准备 |
| 请求体就绪 | 从调用 streamSimple 到首次 onPayload，可能包括认证、adapter 初始化和路由 |
| 响应头 | 从调用 streamSimple 到首次 onResponse，仅在该 adapter 透传此回调时存在 |
| 首次推理增量 | 从调用到首个非空 thinking_delta；不记录思考内容 |
| 首次正文增量 | 从调用到首个非空 text_delta，是客户端看到正文的时刻 |
| 首字至完成 | 首个正文增量至流完成，包含后续生成、网络与解析 |
| 注册表请求耗时 | 整次 streamSimple 调用与消费时间，不能简单等同服务端推理耗时 |
| UI 通知调用 | 本地同步 notify 调用时间，不是终端实际完成绘制的时间 |
| 请求体准备次数 | onPayload 的次数，不是精确 HTTP 请求数或计费次数 |
| 推理参数 | 最终请求体中少量白名单推理控制字段；不展示其他 payload 字段 |
| 推理参数映射 | 本次选择的本地映射：`pi-adapter` 或 `reasoning-effort-none`；不表示上游已执行 |
| 请求采用等级 / Pi 可用等级 | 按 Pi 会话规则计算的本地等级及元数据声明的可用等级；不保证上游实际采用，实验覆盖显示 `explicit-none` |
| 本地推理元数据 | `thinkingLevelMap.off` 和 `compat.supportsReasoningEffort` 的白名单值；`unset` 是未配置，`null` 是声明不支持 off，非服务端探测；任意自定义字符串隐藏为 `custom` |
| `omitted` | 确实看到了 payload，但没有识别到这些推理控制字段，不代表零推理 |
| `-` | 未观测到回调/事件；不能据此推断网络失败或服务器行为 |
| `cache-hit` | 本次只是本地缓存命中，不用于比较远端模型速度 |

自定义 provider 可能不发布流增量或不调用部分 hook，首次正文/响应头为 `-` 是允许的。即使本地很快、首字很慢，也只能定位到请求链，不能仅凭该结果区分网络、Magpie、中转供应商和模型本身。

## 如何继续定位

- 本地准备明显慢：先排查扩展配置 IO、注册表枚举和本地运行环境。
- 本地准备快，但请求体很晚就绪：排查认证刷新、provider 初始化及路由；不先归咎上游生成。
- 请求体很快就绪，响应头/首字等待很长：排查请求链上的网络、排队、上游预填充/推理及缓冲。
- 很早出现推理增量、正文很晚：实际有推理输出；结合 `reasoningOnWire` 检查 off 是否被正确映射或供应商是否支持关闭。
- 首字快但完成慢：检查实际输出量、推理 usage、生成速度及中转流式缓冲。

要把 Magpie 与其上游供应商进一步拆开，需要服务端分段耗时，或者在用户同意费用后使用同一输入、同一模型、相同预算和推理设置，进行经 Magpie 与直接上游的受控对照。比较不同模型的单次请求不能作为责任归因。

本次开发只进行了离线 adapter 和假流测试，没有读取密钥，也没有为排查擅自发送付费请求；未获得 Magpie/中转供应商的服务端计时，所以没有宣称查明远端故障。