# PR #6966 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] feat: add installation instructions for Atlas 950DT A5
- 合并时间：2026-07-07 17:16
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6966

---

# 执行摘要

- 一句话：添加 Atlas 950DT A5 安装指南
- 推荐动作：如果您使用 Atlas 950DT A5 硬件，此文档是必需参考，建议仔细阅读并按步骤操作。同时，审阅中提到的 vllm-ascend 安装改进建议值得在后续文档版本中补齐，以提高用户一次性成功率。该 PR 本身设计上采用独立文档 + 索引链接的模式，适合作为后续其他硬件指南的参考。

# 功能与动机

PR 正文明确指出需要为 Atlas 950DT A5 平台提供安装指南，帮助用户快速搭建开发环境，包括所需的软件版本、依赖和环境设置步骤。

# 实现拆解

纯文档变更，分为三步：
1. **新建独立指南 `install_guidance_A5.rst`**：在 `docs/ascend_tutorial/get_start/` 下创建完整安装说明，包含依赖版本表格和两种后端（vLLM、MindSpeed-LLM）的安装命令。
2. **更新主安装指南 `install_guidance.rst`**：在硬件型号列表中添加一行指向新文档的 RST 链接，采用相对路径 `install_guidance_A5.rst` 而非绝对 URL。
3. **更新文档索引 `index.rst`**：在 `toctree` 指令中增加 `get_start/install_guidance_A5` 条目，使该页面出现在侧栏目录中。

关键文件：
- `docs/ascend_tutorial/get_start/install_guidance_A5.rst`（模块 文档；类别 docs；类型 documentation）: 新增的核心安装指南，包含所有依赖版本表格和安装命令，是 PR 的主要价值所在。
- `docs/ascend_tutorial/get_start/install_guidance.rst`（模块 文档；类别 docs；类型 documentation）: 主安装指南页面，添加了 Atlas 950DT A5 的链接行，是用户导航到新文档的入口。
- `docs/ascend_tutorial/index.rst`（模块 文档；类别 docs；类型 documentation）: 文档根索引，将新文档加入 toctree 使其出现在侧边栏。

关键符号：未识别


# 评论区精华

自动化审阅工具 `gemini-code-assist[bot]` 提出两个高优先级改进建议：
- **链接相对路径**：在 `install_guidance.rst` 中使用相对路径代替硬编码的 GitHub URL，以保证本地构建和 Fork 下的链接正确性。最终代码已采纳此建议。
- **vllm-ascend 安装步骤不完整**：缺少与 vLLM `v0.20.2` 对应的分支检出、子模块初始化和 `--no-build-isolation` 选项，可能导致编译失败。最终代码未体现这些改进，因此该问题在文档中仍然存在。
审查者 `wucong25` 最终批准了 PR。

- 链接使用相对路径 (documentation): 已采纳，最终代码中使用 `install_guidance_A5.rst` 相对路径。
- vllm-ascend 安装步骤不完整 (documentation): 未完全采纳，最终文档中未补充这些步骤，该问题仍存在。

# 风险与影响

- 风险：技术风险较低，因为纯文档变更。潜在风险包括：
 - **版本过时**：依赖版本号固定，若后续软件更新但文档未同步，用户按指南安装可能遇到不兼容。
 - **安装步骤可复现性**：vLLM-Ascend 安装缺少分支检出和子模块初始化，不保证在所有环境下成功。
 - **链接断裂**：虽然已用相对路径，但未来文件移动可能导致断链。
 - 影响：**用户影响**：对 Atlas 950DT A5 用户有直接帮助，提供了从零搭建的完整指南，降低了使用门槛。
**系统影响**：无代码变更，不影响已有功能。
**团队影响**：文档维护者需关注版本更新，确保指南长期有效。

- 风险标记：版本过时风险 , 安装步骤不完整

# 关联脉络

- PR #6929 [fully_async] feat: Adapt vLLM >=0.18 and vLLM < 0.19 for Ascend NPU: 均涉及 Ascend NPU 上的 vLLM 配置，本 PR 的安装指南中 vLLM-Ascend 版本与该补丁适配相关。