# PR #6294 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] refactor: Ascend docs rectification, add parameter and metrics descriptions
- 合并时间：2026-05-13 15:55
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6294

---

## 执行摘要
本 PR 为 Ascend 用户新增了一份详尽的 PPO 训练配置参数与指标说明文档，并更新了文档索引，属于纯文档变更。虽然无代码改动，但大幅提升了文档完备性，有助于用户正确配置和理解训练过程。

## 功能与动机
动机是完善 Ascend 文档，增加参数和指标描述。PR body 明确说明“Ascend docs rectification, add parameter and metrics descriptions”。新文档覆盖了 FSDP 和 Megatron 两种后端的公共与专属参数，以及训练日志中的关键指标解读，旨在降低用户配置门槛。

## 实现拆解

1. **创建参数说明文档**：在 `docs/ascend_tutorial/dev_guide/model_dev/parameter_and_metrics.md` 中编写了 880 行的完整参考，分为公共配置、FSDP 专属、Megatron 专属、Rollout 引擎配置等小节，并包含指标说明。
2. **更新文档索引**：在 `docs/index.rst` 的 toctree 中增加一行引用，使新文档在官网导航中可见。
3. **根据 review 反馈修正**：修正了 `dist_ckpt_optim_fully_reshardable` 默认值（`false` 而非 `true`），并可能补充了 `trainer.rollout_data_dir` 等参数。

### 文档内容为纯文本表格和 Markdown 列表，无需通过代码块展示。

## 评论区精华
- **gemini-code-assist[bot]**指出 `dist_ckpt_optim_fully_reshardable` 默认值描述与实现不符，属于高优先级问题。最终版本已修正。
- **Mind-s**建议添加 `trainer.rollout_data_dir` 参数说明。该建议暂未确认是否采纳。
- **wucong25**要求添加 index.rst 条目和文档更新时间，已得到满足。

## 风险与影响
- **风险**：文档参数默认值错误会误导用户；后续代码演进若不同步更新文档，将导致信息过时。
- **影响**：用户获得权威配置参考，降低错误配置概率；团队需建立文档与代码同步机制。

## 关联脉络
本 PR 属于 Ascend 文档重构系列的一部分，同系列包括 PR#6328（新增 FAQ）和 PR#6298（重构精度对齐与 Dockerfile 文档）。这些 PR 共同提升了 Ascend 用户文档的全面性与准确性。