执行摘要

• 一句话：自动将 reasoning_content 标准化为 reasoning
• 推荐动作：建议精读此 PR，重点了解：
  • 如何通过 Pydantic model_validator(mode="before") 在早期标准化输入数据。
  • 根据 review 合并验证器的决策过程和性能 benchmark 方法。
  • 如何处理已废弃字段的兼容性，包括始终移除旧字段的策略。

此 PR 设计模式适用于类似字段迁移场景。

功能与动机

litellm、OpenCode、Vercel 等客户端在 multi-turn 对话中使用已弃用的 reasoning_content 字段而非标准的 reasoning 字段，导致 vLLM 0.16.0 及以上版本无法正确识别推理内容，在 agentic 评估（如 SWE-bench Verified）中产生假低分。本 PR 在请求解析阶段自动 normalization，确保所有下游路径使用规范字段。

实现拆解

1. 新增 model_validator：在 ChatCompletionRequest 类中添加 _normalize_reasoning_content 方法（mode="before"），遍历 messages 列表，弹出 reasoning_content 并设置为 reasoning（当 reasoning 不存在时）。

2. 合并验证器：根据 review 建议，将 _materialize_tool_calls_before 与上述逻辑合并为统一的 _normalize_messages_before，减少一次列表迭代，测试显示约 18% 性能提升（大型 agentic 对话）。

3. 添加单元测试：在 test_chat_completion_request_validations.py 中新增三个测试用例：

   • test_reasoning_content_normalized_to_reasoning：验证 reasoning_content 被正常转换为 reasoning。
   • test_reasoning_takes_precedence_over_reasoning_content：验证当两字段并存时，reasoning 优先且 reasoning_content 被移除。
   • test_no_reasoning_fields_unchanged：验证无 reasoning 字段的消息保持不变。

4. 手动验证：作者编写脚本在真实服务器上测试，确认有 reasoning_content 时 prompt token 数正确增加，表明推理内容被计入。

关键文件：

• vllm/entrypoints/openai/chat_completion/protocol.py（模块 前端协议；类别 source；类型 core-logic；符号 _materialize_tool_calls_before, _normalize_messages_before）: 实现核心 normalization 逻辑，将 reasoning_content 标准化为 reasoning，并合并 tool_calls 预处理验证器。
• tests/tool_use/test_chat_completion_request_validations.py（模块 请求校验；类别 test；类型 test-coverage；符号 test_reasoning_content_normalized_to_reasoning, test_reasoning_takes_precedence_over_reasoning_content, test_no_reasoning_fields_unchanged）: 添加三个单元测试验证 normalization 行为，包括正常转换、字段优先级和缺失场景。

关键符号：_normalize_messages_before, test_reasoning_content_normalized_to_reasoning, test_reasoning_takes_precedence_over_reasoning_content, test_no_reasoning_fields_unchanged

评论区精华

核心讨论

性能优化：合并验证器避免多次迭代

• gemini-code-assist 提议将 _normalize_reasoning_content 与 _materialize_tool_calls_before 合并。
• bbrowning 起初认为影响小，但 mgoin 支持合并。
• bbrowning 最终合并并附 benchmark 数据：small 场景提升 4.6%，large 场景提升 18.1%。

字段移除策略：总是移除 reasoning_content

• gemini-code-assist 建议始终 pop reasoning_content，即使 reasoning 已存在。
• bbrowning 同意并实现为无条件移除旧字段。

测试断言增强

• gemini-code-assist 建议添加确认 reasoning_content 不存在的断言。

• bbrowning 采纳并更新测试。

• 合并 model_validator 以减少消息列表迭代次数 (performance): 接受合并，将 _normalize_reasoning_content 合并到 _materialize_tool_calls_before，重命名为 _normalize_messages_before。

• 是否总是移除 reasoning_content 字段 (design): 实现为无条件 pop reasoning_content，只有在 reasoning 字段不存在时才将值赋给 reasoning。
• 测试应验证 reasoning_content 被移除 (testing): 测试函数已添加 'assert reasoning_content not in assistant_msg'。

风险与影响

• 风险：
  1. 字段兼容性风险：如果下游代码直接访问 reasoning_content 而非 reasoning，将得到 None。所有 vLLM 核心路径已统一使用 reasoning，但用户自定义 template 或扩展可能受到影响。PR 已在 model_validator 的文档字符串中说明标准化行为。

1. 性能风险：新增的 model_validator 增加一次列表迭代，但通过合并优化已消除额外开销。benchmark 显示性能提升。

2. 测试覆盖：三个单元测试覆盖正常转换、优先级和缺失场景，手动测试也验证。无回归风险。
   - 影响：影响范围：所有使用 Chat Completions API 的客户端，特别是 litellm、OpenCode、Vercel 等传递 reasoning_content 的客户端。

影响程度：正面兼容性改进。用户无需修改代码即可获得正确的 reasoning 内容。

团队影响：减少因 reasoning_content 兼容性问题导致的 issue，标准化字段定义。

• 风险标记：字段迁移风险, 下游依赖兼容性, 单元测试覆盖

关联脉络

• PR #45548 [Chore] Consolidate reasoning/tool parser attributes into unified Parser in chat serving: 同样修改了 protocol.py，且与 reasoning 字段标准化相关，共同推进前端请求处理的统一。