FreeCADWasmDev/docs/current/model-timeout-control-20260910.md

模型请求超时控制记录

核对时间：2026-09-10（Asia/Shanghai）。本记录只描述模型传输和调度器等待策略，不把模型响应次数当作业务验收完成数。

实测结论

历史传输日志 docs/current/continuation-runs/transport-308394.jsonl 共 52 个请求，其中 41 个正常完成、3 个上游 TimeoutError、7 个本地 BrokenPipeError、1 个未结束。正常请求的输入 token 中位数为 28,527、P95 为 33,302，原始请求体中位数为 118,708 字节、P95 为 137,434 字节；首响应头等待中位数 19.919 秒、P95 为 53.806 秒、最大 116.785 秒，总耗时 P95 为 60.953 秒。

最新观测 docs/current/model-timeout-observation-20260910.json 进一步说明上下文大小不是唯一根因：约 72 KB、7 个输入项的请求仍连续经历无响应头超时；同一日志中 14～23 个输入项、约 110～120 KB 的请求又能在 15～30 秒完成。独立生产探针 docs/current/continuation-runs/transport-probe-540727.jsonl 将请求降至 61,445 字节、7 个输入项后，仍经历两次无响应头超时。因此现有证据指向上游首响应不稳定；上下文会影响成本，但目前没有证据证明过大的上下文是这些超时的主因。

已落地的控制

• tools/codex_http_transport.py 在转发前记录请求体大小和脱敏上下文计数（输入项、工具数、工具输出字节），超过 512 KiB 直接返回 context_budget_exceeded，不把超限请求送到上游。
• 调度会话复用上限固定为 96,000 个预测输入 token；已有的单轮提示上限仍为 24,000 字节。达到上限后从持久化检查点启动新会话，保留业务进度，不伪造截断结果。
• 传输状态分为 request、headers、streaming、completed、error、cancelled，并按请求号提供活动快照。首响应尚未产生 headers 时，所有上游重试共享同一个本地静默预算；重试不能把 60 秒首活动上限重新计时。
• 一旦已经收到 headers 或流式数据，以上游读取/空闲预算为准，避免模型正在输出时被调度器的短本地轮询间隔误杀。进程结束、上下文轮换或取消时会关闭对应 socket，取消请求不会伪造完成事件，也不会继续重试。
• 日志只保存大小、计数、阶段和耗时，不保存提示正文或工具输出内容；tools/analyze_model_transport.py 可从 JSONL 计算中位数、P95、重叠请求和结果分布，后续按数据调参。

验证

已通过：

• python3 -m unittest tools.test_codex_http_transport（15 tests，11.590 秒）
• python3 -m unittest tools.test_scheduler_performance tools.test_scheduler_context tools.test_scheduler_business_recovery tools.test_unattended_scheduler（77 tests，16.283 秒）
• python3 -m py_compile tools/codex_http_transport.py tools/run_freecad_web_scheduler.py tools/analyze_model_transport.py
• git diff --check

生产探针 tools/probe_codex_transport.py --production --timeout 150 在约 61 KB 请求上仍复现上游无响应头，第二次尝试后由本地取消；这证明控制层已能及时收敛等待，但上游服务本身的可用性仍是外部变量。调度器继续无人值守运行，业务验收进度以 show_freecad_web_scheduler.py 的 functionalModuleBusiness 字段为准。