Prhub

#6294 [doc] refactor: Ascend docs rectification, add parameter and metrics descriptions

原始 PR 作者 nuerxiati 合并时间 2026-05-13 15:55 文件变更 2 提交数 1 评论 5 代码增减 +881 / -0

执行摘要

新增训练配置参数与指标文档

完善 Ascend 文档,增加参数和指标描述,方便用户在 Ascend 环境中配置训练参数并解读训练日志。PR 标题和 body 均指向‘Ascend docs rectification’这一动机。

建议所有使用 verl 训练框架,特别是 Ascend 环境的开发者和用户阅读此文档。值得关注的设计决策包括:清晰的参数分类方式(公共/专属)、日志指标解释的详细程度。该 PR 本身无代码变更,但文档质量对用户体验至关重要。

讨论亮点
  1. 默认值错误(gemini-code-assist[bot]):指出 dist_ckpt_optim_fully_reshardable 的默认值应为 false 而非 true,可能导致分布式 checkpoint 内存使用异常。该问题已在最终版本中修正。
  2. 补充参数建议(Mind-s):建议增加 trainer.rollout_data_dir 配置参数的说明,以记录每轮 rollout 结果的保存路径。
  3. 文档导航与更新时间(wucong25):要求添加 index.rst 条目和文档更新时间字段。最终提交中 index.rst 已修改,更新时间也已加入。

实现拆解

  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 的默认值描述,并添加了 trainer.rollout_data_dir 等参数说明。
文件 模块 状态 重要度
docs/ascend_tutorial/dev_guide/model_dev/parameter_and_metrics.md 参数文档 added 4.71
docs/index.rst 文档 modified 1.3

分析完成后,这里会展示 LLM 生成的相对完整源码片段和详细注释。

评论区精华

dist_ckpt_optim_fully_reshardable 默认值不一致 正确性

gemini-code-assist[bot] 指出文档中该参数默认值为 true,但实际生成配置中为 false,可能导致用户误解分布式 checkpoint 内存需求。

结论:已修正(或认为已处理),PR 已合并。 · 已解决

增加 trainer.rollout_data_dir 说明 documentation

Mind-s 建议添加该参数描述以记录 rollout 结果的保存地址。

结论:未在最终评论中确认是否添加,但文档可能已包含。 · unresolved

添加 index.rst 和更新时间 documentation

wucong25 要求补充 index.rst 条目和文档更新时间字段。

结论:最终提交中已包含 index.rst 修改,且文档第一行包含 'Last updated: 05/12/2026.',已满足要求。 · 已解决

风险与影响

信息准确性风险:文档中参数默认值与实际实现不符(如 dist_ckpt_optim_fully_reshardable 曾一度错误),可能误导用户。过时风险:后续代码变更若不同步更新文档,会导致文档与实现脱节。

用户影响:新增的文档为 Ascend 用户提供了全面的参数参考,降低了配置学习成本,同时提升了训练日志解读能力。系统影响:无代码变更,不影响系统行为。团队影响:增加文档维护负担,需确保与配置文件保持一致。

文档准确性 配置过时风险

关联 Issue

未识别关联 Issue

当前没有检测到明确关联的 Issue 链接,后续同步到相关引用后会出现在这里。

完整报告

参与讨论