常见故障场景与第一反应#

这章解决什么问题#

前几章已经给了调试工具、扩展路径和发布前清单，但很多读者在真正遇到问题时，仍然会卡在第一步：到底先问什么问题？优秀技术书到最后常常会补这种“现场感很强”的章节，因为它能把前面的抽象知识真正压成可执行动作。

这一章解决的，就是“问题刚发生时，先问哪几个问题，才能少走弯路”。

场景一：请求能进来，但就是不回包#

第一问：请求有没有完成 TokenizerManager -> Scheduler -> DetokenizerManager -> TokenizerManager 的闭环？
第二问：它卡在入口、调度、还是 detokenize 回程？
第三问：trace 或 request stage 里最后一个稳定出现的阶段是什么？

只要这三问答出来，读者通常就知道该回 lifecycle、runtime architecture 还是 observability 一章去追。

场景二：吞吐明显下降，但功能看起来都正常#

第一问：这是整体趋势问题还是特定 batch / 请求问题？
第二问：当前更像 scheduler / cache / backend / graph runner 的问题，还是接口层问题？
第三问：最近是否切了 attention backend、speculative 配置、cache 策略或 graph runner 路径？

这组问题的价值，在于它把“性能异常”拆回 execution model、scheduling/memory 和 observability 三章，而不是让人直接在 benchmark 数字里打转。

场景三：结构化输出偶尔失稳#

第一问：约束真的进入了 generation path，还是只停留在请求表面？
第二问：这是 grammar backend 的问题，还是 parser / tool result 回填的问题？
第三问：失败表现是“格式不合法”“格式合法但语义不对”，还是“tool call 回路不闭合”？

这三问一旦分清楚，结构化生成一章和 API / parser 一章的边界就会立刻派上用场。

场景四：改完代码之后，不知道该信什么#

第一问：这次改动影响的首先是请求主线、执行路径，还是扩展/维护层？
第二问：最小验证应该落在 unit、registered、manual 还是 benchmark？
第三问：如果今天要上线，哪一章里的检查清单最值得先过一遍？

这组问题的意义，是把 extension / testing / operational checklist 这几章真正连成 maintainer workflow。

一张更像值班手册的图#

flowchart TD
    A["故障现象"] --> B{"先判断问题类型"}
    B -->|不回包| C["回 lifecycle 闭环"]
    B -->|吞吐下降| D["回 scheduling / execution / observability"]
    B -->|结构化结果异常| E["回 structured generation / parser / API"]
    B -->|改动后不放心| F["回 testing / checklist / extension"]

这张图并不“高级”，但它非常像好技术书最后会给读者的东西：一张把前面章节都重新压缩成第一反应路径的值班图。

本章对应哪些代码路径#

这一章不新增太多底层锚点，它主要回指前文已经建立好的主线：launch_server.py、http_server.py、TokenizerManager、Scheduler、DetokenizerManager、ForwardBatch、SamplingParams、req_time_stats.py、run_suite.py 等。

小结#

一本更成熟的技术书，最后通常不会只给“工具列表”，而会给“遇到问题时先怎么想”。这一章做的就是这件事：把整本书前面的知识压成第一反应框架。