# PR #5682 完整报告

- 仓库：`verl-project/verl`
- 标题：[fsdp, model] feat: add qwen3.5 fsdp grpo training support.
- 合并时间：2026-03-30 13:48
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/5682

---

# 执行摘要

- 一句话：新增 Qwen3.5 模型的 FSDP GRPO 训练支持，涵盖适配器、补丁和示例脚本。
- 推荐动作：该 PR 值得精读，特别是 qwen3_5.py 中的适配器设计展示了如何修复 FSDP2 CPU 卸载 bug，以及 monkey_patch.py 的扩展模式。建议关注配置参数设置、依赖版本管理和测试覆盖策略，以避免常见部署问题。

# 功能与动机

PR body 明确表述“enables FSDP GRPO training for Qwen3.5 models”，旨在响应用户对 Qwen3.5 模型 FSDP 训练的需求，Issue 评论中用户如 winnieyangwannan 直接询问支持情况，表明这是提升框架实用性的功能扩展。

# 实现拆解

实现拆解为三部分：1) 模型适配器：新增 verl/models/transformers/qwen3_5.py 文件，包含 fast_pos_embed_interpolate 函数修复 FSDP2 CPU 卸载 bug，并提供前向传播函数。2) 补丁集成：修改 monkey_patch.py 添加 qwen3_5 模型类型支持；更新 npu_patch.py 为 Qwen3.5 和 Qwen3.5 MoE 添加 NPU 补丁；调整 npu_vllm_patch.py 版本检查范围。3) 示例脚本：新增四个训练脚本（examples/grpo_trainer/run_qwen3_5_*），配置 GRPO 算法、FSDP2 策略及关键参数，支持普通和 NPU 环境。

关键文件：
- `verl/models/transformers/qwen3_5.py`（模块 model）: 新增 Qwen3.5 适配器核心文件，包含修复 FSDP2 CPU 卸载 bug 的关键函数 fast_pos_embed_interpolate 和前向传播逻辑。
- `verl/models/transformers/monkey_patch.py`（模块 model）: 修改以支持 qwen3_5 和 qwen3_5_moe 模型类型，是补丁应用入口点，影响模型前向传播路径。
- `examples/grpo_trainer/run_qwen3_5_27b_vllm_fsdp.sh`（模块 examples）: 提供 Qwen3.5-27B FSDP GRPO 训练示例脚本，配置关键参数如 actor.use_dynamic_bsz=False，为用户提供开箱即用的训练方案。
- `verl/models/transformers/npu_patch.py`（模块 model）: 扩展 NPU 后端支持，添加 Qwen3.5 和 Qwen3.5 MoE 的补丁函数，确保在 Ascend 硬件上的兼容性。
- `verl/utils/vllm/npu_vllm_patch.py`（模块 vllm）: 调整 vllm 版本检查范围（从 0.13.0 扩展至 0.14.0），确保 NPU 环境下的 vllm 兼容性。

关键符号：fast_pos_embed_interpolate, forward_with_normal_backend, qwen3_5_base_forward, qwen3_5_moe_experts_forward_npu


# 评论区精华

Review 中核心讨论包括：1) CI 看护：beirong8kmiles 建议将模型加入 CI，作者 Zhang1Sheng 回复因 vllm0.18 版本当前 NPU CI 无法直接看护，突显测试覆盖缺口。2) 配置参数：wucong25 质疑 update_weights_bucket_megabytes 设置过大，作者解释当前配置影响不大，参数未调整。3) 依赖版本：wucong25 询问 transformer 版本要求，作者回答需要 v5.0 以上，明确了兼容性约束。4) 文件格式：gemini-code-assist[bot] 指出脚本缺少换行符，建议修复以预防解析错误。

- CI 测试覆盖 (testing): 暂未解决，需后续 CI 更新以覆盖新版本依赖。
- 配置参数优化 (design): 参数保持原样，未进行调整，依赖经验设置。
- 依赖版本管理 (other): 明确了依赖要求，确保兼容性。
- 文件格式规范 (style): 建议已提出，但 PR 中未体现是否采纳，状态未知。

# 风险与影响

- 风险：技术风险包括：1) 回归风险：monkey_patch.py 新增条件分支可能干扰其他模型前向传播。2) 兼容性风险：依赖特定版本（vllm0.18.0、transformer v5.0+），可能导致环境配置问题或升级困难。3) 性能风险：示例脚本中配置参数（如 update_weights_bucket_megabytes）未优化，可能影响训练效率。4) 测试覆盖不足：由于 CI 无法看护，缺乏自动化测试，Issue 评论中用户报告激活卸载错误等 bug 未完全解决。5) 补丁复杂度：新增适配器和补丁增加了代码维护负担。
- 影响：影响分析：1) 用户影响：为 Qwen3.5 模型用户提供了 FSDP GRPO 训练能力，扩展 VERL 框架的模型支持范围，降低部署门槛。2) 系统影响：新增模块化代码（如 qwen3_5.py）有助于隔离变更，但增加了维护成本；修复 FSDP2 CPU 卸载 bug 提升了框架稳定性。3) 团队影响：需后续 PR 支持 ulysses sequence parallel 等功能，并可能需更新 CI 以覆盖新依赖版本。
- 风险标记：缺少测试覆盖 , 依赖版本锁定 , 配置矛盾风险 , 补丁集成复杂度

# 关联脉络

- PR #5874 [megatron, cfg] feat: add Qwen3.5-122B Megatron launch script: 同属 Qwen3.5 模型支持系列，但专注于 Megatron 后端，与本 PR 的 FSDP 后端形成互补。
- PR #5802 [4/n][trainer] feat: flowgrpo - add diffusers + fsdp engine support: 涉及 FSDP 引擎扩展，与本 PR 的 FSDP 训练支持相关，展示框架内 FSDP 功能的演进。
- PR #5381 从 Issue 评论中提及，具体标题未提供 : Issue 评论中 Zhikaiiii 提及 PR #5381 讨论了 Qwen3.5 模型在 Megatron 下的配置约束，与本 PR 的 FSDP 配置设置（如 model.use_remove_padding）引发用户疑问，揭示跨后端配置一致性问题。