# PR #5381 完整报告

- 仓库：`verl-project/verl`
- 标题：[megatron, model] feat: qwen3.5 example 
- 合并时间：2026-03-13 10:47
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/5381

---

# 执行摘要

- 一句话：新增 Qwen3.5 模型的 Megatron 训练示例和代码支持。
- 推荐动作：此 PR 值得工程师精读，以了解如何适配新模型架构到现有训练框架。关注设计决策：chat_template 的异常处理机制、tool_parser 的扩展性、以及 Megatron 配置中 use_remove_padding 参数的设计权衡。对于维护者，建议审查 Exception 捕获逻辑，并跟踪 Megatron-LM 对 Qwen3.5 THD 格式的支持进展。

# 功能与动机

PR body 中说明，感谢 @LiuXTao 在 mbridge 上的工作（https://github.com/ISEEKYAN/mbridge/pull/83）支持了 Qwen3.5，此 PR 基于此在 verl 上成功运行 Qwen3.5 SFT。Issue 评论中用户询问是否支持 RL，作者更新了 RL 脚本，但提到 vllm 依赖问题，体现了添加 Qwen3.5 训练支持的需求。

# 实现拆解

实现方案分为多个模块：
1. 示例脚本：新增 examples/grpo_trainer/run_qwen3_5-35b-megatron.sh 和 examples/sft/gsm8k/run_qwen3_5_megatron.sh，配置 Megatron 并行参数和 Qwen3.5 特定设置（如 use_remove_padding=False）。
2. chat 模板：修改 verl/utils/chat_template.py 中的 apply_chat_template 函数，处理 Qwen3.5 至少需要一个用户消息的模板需求。
3. 工具解析器：在 verl/experimental/agent_loop/tool_parser.py 中新增 Qwen3XMLToolParser 类，支持 Qwen3.5 模型的 XML 格式工具调用解析。
4. agent 循环：调整 verl/experimental/agent_loop/agent_loop.py 中的 _compute_position_ids 函数，以兼容 transformers>=5.3.0 引入的 mm_token_type_ids 参数。
5. 数据处理器：修改 verl/utils/dataset/multiturn_sft_dataset.py，增强对视觉内容的处理和错误处理。
6. Megatron 工具：更新 verl/utils/megatron_utils.py 中的 load_megatron_model_to_gpu 函数，修复 Gated DeltaNet 等非标准层的 grad buffer 处理。
7. 其他修改：包括更新 CI 工作流以支持 transformers>=5.0.0，修复 NestedTensor 处理（verl/utils/tensordict_utils.py）等。

关键文件：
- `examples/grpo_trainer/run_qwen3_5-35b-megatron.sh`（模块 examples）: 新增 GRPO 训练脚本，演示 Qwen3.5-35B-A3B MoE 模型的 Megatron 配置、并行参数设置和 Qwen3.5 特定注意事项（如 use_remove_padding=False）。
- `examples/sft/gsm8k/run_qwen3_5_megatron.sh`（模块 examples）: 新增 SFT 训练脚本，用于 Qwen3.5-397B-A17B 模型的 Megatron 后端训练，包含分布式设置和模型架构注释。
- `verl/utils/chat_template.py`（模块 utils）: 修改 apply_chat_template 函数以处理 Qwen3.5 的 chat 模板需求，特别是至少需要一个用户消息的特殊情况，增强兼容性。
- `verl/experimental/agent_loop/tool_parser.py`（模块 agent_loop）: 新增 Qwen3XMLToolParser 类以支持 Qwen3.5 模型的工具调用解析，基于外部实现适配，扩展工具解析能力。
- `verl/utils/tensordict_utils.py`（模块 utils）: 修复 chunk_tensordict 函数以正确处理 NestedTensor，特别是 3D jagged tensors（如 MRoPE position_ids），解决 PyTorch bug 导致的 unbind 失败。

关键符号：apply_chat_template, extract_tool_calls, _compute_position_ids, chunk_tensordict, load_megatron_model_to_gpu


# 评论区精华

Review 评论中的核心讨论包括：
- gemini-code-assist[bot] 在 verl/utils/dataset/multiturn_sft_dataset.py 中指出捕获宽泛 Exception 可能隐藏 bug，建议捕获更具体的异常类型，但未完全解决。
- wuxibin89 在 verl/workers/engine_workers.py 中讨论 model.use_remove_padding 和 engine.use_remove_padding 参数的关系，ISEEKYAN 回复标记 model.use_remove_padding 为 deprecated，仅使用 engine.use_remove_padding。
- wuxibin89 在 verl/utils/tensordict_utils.py 中询问 NestedTensor unbind 失败原因，ISEEKYAN 解释是 PyTorch bug 导致 3D jagged tensors 问题，已通过文档和代码修复。
- wuxibin89 在 examples/grpo_trainer/run_qwen3_5-35b-megatron.sh 中提出对新模型引擎使用 NestedTensor 的疑问，但未进一步讨论结论。
- mamazi0131 在 Issue 评论中分享成功运行经验并讨论性能对比。

- Exception 捕获风险 (correctness): 未完全解决，PR 中未修改此逻辑，可能需要后续修复以提升代码健壮性。
- use_remove_padding 参数设计 (design): 已解决，决定仅使用 engine.use_remove_padding，model.use_remove_padding 被标记为弃用以简化配置。
- NestedTensor 处理问题 (correctness): 已通过文档更新和代码修复（使用 to_padded_tensor 回退）解决，增强了函数的鲁棒性。

# 风险与影响

- 风险：技术风险具体包括：
- 兼容性风险：依赖特定版本的 vllm、transformers 和 mbridge，Issue 评论中显示版本冲突（如 transformers==5.2.0 与 vllm nightly 的兼容性问题），可能导致用户环境配置复杂。
- 性能风险：Qwen3.5 使用 Gated Delta Net 线性注意力，不支持 packed sequences（THD 格式），必须设置 use_remove_padding=False，可能影响训练性能，直到 Megatron-LM 添加支持（PR 讨论中提及）。
- 代码健壮性风险：verl/utils/dataset/multiturn_sft_dataset.py 中捕获宽泛 Exception 可能掩盖非预期错误，增加调试难度。
- 回归风险：修改核心函数如 verl/utils/tensordict_utils.py 中的 chunk_tensordict 可能影响其他使用 NestedTensor 的模块，需确保向后兼容。
- 依赖外部项目风险：mbridge 支持是关键依赖，但需从源码安装，增加部署复杂度。
- 影响：影响范围：
- 对用户：现在可以在 verl 中运行 Qwen3.5 的 SFT 和 GRPO 训练，通过提供的示例脚本快速上手，但需注意硬件要求（如 128+ GPUs for 397B 模型）和依赖版本管理。
- 对系统：引入新模型架构支持，需升级 transformers 到 >=5.0.0（CI 工作流已更新），可能影响现有模型训练流程的兼容性。
- 对团队：需维护 Qwen3.5 相关代码，处理后续 bug 和性能优化，Issue 评论中显示用户反馈了多个运行问题（如 vllm 初始化、transformers 版本冲突），增加了支持负担。
- 风险标记：版本兼容性问题 , 宽泛 Exception 捕获 , NestedTensor 处理复杂性

# 关联脉络

- PR #5695 [fully_async] fix: Patch vllm013 weight loader for qwen3-moe series: 类似地修复了 vllm 中的模型权重加载问题，与本 PR 的模型兼容性工作相关，都涉及新模型架构的支持。
- PR #5575 [megatron] feat: checkpoint save as HF PEFT format: 涉及 Megatron 模块的改进，与本 PR 的 Megatron 训练示例相关，展示了 Megatron 功能的持续扩展。