# PR #7338 完整报告

- 仓库：`verl-project/verl`
- 标题：[ci] chore: Update npu docker image cann version
- 合并时间：2026-08-10 20:18
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/7338

---

# 执行摘要

- 一句话：Ascend Docker 镜像 CANN 升级至 9.1.0 并同步 CI 与文档
- 推荐动作：该 PR 适合快速浏览，作为版本升级时对 CI 文件名联动影响的参考案例。值得关注的是：Dockerfile 重命名必须同步更新工作流中所有路径引用（触发过滤、grep 解析、build-push 参数），这是一个容易遗漏的联动点；建议维护者后续在 CHANGELOG 或发布说明中提示外部用户迁移文件路径。

# 功能与动机

PR body 中直接说明 'Update docker image cann version 9.1.0'，目的是跟随 CANN 工具链迭代，保证 NPU 训练环境与新版驱动 / 库兼容。结合历史 PR，项目正在系统性推进 Ascend 版本升级（CANN 9.0.1 → 9.1.0、torch 2.9 → 2.10、vLLM 0.18 → 0.23），本 PR 是该演进线的一部分。

# 实现拆解

1. **重命名 Dockerfile 并升级基础镜像**：将 `docker/ascend/Dockerfile.ascend_9.0.0_a2` 和 `Dockerfile.ascend_9.0.0_a3` 重命名为 `Dockerfile.ascend_9.1.0_a2` / `a3`，同时把 FROM 行从 `cann:9.0.1` 改为 `cann:9.1.0`，并将 LD_LIBRARY_PATH 中的 `/usr/local/Ascend/cann-9.0.0` 改为 `/usr/local/Ascend/cann-9.1.0`，使库路径与镜像实际目录一致。
2. **更新 GitHub Actions 工作流**：修改 `.github/workflows/docker-build-ascend-a2.yml` 和 `a3.yml` 中三处引用——push 触发器 `paths` 过滤条件、基础镜像 tag 提取脚本中 `grep '^FROM'` 的文件路径、`docker/build-push-action` 的 `file` 参数，全部指向新的 9.1.0 Dockerfile，确保重命名后自动构建仍然生效。
3. **同步更新文档**：重写 `docs/ascend_tutorial/get_start/dockerfile_build_guidance.rst` 中的版本清单（CANN 9.0.0 → 9.1.0，torch/torch_npu 升至 2.10/2.9，vLLM 0.18 → 0.23 等），更新 Dockerfile 参考链接和最后更新日期，避免用户因文档滞后而引用旧文件名。
4. **无源码与测试改动**：本次变更全部落在 Dockerfile、CI 配置和文档，没有引入算法、训练器或 rollout 逻辑变化，属于纯部署链路维护。

关键文件：
- `docker/ascend/Dockerfile.ascend_9.1.0_a2`（模块 镜像构建；类别 infra；类型 rename-or-move）: CANN 基础镜像升级到 9.1.0 的核心文件，FROM 行与 LD_LIBRARY_PATH 路径同步版本号，文件名从 9.0.0 重命名为 9.1.0。
- `docker/ascend/Dockerfile.ascend_9.1.0_a3`（模块 镜像构建；类别 infra；类型 rename-or-move）: A3 设备对应的 CANN 9.1.0 镜像构建文件，与 a2 同步完成版本升级和文件名重命名。
- `.github/workflows/docker-build-ascend-a2.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: 工作流中三处 Dockerfile 路径引用同步更新，确保重命名后镜像构建仍能触发和执行。
- `.github/workflows/docker-build-ascend-a3.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: A3 工作流与 a2 工作流对称更新，保持两条构建链路行为一致。
- `docs/ascend_tutorial/get_start/dockerfile_build_guidance.rst`（模块 文档说明；类别 docs；类型 documentation）: 用户构建 Ascend 镜像的入口文档，同步更新版本清单，避免用户使用旧版路径和版本信息。

关键符号：未识别

## 关键源码片段

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

CANN 基础镜像升级到 9.1.0 的核心文件，FROM 行与 LD_LIBRARY_PATH 路径同步版本号，文件名从 9.0.0 重命名为 9.1.0。

```dockerfile
# 基础镜像从 CANN 9.0.1 升级到 9.1.0，Dockerfile 文件名同步重命名
FROM swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0-910b-ubuntu22.04-py3.12
ARG SOC_VERSION="ascend910b1"

# 后续 RUN 中按 CPU 架构设置 CANN 库路径，版本号必须与镜像内部目录保持一致
RUN export PIP_EXTRA_INDEX_URL=https://triton-ascend.osinfra.cn/pypi/simple/ && \
    ARCH=$(uname -m) && \
    if [ "$ARCH" = "aarch64" ]; then \
        export LD_LIBRARY_PATH=/usr/local/Ascend/cann-9.1.0/aarch64-linux/devlib/linux/aarch64:$LD_LIBRARY_PATH; \
    elif [ "$ARCH" = "x86_64" ]; then \
        export LD_LIBRARY_PATH=/usr/local/Ascend/cann-9.1.0/x86_64-linux/devlib/linux/x86_64/:$LD_LIBRARY_PATH; \
    fi && \
    source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
    source /usr/local/Ascend/nnal/atb/set_env.sh

```

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

A3 设备对应的 CANN 9.1.0 镜像构建文件，与 a2 同步完成版本升级和文件名重命名。

```dockerfile
# A3 设备基础镜像同步升级到 CANN 9.1.0
FROM swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0-a3-ubuntu22.04-py3.12
ARG SOC_VERSION="ascend910_9392"

# 与 a2 版本一致，LD_LIBRARY_PATH 目录从 cann-9.0.0 改为 cann-9.1.0
RUN export PIP_EXTRA_INDEX_URL=https://triton-ascend.osinfra.cn/pypi/simple/ && \
    ARCH=$(uname -m) && \
    if [ "$ARCH" = "aarch64" ]; then \
        export LD_LIBRARY_PATH=/usr/local/Ascend/cann-9.1.0/aarch64-linux/devlib/linux/aarch64:$LD_LIBRARY_PATH; \
    elif [ "$ARCH" = "x86_64" ]; then \
        export LD_LIBRARY_PATH=/usr/local/Ascend/cann-9.1.0/x86_64-linux/devlib/linux/x86_64/:$LD_LIBRARY_PATH; \
    fi && \
    source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
    source /usr/local/Ascend/nnal/atb/set_env.sh

```

# 评论区精华

无实质 review 讨论。该 PR 的唯一审核者 wucong25 直接 APPROVED，未留下任何评论，说明改动在维护者看来是常规、低风险的版本升级操作，没有出现设计分歧或未解决问题的讨论。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险主要集中在镜像构建链路：
 - **基础镜像可用性**：`swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0-910b-ubuntu22.04-py3.12` 等相关 tag 必须真实存在，否则工作流在拉取 FROM 时会直接失败。
 - **路径版本一致性**：Dockerfile 中 LD_LIBRARY_PATH 硬编码了 `cann-9.1.0`，若 CANN 9.1.0 镜像内部目录不是该名称，运行时会出现库找不到的问题；a2/a3 各架构分支都依赖这个假设。
 - **Dockerfile 重命名的外部影响**：仓库内工作流已同步更新，但任何外部脚本或流水线若仍引用 `Dockerfile.ascend_9.0.0_a2/a3` 都会失效，需要额外迁移成本。
 - **CI 触发盲区**：工作流 `paths` 过滤条件改为只监听新文件名，未来若继续修改旧版本 v0.8.0 Dockerfile，则不会触发镜像构建，可能造成旧版本镜像失去维护。
 - **缺乏测试覆盖**：本 PR 没有配套 CI 冒烟测试来验证新 CANN 版本下 NPU 训练 / 推理能正常执行。
- 影响：影响范围集中在 Ascend/NPU 用户与 CI 基础设施：
 - 对项目内 CI：docker 镜像构建工作流将基于 CANN 9.1.0 产出新镜像，后续 NPU 相关测试（如 nightly_ascend）会默认使用新版本环境。
 - 对用户：自行基于 Dockerfile 构建镜像的用户必须改用新文件名，并确认所依赖的 torch/vLLM 版本与 CANN 9.1.0 兼容。
 - 对文档：版本清单与参考链接更新，减少了用户误用旧文件名的可能。
 - 整体影响程度中等，属于常规依赖升级，不影响训练 / 推理算法逻辑。
 - 风险标记：基础镜像版本升级 , Dockerfile 重命名 , CI 触发路径变更 , 无测试覆盖

# 关联脉络

- PR #7268 [ci] chore: Update python&cann version, delete non-existent file: 同一批 Ascend Dockerfile 的版本升级，之前将 CANN 版本推进到 9.0.1，本 PR 继续升到 9.1.0，属于同一条版本演进线。
- PR #7238 [doc] feat: Update vllm/vllm-ascend and torch version: 同期升级 vLLM/torch 版本，与本 PR 共同构成 NPU 镜像工具链版本更新矩阵。
- PR #7311 [ci] chore: Fix docker image upload: 修复同一 docker-build-ascend 工作流的镜像标签上传逻辑，本 PR 继续修改这些工作流的构建文件引用。
- PR #7305 [ci] chore: Update npu docker build file: 同样在调整 docker-build-ascend-a2/a3 的缓存 scope 与临时 tag，属于同一 CI 文件维护线。