执行摘要

• 一句话：扫描 758 个外部链接，修复 15 类失效链接（16 个文档文件）
• 推荐动作：该 PR 无代码，不值得精读源码，但建议文档维护者通读 PR body——它演示了一种高质量的外链维护方式：全量扫描、根因分类、逐条验证、对“不可盲改”的链接显式留待决策。值得关注的设计决策是作者对 dapo.md 中语义相关的链接保持克制、没有机械替换。建议跟进 Needs decision 列表，把 5 类遗留问题转成 issue 或在下一个文档清理 PR 中处理；长期看可为仓库引入 CI 链接检查（如 lychee）以遏制同类问题复发。

功能与动机

PR body 开篇即说明：“Scanned all 758 external URLs across docs/ and fixed 15 categories of broken links whose new locations were confirmed (16 files). Every replacement URL has been verified with HTTP 200.” 失效根因多样且具典型性：上游文档持续重组（Ray 把 direct-transport 页面移入 direct-transport/ 子目录、vLLM optimization 文档搬迁到 configuration/optimization/、sglang 把 docs_new/ 改名 docs/、vLLM Grafana dashboard 移入 observability/）；仓库内文件移动与改名（Dockerfile.rocm 移入 docker/rocm/、verl/utils/reward_score/math.py 改名 math_reward.py、run_sft_engine_gsm8k.sh 改名 run_sft_engine.sh）；外部分支合并删除（uni-agent 的 rlinsight 分支已并入 main）。文档中的失效外链会直接误导读者（例如按旧路径找不到 Dockerfile 无法构建镜像、SFT 脚本改名后旧链接 404），因此需要系统性清理。

实现拆解

整个变更是一条纯文档清理流水线，按以下步骤展开：

1. 全量审计与根因分类：扫描 docs/ 下全部 758 个外部 URL，按失效原因归为 15 类可修复链接与 5 类“需维护者决策”的链接。这一步的关键产出是分类方法——把“上游重组”“文件改名”“分支删除”“拼写错误”分开处理，避免一刀切替换。
2. 逐类确认新位置并替换：对每一类先确认目标 URL 的准确新位置，再统一替换，且每个替换链接都通过 HTTP 200 验证。主要替换动作如下表：

1. 区分“可修复”与“需决策”：对没有直接替代的失效链接（verl-data 实验日志 7 处、aoshen524 fork 图片 4 处引用、作者个人站点、recipe/dapo 分支 2 处、ubecc about 页）不盲改，逐项列出候选方案（重新上传 / 指向最近资源 / 删除链接 / 重写 FAQ）等维护者拍板。
2. 验证与配套：无源码、测试或配置改动；替换链接全部通过 HTTP 200 验证，文档内部路径（install.rst 与 multinode.rst 的 Dockerfile 引用）保持一致。

关键文件：

• docs/workers/model_engine.rst（模块 引擎文档；类别 docs；类型 documentation）: SFT 测试脚本链接由 run_sft_engine_gsm8k.sh 更新为改名后的 run_sft_engine.sh，反映仓库内测试脚本更名，是文档与代码同步的典型场景。
• docs/start/install.rst（模块 安装部署；类别 docs；类型 documentation）: AMD ROCm 相关 3 处引用（链接、正文、bash 构建命令）同步 Dockerfile.rocm 移入 docker/rocm/ 的新路径，是本次唯一涉及多上下文一致性的修复。
• docs/ascend_tutorial/zh/model_support/examples/ascend_vllm_best_practices.rst（模块 昇腾教程；类别 docs；类型 documentation）: 修复指向不存在 commit 且文件名拼写错误的 doclink，是本次最有代表性的历史引用清理案例。
• docs/ascend_tutorial/zh/dev_guide/model_dev/transfer_to_npu_guide.md（模块 昇腾教程；类别 docs；类型 documentation）: sglang 文档链接从 docs_new/docs/basic_usage 更新为 docs/docs/basic_usage，反映上游目录改名，对 NPU 迁移指南的可用性很重要。
• docs/advance/grafana_prometheus.md（模块 进阶文档；类别 docs；类型 documentation）: 两处 vLLM Grafana dashboard JSON 链接随上游目录重组从 online_serving/ 移到 observability/。
• docs/data/transfer_queue.md（模块 数据文档；类别 docs；类型 documentation）: 同一文件包含两处不同根因的修复：Ray docs 页面重组进子目录并切换文档版本；TransferQueue 教程目录重编号（05 → 06）。
• docs/start/multinode.rst（模块 安装部署；类别 docs；类型 documentation）: slurm 示例脚本中的 DOCKERFILE 变量同步为 docker/rocm/Dockerfile.rocm，与 install.rst 形成跨文件一致性。
• docs/algo/dapo.md（模块 算法文档；类别 docs；类型 documentation）: 首页 Code 链接更新为扁平化后的 verl-recipe 路径；但 FAQ 中两处 recipe/dapo 分支引用因涉及语义未被盲改，是本次修复克制性的代表。
• docs/advance/fully_async.md（模块 进阶文档；类别 docs；类型 documentation）: verl 官方文档站页面迁移：Rollout Importance Sampling 从 advance/rollout_is.html 移至 algo/rollout_corr.html。
• docs/advance/rl_insight.md（模块 进阶文档；类别 docs；类型 documentation）: uni-agent 仓库链接由已合并删除的 rlinsight 分支更新为 main 分支，属于分支生命周期类修复。
• docs/ascend_tutorial/zh/get_start/quick_start.rst（模块 昇腾教程；类别 docs；类型 documentation）: sgl-kernel-npu 仓库将中文 README 合并进主 README，链接从 README_CN.md 更新为 README.md。
• docs/examples/ppo_code_architecture.rst（模块 示例文档；类别 docs；类型 documentation）: verl/utils/reward_score/math.py 改名 math_reward.py 后的链接同步。
• docs/low_precision/fp8.md（模块 低精度文档；类别 docs；类型 documentation）: verl-recipe 仓库中 low_precision 由文件变为顶层目录，链接改为 tree URL。
• docs/perf/device_tuning.rst（模块 性能文档；类别 docs；类型 documentation）: 修复示例脚本链接中的文件名拼写错误（qwen2-14b → qwen2_14b），属于历史链接纠错。
• docs/perf/perf_tuning.rst（模块 性能文档；类别 docs；类型 documentation）: vLLM 官方文档重组后 optimization 页面移到 configuration/optimization/，新页面仍覆盖 Preemption 与 Chunked Prefill 主题。
• docs/preparation/reward_function.rst（模块 准备文档；类别 docs；类型 documentation）: 与 ppo_code_architecture.rst 同源的 math.py → math_reward.py 改名链接同步。

关键符号：未识别

关键源码片段

docs/start/install.rst

AMD ROCm 相关 3 处引用（链接、正文、bash 构建命令）同步 Dockerfile.rocm 移入 docker/rocm/ 的新路径，是本次唯一涉及多上下文一致性的修复。

Find the docker for AMD ROCm: `docker/rocm/Dockerfile.rocm <https://github.com/verl-project/verl/blob/main/docker/rocm/Dockerfile.rocm>`_
​
.. code-block:: bash
​
   # Build the docker in the repo dir:
   # docker build -f docker/rocm/Dockerfile.rocm -t verl-rocm:03.04.2015 .
​
.. 修复说明（本注释为分析辅助，不参与渲染）：
   本次共同步 4 处引用。除了上面的链接与构建命令，install.rst 正文第 167 行附近
   和 multinode.rst 的 slurm 示例脚本（第 582 行）也把 docker/Dockerfile.rocm
   改为 docker/rocm/Dockerfile.rocm，因为该文件已移入 docker/rocm/ 子目录。
   若不同步更新，读者按文档执行 docker build 会直接得到文件不存在的错误。

评论区精华

该 PR 没有 review 评论，wuxibin89 直接 APPROVED（评论为空）。实质性的“讨论”发生在 PR 正文的 Needs decision 部分——作者把无法直接替换的失效链接显式列出并给出候选方案。最有价值的判断是作者没有机械替换 docs/algo/dapo.md 第 173/175 行：

“lines 173/175 of the same file reference the same URL but involve the semantics of the now-missing recipe/dapo branch, so they were not blindly changed”

这说明“链接修复也要尊重内容语义”。另外两处被明确标注的失效场景：

“the experiments branch still exists, but these bsz64_*-lorarank32-score*.log files were deleted”
“the entire aoshen524/verl fork repository has been deleted”

五个待决策项合计 15 处失效引用，作者均未擅动，全部留待维护者决策。

• verl-data 实验日志文件被删除（7 处链接） (question): 作者给出 3 个选项（请作者重新上传 / 链接最接近的现存实验日志 / 移除对比链接），等待维护者决策，本次未改动。
• aoshen524 fork 仓库整体删除导致 3 张图片失效 (question): 提出两个选项（在 verl 仓库或官方数据仓库重新托管图片 / 重新截图），未解决。
• dapo.md FAQ 中 recipe/dapo 分支引用未盲改 (question): 需重写或删除该 FAQ 条目，或恢复历史分支后更新链接，未解决。
• 作者个人站点与 about 页 404 (question): 可改为链接到 GitHub 主页、站点根路径或直接移除作者链接，未解决。

风险与影响

• 风险：
  1) 外部依赖持续漂移：本次替换的链接虽已 HTTP 200 验证，但 Ray、vLLM、sglang、TransferQueue 等上游文档仍在快速重组，同类问题会持续复发；仓库当前没有 CI 链接检查机制兜底，此 PR 是一次性清理而非长效机制。
  2) 遗留失效链接：5 类共 15 处链接（7 个 verl-data 实验日志、4 张 multinode.rst 图片引用、dapo.md 2 处、ray_debug_tutorial.rst 与 sglang_worker.rst 各 1 处作者链接）仍然 404，读者会继续踩坑，且其中 docs/algo/dapo.md 的 FAQ 条目本身语义已过时。
  3) docs/start/multinode.rst 中的图片链接来自已删除的 fork 仓库，视觉效果缺失。
  4) 无任何编码变更，不存在回归、性能或安全问题。
  • 影响：影响范围严格限定在文档层：16 个文档文件中 20 处链接恢复可用，覆盖安装（docs/start/install.rst、multinode.rst）、NPU 迁移（ascend_tutorial 下 4 个文件）、性能调优（device_tuning.rst、perf_tuning.rst）、算法（dapo.md）、数据（transfer_queue.md）、监控（grafana_prometheus.md）、RL-Insight（rl_insight.md）等主要阅读路径，社区用户按文档上手时的 404 中断明显减少。对运行时、API、配置零影响；对团队的收益是文档健康度提升，且 PR body 本身提供了一套可复用的外部链接审计模板（全量扫描 → 按根因分类 → HTTP 200 验证 → 不可修复项单独列出），后续清理可直接照搬。
  • 风险标记：纯文档变更, 外部文档持续漂移, 遗留 15 处失效链接待决策, 无 CI 链接检查兜底

关联脉络

• PR #7563 [doc] refactor: reorganize ascend_tutorial into zh/en directories: 该 PR 将 ascend_tutorial 重组为 zh/en 双目录；本 PR 修复的 ascend_vllm_best_practices.rst 与 transfer_to_npu_guide.md 均位于重组后的 zh 目录下，链接指向与目录重组直接相关。
• PR #7448 [tool] feat: Forward Agent Loop telemetry to RL-Insight: 该 PR 新增 docs/advance/rl_insight.md 并引入 uni-agent 的 rlinsight 分支链接；本 PR 将其修正为合并后的 main 分支。
• PR #7461 [training_utils, env, doc] feat: use Liger fused linear PPO kernel: 该 PR 更新了 docs/perf/perf_tuning.rst；本 PR 修复同一文件中的 vLLM optimization 文档链接。
• PR #7627 [misc] feat: uv support aarch64: 该 PR 改动 docs/start/install.rst 与 docker 相关文件，与本 PR 的 install.rst Dockerfile 路径修复处于同一文档区域，反映文档需持续跟随仓库结构变化。