model_merger 模块总览¶

源码路径：verl/model_merger/

模块定位¶

model_merger 模块的核心任务是：将分布式训练框架（FSDP / Megatron-LM）保存的分片 checkpoint 合并为标准的 HuggingFace 格式模型，使其可以直接用于推理或进一步微调。

在强化学习训练流程中，verl 使用 FSDP 或 Megatron-LM 进行分布式训练。训练过程中模型参数被切分到多个 GPU 上，保存的 checkpoint 也是分片的。如果要用 HuggingFace 的 from_pretrained 加载模型，就需要先把这些分片 checkpoint 合并成一个完整的 HuggingFace 模型。这就是 model_merger 做的事情。

模块架构¶

model_merger/
├── __init__.py               # 包初始化（仅含 license）
├── __main__.py               # CLI 入口，解析参数并调度 merger
├── base_model_merger.py      # 抽象基类 + 配置类 + 公共工具方法
├── fsdp_model_merger.py      # FSDP checkpoint 合并实现
└── megatron_model_merger.py  # Megatron-LM checkpoint 合并实现

核心流程¶

用户执行命令行
    │
    ▼
__main__.py: parse_args() → generate_config_from_args()
    │
    ├── backend == "fsdp"  →  FSDPModelMerger(config)
    │                              │
    │                              ▼
    │                      merger.merge_and_save()
    │                        1. 读取 fsdp_config.json 获取 world_size
    │                        2. 并行加载所有 rank 的分片 checkpoint
    │                        3. 根据 DTensor placement 合并张量
    │                        4. 保存为 HuggingFace 格式
    │
    └── backend == "megatron" → MegatronModelMerger(config)
                                       │
                                       ▼
                               merger.merge_and_save()
                                 1. 初始化分布式环境 + Megatron 并行组
                                 2. 构建 Megatron 模型并加载 dist checkpoint
                                 3. 参数名映射（Megatron → HuggingFace）
                                 4. 拆分 QKV / gate_up 融合张量
                                 5. 保存为 HuggingFace 格式

使用方式¶

合并 FSDP checkpoint：

python -m verl.model_merger merge \
    --backend fsdp \
    --local_dir path/to/fsdp/checkpoints \
    --target_dir path/to/output

合并 Megatron checkpoint：

python -m verl.model_merger merge \
    --backend megatron \
    --tie-word-embedding \
    --local_dir path/to/megatron/checkpoints \
    --target_dir path/to/output

大规模分布式合并（如 DeepSeek-V3 671B）：

torchrun --nproc_per_node 1 --nnodes 8 --node_rank ${RANK} \
    -m verl.model_merger merge \
    --backend megatron \
    --local_dir ./checkpoints/global_step_1/actor \
    --target_dir path/to/output

类继承关系¶

BaseModelMerger (ABC)
    ├── FSDPModelMerger        # 处理 FSDP 分片
    └── MegatronModelMerger    # 处理 Megatron 分布式 checkpoint

文件阅读顺序¶

建议按以下顺序阅读本模块的文档：

init.py - 包初始化，内容简单
main.py - CLI 入口，理解整体调度逻辑
base_model_merger.py - 抽象基类，理解公共接口和配置
fsdp_model_merger.py - FSDP 合并实现
megatron_model_merger.py - Megatron 合并实现

与其他模块的关系¶

verl/utils/ - 使用了 tokenizer、processor、device 等工具函数
verl/models/mcore/ - Megatron 合并时需要构建 Megatron Core 模型
verl/utils/megatron/ - 使用 Megatron 的分布式 checkpoint 加载工具
HuggingFace Transformers - 最终输出为 HuggingFace 格式模型