执行摘要

• 一句话：修复 MoE 专家路由捕获器在数据并行和 MK 量化路径下的断言错误，避免 CUDA 图捕获崩溃。
• 推荐动作：建议工程师精读 routed_experts_capturer.py 的 capture 方法变更，理解两种 DP dispatch 路径的差异及其在量化上下文中的处理方式。关注错误处理从警告到断言的演变，这体现了对可靠性的重视。

功能与动机

Issue #37857 报告了当启用 --data-parallel-size > 1 和 supports_internal_mk=True 的量化方法时，RoutedExpertsCapturer.capture() 在 CUDA 图捕获期间会崩溃，抛出 AssertionError。根因是原有逻辑假设所有 DP 等级的令牌在路由前已拼接，而 MK 路径下 DP 组合发生在量化方法内部，导致断言失败。PR body 详细描述了这一场景和修复必要性。

实现拆解

在 routed_experts_capturer.py 的 capture 方法中，重构了多 DP 情况下的逻辑：根据 topk_ids.shape[0] 与总令牌数或本地令牌数的比较，区分两种 DP dispatch 路径（朴素 dispatch 和 MK 路径），并计算正确的起始和结束位置。新增了 AssertionError 处理意外形状。在测试文件 test_routed_experts_capture.py 中添加了三个新测试用例，覆盖单 DP、朴素 dispatch 和 MK 路径场景，确保修复的正确性。

关键文件：

• vllm/model_executor/layers/fused_moe/routed_experts_capturer.py（模块 fused_moe）: 核心修复文件，实现了动态处理 DP dispatch 路径的逻辑变更，解决了断言失败问题。
• tests/model_executor/test_routed_experts_capture.py（模块 testing）: 新增测试用例，验证修复的正确性，覆盖单 DP、朴素 dispatch 和 MK 路径等场景。

关键符号：RoutedExpertsCapturer.capture

评论区精华

Review 中，pavanimajety 和 bnellnm 对初始实现中的警告处理提出质疑，认为应使用断言快速失败而非继续执行。pavanimajety 评论：'I think this should be an assertion, we can't throw a warning and continue.' bnellnm 附和：'Should this be an error instead?' 作者 Young-Leo 随后更新代码，将日志警告改为抛出 AssertionError，确保在意外情况下立即终止捕获过程，反映了对系统健壮性的设计权衡。

• 错误处理策略：断言 vs 警告 (correctness): 作者更新代码，将警告改为抛出 AssertionError，实现快速失败处理。

风险与影响

• 风险：风险较低，因为修复针对特定崩溃场景，且添加了测试覆盖。但变更涉及核心 MoE 路由逻辑，需确保不影响其他量化路径或 DP 配置；修改后的 AssertionError 可能在边缘情况下抛出，但有助于早期发现问题。关键风险在于断言逻辑变更可能引入新的崩溃点，但测试用例提供了验证。
• 影响：影响范围限于使用 MoE 模型、启用专家并行、数据并行大于 1 且采用 MK 量化路径的用户。修复后，这些配置下的 CUDA 图捕获将不再崩溃，提升系统稳定性和用户体验。对性能无直接影响，但避免了因崩溃导致的服务中断。
• 风险标记：断言逻辑变更, 多路径处理

关联脉络

• PR #39344 fix(kimi_k25): resolve media_placeholder_token_id from tokenizer: 同为模型层 bugfix，展示了 vLLM 对模型兼容性和多模态推理的持续维护，与本 PR 在 bugfix 类别上相关。