执行摘要

• 一句话：修复调试日志启用时工具调用迭代器被消耗导致失败的问题。
• 推荐动作：建议工程师精读 _materialize_tool_calls_before 和 _materialize_tool_calls_after 的实现，理解 Pydantic v2 验证器在 before/after 模式下的作用时机，以及如何组合使用以防御一次性迭代器消耗。同时，可浏览测试文件以掌握工具调用序列化的边界用例。

功能与动机

修复 Issue #34792：当 VLLM_LOGGING_LEVEL=debug 时，使用 Mistral 模型进行工具调用会失败，抛出 ValueError: Unexpected tool call id ...。根本原因是 OpenAI Python SDK 将 tool_calls 类型化为 Iterable[...]，Pydantic v2 在从 Python 对象验证时将其包装为一次性懒迭代器，调试日志调用 model_dump_json() 消耗了迭代器，使后续读取为空。

实现拆解

1. 修改内部类型注解：在 vllm/entrypoints/chat_utils.py 中，将 CustomChatCompletionMessageParam 和 ConversationMessage 的 tool_calls 字段类型从 Iterable[...] 改为 list[...]，防止 Pydantic 为 vLLM 自有类型创建懒迭代器。
2. 添加模型验证器组合：在 vllm/entrypoints/openai/chat_completion/protocol.py 的 ChatCompletionRequest 类中，添加两个 model_validator：
   • _materialize_tool_calls_before（mode="before"）：在验证前遍历消息，将非列表的 tool_calls 转换为列表，避免 Pydantic 在联合类型匹配时消耗一次性生成器。
   • _materialize_tool_calls_after（mode="after"）：在验证后将 Pydantic 可能重新包装的 ValidatorIterator 转换回列表，确保下游代码（如 tokenizer、model_dump_json）始终看到普通列表。
3. 新增测试覆盖：创建 tests/entrypoints/openai/test_tool_calls_serialization.py，包含 5 个测试函数，验证列表持久性、生成器转换、多工具调用等场景，确保修复后行为正确且回归可防。
4. 无其他配套改动：本次变更仅涉及源码逻辑和测试，无需配置、部署或文档更新。

关键文件：

• vllm/entrypoints/openai/chat_completion/protocol.py（模块 请求协议；类别 source；类型 core-logic；符号 _materialize_tool_calls_before, _materialize_tool_calls_after）: 添加了核心修复逻辑：两个 Pydantic 模型验证器，确保 tool_calls 迭代器在验证过程中被转换为列表，防止后续消耗。
• vllm/entrypoints/chat_utils.py（模块 聊天工具；类别 source；类型 core-logic）: 修改了 vLLM 内部消息类型的类型注解，将 tool_calls 从 Iterable 改为 list，减少 Pydantic 创建懒迭代器的机会。
• tests/entrypoints/openai/test_tool_calls_serialization.py（模块 测试序列化；类别 test；类型 test-coverage；符号 _make_tool_call, _make_request, test_tool_calls_list_preserved_after_model_dump, test_tool_calls_from_generator_are_materialised）: 新增测试文件，全面验证修复后的行为，包括列表持久性、生成器转换、无 tool_calls 消息处理等，防止回归。

关键符号：_materialize_tool_calls_before, _materialize_tool_calls_after, test_tool_calls_list_preserved_after_model_dump, test_tool_calls_from_generator_are_materialised

评论区精华

• 验证器模式迭代：@bbrowning 在 Issue 评论中指出，初始仅使用 mode="after" 的验证器不足，因为 Pydantic v2 会在联合类型验证期间消耗生成器。作者最终采用 mode="before" 和 mode="after" 的组合来全面处理。
• 测试失败与修复：合并冲突导致单元测试失败，@bbrowning 建议合并最新 main 以获取对 #37831 的 revert，作者跟进后测试通过。

• 外部影响确认：@Alkacid 提到在 Qwen3.5 系列通过 Anthropic API 时遇到类似问题，工具调用内容消失而无错误，强调本 PR 对修复此类问题的重要性。

  • 验证器模式调整与测试修复 (correctness): 采用 before 和 after 验证器组合，并合并最新 main 以获取对 #37831 的 revert，最终使测试通过并完全修复问题。

风险与影响

• 风险：- 回归风险：修复集中于 tool_calls 字段，但其他 Iterable 类型字段（如 content 中的列表）若类似处理可能仍存在风险，不过当前变更范围可控。
• 性能影响：急切转换迭代器为列表可能轻微增加内存开销，但 tool_calls 数据量通常较小，且避免了调试日志下的功能故障，权衡合理。
• 兼容性：类型注解从 Iterable 改为 list 仅影响 vLLM 内部 TypedDicts，不破坏外部 API 合约，因为外部 SDK 仍使用 Iterable 类型。
• 测试覆盖：新增测试全面覆盖了边界情况，降低了未来变更引入类似 bug 的风险。
• 影响：- 用户影响：修复后，用户可在启用调试日志时正常使用工具调用功能，提升 Mistral、Qwen 等模型的可用性和调试便利性。
• 系统影响：确保聊天完成请求处理管道中 tool_calls 数据在多轮读取下保持完整，防止因序列化导致的静默数据丢失。
• 团队影响：提供了处理 Pydantic v2 懒迭代器的通用模式，可作为类似问题（如其他 Iterable 字段）的参考解决方案。
• 风险标记：一次性迭代器消耗风险, 类型注解变更, Pydantic 验证器复杂性

关联脉络

• PR #37848 [Reasoning][Frontend] Add model config to adjust_request in reasoning parser: 涉及前端请求处理修改，与本 PR 同属 entrypoints 模块，关注点不同但共享对聊天完成请求的增强。