# 在 verl 中使用 NVIDIA Nsight Systems 进行性能分析

上次更新时间：2025/06/20。

本指南将介绍如何使用 NVIDIA Nsight Systems 来分析 verl 训练运行。

## 配置

verl 中的性能分析可以通过 trainer 配置文件（`ppo_trainer.yaml` 或其他类似 `dapo_trainer.yaml` 的文件）中的多个参数进行配置：

### 先决条件

Nsight Systems 的版本很重要，请参考 `docker/Dockerfile.vllm.sglang.megatron` 文件中我们使用的版本。

### 全局性能分析控制

verl 有一个单独的控制器进程和多个工作进程。控制器进程和工作进程都可以进行性能分析。由于控制器进程可以在集群中的任何节点上执行，日志中会打印一条消息，指示控制器进程的节点主机名和进程 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`，则每一步至少占用一个数据库。此配置的目的是观察训练步之间的程序行为。

控制器节点和工作节点中的 Nsys 选项在 `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。`capture-range` 用于在何时开始和停止分析。所以 `capture-range: "cudaProfilerApi"` 是固定的，不会改变。用户可以对 `capture-range-end` 进行精确计算，或者将其留空 (`null`)。

### 工作进程性能分析

verl 管理多个 RL 角色（Roles），如 _Actor_、_Ref_、_Rollout_、_Critic_、_Reward_，这些角色在不同的 Worker 类中实现。这些 Worker 可以被组合到同一个 Ray Actor 中，运行在一个进程组里。每个 RL 角色都有自己的性能分析配置组 `profiler`，该组包含三个字段：

*   **`all_ranks` 和 `ranks`**：当 `all_ranks` 设置为 `True` 时，所有 rank 都会被分析；当设置为 `False` 时，则只分析 `ranks` 中指定的 rank。默认情况下，verl 会分析整个训练过程，为每个进程 rank 生成一系列 `worker_process_<PID>.<RID>.nsys-rep` 文件。PID 是进程 ID；RID 是捕获范围 ID。
*   **`discrete`**：当设置为 `False` 时，一个训练步中的所有角色动作将转储到同一个数据库中。当设置为 `True` 时，由 `DistProfiler.annotate` 标注的动作将被转储到离散的数据库中。在这种情况下，每个角色的动作占用一个 `<RID>`。
*   **Verl 协作模式**：Verl 可以将两个 Worker 子类合并到一个 Worker Actor 中。在这种情况下，用户应注意合并后的 Workers 具有一致的 `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 # 禁用分析
```

### 启用分析器，并在一个训练步中使用一个数据库

```yaml
    global_profiler:
        steps: [1, 2, 5]
        discrete: False
    actor_rollout_ref:
        actor:
            profiler:
                enable: True
                all_ranks: True
        # rollout & ref 沿用 actor 的设置
    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 支持多报告视图，可以同时打开多个数据库。在这种模式下，不同进程和训练步可以在同一时间线上对齐，以便更好地进行分析。