# PR #5871 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] chore: add npu faq doc
- 合并时间：2026-04-03 10:13
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/5871

---

# 执行摘要
本 PR 新增了 NPU（Ascend）常见问题解答文档，覆盖环境配置、调试诊断和常见错误处理，旨在提升用户使用 NPU 的便利性。review 中指出了配置准确性风险，建议使用文档时注意核对实际配置文件。

# 功能与动机
PR 作者 hustmf 在 body 中明确表示“add NPU faq”，Issue 评论中 wuxibin89 建议将文档添加到 `docs/index.rst` 索引，作者回复已添加。动机是完善 NPU 相关文档，帮助用户解决在 NPU 上执行 VERL 训练和推理时遇到的常见问题。

# 实现拆解
仅修改一个文件：`docs/ascend_tutorial/faq/faq.rst`。关键变更点：
- 更新最后修改日期为 03/26/2026。
- 添加结构化内容：
 - **环境配置问题**：如 NPU 设备不可见的解决方案（设置环境变量）。
 - **调试和诊断**：包括启用 NPU 性能分析的代码示例。
 - **常见错误信息**：列举错误如“KeyError: decoder.layers.0.self_attention.q_layernorm.weight”及其原因和解决方案。
 - **参考资料**：链接到其他 NPU 相关文档。

# 评论区精华
reviewer gemini-code-assist[bot] 在评论中强调：
> “The configuration keys provided in the documentation do not match the structure defined in the repository's configuration file (verl/trainer/config/npu_profile/npu_profile.yaml). Using incorrect configuration paths will lead to runtime errors or ignored settings.”

并给出修正建议，使用正确配置键如 `profiler.tool_config.npu.with_npu=true`。此讨论未在 PR 中直接解决，但 PR 被批准，可能待后续处理。

# 风险与影响
- **风险**：文档中 NPU profiler 配置部分（第 41 行附近）可能不准确，用户若按此设置，可能导致配置错误或性能问题。需参考实际配置文件 `verl/trainer/config/npu_profile/npu_profile.yaml`。
- **影响**：对用户，提供实用指南，降低 NPU 使用门槛；对系统无技术影响；对团队，需定期同步文档与代码变更。

# 关联脉络
从历史 PR 看，NPU 是 verl 仓库的重要支持方向，相关 PR 如：
- **PR 5864**：更新 NPU 训练脚本，与本 PR 的 FAQ 文档相辅相成。
- **PR 5824**：修复 NPU 环境设备名设置，可视为 FAQ 中环境配置问题的实践案例。
- **PR 5795**：启用 NPU expandable segment 支持，展示 NPU 功能的持续优化。
这些 PR 共同推动 NPU 生态完善，本 PR 作为文档补充，有助于用户更好地利用这些功能。