# verl Profiler 系统

最后更新：2025 年 8 月 18 日。

## 架构

verl profiler 系统的架构如下所示：

![verl-profiler-arch](https://raw.githubusercontent.com/eric-haibin-lin/verl-community/2bc7ed0ba2f37f21707bfac3b241eca4b86d1bc6/docs/verl_profiler_arch.png)

有一个全局 profiler 和工具配置，用于在单个控制器级别设置一些通用配置，决定：

- `tool`: 使用哪个工具
- `steps`: 哪些步骤需要 profiling
- `save_path`: 结果保存路径

当某个工具需要对每个角色的行为进行 profiling 时，需要角色级别的配置：

- `tool`: 使用哪个工具
- `enable`: 是否启用此角色的 profiling
- rank 信息：`all_ranks` 和 `rank` 用于决定 profiling 或日志输出的 rank

对于角色级别的工具配置，需要控制一些详细的行为，例如 nsys profiler 中的 `discrete` 模式。

每个角色都有一个 profiler 配置，默认情况下，rollout/ref/reward 模型遵循 Actor 的行为。

## 添加新的 profiling 工具

新添加的 profiling 工具应尽可能复用现有 API。

1. **是否使用该工具的逻辑**：`tool == [new tool]`。
2. 将全局和本地工具配置添加到 `ppo_trainer.yaml`/`ppo_megatron_trainer.yaml` 和每个 `[role].yaml` 文件中，位于 `global_tool_config.[new tool]` 和 `tool_config.[new tool]` 下。
3. 工具配置应在 `verl/utils/profiler/config.py` 中实现，继承 `BaseConfig` 类。
4. 使用 `global_profiler.global_tool_config.[new tool]` 中的配置实现 profiling 工具的初始化逻辑，以及结果的保存逻辑（也可以保存在角色级别的 profile 中）。
5. 对于角色函数级别的 profiling，请遵循 `nvtx_profiler.py` 中 nsys profiler 的方式，实现一个继承 `DistProfiler` 的 profiler 类，并在 `verl/utils/profiler/__init__.py` 中导入新的 profiler。
6. 添加单元测试和示例，方便他人使用。