# PR #6298 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] refactor: ascend doc refactor of precision guide and dockerfile build guidance
- 合并时间：2026-05-12 16:52
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6298

---

# 执行摘要

- 一句话：重构 Ascend 精度对齐文档和 Dockerfile 构建指南
- 推荐动作：建议 NPU 用户和文档维护者详细阅读精度对齐指南和 Dockerfile 构建指南，特别是容器启动模板的挂载路径和参数使用的准确性。该 PR 作为文档基础设施的改进，值得参考其组织方式。

# 功能与动机

提供完整的 Ascend NPU 精度对齐指导，帮助用户在 NPU 上复现 GPU 训练精度并排查精度问题；更新 Dockerfile 构建文档以匹配最新依赖版本和最佳实践，降低用户搭建环境门槛。

# 实现拆解

1. **新增精度对齐指南 **（`precision_alignment_zh.md`）：从环境与权重对齐、输入数据对齐、配置对齐、固定确定性、训练验证、推理验证到 dump 对比，完整覆盖精度对齐工作流。详细阐述了 HCCL/LCCL 通信下确定性环境变量设置、rollout 打桩和回放验证方法。
2. **迁移并更新 Dockerfile 构建指南 **（`dockerfile_build_guidance.rst`）：从 `quick_start` 目录移至 `get_start` 目录，更新依赖版本表（vLLM->0.18.0, Torch->2.9.0, SGLang->0.5.10 等），新增容器启动命令模板、容器管理说明（start/exec），并强调镜像为参考样例。
3. **更新文档索引 **（`index.rst`）：添加新增的精度对齐文档路径，调整 dockerfile 构建指南路径，删除旧的 precision_debugger.md 索引（已移至新位置）。
4. **配套 CI 脚本更新 **（`run_gspo_qwen3_30b_megatron_npu.sh`）：在 rollout 配置中增加 `calculate_log_probs=True` 参数，确保在 GSPO 训练中正确计算 log probability。

关键文件：
- `docs/ascend_tutorial/dev_guide/precision_analysis/precision_alignment_zh.md`（模块 精度指南；类别 docs；类型 documentation）: 新增的精度对齐指南，是本次文档重构的核心内容，详细描述了 NPU 与 GPU 精度对齐的全流程方法。
- `docs/ascend_tutorial/get_start/dockerfile_build_guidance.rst`（模块 构建指南；类别 docs；类型 rename-or-move）: 重命名并大幅更新，包含依赖版本升级和容器管理新内容，是 Ascend 用户构建环境的关键参考。
- `tests/special_npu/nightly_ci_ascend/run_gspo_qwen3_30b_megatron_npu.sh`（模块 测试脚本；类别 test；类型 test-coverage）: NPU nightly CI 测试脚本，添加了 calculate_log_probs 配置，确保 rollout 阶段正确计算 log probability。
- `docs/index.rst`（模块 文档索引；类别 docs；类型 documentation）: 更新文档索引以反映新增和调整的文档路径，保证文档结构一致性。
- `docs/ascend_tutorial/dev_guide/precision_analysis/precision_debugger_zh.md`（模块 调试工具；类别 docs；类型 rename-or-move）: 文件重命名，从 profiling 目录移至 precision_analysis 目录，无内容变化。

关键符号：未识别


# 评论区精华

- **@gemini-code-assist[bot]**指出 Dockerfile 构建指南中挂载 `/usr/local/sbin`、`/usr/sbin` 等主机系统目录进入容器会导致二进制不兼容，建议仅挂载 Ascend 驱动和固件路径。（`dockerfile_build_guidance.rst` 第 107 行）
- **@gemini-code-assist[bot]**指出精度对齐指南中使用 `actor_rollout_ref.rollout.skip_dump_dir` 参数疑似拼写错误，应使用 `load_path`，且末尾反斜杠可能引发 shell 语法错误。（`precision_alignment_zh.md` 第 104 行）
- **@wucong25**审核并批准了该 PR。

- 容器挂载系统目录风险 (security): PR 合并时未修改，建议后续文档更新中修正或增加警告。
- 参数 skip_dump_dir 可能拼写错误 (correctness): PR 合并时保持原状，用户需注意实际参数名称。

# 风险与影响

- 风险：文档中使用的参数 `skip_dump_dir` 可能是拼写错误，建议用户根据实际版本使用 `load_path`；容器启动模板中挂载系统目录存在安全隐患和兼容性风险，应在后续文档中更正或新增警告。测试脚本新增一行配置，影响 CI 的正确性，但经过验证无误。
- 影响：对 Ascend NPU 用户提供了一站式精度对齐指南，降低排查难度；Dockerfile 构建指南更新使得用户更容易获取最新环境；文档结构调整提升了可维护性。
- 风险标记：参数错误风险 , 容器挂载风险

# 关联脉络

- PR #6291 [doc] chore: update vllm and vllm ascend from 0.13.0 to 0.18.0 in docs and dockerfile: 本 PR 的 Dockerfile 构建指南依赖此 PR 中的版本更新，作者建议先合并 #6291。