# veril 中的 NVIDIA Nsight Systems 性能分析

最后更新：2025/06/20。

本指南解释了如何使用 NVIDIA Nsight Systems 来分析 verl 训练运行的性能。这可以帮助开发者深入了解训练过程中的资源使用情况，如 GPU 计算、内存操作和 CPU-GPU 同步，以便优化性能。

## 配置

verl 中的性能分析可以通过训练器配置文件（如 `ppo_trainer.yaml` 或其他类似 `dapo_trainer.yaml` 的文件）中的多个参数来配置。这些配置控制何时启动分析、哪些步骤或组件被分析，以及如何保存结果。

### 先决条件

Nsight Systems 的版本很重要，请参考 `docker/Dockerfile.vllm.sglang.megatron` 来确认我们使用的版本。如果版本不匹配，可能导致分析功能失效或报告错误。

### 全局性能分析控制

verl 包含一个控制器进程（controller process）和多个工作者进程（worker processes）。这两个进程都可以被分析。由于控制器进程可以在集群中的任意节点上运行，一个日志消息会输出控制器进程的节点主机名和进程 ID，以便定位。

在 `global_profiler` 配置中，有三个新条目来控制分析器的行为：

* **`global_profiler.steps`**。这是一个步骤编号列表，用于指定在哪些步骤执行分析。例如：[1, 2, 5] 表示在步骤 1、2 和 5 进行分析。如果设置为 ``null``，则不执行任何分析。
* **`global_profiler.profile_continuous_steps`**。如果设置为 true，且 `global_profiler.discrete==False`，则将 `global_profiler.steps` 中的连续步骤合并到一个数据库中。例如，上面的步骤 1 和 2 会合并到一个数据库，而步骤 5 在另一个中。如果设置为 false，则每个步骤至少占用一个单独的数据库。这个配置的目的是观察步骤之间的程序行为变化。
* Nsight 在控制器节点和工作节点上的选项通过 `global_profiler.global_tool_config.nsys` 配置：
  * **`global_profiler.global_tool_config.nsys.controller_nsight_options`**。这个配置组适用于单个控制器进程。所有字段都会在 Ray 启动控制器进程时直接传递给 Nsight Systems（用于性能分析）。`ppo_trainer.yaml` 提供了一个可工作的示例，用户可以参考 [Nsight Systems 手册](https://docs.nvidia.com/nsight-systems/UserGuide/index.html) 和 [Ray 用户指南](https://docs.ray.io/en/latest/ray-observability/user-guides/profiling.html) 来获取更多细节。
  * **`global_profiler.global_tool_config.nsys.worker_nsight_options`**。这个配置组适用于工作者进程。类似地，所有字段都会在 Ray 启动控制进程时传递给 Nsight Systems（这里可能是笔误，原文提到“when Ray starts the controller process”，但根据上下文，应指工作者进程）。捕获范围（capture range）用于控制分析器的启动和停止时机。因此，`capture-range: "cudaProfilerApi"` 是固定不变的，用户可以根据精确计算更改 `capture-range-end`，或者保持为 `null`。

### 工作者进程性能分析

verl 管理多个强化学习（RL）角色，包括 _Actor_、_Ref_、_Rollout_、_Critic_ 和 _Reward_，这些角色由不同的 Worker 类实现。这些工作者可以组合成一个 Ray Actor，在一个进程组中运行。每个 RL 角色都有自己的性能分析配置组 `profiler`，包含三个字段：

* **`all_ranks` and `ranks`**。如果 `all_ranks` 设置为 `True`，则所有秩（ranks，通常指 GPU 或进程实例）的都会被分析；如果设置为 `False`，则只有 `ranks` 指定的秩被分析。默认情况下，verl 会为每个进程秩生成一系列命名格式为 `worker_process_<PID>.<RID>.nsys-rep` 的文件，其中 PID 是进程 ID，RID 是捕获范围 ID。
* **`discrete`**。如果设置为 `False`，则一个训练步骤中所有角色的操作会被转储到一个数据库中。如果设置为 `True`，则由 `DistProfiler.annotate` 注释的操作会被转储到离散数据库中。在这种情况下，每个角色的操作占用一个 `<RID>`。
* **verl 合并模式（collocate mode）**。verl 可以将两个 Worker 子类合并到一个 Worker Actor 中。在这种情况下，用户需要确保合并的工作者有一致的 `discrete` 设置。Nsight Systems 分析器无论如何都会使用 `torch.cuda.profiler.start()` 和 `stop()` 对来转储一个 `<step>` 数据库。

### 分析数据的保存位置

默认情况下，`*.nsys-rep` 文件保存在每个节点的 `/tmp/ray/session_latest/logs/nsight/` 目录中。根据 Ray 手册，这个默认目录无法更改。["然而，Ray 保留了默认配置中的 `--output` 选项"](https://docs.ray.io/en/latest/ray-observability/user-guides/profiling.html)。

一些用户可能觉得这不方便，但可以理解，因为 Ray 可能会启动数百个进程，如果将文件保存到一个中央位置，会对网络文件系统造成巨大压力（这意味着性能和存储挑战）。

## 用法示例

要为特定组件和步骤启用性能分析，请修改你的 `ppo_trainer.yaml`，如下所示：

### 禁用分析器

```yaml
    profiler:
        steps: null # disable profile
```

### 启用分析器，并为一个训练步骤生成一个数据库

```yaml
    global_profiler:
        steps: [1, 2, 5]
        discrete: False
    actor_rollout_ref:
        actor:
            profiler:
                enable: True
                all_ranks: True
        # rollout & ref follow actor settings
    critic:
            profiler:
                enable: True
                all_ranks: True
    reward_model:
            profiler:
                enable: True
                all_ranks: True
```

### 启用分析器，并为一个训练步骤生成多个数据库

```yaml
    profiler:
        steps: [1, 2, 5]
        discrete: True
```

## 性能分析输出

启用性能分析后，verl 会为指定的组件和步骤生成 Nsight Systems 分析报告。这些报告包括：

- CUDA 内核执行
- 内存操作
- CPU-GPU 同步
- 用于关键操作的 NVTX 标记（这些标记帮助在分析工具中可视化事件）

Nsight Systems 支持多报告视图，可以同时打开多个数据库。在这种模式下，不同的进程和步骤可以在一个时间线上对齐，便于进行更全面的分析。