# PR #7604 完整报告

- 仓库：`verl-project/verl`
- 标题：[megatron, ci] chore: upgrade Ascend stack to Megatron 0.18.0
- 合并时间：2026-09-04 10:30
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/7604

---

# 执行摘要

- 一句话：升级 Ascend A2/A3 镜像至 Megatron 0.18.0 并切换依赖栈。
- 推荐动作：这是一个重要的基础设施升级 PR，虽然不涉及核心算法或训练逻辑的改动，但它改变了 Ascend 平台上所有训练任务的底层依赖栈和运行时配置。对于使用 Ascend 的开发者或运维人员，此 PR 值得精读，以理解版本升级的具体内容和配置切换点，从而安全地完成环境迁移。对于不使用 Ascend 的读者，可以略过。

# 功能与动机

动机是跟随 Ascend 硬件生态的升级。PR body 明确指出，目标是“Upgrade the Ascend A2 and A3 images to MindSpeed and Megatron-LM core_r0.18.0”，并安装一系列新的依赖组件（Ascend adaptor, TransformerEngineNPU 等），以替换旧的方案。

# 实现拆解

1. **更新 Docker 镜像构建文件**：修改 `docker/ascend/Dockerfile.ascend_9.1.0_a2` 和 `docker/ascend/Dockerfile.ascend_9.1.0_a3`。将 `MindSpeed` 和 `Megatron-LM` 的版本从 `core_r0.16.0` 提升至 `core_r0.18.0`。新增克隆并安装 `MegatronAdaptor`、`TransformerEngineNPU`、`MindSpeed-Ops`、`MindSpeed-Bridge`、`Megatron-Bridge` 等依赖。移除了对 `transformers` 特定 commit 的固定克隆和安装，以及旧版 `mbridge` 的安装和针对 DeepSeek 模型的 `cuda` 到 `npu` 的 `sed` 修改操作。此举确保了镜像使用最新且一致的依赖栈。
2. **修改本地安装脚本**：更新 `scripts/install_vllm_mcore_npu.sh`，使其与 Dockerfile 的逻辑保持同步。将 MindSpeed 和 Megatron-LM 的版本更新至 `core_r0.18.0`，并新增 `MegatronAdaptor`、`TransformerEngineNPU`、`MindSpeed-Ops`、`MindSpeed-Bridge`、`Megatron-Bridge` 的安装步骤，同时移除旧版 `mbridge` 的安装。这保证了开发者在本地也能构建一致的运行环境。
3. **同步修改 NPU 测试脚本配置**：在 `tests/special_npu/` 和 `tests/special_e2e/` 下的多个 NPU 训练启动脚本（如 `run_gspo_qwen3_30b_megatron_npu.sh`， `run_dapo_moonlight-16b_megatron_npu.sh` 等）中，将 `actor_rollout_ref.actor.megatron.vanilla_mbridge` 和 `actor_rollout_ref.ref.megatron.vanilla_mbridge` 的值从 `True` 统一修改为 `False`。这是核心的运行时配置切换，使脚本使用新的通信桥接后端。部分脚本（如 `run_v1_separate_async_ascend.sh`）则直接移除了该配置。
4. **调整 CI 工作流**：修改 `.github/workflows/` 下的 Ascend 相关工作流文件（如 `e2e_sft_llm_ascend.yml`， `model_ascend.yml`）。主要变更是移除在运行测试前通过 `pip uninstall` 和 `pip install` 来替换 `mbridge` 的步骤，以及移除在调用测试脚本时传递的 `VANILLA_MBRIDGE=True` 环境变量。这使 CI 流程更简洁，并直接使用新镜像或安装脚本提供的默认环境。
5. **更新文档**：在 `docs/ascend_tutorial/` 下更新安装和 Dockerfile 构建指南中的版本号和步骤说明，使其与实际变更同步。

关键文件：
- `docker/ascend/Dockerfile.ascend_9.1.0_a2`（模块 镜像构建；类别 infra；类型 infrastructure）: Ascend A2 镜像的构建蓝图，定义了所有依赖的版本和安装方式，是本次升级的核心文件。
- `scripts/install_vllm_mcore_npu.sh`（模块 安装脚本；类别 other；类型 infrastructure）: 本地开发环境的安装脚本，与 Dockerfile 逻辑对齐，确保开发者能复现一致的 Ascend 环境。
- `tests/special_npu/nightly_ci_ascend/run_gspo_qwen3_30b_megatron_npu.sh`（模块 CI 测试脚本；类别 test；类型 configuration）: 代表性的 NPU 夜间 CI 测试脚本，展示了核心运行时配置 `vanilla_mbridge` 的关键切换。

关键符号：未识别

## 关键源码片段

### `docker/ascend/Dockerfile.ascend_9.1.0_a2`

Ascend A2 镜像的构建蓝图，定义了所有依赖的版本和安装方式，是本次升级的核心文件。

```dockerfile
# 关键变更：升级 MindSpeed/Megatron 版本并安装新组件
RUN ARCH=$(uname -m) && \
    # ... vllm, vllm-ascend clone ...
    git clone https://gitcode.com/Ascend/MindSpeed.git && \
    cd MindSpeed && git checkout core_r0.18.0 && cd .. && \
    git clone --depth 1 --branch core_r0.18.0 https://github.com/NVIDIA/Megatron-LM.git && \
    # 新增：克隆 Ascend 适配器和桥接组件
    git clone --depth 1 --branch core_r0.18.0 https://gitcode.com/ascend/MegatronAdaptor.git && \
    git clone --depth 1 https://gitcode.com/ascend/TransformerEngineNPU.git && \
    git clone --depth 1 https://gitcode.com/ascend/MindSpeed-Ops.git && \
    git clone --depth 1 https://gitcode.com/ascend/MindSpeed-Bridge.git && \
    git clone --depth 1 --branch v0.5.0 https://github.com/NVIDIA-NeMo/Megatron-Bridge.git
# ...
# 关键变更：安装顺序和依赖声明
# 安装 Megatron 及 Ascend 适配组件
RUN ... && \
    # 安装 Megatron & MindSpeed
    pip install -e Megatron-LM && \
    pip install -e MindSpeed && \
    # 新增：安装一系列 Ascend 特定适配组件
    pip install -e MegatronAdaptor && \
    pip install -e TransformerEngineNPU --no-build-isolation && \
    pip install -e MindSpeed-Ops --no-build-isolation --no-deps && \
    pip install -r MindSpeed-Bridge/requirements.txt && \
    pip install -e MindSpeed-Bridge --no-deps && \
    pip install -e Megatron-Bridge --no-build-isolation --no-deps && \
# 移除：旧版 transformers 固定、mbridge 安装和 cuda->npu 的 sed 操作

```

### `scripts/install_vllm_mcore_npu.sh`

本地开发环境的安装脚本，与 Dockerfile 逻辑对齐，确保开发者能复现一致的 Ascend 环境。

```bash
# 脚本中的关键安装序列变更
if [ $USE_MEGATRON -eq 1 ]; then
    echo "3. install Megatron & MindSpeed"
    # 更新版本号
    git clone https://gitcode.com/Ascend/MindSpeed.git
    cd MindSpeed && git checkout core_r0.18.0 && cd ..
    git clone --depth 1 --branch core_r0.18.0 https://github.com/NVIDIA/Megatron-LM.git
    # 新增：克隆 Ascend 依赖
    git clone --depth 1 --branch core_r0.18.0 https://gitcode.com/ascend/MegatronAdaptor.git
    git clone --depth 1 https://gitcode.com/ascend/TransformerEngineNPU.git
    git clone --depth 1 https://gitcode.com/ascend/MindSpeed-Ops.git
    git clone --depth 1 https://gitcode.com/ascend/MindSpeed-Bridge.git
    git clone --depth 1 --branch v0.5.0 https://github.com/NVIDIA-NeMo/Megatron-Bridge.git
    
    # 安装命令更新
    pip install -e Megatron-LM
    pip install -e MindSpeed
    # 新增：安装组件
    pip install -e MegatronAdaptor
    pip install -e TransformerEngineNPU --no-build-isolation
    pip install -e MindSpeed-Ops --no-build-isolation --no-deps
    pip install -r MindSpeed-Bridge/requirements.txt
    pip install -e MindSpeed-Bridge --no-deps
    pip install -e Megatron-Bridge --no-build-isolation --no-deps
fi
# 移除 : pip install mbridge

```

# 评论区精华

PR 的 review 过程中没有产生任何讨论。只有一条来自 `wucong25` 的简单 “APPROVED” 评论。

- 暂无高价值评论线程

# 风险与影响

- 风险：
 1. **依赖版本跳跃风险**：将 `Megatron-LM` 和 `MindSpeed` 从 `core_r0.16.0` 直接升级至 `core_r0.18.0`，跳过了一个大版本。可能存在未预见的 API 变更或行为差异，尽管这是上游维护者的选择，但仍需关注后续集成测试的稳定性。
 2. **配置默认值改变的风险**：`vanilla_mbridge` 配置从 `True` 切换到 `False` 是一个破坏性变更（尽管标题未标记为 `[BREAKING]`）。如果用户的自定义脚本或配置文件中显式依赖 `vanilla_mbridge=True` 的旧行为，升级后可能导致训练失败或行为异常。该 PR 在公共仓库脚本中完成了切换，但无法覆盖外部用户。
 3. **移除工作代码的风险**：Dockerfile 中移除了对 `mbridge` 包的安装以及针对 `deepseek_v3` 模型的 `cuda` 转 `npu` 的 `sed` 命令。这暗示新依赖栈已原生解决了此问题，但若有边缘场景或未被 CI 覆盖的模型（如其他 DeepSeek 变体）仍依赖旧的 work-around，则可能出错。
 4. **新依赖的构建兼容性**：新增了 `TransformerEngineNPU`、`MindSpeed-Ops` 等组件的安装，部分使用了 `--no-build-isolation` 和 `--no-deps` 标志。这降低了隔离性，可能与环境中的其他包产生冲突，或在构建过程中产生难以调试的问题。
 - 影响：**影响范围**：主要影响使用 Ascend NPU 硬件（A2/A3 卡）的用户和 CI 环境。
**影响程度**：
- **对用户**：用户需要重新构建或拉取更新后的 Docker 镜像，并确保其训练脚本不依赖于旧的 `vanilla_mbridge=True` 配置。若用户自定义脚本未更新，升级后训练流程可能中断。正面影响是能使用更新的 Megatron 0.18.0 特性和优化的 Ascend 适配组件。
- **对系统**：统一了项目内 Ascend 生态的依赖版本，清理了历史遗留的 work-around 代码，使依赖栈更清晰、更现代。这有助于长期维护和稳定性。
- **对团队**：减少了维护旧版 work-around 脚本的负担。CI 流程得到简化。但需要团队跟进，确保文档和示例全部更新。
- 风险标记：依赖版本跳跃 , 配置行为改变 , 移除 work-around 代码

# 关联脉络

- PR #7627 [misc] feat: uv support aarch64: 同属于 Ascend 基础设施的改进，该 PR 支持 aarch64 架构，与本 PR 的镜像升级共同推进 Ascend 平台的现代化。
- PR #7606 [env] fix: Update ascend image build workflow: 同属于 Ascend Docker 镜像构建流程的调整，该 PR 修复了镜像推送问题，与本 PR 的镜像内容升级直接相关。
- PR #7633 [ci, trainer] refactor: switch fsdp_turbo e2e test from GPU to NPU: 该 PR 将 FSDP 测试迁移到 NPU，表明项目正积极将更多测试负载转移到 Ascend 平台，与本 PR 升级 Ascend 栈的目标一致。