verl/utils 模块总览
模块简介
verl/utils/ 是 verl 框架的工具模块，提供了从设备管理、分布式训练、数据处理到性能分析等方方面面的基础设施。它是整个 verl 框架的"底座"，被上层的 trainer、worker、model 等模块广泛依赖。
目录结构
verl/utils/
├── __init__.py # 模块入口，导出核心工具
├── activation_offload.py # 激活值 CPU 卸载（节省 GPU 显存）
├── attention_utils.py # 注意力计算工具（CUDA/NPU 统一接口）
├── chat_template.py # 聊天模板处理（提取 system prompt 等）
├── config.py # 配置管理（OmegaConf → dataclass 转换与校验）
├── device.py # 设备抽象层（CUDA / NPU / CPU 统一）
├── distributed.py # 分布式训练工具（进程组初始化等）
├── flops_counter.py # 浮点运算量估算
├── fs.py # 文件系统工具（HDFS / 本地文件操作）
├── fsdp_utils.py # FSDP 分布式训练工具（模型加载/卸载/LoRA）
├── groupwise.py # 分组统计（均值/标准差）
├── hdfs_io.py # HDFS 文件 IO
├── import_utils.py # 动态导入与可选依赖检查
├── logging_utils.py # 日志工具
├── megatron_peft_utils.py # Megatron + PEFT/LoRA 适配
├── megatron_utils.py # Megatron 模型转换工具（HF ↔ Megatron）
├── memory_utils.py # 显存管理与可视化
├── model.py # 模型创建工具
├── net_utils.py # 网络工具（端口查找等）
├── npu_flash_attn_utils.py # NPU FlashAttention 适配
├── py_functional.py # Python 通用函数式工具
├── ray_utils.py # Ray 分布式计算工具
├── rollout_skip.py # Rollout 跳过策略
├── rollout_trace.py # Rollout 追踪日志
├── seqlen_balancing.py # 序列长度负载均衡（Karmarkar-Karp 算法）
├── tensordict_utils.py # TensorDict 操作工具
├── tokenizer.py # Tokenizer 加载与处理
├── torch_dtypes.py # PyTorch 数据类型工具
├── torch_functional.py # 核心 Torch 函数（log-prob、LR 调度器等）
├── tracking.py # 实验追踪（WandB / MLflow / TensorBoard 等）
├── transformers_compat.py # Transformers 库版本兼容
├── ulysses.py # Ulysses 序列并行（DeepSpeed）
│
├── checkpoint/ # 检查点管理子模块
│ ├── __init__.py
│ ├── checkpoint_manager.py # 基础检查点管理器
│ ├── checkpoint_handler.py # 检查点保存/加载处理器
│ ├── fsdp_checkpoint_manager.py # FSDP 检查点管理
│ └── megatron_checkpoint_manager.py # Megatron 检查点管理
│
├── dataset/ # 数据集子模块
│ ├── __init__.py
│ ├── rl_dataset.py # RLHF 数据集
│ ├── rm_dataset.py # 奖励模型数据集
│ ├── dataset_utils.py # 数据集工具（Collator 等）
│ ├── vision_utils.py # 多模态视觉处理
│ └── multiturn_sft_dataset.py # 多轮对话 SFT 数据集
│
├── megatron/ # Megatron 并行训练子模块
│ ├── __init__.py
│ ├── optimizer.py # Megatron 优化器
│ ├── sequence_parallel.py # 序列并行
│ ├── pipeline_parallel.py # 流水线并行
│ ├── tensor_parallel.py # 张量并行
│ ├── memory.py # 内存管理
│ ├── dist_checkpointing.py # 分布式检查点
│ ├── router_replay_patch.py # MoE 路由重放补丁
│ └── router_replay_utils.py # MoE 路由重放工具
│
├── profiler/ # 性能分析子模块
│ ├── __init__.py
│ ├── config.py # 分析器配置
│ ├── profile.py # 分布式分析器核心
│ ├── nvtx_profile.py # NVTX 标记（NVIDIA GPU）
│ ├── mstx_profile.py # MSTX 标记（华为 NPU）
│ ├── torch_profile.py # PyTorch 分析器
│ ├── performance.py # 性能指标（计时、显存日志）
│ └── empty_annotations.py # 空标记实现（fallback）
│
└── kernel/ # 高性能内核子模块
├── __init__.py
├── linear_cross_entropy.py # 线性交叉熵（融合 kernel）
├── kernels.py # Triton 内核实现
└── fp8_kernel.py # FP8 量化内核
模块分类导航
第一层：基础设施（建议首先阅读）
第二层：分布式与并行
第三层：数据与模型
第四层：训练辅助
第五层：其他工具
子模块文档
推荐阅读顺序
- 先读本文档了解全局结构
- 从
device.py 开始，理解设备抽象
- 阅读
config.py 了解配置管理
- 阅读
distributed.py 和 fsdp_utils.py 了解分布式训练基础
- 阅读
torch_functional.py 了解核心计算
- 根据你的兴趣，深入特定子模块（checkpoint / dataset / megatron / profiler / kernel）