执行摘要

本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作为文档补充，有助于用户更好地利用这些功能。