执行摘要

• 一句话：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。

# 基础镜像从 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 同步完成版本升级和文件名重命名。

# 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 文件维护线。