# PR #6826 完整报告

- 仓库：`verl-project/verl`
- 标题：[doc] chore: modify the profiling documentation of ascend
- 合并时间：2026-06-24 14:45
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6826

---

# 执行摘要

- 一句话：更新 Ascend 性能分析文档，配置示例由 YAML 改为 Bash 命令格式
- 推荐动作：纯文档更新，无需深度精读。开发者可关注本 PR 中配置示例格式的演变，了解 verl 项目对 Ascend 平台配置方式的偏好变化。

# 功能与动机

PR body 中说明为 'modify the profiling documentation of ascend'，旨在更新 Ascend 平台性能分析的使用文档，使配置示例更贴近实际命令行操作方式，提升用户参考体验。

# 实现拆解

1. **修改英文文档 **(`ascend_profiling_en.rst`)：将全部配置示例从 YAML 转换为 Bash 键 = 值格式，调整参数描述（如 analysis 参数从 'Enables automatic data parsing' 改为 'Whether to enable automatic data parsing'），并增加行内注释。
2. **修改中文文档 **(`ascend_profiling_zh.rst`)：同步英文修改，并调整章节标题“离散模式采集”为“训练和推理阶段分离”。
3. **统一格式**：两文档均删除了 YAML 示例，统一为 Bash 格式，对 `['npu','cpu']` 等数组值已使用双引号包裹，防止 Shell 解析错误。

关键文件：
- `docs/ascend_tutorial/dev_guide/performance/ascend_profiling_en.rst`（模块 文档；类别 docs；类型 documentation）: 核心文件，更新了英文版 profiling 配置示例与参数描述，并调整章节结构。
- `docs/ascend_tutorial/dev_guide/performance/ascend_profiling_zh.rst`（模块 文档；类别 docs；类型 documentation）: 同步英文文档修改，更新中文版配置示例，并调整章节标题为更清晰的表述。

关键符号：未识别

## 关键源码片段

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

核心文件，更新了英文版 profiling 配置示例与参数描述，并调整章节结构。

```bash
# End-to-End collection example
global_profiler.tool=npu
global_profiler.steps="[1, 2, 5]"  # Number of steps to be collected
global_profiler.save_path=./outputs/profile
actor_rollout_ref.actor.profiler.enable=True
actor_rollout_ref.actor.profiler.all_ranks=False
actor_rollout_ref.actor.profiler.ranks="[0]"  # Only collect rank 0 data
actor_rollout_ref.actor.profiler.tool_config.npu.discrete=True  # Recommended discrete mode
actor_rollout_ref.actor.profiler.tool_config.npu.contents="['npu','cpu']"  # Control collection list
actor_rollout_ref.actor.profiler.tool_config.npu.level=level1
actor_rollout_ref.actor.profiler.tool_config.npu.analysis=False  # Disable automatic data parsing

```

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

同步英文文档修改，更新中文版配置示例，并调整章节标题为更清晰的表述。

```bash
# 端到端采集示例
global_profiler.tool=npu
global_profiler.steps="[1, 2, 5]"  # 采集步数
global_profiler.save_path=./outputs/profile
actor_rollout_ref.actor.profiler.enable=True
actor_rollout_ref.actor.profiler.all_ranks=False
actor_rollout_ref.actor.profiler.ranks="[0]"  # 只采集 rank 0 数据
actor_rollout_ref.actor.profiler.tool_config.npu.discrete=True  # 推荐使用离散模式
actor_rollout_ref.actor.profiler.tool_config.npu.contents="['npu','cpu']"  # 控制采集列表
actor_rollout_ref.actor.profiler.tool_config.npu.level=level1
actor_rollout_ref.actor.profiler.tool_config.npu.analysis=False  # 禁用自动数据解析

```

# 评论区精华

Review 中存在两类核心讨论：
- **Bash 语法正确性**：gemini-code-assist 两次指出 `['npu','cpu']` 在 Bash 中缺少双引号可能触发模式匹配错误，建议添加双引号。该建议已被采纳，最终代码中已修正。
- **示例格式保留**：beirong8kmiles 建议保留原有 YAML 示例并补充日常使用配置（如轻量化推理采集）。该建议未被采纳，最终版本仅保留 Bash 格式。另有关于“端到端采集应补充推理阶段采集”的建议，但未在代码中体现。

 - Bash 中数组字符串需要用双引号包裹 (correctness): 最终代码已为 contents 参数添加双引号，问题已解决。
 - 建议保留 YAML 配置示例 (design): 最终版本删除了 YAML 示例，仅保留 Bash 格式，建议未被采纳。
 - 端到端采集应补充推理阶段采集 (question): 最终版本未补充推理阶段采集示例，仅保留原有配置框架。

# 风险与影响

- 风险：配置示例从 YAML 改为 Bash 后，若用户直接复制，需注意 Bash 中数组字符串（如 ['npu','cpu']）需用双引号包裹防止 Shell 解析错误。当前文档已使用双引号，风险较低。此外，文档删除了 YAML 示例，对习惯 YAML 配置的用户可能造成不便，但整体影响可控。未涉及任何代码逻辑变更，无回归风险。
- 影响：影响范围仅限于 Ascend 平台的文档用户，不涉及任何代码逻辑变更。用户可通过更新后的文档更便捷地使用命令行配置 profiler，降低学习成本。但需注意示例仅覆盖部分配置，未涵盖所有场景。
- 风险标记：配置示例 Bash 语法准确性 , 缺少 YAML 示例兼容性

# 关联脉络

- 暂无明显关联 PR