# verl Profiler 系统

最后更新：08/18/2025。

## 架构

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

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

系统包含一个全局 profiler 和工具配置，用于在单个控制器层面设置一些通用配置，这些配置决定了：

- `tool`：使用哪种工具
- `steps`：分析哪些步骤
- `save_path`：结果保存路径

当某些工具需要分析每个角色的行为时，需要角色级别的配置：

- `tool`：使用哪种工具
- `enable`：是否在此角色上启用 profiling
- rank 信息：`all_ranks` 和 `rank` 用于决定分析或输出日志的哪一 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. 添加单元测试和示例，以便他人方便使用。