# PR #6328 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] refactor: Ascend docs rectification, add new FAQ questions
- 合并时间：2026-05-13 15:57
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6328

---

# 执行摘要

- 一句话：更新 Ascend FAQ 文档，新增权重传输与非共享存储问题
- 推荐动作：建议 Ascend 用户阅读此 FAQ 更新，尤其是分布式训练中遇到相关错误时。对于文档维护者，可参考其问题描述和解决方案的清晰度。整体变更简单直接，无需深入代码审查。

# 功能与动机

根据 PR 描述 'Ascend docs rectification, add new FAQ questions'，旨在补充用户在实际部署中遇到的高频问题及解决指导，提升文档实用性与用户支持效率。

# 实现拆解

仅涉及一个文档文件的更新：`docs/ascend_tutorial/faq/faq.rst`。

1. **更新最后修改日期**：从 03/26/2026 改为 05/13/2026。
2. **新增 Q3**：针对权重传输 bucket 溢出断言错误，详细说明了问题现象、权重大小计算方法、具体解决方案（通过 `update_weights_bucket_megabytes` 参数调节 bucket 大小）、参数值选择建议（计算、向上取整、预留余量、注意内存限制）以及常见模型的推荐 bucket 大小表格。
3. **新增 Q4**：针对非共享存储环境下 checkpoint 加载时找不到 `common.pt`、`.metadata`、`metadata.json` 的问题，分析了原因（元数据文件仅保存在执行保存操作的节点），并提供了手动复制元数据文件的临时解决方案及注意事项。

关键文件：
- `docs/ascend_tutorial/faq/faq.rst`（模块 文档；类别 docs；类型 documentation）: 唯一变更文件，新增两个 FAQ 问题和解决方案，影响所有阅读 Ascend 文档的用户。

关键符号：未识别


# 评论区精华

该 PR 未触发实质性的审核讨论。`gemini-code-assist[bot]` 自动评论确认无反馈问题，`wucong25` 直接批准合并。未发现未解决的疑虑或争议。

- 整体审核 (other): 无修改必要

# 风险与影响

- 风险：作为纯文档变更，无代码或配置修改，对系统运行无风险。文档内容描述准确，但 bucket 大小推荐值需用户自行校验，若有误仍可能误导用户。若用户未遵循推荐仍可能遇到 OOM 或传输失败，但文档已给出注意事项，风险极低。
- 影响：直接影响阅读 Ascend NPU 文档的用户，尤其是遇到权重传输报错或非共享存储 checkpoint 加载失败的用户，可快速找到解决方案。对系统无影响，对团队维护成本无增加。
- 风险标记：文档变更，无实质风险

# 关联脉络

- PR #6298 [doc] refactor: ascend doc refactor of precision guide and dockerfile build guidance: 同为 Ascend 文档改进，FAQ 是对此前文档重构的补充，展示了对文档体系的持续完善。