# PR #6102 完整报告

- 仓库：`verl-project/verl`
- 标题：[ci] chore: update npu docker build pipeline
- 合并时间：2026-04-21 22:47
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6102

---

# 执行摘要

- 一句话：更新 NPU Docker 构建流水线与环境变量配置
- 推荐动作：本 PR 适合 CI/DevOps 维护者精读，尤其是多架构 Docker 构建模式的实现。代码变更安全，但建议后续跟进解决 review 中提出的冗余行问题。其余开发者可略过。

# 功能与动机

本 PR 旨在更新 NPU Docker 构建流水线，统一并优化构建流程：支持多架构 manifest、清理旧版本配置、适配新版 CANN 编译要求。

# 实现拆解

1. **Docker 构建工作流重构 **（docker-build-ascend-a2.yml、a3.yml）：将原先单步骤的并行平台构建拆分为两阶段——第一阶段按架构（amd64/arm64）分别构建并推送 digest，第二阶段合并为 manifest；同时移除了针对 v0.7.1 的独立构建任务。
2. **夜间 CI 配置更新 **（nightly_ascend.yml）：在 DAPO Moonlight 测试步骤前注入 HCCL_OP_EXPANSION_MODE 环境变量，以兼容新版 CANN。
3. **测试脚本参数调整 **（run_dapo_moonlight-16b_megatron_npu.sh）：切换训练 / 验证数据集为 dapo-math-17k；调整上下文并行（CP=2）、张量并行（TP=1）、专家并行（EP=2）等参数；新增 data.prompt_key 和 context_parallel_size 显式覆盖。
4. **示例脚本环境变量添加 **（两个 run_qwen3 脚本）：在脚本开头添加 export HCCL_OP_EXPANSION_MODE="AIV"。
5. **文档同步更新 **（ascend_quick_start.rst）：添加对应环境变量的说明。

关键文件：
- `.github/workflows/docker-build-ascend-a2.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 核心重构文件之一，将 Ascend A2 的 Docker 构建从单平台并行改为多架构矩阵 + digest 模式，并移除 v0.7.1 镜像构建。
- `.github/workflows/docker-build-ascend-a3.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 与 a2.yml 对应的 A3 构建工作流重构，结构和变更同步。
- `.github/workflows/nightly_ascend.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 在夜间 CI 中为 DAPO Moonlight 测试任务添加 HCCL_OP_EXPANSION_MODE 环境变量。
- `tests/special_npu/nightly_ci_ascend/run_dapo_moonlight-16b_megatron_npu.sh`（模块 NPU 测试；类别 test；类型 test-coverage）: 测试脚本：更新数据集路径、并行参数，添加 context_parallel_size 等新配置。
- `examples/grpo_trainer/run_qwen3-32b_sglang_mindspeedllm_npu.sh`（模块 示例配置；类别 other；类型 core-logic）: 为 NPU GRPO 示例脚本添加 HCCL_OP_EXPANSION_MODE 环境变量。
- `examples/grpo_trainer/run_qwen3moe-30b_sglang_mindspeedllm_npu.sh`（模块 示例配置；类别 other；类型 core-logic）: 与上同理，为另一个 NPU GRPO 示例脚本添加相同环境变量。
- `docs/ascend_tutorial/quick_start/ascend_quick_start.rst`（模块 文档；类别 docs；类型 documentation）: 文档同步更新，添加 HCCL_OP_EXPANSION_MODE 环境变量说明。

关键符号：未识别

## 关键源码片段

### `tests/special_npu/nightly_ci_ascend/run_dapo_moonlight-16b_megatron_npu.sh`

测试脚本：更新数据集路径、并行参数，添加 context_parallel_size 等新配置。

```bash
# 数据文件路径从 gsm8k 切换为 dapo-math-17k
TRAIN_FILE=$HOME/.cache/datasets/dapo-math-17k.parquet
TEST_FILE=$HOME/.cache/datasets/dapo-math-17k.parquet

# 并行参数调整（适用于双卡 NPU 集群）
COMMON_CP=${COMMON_CP:-2}    # context parallel size
COMMON_TP=${COMMON_TP:-1}    # tensor parallel size
COMMON_EP=${COMMON_EP:-2}    # expert parallel size
COMMON_ETP=${COMMON_ETP:-1}  # expert tensor parallel size

# 显式设置 context_parallel_size override（review 指出该行可能冗余且前缀 '++' 应改为 '+'）
++actor_rollout_ref.actor.megatron.override_transformer_config.context_parallel_size=${ACTOR_CP} \
++actor_rollout_ref.ref.megatron.override_transformer_config.context_parallel_size=${REF_CP} \

```

# 评论区精华

仅 gemini-code-assist[bot] 提出一条审核意见，指出测试脚本中 `++actor_rollout_ref.ref.megatron.override_transformer_config.context_parallel_size=${REF_CP}` 是冗余的（该值已在 line 171 通过 `actor_rollout_ref.ref.megatron.context_parallel_size` 设置），且错误使用了 Hydra 的 `++` 前缀（应使用 `+`）。该意见未得到作者或审查者的回复，PR 最终被批准合并。

- 测试脚本中冗余配置行及错误前缀 (correctness): 作者未回应，审查者批准合并，该问题未解决。

# 风险与影响

- 风险：
 - **Docker 构建工作流 **改为矩阵 + digest 模式需要仓库 secret（如 Quay 登录）正确配置，否则 manifest 合并阶段可能失败。
 - **测试脚本参数变更 **（数据集、并行策略）可能影响模型训练收敛性，需在 NPU 环境进行回归验证。
 - **环境变量 HCCL_OP_EXPANSION_MODE**设置为 "AIV"，可能与其他通信库或工具链冲突，若未在目标环境测试可能导致运行时错误。
 - **冗余配置行 **（review 中指出的）目前已存在于合并代码中，可能引起混淆或未来维护问题。
- 影响：
 - **影响范围**：仅限于 Ascend NPU 相关的 CI 构建、夜间测试和示例脚本。
 - **用户影响**：普通用户无影响；NPU 用户在使用新版 CANN 时需设置 HCCL_OP_EXPANSION_MODE 环境变量。
 - **团队维护**：CI 维护者需适应新的 Docker 构建模式；测试维护者需关注数据集和参数变更的正确性。
 - 风险标记：CI 构建流程重构 , 测试参数敏感 , 环境变量兼容性 , 冗余配置未清理

# 关联脉络

- PR #6085 [ci] chore: add sgl_ascend cu for NPU: 同为 NPU CI 增强，新增 sglang 的 Ascend CI 工作流，与当前 PR 的 NPU Docker 构建流水线更新同属 NPU 基础设施改进线。
- PR #6020 [ci] fix: engine_mindspeed_llm_rl_job switch to A3.: 切换 Ascend CI 至 A3 节点，与当前 PR 更新 Docker 构建（支持 A2/A3）相关。
- PR #6174 [doc] fix: fix ascend qucik start: 修正 Ascend 快速启动文档，与当前 PR 的文档更新（添加环境变量）同属一个演进路径。