# PR #6922 完整报告

- 仓库：`verl-project/verl`
- 标题：[vllm, rollout] fix: require vLLM>=0.22.0 for Qwen3.5 router replay (R3)
- 合并时间：2026-07-07 10:55
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6922

---

# 执行摘要

- 一句话：vLLM 版本门控防止 Qwen3.5 R3 路由器回放崩溃
- 推荐动作：该 PR 是防御性编程的典型例子，值得精读。设计决策（运行时版本检查 vs 依赖门控）的权衡体现了对用户透明度和维护成本的考虑。

# 功能与动机

R3 模式依赖 vLLM 的 `enable_return_routed_experts` 路径，该路径仅在 vLLM>=0.22.0 时才能正确处理混合注意力 MoE 模型（如 Qwen3.5）。旧版本 vLLM 会因主机缓冲区不足而在 rollout 过程中崩溃，出现晦涩的 IndexError。PR 旨在提供即时反馈，避免用户遭遇难以调试的运行时错误。

# 实现拆解

1. **运行时版本检查**：在 `verl/workers/rollout/vllm_rollout/vllm_async_server.py` 的 `launch_server` 方法中，当 `enable_rollout_routing_replay=True` 时，添加版本检查：如果 `_VLLM_VERSION < version.parse("0.22.0")`，则抛出 `RuntimeError`，提示用户升级 vLLM 或禁用该功能。
2. **依赖配置调整**：在 `setup.py` 中新增 `VLLM_ROUTER_REPLAY_REQUIRES` 变量，指定 `vllm>=0.22.0` 和 `flash-linear-attention`，并添加 `vllm-router-replay` extra。但根据 Review 反馈，该 extra 最终被移除。
3. **文档更新**：在 `examples/router_replay/README.md` 中添加了 vLLM 版本要求说明，明确混合注意力 MoE 模型需要 vLLM>=0.22.0。

关键文件：
- `verl/workers/rollout/vllm_rollout/vllm_async_server.py`（模块 rollout 服务器；类别 source；类型 core-logic）: 核心变更：在 launch_server 中添加 vLLM 版本检查，当版本低于 0.22.0 时抛出 RuntimeError，避免运行时崩溃。
- `examples/router_replay/README.md`（模块 文档；类别 docs；类型 documentation）: 文档更新，明确 vLLM 版本要求，帮助用户了解 R3 模式的依赖。

关键符号：未识别

## 关键源码片段

### `verl/workers/rollout/vllm_rollout/vllm_async_server.py`

核心变更：在 launch_server 中添加 vLLM 版本检查，当版本低于 0.22.0 时抛出 RuntimeError，避免运行时崩溃。

```python
# 位于 launch_server 方法中，在设置 enable_return_routed_experts 之前
if self.config.enable_rollout_routing_replay:
    # R3 (Rollout Router Replay) 依赖 vLLM 的 enable_return_routed_experts 路径
    # 该路径仅在 vLLM >= 0.22.0 时能为混合注意力 MoE 模型（如 Qwen3.5）
    # 正确分配主机缓冲区。旧版本会因缓冲区不足抛出 IndexError。
    # 这里快速失败，提供可操作信息，而非让用户面对晦涩的内部错误。
    if _VLLM_VERSION < version.parse("0.22.0"):
        raise RuntimeError(
            "rollout.enable_rollout_routing_replay=True requires vLLM >= 0.22.0 "
            f"(installed: {vllm.__version__}). Upgrade vLLM (e.g. `pip install -U "
            "'vllm>=0.22.0'`) or disable enable_rollout_routing_replay."
        )
    args.update({"enable_return_routed_experts": True})

```

# 评论区精华

Reviewer wuxibin89 在 `setup.py` 的 diff hunk 上评论说“不需要这个，`vllm_async_server.py` 中添加的 `RuntimeError` 就足够了”，随后请求变更。之后 wuxibin89 又批准了 PR。这表明最终决策是仅保留运行时检查，移除依赖 extra 的更改。

- 依赖 extra 是否多余 (design): 接受 reviewer 建议，移除了 setup.py 中多余的依赖 extra，仅保留运行时检查。

# 风险与影响

- 风险：低风险。版本检查是纯防御性逻辑，不改变现有功能路径。对于正常启用了 R3 且 vLLM>=0.22.0 的用户，检查是透明的。主要风险在于如果用户依赖旧 vLLM 版本且需要 R3 功能，可能会被阻止，但这正是预期行为。
- 影响：影响范围局限于 R3 模式用户。对于未启用 R3 的用户无影响。修复了混合注意力 MoE 模型（如 Qwen3.5）在旧 vLLM 下的崩溃问题，提高了用户体验和可调试性。
- 风险标记：核心路径变更

# 关联脉络

- PR #6653 Preserve router replay fallback config flag: 涉及相同的 router replay 功能，可能影响实现细节。
- PR #4567 RouterReplay/TopKRouter mismatch for qwen3vl: 之前修复了 Qwen3VL 的 router replay 问题，与本 PR 的 Qwen3.5 相关。
- PR #4517 routed_experts to AgentData: 涉及路由专家数据流，与本 PR 的 enable_return_routed_experts 路径相关。