# PR #7024 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] refactor: edit profiling docs of npu for usability
- 合并时间：2026-07-15 20:31
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/7024

---

# 执行摘要

- 一句话：重构 Ascend profiling 文档，添加快速开始并优化细粒度采集说明
- 推荐动作：此 PR 适合需要深入使用 Ascend profiling 功能的用户阅读，可快速掌握配置方法。但应注意 review 中提出的问题可能残留，建议在本地测试文档示例的正确性。合并者可能认为文档已足够好，但后续跟进清理遗留问题将进一步提升质量。

# 功能与动机

PR body 明确指出主要修改动机：添加快速开始案例以便用户直接使用；修改细粒度采集部分并提取常见参数设置以便用户操作。review 还指出文档存在重复和格式问题，本次重构也一并清理。

# 实现拆解

1. 在英文和中文文档开头新增快速开始章节，提供禁用采集、端到端采集、训练推理阶段分离三种场景的 YAML 配置示例和对应的命令行参数示例。
2. 重构细粒度采集部分：将 Rollout、update_policy、compute_log_prob 各阶段的公共参数（如 discrete、contents、profile_token_start/end）提取并统一说明，避免重复。
3. 补充工具列表（nsys、npu、torch、torch_memory）的简要描述，帮助用户理解各工具用途。
4. 根据 review 反馈，清理英文文档中重复的列表项、重复的 YAML 示例块和 update_policy 重复章节；修正中文文档中 bash 示例的引号问题和章节编号错误。

关键文件：
- `docs/ascend_tutorial/dev_guide/performance/ascend_profiling_en.rst`（模块 教程文档；类别 docs；类型 documentation；符号 TrainingWorker, __init__, train_mini_batch）: 英文版 Ascend profiling 文档，进行了全面重构，包括新增快速开始、细粒度采集重组和重复内容清理。
- `docs/ascend_tutorial/dev_guide/performance/ascend_profiling_zh.rst`（模块 教程文档；类别 docs；类型 documentation；符号 TrainingWorker, __init__, train_mini_batch）: 中文版 Ascend profiling 文档，同步重构，并修复 bash 示例引号和章节编号问题。

关键符号：TrainingWorker, __init__, train_mini_batch

## 关键源码片段

### `docs/ascend_tutorial/dev_guide/performance/ascend_profiling_zh.rst`

中文版 Ascend profiling 文档，同步重构，并修复 bash 示例引号和章节编号问题。

```yaml
# 中文文档新增的端到端采集 YAML 示例（带注释）
global_profiler:
    steps: [1, 2, 5]  # 采集步数：第 1、2、5 步
    save_path: ./outputs/profile  # 保存路径
actor_rollout_ref:
    actor:
        profiler:
            enable: True  # 启用训练阶段采集
            all_ranks: True  # 采集所有 Rank
            tool_config:
                npu:
                    discrete: True  # 离散模式，各阶段数据分开存储
                    contents: [npu, cpu]  # 采集 NPU 和 CPU 数据

```

# 评论区精华

在 review 中，gemini-code-assist 提出了 6 个 high-priority 评论，主要涉及：
- 英文文档全局 profiler 配置部分列表重复、快速开始 YAML 块重复、update_policy 章节重复。
- 中文文档 bash 示例中列表参数 `contents=['npu','cpu']` 缺少外层引号，会导致语法错误。
- 中文文档 compute_log_prob 部分章节编号错误（应为 4 而不是 1）。
这些评论均未收到作者回复，但 PR 最终由 wucong25 批准合并，评论状态未明确 resolved。

- 英文文档重复问题 (documentation): PR 已合并，但评论未明确 resolved，可能存在残留重复。
- 中文文档 bash 引号问题 (correctness): PR 已合并，但评论未解决；若未修复可能误导用户。
- 中文文档章节编号错误 (documentation): PR 已合并，未解决。

# 风险与影响

- 风险：文档变更本身无直接运行风险，但若 review 中指出的 bash 引号问题和章节编号错误未被修复，可能导致用户直接复制命令执行失败或混淆文档结构。建议合并前验证这些评论是否已被处理，或后续提交补丁修复。
- 影响：影响范围为所有参阅 Ascend profiling 文档的用户，降低其使用门槛，提高文档准确性；对系统行为无影响；对文档维护团队而言，重构后的结构更清晰，易于后续扩展。
- 风险标记：命令示例引号缺失 , 文档章节重复

# 关联脉络

- 暂无明显关联 PR