跳转至

verl/models 模块总览

模块简介

verl/models 是 verl 框架中负责 模型定义、并行化、权重转换和前向推理 的核心模块。它的主要目标是让各种大语言模型（LLM）和视觉语言模型（VLM）能够在分布式强化学习训练流程（如 PPO）中高效运行。

模块架构图

verl/models/
|
|-- __init__.py                    # 模块入口（仅包含 license）
|-- registry.py                    # Megatron-LM 模型注册表（旧版）
|-- weight_loader_registry.py      # 权重加载/保存注册表
|
|-- transformers/                  # HuggingFace Transformers 适配层
|   |-- __init__.py                # 导出 monkey_patch 接口
|   |-- monkey_patch.py            # ★ 核心：统一的 monkey patch 入口
|   |-- dense_common.py            # 纯文本模型的通用 forward（PPO 优化）
|   |-- llama.py                   # LLaMA 注意力层 Ulysses SP 适配
|   |-- qwen2.py                   # Qwen2 注意力层 Ulysses SP 适配
|   |-- qwen2_vl.py                # Qwen2-VL 视觉语言模型适配
|   |-- qwen3_vl.py                # Qwen3-VL 视觉语言模型适配
|   |-- glm4v.py                   # GLM-4V 视觉语言模型适配
|   |-- kimi_vl.py                 # KimiVL（DeepSeek-V3 架构）适配
|   |-- apertus.py                 # Apertus 模型注意力层适配
|   |-- tiled_mlp.py               # TiledMLP：内存高效的分片 MLP
|   |-- npu_patch.py               # 华为 NPU 专用优化补丁
|
|-- mcore/                         # Megatron-Core (mcore) 集成层
|   |-- __init__.py                # 导出核心 API
|   |-- registry.py                # ★ 核心：模型注册与工厂方法
|   |-- config_converter.py        # HF config -> mcore TransformerConfig 转换
|   |-- model_initializer.py       # 各架构模型初始化器
|   |-- model_forward.py           # 标准前向传播（thd/bshd 格式）
|   |-- model_forward_fused.py     # 融合前向传播（fused kernel）
|   |-- model_forward_1f1b_overlap.py # 1F1B 流水线重叠前向
|   |-- util.py                    # 序列打包/解包工具函数
|   |-- loader.py                  # HF 权重 -> Megatron 分片加载
|   |-- saver.py                   # Megatron 分片 -> HF 权重合并保存
|   |-- weight_converter.py        # mcore 权重名 <-> HF 权重名映射
|   |-- bridge.py                  # Megatron-Bridge 集成（新版）
|   |-- mbridge.py                 # mbridge 集成（轻量版）
|   |-- patch.py                   # mcore MLA 等 bug 修补
|   |-- mtp_patch.py               # Multi-Token Prediction (MTP) 补丁
|   |-- qwen2_5_vl/               # Qwen2.5-VL 的 mcore 视觉模型实现
|
|-- llama/megatron/                # LLaMA 的旧版 Megatron 并行实现
|   |-- modeling_llama_megatron.py # 并行 LLaMA 模型定义
|   |-- layers/                    # 并行层组件
|   |-- checkpoint_utils/          # 权重加载/保存工具
|
|-- qwen2/megatron/                # Qwen2 的旧版 Megatron 并行实现
|   |-- modeling_qwen2_megatron.py # 并行 Qwen2 模型定义
|   |-- layers/                    # 并行层组件
|   |-- checkpoint_utils/          # 权重加载/保存工具

两条并行化路线

verl 中存在两条并行化路线，理解这一点非常重要：

路线 1：HuggingFace Transformers + FSDP/Ulysses（推荐新用户）

  • 使用 transformers/ 子模块
  • 通过 monkey patch 替换模型的注意力层和前向函数
  • 支持 Ulysses 序列并行、融合 kernel、TiledMLP 等优化
  • 适用于 FSDP2 训练

路线 2：Megatron-Core (mcore)

  • 使用 mcore/ 子模块
  • 将 HuggingFace 配置转换为 Megatron 原生配置
  • 使用 Megatron 原生的张量并行 (TP)、流水线并行 (PP)、上下文并行 (CP)、专家并行 (EP)
  • 适用于超大规模训练

路线 3：旧版 Megatron（已弃用）

  • llama/megatron/ 和 qwen2/megatron/ 子模块
  • 手动实现张量并行的 LLaMA/Qwen2 层
  • 逐步被 mcore 路线取代

推荐阅读顺序

  1. 本文档（你正在读的）-- 建立全局认识
  2. transformers/monkey_patch.py -- 理解 monkey patch 机制
  3. transformers/dense_common.py -- 理解 PPO 前向传播
  4. transformers/llama.py 或 transformers/qwen2.py -- 理解 Ulysses 序列并行
  5. mcore/registry.py -- 理解 mcore 模型注册
  6. mcore/config_converter.py -- 理解配置转换
  7. mcore/model_forward.py -- 理解 mcore 前向传播
  8. mcore/util.py -- 理解序列打包/解包

关键概念速查

概念 解释
Monkey Patch 在运行时替换模型的方法，无需修改原始代码
Ulysses SP DeepSpeed-Ulysses 序列并行，通过 AlltoAll 通信在注意力头和序列维度之间交换数据
Fused Kernel 将多个运算融合为一个 GPU kernel，减少显存和计算开销
TiledMLP 将 MLP 的输入分块计算，降低显存峰值
THD 格式 Token-Head-Dimension，即序列打包格式，去除 padding
BSHD 格式 Batch-Sequence-Head-Dimension，标准批处理格式
mcore Megatron-Core，NVIDIA 的分布式训练核心库
PPO Proximal Policy Optimization，强化学习算法
MTP Multi-Token Prediction，多 token 预测