# PR #42148 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Bugfix] Skip routed-experts hot path when disabled
- 合并时间：2026-05-10 09:01
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/42148

---

# 执行摘要

- 一句话：禁用路由专家路径修复
- 推荐动作：该 PR 变更简洁明确，建议合入。但由于测试未在 CI 中运行，建议后续跟进确保测试覆盖（如将 `test_routed_experts_capture.py` 加入测试套件）。值得关注的设计决策是：通过 early return 和条件守卫双重确保禁用的正确性，而非仅依赖一处判断。

# 功能与动机

PR #39917 在 `capture_model()` 中无条件调用 `init_routed_experts_capturer()`，导致即使 `enable_return_routed_experts` 为 false，V1 仍会初始化 routed-experts 状态并进入相关热路径守卫。PR body 指出这匹配了 Qwen3.5-35B-A3B-FP8 在 R3 禁用时的吞吐量回归。

# 实现拆解

1. **在 `capture_model()` 中添加条件守卫 **（位于 `vllm/v1/worker/gpu_model_runner.py`）：在 `CUDAGraphMode.NONE` 分支和正常 CUDA Graph 捕获前的初始化调用处，都增加 `if self.model_config.enable_return_routed_experts:` 判断，只有启用时才调用 `init_routed_experts_capturer()`。
2. **在 `init_routed_experts_capturer()` 中添加 early return**（同一文件）：方法开头检查 `enable_return_routed_experts`，如果为 false 则设置 `routed_experts_initialized = False` 并立即返回，避免后续逻辑执行。
3. **总计变更**：仅修改一个源文件，+8/-2 行。未包含测试配套变更（但 reviewer 指出测试文件 `test_routed_experts_capture.py` 实际不运行于 CI）。

关键文件：
- `vllm/v1/worker/gpu_model_runner.py`（模块 模型运行器；类别 source；类型 data-contract）: 核心变更文件，修复 routed-experts capturer 在禁用时的初始化问题，包含 CUDAGraphMode.NONE 分支和正常捕获分支的两处条件守卫，以及 init_routed_experts_capturer 中的 early return。

关键符号：未识别

## 关键源码片段

### `vllm/v1/worker/gpu_model_runner.py`

核心变更文件，修复 routed-experts capturer 在禁用时的初始化问题，包含 CUDAGraphMode.NONE 分支和正常捕获分支的两处条件守卫，以及 init_routed_experts_capturer 中的 early return。

```python
# 在 capture_model 方法的 CUDA Graph 禁用分支中，原无条件调用 init_routed_experts_capturer
if self.compilation_config.cudagraph_mode == CUDAGraphMode.NONE:
    logger.warning(
        "Skipping CUDA graph capture. To turn on CUDA graph capture, "
        "ensure `cudagraph_mode` was not manually set to `NONE`"
    )
    # 新增条件守卫：仅在开启 routed-experts 时才初始化 capturer
    if self.model_config.enable_return_routed_experts:
        self.init_routed_experts_capturer()
    return 0

# 在正常捕获前的初始化调用处，同样添加条件守卫
if self.model_config.enable_return_routed_experts:
    self.init_routed_experts_capturer()

```

# 评论区精华

讨论集中在 reviewer ZJY0516 指出的测试覆盖问题：`tests/model_executor/test_routed_experts_capture.py` 实际上不在 CI 中运行。作者 aoshen02 简单回复 "ok" 表示接受该备注，但未进一步追加测试。

- 测试不运行于 CI (testing): 作者确认接受该反馈，但未进一步处理。

# 风险与影响

- 风险：风险较低：该修复仅添加条件检查，无逻辑重构；变更局限在单个文件的 10 行内；不涉及核心路径性能回归。主要风险是现有测试 `test_routed_experts_capture.py` 未被 CI 执行，可能遗漏回归。
- 影响：影响范围：所有使用 V1 `GPUModelRunner` 且未启用 `enable_return_routed_experts` 的模型（如 Qwen3.5-35B-A3B-FP8）。修复后，禁用 R3 时将完全跳过 routed-experts 初始化及热路径守卫，恢复预期吞吐量。对启用 R3 的模型无行为变化。
- 风险标记：测试覆盖缺失

# 关联脉络

- PR #39917 Add routed-experts capture initialization inside capture_model(): 此 PR 引入的变更导致本问题——无条件调用了 init_routed_experts_capturer，本 PR 为其提供修复。