执行摘要

• 一句话：重组 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，属于基础设施迁移的关键配置。

# 模型评测类 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 基础设施逐步向新硬件收敛。