# PR #6339 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] chore: add npu advanced features
- 合并时间：2026-05-14 17:06
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6339

---

## 执行摘要

本次 PR 主要面向 Ascend NPU 用户，新增了一份详实的高级特性指南文档，并重组了现有文档目录结构。虽然 review 中发现了早期脚本文件的严重配置错误，但最终合并版本仅包含文档变更，风险可控。

## 功能与动机

正如 PR 标题所言，这是“NPU 高级特性的初步添加”。团队在持续完善 Ascend 相关文档，为用户提供更全面的参考。新增文档涵盖了推理后端（vLLM、SGLang）和训练后端（FSDP、Megatron）的高级参数配置、性能优化以及 MoE 特性，帮助用户充分发挥 NPU 能力。

## 实现拆解

1. **新增核心文档**：`npu_advance_features.md` 详细描述了 vLLM-ascend 插件、SGLang 的 ascend 内核、MindSpeed 的 Monkey Patch 机制，以及内存、计算、并行策略等优化参数。
2. **目录重组**：将 `feature` 目录下的两个文档移至 `feature_support`，使同一类素材集中存放。
3. **更新索引**：修改 `docs/index.rst` 中的 toctree，确保新文档出现在文档站点中。

### 以下截取自新增的 `npu_advance_features.md`，展示 SGLang 推理后端高级参数配置表格：

```markdown
<!-- SGLang 推理后端高级参数配置表格，说明 NPU 特有参数映射到 verl 通用参数 -->

| SGLang 参数 | verl 对应通用参数 | 功能说明 |
|:---|:---|:---|
| `attention_backend` | `actor_rollout_ref.rollout.engine_kwargs.sglang.attention_backend` | **注意力后端选择** — NPU 上应设置为 `ascend` 以调用昇腾优化内核 |
| `quantization` | `actor_rollout_ref.rollout.quantization` | **量化支持** — 支持模型量化加载与推理 |

```

## 评论区精华

代码审查机器人（gemini-code-assist[bot]）在早期脚本文件上提出了多项严重问题，但作者选择移除这些脚本，使得问题没有直接在本 PR 中解决。关键发现问题：

- **use_mbridge 错误**：脚本设置 `use_mbridge=False`，但加载 HF 权重必须为 `True`。（路径 : `run_qwen3_30b_a3b_megatron.sh`）
- **不支持的参数**：`expert_tensor_parallel_size` 和 `grad_offload` 不属于 verl 标准配置。
- **硬编码路径**：`global_profiler.save_path=/profpath` 可能导致权限问题。

这些评论均处于“未解决”状态，但最终 PR 不包含这些文件，风险得以避免。

## 风险与影响

**风险**：文档无执行风险，但 review 发现的配置错误提示团队在编写示例脚本时需严格校对 Hydra 参数。若用户自行编写类似脚本，应参考官方文档而非早期版本。

**影响**：对 Ascend 用户是积极改进，提供了久经欠缺的高级配置指引；目录重组可能使直接链接书签失效，但有利于长期维护。

## 关联脉络

本 PR 与近期多个 NPU 文档 PR 构成系列：

- PR #6337 拆分安装与快速入门
- PR #6328 新增 FAQ
- PR #6347 模型支持统计

它们共同构建了较为完整的 Ascend NPU 文档体系，方便开发者快速上手和深度调优。