# PR #7563 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] refactor: reorganize ascend_tutorial into zh/en directories
- 合并时间：2026-08-28 14:52
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/7563

---

# 执行摘要

- 一句话：重组 Ascend 教程为中英目录并迁移 CI 到 a3
- 推荐动作：
 - 值得快速浏览 `zh/index.rst` 与 `en/index.rst` 的拆分方式，了解多语言文档在 Sphinx 中的组织模式。
 - 关注 CI 迁移后第一个夜间运行的 `model_ascend.yml` 是否稳定，若 a3 镜像缺失需及时回退。
 - 若团队后续维护 Ascend 文档，建议遵循 `zh/`、`en/` 目录约定，避免再次出现 `_zh/_en` 后缀冗余。

# 功能与动机

PR body 明确说明目标是让多语言文档结构更清晰：中文文档归入 zh/，英文归入 en/，去掉后缀冗余，并拆分 index.rst 为顶层 dispatcher；同时将 Ascend CI 从 910b 迁移到 a3。虽然没有关联 issue，但结合 2026Q2 Ascend roadmap（issue#5526）以及近期多笔 Ascend CI 维护提交，本次属于昇腾支持持续演进中的文档与基础设施配套整理。

# 实现拆解

1. **目录重组**：将 `docs/ascend_tutorial/` 下的中文文档整体迁移到 `zh/`，英文文档迁移到 `en/`，并删除文件名中冗余的 `_zh` / `_en` 后缀（如 `precision_alignment_zh.md` → `precision_alignment.md`）。涉及 `transfer_to_npu_guide.md`、`install_guidance.rst`、`quick_start.rst`、`gspo_optimization_practice.md` 等大量 rename，需要同步更新文件内相对链接。
2. **索引拆分**：将原 `docs/ascend_tutorial/index.rst` 改为顶层 dispatcher，新增 `zh/index.rst` 与 `en/index.rst` 分别承载中英文 toctree。`zh/index.rst` 按“快速入门、特性支持、模型支持、开发指南、FAQ 与贡献指南”组织 5 组 toctree，覆盖 20 余篇文档。
3. **标题汉化与链接对齐**：将中文文档中的英文标题替换为中文（如 `Transfer to NPU guide` → `模型迁移至 NPU 指南`），并刷新 README、index 及正文交叉引用；同时更新 root README 与 `examples/ascend_extras` 中 gspo 脚本对教程路径的外部引用。提交历史中多次出现“align cross-reference link texts”与“revert link text”修正，说明链接文本一致性是本次重组的重点检查项。
4. **CI 迁移**：将 `model_ascend.yml`、`reward_model_vllm_ascend.yml` 两个 workflow 的 `runs-on` 从 `linux-aarch64-a2b3-8` 切换到 `linux-aarch64-a3-8`，容器镜像从 `latest-vllm-910b-ubuntu` 切换为 `latest-vllm-a3-ubuntu`，使 Ascend CI 跑在 a3 新硬件上。
5. **测试与验证**：本次为纯文档与 CI 配置变更，无代码测试联动；文档侧依赖 Sphinx 构建和人工校对链接，CI 侧依赖 workflow 在合并后实际跑通验证。

关键文件：
- `docs/ascend_tutorial/index.rst`（模块 教程入口；类别 docs；类型 documentation）: 顶层导航入口，被改写为按语言分发的 dispatcher，是本次文档重组的核心。
- `docs/ascend_tutorial/zh/index.rst`（模块 中文目录；类别 docs；类型 documentation）: 新增的中文目录页，集中承载全部中文文档的 toctree，是中文读者进入教程的主入口。
- `docs/ascend_tutorial/README.md`（模块 教程首页；类别 docs；类型 deletion）: 原教程首页被整体平移至 zh/README.md，删除动作代表目录结构的迁移起点。
- `docs/ascend_tutorial/zh/README.md`（模块 教程首页；类别 docs；类型 documentation）: 承接原 README 内容并汉化章节标题，所有链接指向 zh/ 路径。
- `docs/ascend_tutorial/zh/dev_guide/model_dev/transfer_to_npu_guide.md`（模块 迁移指南；类别 docs；类型 rename-or-move）: 代表性 rename 文件，标题汉化并刷新多个交叉引用，体现重组时链接同步的细节工作。
- `.github/workflows/model_ascend.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: Ascend CI 核心 workflow，runner 与镜像从 910b 切换到 a3，属于基础设施迁移的关键配置。
- `.github/workflows/reward_model_vllm_ascend.yml`（模块 CI 工作流；类别 infra；类型 infrastructure）: reward model 的 Ascend CI 同样迁移到 a3，属于 CI 配套调整。
- `docs/ascend_tutorial/zh/get_start/install_guidance.rst`（模块 安装指南；类别 docs；类型 rename-or-move）: 用户安装入口文档，迁移到 zh/ 后更新引用文本。

关键符号：未识别

## 关键源码片段

### `.github/workflows/model_ascend.yml`

Ascend CI 核心 workflow，runner 与镜像从 910b 切换到 a3，属于基础设施迁移的关键配置。

```yaml
# 模型评测类 Ascend CI：本次将运行环境从 910b 切换到 a3 新硬件
jobs:
  model_rmpad_ascend:
    # 仅官方仓库触发该任务
    if: github.repository_owner == 'verl-project'
    # runner 从 linux-aarch64-a2b3-8 更换为 a3 系列
    runs-on: linux-aarch64-a3-8
    timeout-minutes: 60
    container:
      # 容器镜像同步切换为 a3 专用镜像
      image: swr.cn-southwest-2.myhuaweicloud.com/modelfoundry/ascend-ci/verl/verl:latest-vllm-a3-ubuntu
      options: >-
        --shm-size 16g

```

# 评论区精华

该 PR 全程没有 review 评论或讨论线程，maintainer `wucong25` 直接给予 3 次 APPROVED。从提交历史可见，合并前作者围绕链接文本做了多轮修正：例如回退 A5 安装指南链接文本（`51b5e3b`）、回退精度调试器链接文本（`28f7f51`），说明目录重组后交叉引用对齐是主要质量隐患，最终通过小步修正收敛。

- 暂无高价值评论线程

# 风险与影响

- 风险：
 - **链接失效风险**：34 个文件中有大量 rename，若 `index.rst`、README 与正文中的相对路径未同步更新，会导致 Sphinx 构建死链或导航缺失。本 PR 已通过多次 commit 修正，但合并后仍需抽查 `zh/` 与 `en/` 两个索引下的所有条目。
 - **CI 硬迁移风险**：`model_ascend.yml` 与 `reward_model_vllm_ascend.yml` 切换到 a3 runner 与镜像 `latest-vllm-a3-ubuntu` 后，若镜像标签尚未发布或 a3 资源队列不稳定，可能导致 Ascend CI 失败，需确认新镜像已在镜像仓库就绪。
 - **外部引用同步风险**：root README 与 `examples/ascend_extras` 中的 gspo 脚本引用旧教程路径，若本次未彻底刷新，外部链接会落到 404。
- 影响：
 - **用户影响**：访问 Ascend 教程的路径全部变化，已收藏旧链接的读者需跳转到新的 `zh/` 或 `en/` 目录；中文读者获得更统一的导航入口（`zh/index.rst`）。
 - **团队影响**：Ascend CI 迁移到 a3 硬件后，相关工作流将运行在新架构上，维护者需要关注 a3 上的镜像与依赖兼容性。
 - **影响范围**：主要局限于文档目录与 2 个 CI workflow，不涉及训练 / 推理运行时逻辑，对产品代码无影响。
 - 风险标记：交叉引用失效风险 , CI 硬件迁移 , 文档路径变更

# 关联脉络

- PR #7585 [ci] chore: Remove Ascend CI: 同属 Ascend CI 维护线，本 PR 迁移 runner 至 a3 后可能使部分旧 job 配置失效，二者需配合验证。
- PR #7549 [ci] chore: correct step naming for Ascend ci: 同样是 Ascend CI 工作流的稳定性维护，与本次 CI 迁移直接相关。
- PR #7584 [ci] fix: drop stale enable_chunked_prefill=False from Ascend NPU scripts: 同样涉及 Ascend CI 与脚本配置同步清理，反映 Ascend 基础设施逐步向新硬件收敛。