# PR #6399 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] chore: Update Ascend Docker build guidance
- 合并时间：2026-05-19 19:49
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6399

---

# 执行摘要

- 一句话：更新 Ascend Docker 构建文档以匹配最新文件
- 推荐动作：该 PR 为积极响应社区反馈的文档改进，建议合并。未来可考虑自动化脚本验证文档中列出的 Dockerfile 列表与目录实际文件一致，防止再次出现遗漏。

# 功能与动机

根据 Issue #6369 中用户提出的 7 条改进建议，对 Ascend Dockerfile 构建指南进行文档修正和同步更新，以解决指引模糊、信息遗漏、版本排序不合理等问题。

# 实现拆解

1. **澄清公开镜像来源**：在 " 镜像获取 & 公开镜像地址 " 段落中，将 " 基于上述 Dockerfile 构建 " 明确为 " 基于下方“Dockerfile 构建镜像脚本清单”中列出的 Dockerfile 构建 "，并新增内部锚点 `.. _ascend-dockerfile-list:` 便于交叉引用。
2. **修正表头与补全 Dockerfile 条目**：将表格列名从 " 基础镜像版本 " 改为 "CANN 基础镜像版本 "；根据 `docker/ascend` 目录下实际存在的 14 个文件，补全了缺失的 Dockerfile 条目，包括多个 8.5.1/8.5.2 版本和 Qwen3-5 专用文件，并正确标注了混合版本的 CANN 基镜像（如 `8.5.1 + 8.5.2组件`）。
3. **优化排序与更新示例**：在每个设备类型（A2/A3）和推理后端（vLLM/SGLang）分组内，将较新的 Dockerfile 放在前面（如 8.5.0 优先于 8.3.RC1）；将 " 镜像构建命令示例 " 和 " 容器启动命令模板 " 中的示例镜像版本从 8.3.RC1 更新为 8.5.0。
4. **统一术语与格式**：将所有 "VLLM" 修正为 "vLLM"；在容器名称、镜像名等位置添加 `{}` 占位符标记（如 `{your_docker_name}`、`{image_name:tag}`），明确提示用户需替换。
5. **添加本地镜像查看命令**：在 " 镜像构建命令示例 " 之后新增 `docker images` 指令，方便用户验证本地构建的镜像。

关键文件：
- `docs/ascend_tutorial/get_start/dockerfile_build_guidance.rst`（模块 文档；类别 docs；类型 documentation）: 唯一变更文件，全面重写了 Ascend Docker 构建指南，涉及公开镜像说明、Dockerfile 清单、构建示例、容器启动命令等所有章节。

关键符号：未识别


# 评论区精华

该 PR 没有产生 Review 讨论，仅有一个自动 Bot 评论和一个批准（来自 wucong25）。

- 暂无高价值评论线程

# 风险与影响

- 风险：作为纯文档变更，技术风险极低。但需确保文档中列出的 Dockerfile 路径和链接与 `docker/ascend` 目录下的实际文件保持同步，避免因未来新增或删除文件导致文档过时。
- 影响：对用户：改进了 Ascend 平台用户构建 Docker 镜像的指引清晰度和准确性，降低了新手用户的困惑。对系统：无影响。对团队：需要维护文档与 `docker/ascend` 目录的实际文件列表一致。
- 风险标记：纯文档变更，无技术风险

# 关联脉络

- 暂无明显关联 PR