执行摘要

• 一句话：重构 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 训练脚本，代表重构后的目录结构和配置方式。

#!/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 脚本重构相关。