# PR #6924 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] chore: update ascend Retool/DAPO/GSPO best practice version compatibility
- 合并时间：2026-07-03 17:55
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6924

---

## 执行摘要
本 PR 更新了 Ascend 平台的三份最佳实践文档（Retool、DAPO 多模型、GSPO）中的软件版本要求，与 CANN 9.0.0、PyTorch 2.9.0、vLLM 0.18.0 等最新稳定版本对齐。同时将 verl 引用指向 main 分支。改动均为文档层面，无代码变更。

## 功能与动机
PR 旨在解决文档中软件版本与实际验证通过版本不一致的问题。PR body 明确说明更新了 CANN、Python、PyTorch、torch_npu、vLLM、vLLM-Ascend 和 triton_ascend 的版本要求，确保用户能基于正确的环境复现实验。

## 实现拆解

1. **Retool 文档 (`ascend_retool_best_pratice.rst`)**: 重构了软件版本表，从旧版列表式改为带表头的 list-table，版本号全面升级（例如 CANN 8.3.RC1 → 9.0.0.B160，Python >=3.10,<3.12 → 3.11），verl 从指定 commit 改为 `main` 分支。
2. **DAPO 文档 (`dapo_multi_model_optimization_practice.md`)**: 同步更新版本表，将 Quickstart 链接指向新的 commit，并将 `VLLM_VERSION` 环境变量从 0.13.0 改为 0.18.0。
3. **GSPO 文档 (`gspo_optimization_practice.md`)**: 类似更新版本表，verl 引用从指定 commit 改为 `main`，并新增警告建议使用 `release/v0.8.0` 分支以保证稳定。
4. **遗留问题**: 在 DAPO 和 GSPO 文档中，文本建议切换到指定 commit ID，但 git 命令仍为 `git checkout main`，存在矛盾。

### 以下为 Retool 文档中更新后的版本要求表（使用 RST 格式）：
```rst
.. 软件版本要求表（更新后）
.. list-table::
   :header-rows: 1

   * - software
     - version
   * - Python
     - ``3.11``
   * - CANN
     - ``==9.0.0.B160`` (CANN900B160)
   * - torch
     - ``==2.9.0``
   * - torch_npu
     - ``==2.9.0``
   * - triton_ascend
     - ``==3.2.1``
   * - verl
     - ``main``
   * - vllm
     - ``v0.18.0``
   * - vllm-ascend
     - ``v0.18.0``
   * - transformers
     - ``5.3.0``

```

## 评论区精华
reviewer gemini-code-assist[bot] 在 DAPO 和 GSPO 文档中均指出了同一个问题：文档说明应使用指定 commit ID 以保证稳定性，但提供的命令却是 `git checkout main`。例如在 DAPO 文档中，reviewer 建议将命令改为 `git checkout 9d05508f5e3bd8ecb70cf94ab10dc087b57a716d`。该建议未被采纳，PR 即被合并。

## 风险与影响
- **风险**: 两个文档中存在文字与命令矛盾，可能误导用户；版本信息虽已更新但未经验证，若环境变化可能导致过时。
- **影响**: 主要影响 Ascend 平台用户，提供更准确的版本指导，降低环境配置错误率。但遗留的不一致可能造成混淆。

## 关联脉络
- PR #6890 引入了 GSPO 最佳实践文档，本 PR 对其版本信息进行了更新。
- PR #6900 重构了 Ascend Quickstart 文档，本 PR 中 DAPO 文档的 Quickstart 链接也同步指向了 #6900 后的最新 commit。