# PR #6285 完整报告

- 仓库：`verl-project/verl`
- 标题：[model] chore: refactor npu scripts
- 合并时间：2026-05-11 09:40
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6285

---

# 执行摘要

- 一句话：重构 Ascend NPU 训练脚本目录结构
- 推荐动作：建议阅读此 PR 以了解 NPU 脚本组织方式；注意删除的脚本可能中断现有用户工作流；后续应关注作者承诺的 PR 以进一步优化配置管理。

# 功能与动机

PR 标题和描述指出需要重构 NPU 脚本，使 NPU 相关的训练配置更清晰和独立，便于维护。

# 实现拆解

1. 删除旧的 NPU 专用脚本：移除 `examples/grpo_trainer/run_qwen3_30b_a3b_mindspeed.sh`。
2. 创建新的 `examples/ascend_extras/grpo_trainer/` 目录：将原有的 MindSpeed 脚本迁移并增强，同时新增多个 Qwen3/Qwen2.5 的 FSDP、Megatron 训练脚本。
3. 修改现有 GRPO 示例脚本：在 `run_qwen3_8b_fsdp.sh`、`run_qwen2_5_vl_7b_fsdp.sh` 等 5 个脚本中增加 `case "${DEVICE}"` 分支，自动检测 GPU/NPU 并设置相应的环境变量和并行参数。
4. 细节调整：统一配置键，修复变量命名（如 `train_etp` 改为 `actor_etp`），添加必要的 NPU 环境变量（如 `HCCL_*` 端口）。

关键文件：
- `examples/ascend_extras/grpo_trainer/run_qwen3_30b_a3b_mindspeed.sh`（模块 NPU 脚本；类别 config；类型 core-logic）: 新增的 NPU MindSpeed 训练脚本，代表重构后的目录结构和配置方式。
- `examples/grpo_trainer/run_qwen3_30b_a3b_mindspeed.sh`（模块 GRPO 示例；类别 config；类型 deletion）: 被删除的原 NPU 脚本，PR 中将其迁移至 ascend_extras 目录，属于核心变更。
- `examples/ascend_extras/grpo_trainer/run_qwen3_30b_a3b_megatron.sh`（模块 NPU 脚本；类别 config；类型 core-logic）: 新增的 NPU Megatron 训练脚本，与原文件相比增加了更详细的配置和注释，且由 review 指出多处语法错误。
- `examples/grpo_trainer/run_qwen3_8b_fsdp.sh`（模块 GRPO 示例；类别 config；类型 configuration）: 修改以支持通过 DEVICE 环境变量区分 GPU/NPU，是通用化改造的代表。
- `examples/ascend_extras/grpo_trainer/run_qwen3_4b_fsdp_npu.sh`（模块 NPU 脚本；类别 config；类型 core-logic）: 新增的 NPU 专用 FSDP 脚本，review 中专为 NPU 创建独立脚本的必要性受到质疑。
- `examples/grpo_trainer/run_qwen2_5_vl_7b_fsdp.sh`（模块 GRPO 示例；类别 config；类型 configuration）: 修改以支持 NPU，增加了 DEVICE 分支和并行配置调整。

关键符号：未识别

## 关键源码片段

### `examples/ascend_extras/grpo_trainer/run_qwen3_30b_a3b_mindspeed.sh`

新增的 NPU MindSpeed 训练脚本，代表重构后的目录结构和配置方式。

```bash
#!/bin/bash
set -xeuo pipefail
# Project Configuration
project_name='GRPO-Qwen3-30b-A3B-BASE-MATH'
exp_name='GRPO-Qwen3-30B-A3B-BASE-MindSpeedLLM-SGLang'

# Necessary env
export HCCL_CONNECT_TIMEOUT=1500
export HCCL_HOST_SOCKET_PORT_RANGE=60000-60050
export HCCL_NPU_SOCKET_PORT_RANGE=61000-61050
export RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES=1
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
export DISABLE_L2_CACHE=1
export TASK_QUEUE_ENABLE=1
# For CANN versions 8.5.0 and above, using mbridge, set this ENV
export HCCL_OP_EXPANSION_MODE="AIV"

# Node Info
NNODES=${NNODES:-1}
NPUS_PER_NODE=${NPUS_PER_NODE:-16}

# Model Weights Paths
MODEL_PATH=Qwen/Qwen3-30B-A3B
# ...（后续配置类似原脚本，但整合了更清晰的变量和注释）

```

# 评论区精华

- **Shell 语法错误**：gemini-code-assist[bot] 指出多个脚本存在缺少 `fi`、未定义变量 `train_etp`、多余反斜杠等问题，均为纠正。
- **设计争议**：wuxibin89 质疑为何训练配置与 rollout backend 耦合（L105-L126），作者回应 sglang 和 vllm 配置已统一；但 reviewer 未完全认同。
- **NPU 脚本必要性**：wuxibin89 询问为何需要单独 NPU 脚本（如 run_qwen2_5_32b_fsdp_npu.sh），作者未直接回答但承诺后续 PR 全面修订。
- **配置硬编码**：wuxibin89 建议将 `sp_size` 等 NPU 必要配置直接设置在 `async_sglang_server.py` 中而非 shell 脚本，作者同意后续 PR 处理。

 - 缺少 fi 导致 shell 语法错误 (correctness): 已修复（在后续 commit 中合并）。
 - 未定义变量 train_etp vs actor_etp (correctness): 已修复。
 - 训练配置与 rollout backend 耦合的设计质疑 (design): 作者解释后 reviewer 未完全认同，但未阻止合并。
 - 需要单独 NPU 脚本的设计决策 (design): 作者未直接回应但承诺后续 PR 全面修订。
 - 建议将 NPU 配置移入源码 (design): 作者同意将提交单独 PR。

# 风险与影响

- 风险：
 - **Shell 语法错误**：review 中发现了缺少 fi、变量未定义等问题，虽已修复，但类似风险可能在其他未覆盖脚本中存在。
 - **Breaking change**：删除了 `examples/grpo_trainer/run_qwen3_30b_a3b_mindspeed.sh`，用户若直接引用该路径将失败，PR 未标注 `[BREAKING]`。
 - **CI 覆盖不足**：新增的 `examples/ascend_extras` 目录未纳入 CI pipeline，可能引入回归。
 - **配置分散**：部分 NPU 环境变量仍硬编码在 shell 脚本中，后续维护成本较高。
- 影响：
 - **GPU 用户**：不受影响，现有脚本仅增加 `DEVICE` 分支，GPU 路径保持不变。
 - **NPU 用户**：需改用 `examples/ascend_extras` 目录下的新脚本或通过 `DEVICE=npu` 运行修改后的脚本；旧路径失效。
 - **团队**：NPU 配置更加独立清晰，但后续仍需统一配置到源码，减少 shell 脚本维护。
 - 风险标记：Shell 语法错误 , 删除旧脚本 break, 新目录未覆盖 CI, 配置硬编码待优化

# 关联脉络

- PR #6273 [ci] feat: add gspo qwen3-30b in nightly npu ci: 同样涉及 NPU 训练脚本的 CI 配置，与本 PR 的脚本重构有间接关联。
- PR #6253 [ci] fix: remove the redundant config: 涉及 NPU 测试脚本的配置清理，与本 PR 的 NPU 脚本重构相关。