# PR #1750 完整报告

- 仓库：`THUDM/slime`
- 标题：feat: add npu patch for qwen3-vl-8b grpo & ppo
- 合并时间：2026-04-07 11:19
- 原文链接：http://prhub.com.cn/THUDM/slime/pull/1750

---

# 执行摘要

- 一句话：添加 NPU 补丁以支持 Qwen3-VL-8B 模型的 GRPO 和 PPO 训练。
- 推荐动作：该 PR 值得精读，特别是对于涉及硬件适配或多模态训练的工程师。重点关注：
 1. `slime.patch` 中的资源分配逻辑变更，如 Ray API 替换，这可能影响分布式训练稳定性。
 2. 补丁中的手动代码替换（如 cuda→npu），需理解其背后的兼容性设计决策。
 3. 环境配置和版本依赖，以评估部署可行性。建议结合 README.md 进行实操验证。

# 功能与动机

PR body 中指出，此变更旨在 'adapt the training stack (megatron-bridge, megatron, mindspeed, sglang, slime) for NPU (Ascend) compatibility, along with several bug fixes'，即适配 NPU 硬件以提供兼容性并修复相关 bug。没有关联 Issue，直接基于内部需求进行。

# 实现拆解

实现拆解为多个模块：
1. **补丁文件**：在 `docker/npu_patch/` 目录下添加五个 .patch 文件，分别修改 Megatron-Bridge（如 param_mapping.py 添加兼容性处理）、Megatron（移除 @jit_fuser 装饰器并手动 cuda→npu 替换）、MindSpeed（添加参数对齐和格式转换）、SGLang（修复位置嵌入并路由 attention 计算）、SLime（添加 is_npu() 检测并调整 Ray 资源分配）。
2. **工具和文档**：新增 `README.md` 提供详细安装指南，包括环境配置和依赖版本映射。
3. **示例脚本**：在 `examples/geo3k_vlm_multi_turn/` 目录下添加两个 Python 脚本（run_geo3k_vlm_multi_turn_grpo_npu.py 和 run_geo3k_vlm_multi_turn_ppo_npu.py）和对应的 Shell 脚本，展示如何在 NPU 上运行 GRPO 和 PPO 训练。
关键改动点包括：移除不支持的操作符、设备名称替换（cuda→npu）、通信后端调整（nccl→hccl）、Ray API 适配（如 resources 替换 num_gpus）、环境变量设置（ASCEND_RT_VISIBLE_DEVICES）。

关键文件：
- `docker/npu_patch/slime.patch`（模块 slime 核心）: 核心 SLime 代码修改，添加 NPU 检测和 Ray 资源分配逻辑，影响训练后端和分布式通信。
- `docker/npu_patch/megatron.patch`（模块 megatron 后端）: 移除 @jit_fuser 并手动 cuda→npu 替换，涉及 Megatron 核心激活和融合函数，可能影响性能。
- `docker/npu_patch/sglang.patch`（模块 sglang 后端）: 修复 Qwen3-VL 位置嵌入并路由 attention 计算到 NPU 算子，关键于多模态模型推理。
- `examples/geo3k_vlm_multi_turn/run_geo3k_vlm_multi_turn_grpo_npu.py`（模块 示例）: 新增 NPU 示例脚本，展示如何配置和运行 GRPO 训练，对用户有直接参考价值。

关键符号：is_npu, repatch, bias_dropout_add_fused_train, apply_rotary_pos_emb


# 评论区精华

无 review 评论，讨论为空。PR 直接合并，没有公开的技术讨论记录。

- 暂无高价值评论线程

# 风险与影响

- 风险：技术风险包括：
 1. **回归风险**：手动移除 @jit_fuser 可能影响 GPU 上的性能优化（如 Megatron.patch），需确保不影响原始 CUDA 路径。
 2. **兼容性风险**：补丁依赖于特定版本（如 CANN 8.5.0、Python 3.11），环境配置复杂，可能导致部署问题。
 3. **安全风险**：设备 ID 处理（如 Ray API 中的字符串转换）可能引入类型错误或资源分配异常。
 4. **测试覆盖不足**：新增补丁和示例脚本缺少自动化测试，可能隐藏未发现的 bug。
 5. **维护复杂度**：多个补丁文件需随上游更新同步，增加长期维护负担。
- 影响：影响范围：
 1. **用户影响**：使 SLime 用户能在 NPU 硬件上训练 Qwen3-VL-8B 模型，支持 GRPO 和 PPO 算法，扩展了用户硬件选择。
 2. **系统影响**：引入 NPU 特定逻辑（如 is_npu() 检测），系统现在需区分 GPU/NPU 路径，可能增加运行时开销；环境依赖更复杂（如需安装 CANN 和特定 PyTorch 版本）。
 3. **团队影响**：开发团队需维护 NPU 补丁集，可能涉及跨组件（Megatron、SGLang）的协调，增加技术债务。影响程度为中等，主要针对 NPU 用户，但核心训练逻辑有变更。
- 风险标记：硬件依赖复杂 , 手动代码替换 , 缺少测试覆盖 , 核心路径变更

# 关联脉络

- PR #1760 [Multimodal] Add Multimodal OPD support: 同为多模态模型支持，扩展了 SLime 的多模态能力，与本 PR 的 Qwen3-VL 适配有功能关联。
- PR #1805 sync from internal: 涉及多模态模型优化和 SGLang 调整，与本 PR 的 SGLang 补丁和性能改进有技术延续性。