执行摘要

• 一句话：reasoning 结束判定统一由语法派生，删除多模型 override
• 推荐动作：值得精读，尤其推荐 parser / structured-output 方向的 owner 逐段读 ParserEngine.is_reasoning_end 的新实现与两条新测试。三个最值得关注的设计决策：一是把「无标记尾部」语义显式提为 config 字段而不是继续散落在模型分支里；二是用「从初始状态出发的 THINK_START 迁移是否进入 REASONING」来区分惰性 <think> 与真正打开 reasoning，这一条同时支撑了 thinking off 的行为修正；三是用 turn_boundary_tokens 而非更长的手写分支来限定回合。阅读时请一并记住作者自曝的三处未解决项（extract_content_ids 分歧、未声明边界的 latch、gemma4 惰性 <|tool_response>），若后续要动这些模型的 continue_final_message 或多轮工具调用，应优先补上边界声明与针对性用例。

功能与动机

PR body 点明 vLLM 经常要回答一个问题：一串 token id 是否还在 reasoning 块内。两个调用方依赖它——结构化输出（请求要 JSON 时，语法不能在模型仍思考时生效，否则模型写不出 <think> 块；engine core 在生成前调用一次 is_reasoning_end(prompt_token_ids)，之后每步再检查）与流式（首 token 前 frontend 对 prompt 问同一问题，决定以 reasoning 还是 content 模式起解析）。两者只有 token id，因此它必须是 token id 的纯函数。但「什么结束 reasoning」此前在三个地方回答：两个从语法派生，第三个是每个模型手写的，且恰好是结构化输出门控在 prompt 阶段读到的那个。作者据此提出「一张表、一个执行器、两个投影」：事实全部来自 config，frontend 引擎执行这张表，两个只读 id 的调用方投影同一份派生集合。

实现拆解

1. 配置契约新增开关。vllm/parser/engine/parser_engine_config.py 的 ParserEngineConfig 增加 wait_for_reasoning: bool | None = None（该 hunk 同时补上了 arg_converter 字段声明）。这条语义原先散落在各模型 override 的 if not self.thinking_enabled: return True 分支里，必须先提升为 config 事实，基类才能统一判定。默认 None 表示沿用旧语义（initial_state is REASONING 才等待），保证未显式声明的解析器行为不变。

2. 基类 is_reasoning_end 改为语法投影。vllm/parser/engine/parser_engine.py 中，函数体不再只看单数 self._reasoning_end_token_id，而是读取三组派生事实：self._reasoning_end_token_ids（由带 EventType.REASONING_END 的迁移派生的 token 集合，天然包含 <tool_call>、<|tool_call>、<|tool_calls_section_begin|>、[TOOL_CALLS] 这类隐式结束符）、start_opens_reasoning（从 config.initial_state 出发的 THINK_START 迁移是否真的进入 REASONING）、self._turn_boundary_token_ids。反向扫描命中 end_ids 返回 True；命中 start_id 且 start_opens_reasoning 为真返回 False，否则 break；命中边界也 break；最后统一 return not wait_for_reasoning。旧实现的空 input_ids 特判与 self._reasoning_ended 运行期回落一并消失，判定彻底变成 id 列表的纯函数——这正是结构化输出门控所需要的性质。

3. 各模型 config 回填语义并删除 override。vllm/parser/qwen3.py（wait_for_reasoning=thinking，同时删掉 is_reasoning_end 与仅供它使用的 _tool_call_token_id / _tool_call_end_token_id 字段）、vllm/parser/kimi_k2.py（thinking）、vllm/parser/glm47_moe.py（thinking）、vllm/parser/mistral.py（reasoning_encoding != "none"，等价于原来的 [TOOL_CALLS] 隐式结束）、vllm/parser/gemma4.py（gemma4_config 参数化为 gemma4_config(thinking)，新增 turn_boundary_tokens=frozenset({"<|turn>", "<|tool_response>"})，删掉 27 行 override）、vllm/parser/deepseek_v32.py / deepseek_v4.py（显式 False）、vllm/parser/inkling.py（显式 True，PR body 称其为 load-bearing）、vllm/parser/minimax_m2.py。因为派生集合已经覆盖隐式结束符，手写分支得以逐条等价删除。

4. 测试配套固定新语义。tests/parser/engine/test_qwen3_reasoning.py 新增 TestIsReasoningEndDerivedFromGrammar，用 (ids, thinking, ended) 参数化覆盖显式关闭、隐式关闭、块内未关闭、空序列与 thinking off 的静默尾部，并新增 test_wait_for_reasoning_follows_thinking 断言 config 开关跟随 enable_thinking；原先断言「已配对 <tool_call>...</tool_call> 不算结束」的 test_paired_tool_call_not_end 被改名为 test_completed_tool_call_after_open_think_is_end 并翻转断言，等于把行为变化写进测试契约。tests/parser/engine/test_gemma4_streaming_reasoning.py 新增 TestGemma4IsReasoningEnd，覆盖 channel 关闭、<|turn> 边界、thinking off 的闭合 channel prompt 以及「结束标记仍优先于边界」的用例。

5. 验证策略。除 pytest tests/parser/ tests/reasoning/ tests/tool_parsers/ 外，PR body 给出与 main（c7e9816c6）的双机 A/B 差分：同请求、temperature=0, seed=0，并用 /proc/<pid>/maps 确认两侧加载不同代码树。gemma-4-31B、gemma-4-E4B、Qwen3-8B、Qwen3.6-27B-FP8、GLM-4.7-Flash、Magistral-Small-2509 与 /v1/responses 路径合计约 370 组逐字节一致，离线 8 个模型 369 组 0 分歧。之所以依赖差分而非单测，是因为两种失败模式都是静默的（HTTP 200、finish_reason 正常、无日志）。

关键文件：

• vllm/parser/engine/parser_engine.py（模块 解析器引擎；类别 source；类型 core-logic；符号 ParserEngine.is_reasoning_end, _reasoning_end_token_ids, turn_boundary_tokens）: 改动核心：基类 is_reasoning_end 从「只看单数结束 token + 运行期回落」重写为对 config 语法表的投影，是全仓 reasoning 结束判定的唯一实现点。
• vllm/parser/gemma4.py（模块 模型解析器；类别 source；类型 core-logic；符号 gemma4_config, Gemma4Parser.init, Gemma4Parser.is_reasoning_end）: 删除 27 行手写 override 的样板：gemma4_config 参数化为 gemma4_config(thinking) 并声明 wait_for_reasoning 与 turn_boundary_tokens，是「config 声明替代 override」的最佳示例。
• vllm/parser/qwen3.py（模块 模型解析器；类别 source；类型 core-logic；符号 qwen3_config, Qwen3Parser.is_reasoning_end）: Qwen3 系（含 ChatML 边界子类）是最大受益者：删除以「配对 </tool_call>」为核心的手写 override 与两个 token id 字段，并新增 wait_for_reasoning=thinking，行为变化在测试中被显式固定。
• vllm/parser/engine/parser_engine_config.py（模块 解析器配置；类别 source；类型 data-contract；符号 ParserEngineConfig.wait_for_reasoning, ParserEngineConfig.arg_converter）: 新增 wait_for_reasoning 字段，是本 PR 唯一的数据契约变更；所有模型语义差异都归拢到这一个开关上。
• tests/parser/engine/test_qwen3_reasoning.py（模块 解析器测试；类别 test；类型 test-coverage；符号 TestIsReasoningEndDerivedFromGrammar, test_is_reasoning_end, test_wait_for_reasoning_follows_thinking, test_completed_tool_call_after_open_think_is_end）: 把新语义写成契约：新增 TestIsReasoningEndDerivedFromGrammar 参数化矩阵与 wait_for_reasoning 断言，并翻转了配对 tool call 的断言。
• vllm/parser/mistral.py（模块 模型解析器；类别 source；类型 core-logic；符号 mistral_config, MistralParser.is_reasoning_end）: 语义映射最特殊的一处：用 wait_for_reasoning=reasoning_encoding != "none" 复刻 [TOOL_CALLS] 隐式结束与 none 编码短路，说明 config 层能表达非布尔的 thinking 配置。
• vllm/parser/kimi_k2.py（模块 模型解析器；类别 source；类型 core-logic；符号 kimi_k2_config, KimiK2Parser.is_reasoning_end）: 典型的「thinking 开关 + 隐式结束符」模型；删除 override 后 TOOL_SECTION_START 的 REASONING_END 迁移自动承担原逻辑，验证了派生路径对多终止符语法同样成立。
• tests/parser/engine/test_gemma4_streaming_reasoning.py（模块 解析器测试；类别 test；类型 test-coverage；符号 TestGemma4IsReasoningEnd, _parser, test_is_reasoning_end）: 新增 TestGemma4IsReasoningEnd，用 9 组参数固定 Gemma4 的边界与 thinking 组合语义，是新 turn_boundary_tokens 行为的主要证据。

关键符号：ParserEngine.is_reasoning_end, ParserEngine._reasoning_end_token_ids, gemma4_config, Gemma4Parser.init, qwen3_config, kimi_k2_config, mistral_config, glm47_moe_config, TestIsReasoningEndDerivedFromGrammar.test_is_reasoning_end, TestGemma4IsReasoningEnd.test_is_reasoning_end

评论区精华

PR 的 review 环节很轻：claude[bot] 因 PR 来自 fork 直接声明自动评审被禁用（「This pull request is from a fork — automated review is disabled.」），唯一人工 review 是 chaunceyjiang 的 APPROVED +「Thanks~」，Issue 时间线上只有 /ci run 触发记录，其中一次因分支落后上游 50 个 commit 被 CI 机器人拒绝，rebase 后重新触发。真正的技术交锋全在 PR body 的 Reviewer notes 里（作者自曝），也是本 PR 最值得读的部分：

「extract_content_ids still scans only the singular _reasoning_end_token_id while is_reasoning_end uses the derived set — they disagree on a <tool_call>-terminated sequence. Nothing pairs them today.」

「minimax_m2, glm47_moe, kimi_k2, deepseek_v4 declare no turn_boundary_tokens, so the unbounded backward scan can latch onto a tool-start token in the system prompt's own format example (shown on minimax_m2: index 173/235).」（作者同时指出，只有 continue_final_message 会打破当前模板的遮蔽）

「<|tool_response> in gemma4's new turn_boundary_tokens is inert — grep -rn '"tool_responses"' vllm/ returns zero hits; ... <|turn> is live and load-bearing.」

「seed_oss requires #54264 (already on main) ... Rebasing onto a base older than #54264 would not be safe.」

结论上，这四条自曝都是「已知未解决」而非「已修」，也没有 reviewer 就其中任何一条展开追问——这是本 PR review 环节最明显的缺口。

• is_reasoning_end 与 extract_content_ids 的语义分歧 (design): 当前「Nothing pairs them today」，无人配对调用所以不构成 bug，但属于明确的后续埋雷，review 中无人追问。
• 未声明 turn_boundary_tokens 导致反向扫描 latch (correctness): 潜在问题，目前靠「这些模板的 generation prompt 以 reasoning 标记结尾」遮蔽，continue_final_message 会打破保护；作者建议像 gemma4 一样声明边界，但本 PR 未做。
• seed_oss 对 #54264 的硬依赖 (correctness): 依赖已在 main 上，因此合并安全；但基于早于 #54264 的 base rebase 不安全，属于发布顺序约束。
• gemma4 新增边界中的 <|tool_response> 是惰性配置 (design): 保留但无效，可能误导后续读者；未决定是否删除。
• 静默失败下的等价性验证方式 (testing): 约 370 组在线用例逐字节一致、离线 369 组 0 分歧，等价性成立；但差分脚本不是 CI 常驻资产，后续回归保护仍依赖单元测试。
• CI 因分支落后上游 50 个 commit 被拒 (other): 作者 rebase 后重新触发，Buildkite #89052 正常开跑，随后 chaunceyjiang 批准。

风险与影响

• 风险：
  1. 行为语义变更（Qwen3 配对 tool call）。新实现不再有「向后找配对 </tool_call>」的逻辑，只要历史里出现结束 token 就返回 True。tests/parser/engine/test_qwen3_reasoning.py 把 test_paired_tool_call_not_end 改名为 test_completed_tool_call_after_open_think_is_end 并翻转断言，正式承认这一变化。对结构化输出是修复（Qwen3-8B 的 4 种 prefill 形状从自由文本 / location 修正为 schema-valid），但对任何把 is_reasoning_end 当作「本轮是否还有 reasoning」的调用方都是语义变化。

1. 反向扫描 latch（最实际的潜在回归）。minimax_m2、glm47_moe、kimi_k2、deepseek_v4 未声明 turn_boundary_tokens，扫描没有回合护栏，可能命中 system prompt 自带格式示例里的 tool-start token（作者在 minimax_m2 上观察到 index 173/235）。当前靠「这些模板的 generation prompt 以 reasoning 标记结尾」遮蔽，continue_final_message 会打破该保护。

2. 基类去掉运行期回落。旧实现有 return self._reasoning_ended 与空 input_ids 特判，新实现只有 return not wait_for_reasoning。对「语法里有 reasoning 但结束标记不在词表」的配置，_reasoning_end_token_ids 会派生为空集，此时结果完全由 wait_for_reasoning 决定（thinking on 会返回「未结束」）。PR 未逐一核对是否还有解析器依赖旧回落，建议按 parser 列表扫一遍。

3. extract_content_ids 与 is_reasoning_end 分歧。前者仍只看单数 _reasoning_end_token_id，后者用派生集合，在 <tool_call> 结尾的序列上结论相反。当前没有代码把二者配对，但一旦有人用 is_reasoning_end 判边界、再用 extract_content_ids 切内容，就会得到不一致的切分。

4. 测试覆盖不对称。改动波及 9 个 parser 源文件，针对性单测只加在 qwen3 与 gemma4；mistral 的 reasoning_encoding != "none" 映射、deepseek_v32 / deepseek_v4、inkling、minimax_m2 的新开关仅靠非 CI 的 A/B 差分背书，回归时 CI 不一定能拦住。

5. 依赖与缓存细节。seed_oss 的正确性依赖 #54264 已在 main（基于更早 base 的 rebase 不安全）；gemma4_config 与其余 config 仍是 @functools.cache 且无淘汰策略，长期进程内按参数组合常驻，影响很小但值得知道。
   - 影响：

   • 用户 / 请求侧：使用 Qwen3 系、Gemma4、Kimi K2、Mistral、GLM-4.7、DeepSeek v3.2/v4、seed_oss 等模型且同时使用 thinking + 结构化输出/工具调用的请求，行为会变——多数是修复（不再在思考阶段强行套用 JSON 语法、thinking off 时正确启用语法、prefill 与工具响应后续轮恢复 schema 校验），少数是语义调整（已配对 tool call 现在算作 reasoning 结束）。
   • 系统侧：is_reasoning_end 是结构化输出门控（生成前一次 + 每步一次）与 frontend 流式模式选择的共同入口，因此影响的是 token 0 处 bitmask 是否生效，而非某个模型的特例分支；解析器子系统从「每模型一份启发式」转为「config 声明 + 基类投影」的单一契约，reasoning_end_token_ids 的派生集合也同时服务每步快路径。
   • 团队侧：新模型接入 parser 时不必再手写 is_reasoning_end，但必须理解 wait_for_reasoning 并正确声明 turn_boundary_tokens，否则会踩到上述第 2 条 latch。净删除约 6 行代码但删掉了 5 份重复逻辑，维护成本下降、契约更清晰。
   • 风险标记：核心路径变更, 行为语义变更, 跨模型影响面广, 反向扫描潜在误判, 部分模型缺少针对性测试, 依赖 #54264

关联脉络

• PR #48200 [Refactor] StructuredOutputManager x Speculative Decoding Refactor: 同属 parser engine 与结构化输出契约的演进（改动 vllm/v1/structured_output/__init__.py、vllm/parser/engine/parser_engine.py 等），本 PR 触碰的正是该契约里『reasoning 是否结束』这一环，可对照理解约束起点与门控的关系。
• PR #42904 [feature] [xgrammar] support patternProperties/propertyNames/unevaluatedProperties kw for object types: 结构化输出后端的 schema 能力放宽；与本 PR 修的『门控在 prompt 阶段误判导致语法过早/过晚生效』共同决定同一批 JSON 请求的实际行为。
• PR #56408 [Frontend] Use XGrammar schema constraints for DeepSeek V4.1: 同属工具调用 + 结构化输出前沿改动；本 PR 中 deepseek_v4 显式声明 wait_for_reasoning=False 与这条线同源。
• PR #53124 [Bugfix] Load reasoning parser plugins before headless engine config: 同为 reasoning parser 子系统的加载/契约类修复，说明该模块近期在集中收敛调用时序与配置语义。