执行摘要
- 一句话：vLLM版本门控防止Qwen3.5 R3路由器回放崩溃
- 推荐动作：该PR是防御性编程的典型例子，值得精读。设计决策（运行时版本检查 vs 依赖门控）的权衡体现了对用户透明度和维护成本的考虑。
功能与动机
R3模式依赖vLLM的enable_return_routed_experts路径，该路径仅在vLLM>=0.22.0时才能正确处理混合注意力MoE模型（如Qwen3.5）。旧版本vLLM会因主机缓冲区不足而在rollout过程中崩溃，出现晦涩的IndexError。PR旨在提供即时反馈，避免用户遭遇难以调试的运行时错误。
实现拆解
- 运行时版本检查：在
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或禁用该功能。
- 依赖配置调整：在
setup.py中新增VLLM_ROUTER_REPLAY_REQUIRES变量，指定vllm>=0.22.0和flash-linear-attention，并添加vllm-router-replay extra。但根据Review反馈，该extra最终被移除。
- 文档更新：在
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，避免运行时崩溃。
# 位于 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路径相关。
参与讨论