pikasTech-unidesk/docs/MDTODO/details/sub2api-upstream-reliability/R2.2.1_Task_Report.md

R2.2.1 客户可见错误溯源与调优建议

范围与数据源

• 运行目标：PK01 host-Docker，Sub2API 0.1.153。
• 原生 API：dashboard/overview、upstream-errors、account-availability、concurrency、requests、system-logs/health。
• 原生 system-logs 未索引策略事件，按既定 CLI 规则回退读取 runtime 日志。
• 观察窗口：连续 20 分钟快照与 60 分钟汇总。
• 本轮只分析，没有修改 YAML、runtime 配置或 Sub2API 代码。

客户错误率

• 20 分钟窗口：335 次请求，4 次客户错误，客户错误率 1.19%，上游错误率 2.99%。
• 60 分钟窗口：907 次请求，8 次客户错误，客户错误率 0.88%，上游错误率 3.64%。
• 60 分钟内发生 7 次 account_select_failed，几乎覆盖全部客户可见错误。
• 组并发快照为 9/218，负载 4.13%，排队 0；全池并发不是主因。
• system-log sink 的 queue、drop 和 write failure 均为 0；日志落库不是业务错误来源。

请求级根因

模型候选为零

• 三个 gpt-5.4-nano 流式请求分别在 5ms、10ms、28ms 内未选中账号并返回 404。
• 请求 ID：21e5d449-3b0d-4a70-a798-1dc0af0ba110、55f7eb2a-b469-4d90-9ec9-3d20d278aef7、e90dfd63-22c1-419b-a479-53f860d4151a。
• 官方源码会在组内存在账号但没有任何 model_mapping 支持请求模型时返回 404 model_not_found。
• 这不是瞬时容量问题，重试、临时不可调度和提高切号次数均无效。

多账号连续失败后候选耗尽

• 8150234d-eee2-4a08-a43e-e47a22274609：gpt-5.4，account 28 返回 503、account 27 返回 429、account 31 返回 429，约 6.1 秒后无候选，最终 429。
• bf9aea0a-869a-4ee0-a99c-3b0ceb553822：gpt-5.6-luna，account 28 返回 503、account 27 返回 429，约 67 秒后上下文取消且无候选，最终 429。
• 03a94444-ff26-4038-b1b9-67e249ce7f59：gpt-5.6-sol，account 33 返回 524、account 31 返回 502，约 180 秒后上下文取消且无候选，最终 502。
• 5d8f05ff-9cbc-4040-b6eb-4b262ab85f39：gpt-5.6-sol，account 33 返回 524，约 126 秒后上下文取消且无候选，最终 502。
• max_account_switches=10 只是上限。官方实现会排除已失败账号并重新选号；剩余账号不满足模型或运行状态时，会在只切 1 至 3 次后结束。

流式提交后错误

• 成功样本证明自动 failover 正常工作：account 27 的 502 可切到 account 33，account 28 的 503 可切到 account 31。
• 存在 forward_failed + HTTP 200，例如 account 31 返回 Concurrency limit exceeded，但下游已经提交流式响应。
• 官方 v0.1.153 在检测到已写入语义响应后明确禁止换号，以免拼接两个上游流。
• 此类错误不能靠临时不可调度透明恢复，只能减少上游发生率，或由客户端在流中断后重试或恢复。

上游账号主因

• 60 分钟上游记录共 72 条：rate-limit 24、overload 15、concurrency 12、generic upstream failure 11、status-only 6、model-route-unavailable 4。
• account 28：10 次 overload，当前高频触发 503 临时不可调度。
• account 27：rate-limit 为主，同时有 502 generic failure；现有规则只覆盖 502，不覆盖真实 429 文本。
• account 31：13 次 rate-limit 为主，另有 concurrency 和一次 GROUP_DISABLED；模板未匹配 Upstream rate limit exceeded。
• account 19：7 次 504，其中 2 次明确 concurrency、1 次 upstream unavailable、4 次只有状态；另有 3 次 No available channel for model。
• account 32：2 次 429 rate-limit、1 次 502 concurrency。
• account 29、30：余额不足导致 403，已处于 status=error、schedulable=false，不会继续被调度，但减少了候选容量。

官方版本判断

• PK01 运行 v0.1.153。
• v0.1.152..v0.1.153 的相关变更是 WebSocket ingress 生命周期限制，不改变当前 HTTP 模型选号、failover 或临时不可调度匹配。
• v0.1.149 已包含无账号支持模型时返回 404 的实现，因此回退不会消除 gpt-5.4-nano 404。
• v0.1.153 已包含 compact 心跳不阻断 failover 的官方 #3887 修复。没有证据表明回退能降低当前错误率，不建议回退。

调优建议

P0：修正模型目录与映射

• 查明 gpt-5.4-nano 是客户端误配、错误广告模型还是预期别名。
• 若没有真实上游支持，从客户可见模型目录和调用配置中移除。
• 若业务确实需要，只映射到已经实测支持的真实模型，不能为消除 404 添加虚假映射。

P1：扩展保守临时不可调度模板

• 在 429 规则增加真实关键词 upstream rate limit exceeded，保持 1 分钟冷却。
• 新增 504 规则时只加入实测关键词 concurrency limit exceeded 和 upstream service temporarily unavailable，保持 1 分钟冷却。
• 不增加任意 504 规则；4 次 504 只有状态码，不能推断真实原因。
• 不把 No available channel for model 放入通用账号级模板；这是模型级缺口，账号级摘除会误伤其他模型。
• lyon9801 继续保持例外，不绑定临时不可调度规则。

P1：账号级并发对照调优

• 不降低组级并发。
• account 31 有最强直接并发证据，可先做单账号对照，例如从 30 降到 20，观察 30 至 60 分钟的错误和吞吐。
• account 19、27、32 也有信号，但没有错误时刻并发历史；不要一次性全降。
• 手工账号属于 runtime 管理面，后续通过 runtime CRUD 调整，不纳入 YAML managed profile 自动同步。

P1：降低慢失败对客户时间预算的吞噬

• 524 请求分别在约 126 秒和 180 秒后穿透，第一个慢上游已消耗大部分客户超时预算。
• 官方默认 gateway.response_header_timeout=600s，明显长于当前客户或边缘上下文。
• 建议先确认运行实际值，再受控收紧 OpenAI 响应头超时，为一次 failover 预留预算；不能直接照抄固定值。
• 对照指标应包含首 token 延迟、超时型上游错误、failover 成功率和客户错误率。

P2：恢复候选容量与调度偏好

• account 29、30 只有补足余额并通过真实请求验证后才能恢复，不能直接改为 schedulable。
• account 28、27、31 当前优先级高且错误集中，可在确认模型覆盖后降低调度偏好，让更稳定账号先承担请求。
• Ops system-log 未索引策略事件，60 分钟有 144 条事件依赖 runtime fallback；这不造成业务错误，但限制长期归因，由 R2.3 跟踪。

不建议的措施

• 不建议回退到 v0.1.149。
• 不建议提高 max_account_switches。
• 不建议降低全池并发。
• 不建议启用 pool_mode 做同账号重试。
• 不建议对所有 4xx/5xx 做无关键词临时不可调度。

后续验收

• 按 20 分钟和 60 分钟双窗口继续观察客户错误率、upstream error rate、account_select_failed、模型 404、failover 成功率、forward_failed + 200 和每账号根因。
• 每次只改变一个变量并保留前后窗口；R2.2 继续保持进行中。