# PR #6017 完整报告

- 仓库：`verl-project/verl`
- 标题：[fsdp] feat: qwen3.5 modify npu docker file based on CANN 8.5.2
- 合并时间：2026-04-16 20:39
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6017

---

# 执行摘要

- 一句话：为 Qwen3.5 模型升级 Ascend NPU Docker 镜像至 CANN 8.5.2 版本。
- 推荐动作：此 PR 主要涉及基础设施更新，变更相对直接，适合快速浏览以了解 CANN 版本升级的配置细节。建议关注 Dockerfile 中 CANN 安装和路径设置的实现方式，以及 review 中讨论的架构兼容性修复，这些对构建可靠的多架构镜像有参考价值。

# 功能与动机

根据 PR 标题和 body 描述，此变更旨在为 Qwen3.5 模型提供基于 CANN 8.5.2 的 Docker 镜像，以支持 FSDP 后端训练。虽然没有直接关联的 Issue，但从上下文推断，升级 CANN 版本可能为了获得性能改进、新特性支持或 bug 修复，确保训练环境与最新硬件驱动和软件栈保持同步。

# 实现拆解

1. **升级 Dockerfile 中的 CANN 版本**：修改 `docker/ascend/Dockerfile.ascend_8.5.2_a3_qwen3-5`，从 CANN 8.5.1 升级到 8.5.2。关键变更包括：下载并安装 CANN 8.5.2 的 toolkit、A3-ops 和 nnal 组件，并更新 `LD_LIBRARY_PATH` 环境变量指向新版本路径。
2. **同步 CI 工作流配置**：更新 `.github/workflows/docker-build-ascend-a3-qwen3_5.yml`，将 Dockerfile 引用从 `Dockerfile.ascend_8.5.1_a3_qwen3-5` 改为 `Dockerfile.ascend_8.5.2_a3_qwen3-5`，并相应调整生成的镜像标签版本号。
3. **修复 review 中发现的构建问题**：根据 gemini-code-assist[bot] 的评论，修复了硬编码架构路径、vLLM 版本标签错误和 Python 包版本不匹配等问题，确保 Docker 镜像能在多架构（aarch64/x86_64）上正确构建。

关键文件：
- `docker/ascend/Dockerfile.ascend_8.5.2_a3_qwen3-5`（模块 Docker 镜像；类别 infra；类型 rename-or-move）: 核心变更文件，定义了基于 CANN 8.5.2 的 Qwen3.5 Docker 镜像构建步骤，包括 CANN 升级、环境变量设置和依赖安装。
- `.github/workflows/docker-build-ascend-a3-qwen3_5.yml`（模块 CI 流水线；类别 infra；类型 infrastructure）: CI 工作流文件，更新了 Dockerfile 引用和镜像标签，确保新镜像能被自动构建和推送。

关键符号：未识别


## 关键源码片段

### `docker/ascend/Dockerfile.ascend_8.5.2_a3_qwen3-5`

核心变更文件，定义了基于 CANN 8.5.2 的 Qwen3.5 Docker 镜像构建步骤，包括 CANN 升级、环境变量设置和依赖安装。

```dockerfile
# 升级 CANN 到 8.5.2 并设置环境变量
RUN set -e && \
    cd /tmp && \
    # 下载并安装 CANN 8.5.2 toolkit（应根据 ARCH 变量选择 aarch64 或 x86_64 版本）
    wget -v --no-check-certificate https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.2/Ascend-cann-toolkit_8.5.2_linux-aarch64.run && \
    bash Ascend-cann-toolkit_8.5.2_linux-aarch64.run --quiet --install && \
    rm -f Ascend-cann-toolkit_8.5.2_linux-aarch64.run && \
    # 类似地安装 A3-ops 和 nnal 组件
    wget -v --no-check-certificate https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.2/Ascend-cann-A3-ops_8.5.2_linux-aarch64.run && \
    bash Ascend-cann-A3-ops_8.5.2_linux-aarch64.run --quiet --install && \
    rm -f Ascend-cann-A3-ops_8.5.2_linux-aarch64.run && \
    source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
    wget -v --no-check-certificate https://ascend-repo.obs.cn-east-2.myhuaweicloud.com/CANN/CANN%208.5.2/Ascend-cann-nnal_8.5.2_linux-aarch64.run && \
    bash Ascend-cann-nnal_8.5.2_linux-aarch64.run --quiet --install && \
    rm -f Ascend-cann-nnal_8.5.2_linux-aarch64.run && \
    source /usr/local/Ascend/cann/set_env.sh && \
    rm -rf /tmp/*

# 根据架构设置 LD_LIBRARY_PATH，指向 CANN 8.5.2 库路径
RUN ARCH=$(uname -m) && \
    if [ "$ARCH" = "aarch64" ]; then \
        export LD_LIBRARY_PATH=/usr/local/Ascend/cann-8.5.2/aarch64-linux/devlib/linux/aarch64:$LD_LIBRARY_PATH; \
    elif [ "$ARCH" = "x86_64" ]; then \
        export LD_LIBRARY_PATH=/usr/local/Ascend/cann-8.5.2/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 中 gemini-code-assist[bot] 指出了多个关键构建问题：
- **架构兼容性问题**：Dockerfile 中硬编码下载 aarch64 架构的 CANN 安装包，但文件逻辑支持 x86_64，导致跨架构构建失败。建议使用 `ARCH` 变量动态选择安装包。
- **vLLM 版本错误**：引用了不存在的 vLLM 分支 `v0.18.0`（实际版本约为 v0.7.x），会导致 `git clone` 失败。
- **版本不一致**：`LD_LIBRARY_PATH` 仍指向 CANN 8.5.1，与安装的 8.5.2 版本不匹配，可能引发运行时链接错误。
- **Python 包版本不匹配**：指定的 torch、accelerate 等版本（如 torch==2.9.0）与官方版本不符，可能导致安装失败。
作者 ruanhao566 回复“已修复”，表明这些问题在提交前已解决，但未在讨论中详细说明修复细节。

- Dockerfile 构建问题修复 (correctness): 作者 ruanhao566 回复“已修复”，但未提供细节；问题应在提交前解决。

# 风险与影响

- 风险：1. **构建失败风险**：如果 review 中指出的问题（如架构路径、版本标签）未完全修复，Docker 镜像构建可能在 CI 或本地环境中失败。
2. **运行时兼容性风险**：升级 CANN 版本可能引入不兼容的 API 变化，影响基于该镜像的 FSDP 训练任务，需验证新镜像与现有训练脚本的兼容性。
3. **多架构支持风险**：Dockerfile 中涉及架构判断的逻辑（如 `LD_LIBRARY_PATH` 设置）若处理不当，可能导致在 x86_64 主机上运行时库路径错误。
4. **依赖版本冲突风险**：Python 包版本（如 torch）若指定不当，可能与其他依赖产生冲突，影响训练稳定性。
- 影响：1. **对用户的影响**：使用 Qwen3.5 模型进行 Ascend NPU FSDP 训练的用户将获得基于 CANN 8.5.2 的更新 Docker 环境，可能带来性能提升或 bug 修复，但需重新拉取镜像并验证兼容性。
2. **对系统的影响**：CI 工作流将构建并推送新标签的镜像，旧镜像（基于 CANN 8.5.1）可能逐渐被替代，影响依赖旧版本的流水线。
3. **对团队的影响**：基础设施团队需维护多版本 Dockerfile，增加了版本管理复杂度；训练团队需测试新镜像以确保训练任务不受影响。
- 风险标记：构建失败风险 , 版本兼容性风险 , 多架构支持风险

# 关联脉络

- PR #5991 [fsdp] feat: qwen3.5 add npu docker file: 相关 PR 5991 新增了 Qwen3.5 的 NPU Docker 镜像（基于 CANN 8.5.1），本 PR 在此基础上升级到 CANN 8.5.2，属于同一功能线的版本迭代。
- PR #6021 [ci] chore: add sglang new version docker for NPU: 相关 PR 6021 也涉及 Ascend NPU 的 Docker 镜像更新，展示了仓库中基础设施升级的常见模式，可参考其 CI 和版本管理实践。