大语言模型检查点合并全攻略：从分布式碎片到完整模型的无缝转换

2026-04-15 08:25:15作者：段琳惟

引言：分布式训练后的模型整合困境

在大语言模型（LLM）训练过程中，为了应对庞大的参数量和计算需求，我们通常采用分布式训练架构。这种方式虽然显著提升了训练效率，但也带来了一个棘手的问题：训练结束后得到的是碎片化的检查点文件，而非一个完整可用的模型。这些分散在多个设备上的参数碎片，如同散落的拼图，给模型部署、推理和分析带来了极大不便。

如何将这些分布式检查点高效合并为标准格式的完整模型？Verl项目提供的检查点合并工具正是为解决这一痛点而生。本文将系统介绍检查点合并的核心技术，帮助你掌握从分布式碎片到Hugging Face格式完整模型的转换方法。

核心概念解析：分布式检查点的底层逻辑

什么是检查点合并？

检查点合并是将分布式训练过程中产生的碎片化参数文件，按照特定规则重新组合为完整模型权重的过程。这一过程不仅涉及参数的物理整合，还包括不同框架间参数名称映射、张量维度调整等关键步骤。

分布式架构的参数分片策略

目前主流的分布式训练架构主要有两种，它们的参数分片策略各有不同：

FSDP（Fully Sharded Data Parallel）：将模型参数、梯度和优化器状态按指定维度分片到多个设备，每个设备只保存部分参数。检查点文件通常命名为model_world_size_<N>_rank_<R>.pt。
Megatron-LM：采用张量并行（TP）和管道并行（PP）相结合的方式，将模型层和参数分散到不同设备。检查点通常存储在以mp_rank_为前缀的目录中。

理解这些分片策略是成功合并检查点的基础，因为不同架构需要不同的合并逻辑。

工具原理与架构：Verl检查点合并工具解析

核心工具：legacy_model_merger.py

Verl项目提供的scripts/legacy_model_merger.py是检查点合并的核心工具。该工具采用面向对象设计，通过抽象类BaseModelMerger定义了通用合并流程，并针对不同架构实现了两个子类：

FSDPModelMerger：处理FSDP架构的检查点合并
MegatronModelMerger：处理Megatron架构的检查点合并

合并流程概览

无论针对哪种架构，检查点合并都遵循以下基本流程：

检查点解析：识别检查点文件结构，确定分布式世界大小和设备配置
参数加载：并行加载所有分片文件到内存
参数映射：将分布式参数名称转换为目标格式（如Hugging Face格式）
张量合并：根据分片策略合并分散的参数张量
模型保存：将合并后的完整参数保存为标准格式

分场景实战指南：FSDP与Megatron合并详解

场景一：FSDP检查点合并

基本命令

python scripts/legacy_model_merger.py merge \
    --backend fsdp \
    --local_dir checkpoints/verl_fsdp_gsm8k_examples/qwen2_5_0b5_fsdp_saveload/global_step_1/actor \
    --target_dir /path/to/merged_hf_model

关键参数说明

--backend fsdp：指定合并后端为FSDP
--local_dir：分布式检查点所在目录
--target_dir：合并后模型的保存路径
--low_cpu_mem_usage：可选，启用低内存模式

合并原理

FSDP合并的核心在于根据DTensor（分布式张量）的placement信息重组参数。工具会先解析rank 0的状态字典获取设备网格信息，然后多线程并行加载所有分片文件，最后根据张量的分片策略（如Shard、Replicate）进行参数合并。

场景二：Megatron检查点合并

基本命令

python scripts/legacy_model_merger.py merge \
    --backend megatron \
    --tie-word-embedding \
    --local_dir checkpoints/verl_megatron_gsm8k_examples/qwen2_5_0b5_megatron_saveload/global_step_1/actor \
    --target_dir /path/to/merged_hf_model

关键参数说明

--backend megatron：指定合并后端为Megatron
--tie-word-embedding：可选，是否共享词嵌入层参数
--num-attention-heads：可选，注意力头数，用于QKV投影层合并

合并难点与解决方案

Megatron合并的主要挑战在于层名称映射和特殊参数处理：

名称映射：工具通过params_mapping字典实现Megatron到Hugging Face格式的名称转换：

self.params_mapping = {
    "embedding.word_embeddings": "model.embed_tokens",
    "self_attention.linear_qkv": "self_attn.qkv_proj",
    "self_attention.linear_proj": "self_attn.o_proj",
    # 更多参数映射...
}

QKV投影层合并：对于张量并行的QKV投影层，工具会先按TP维度拆分，再合并：

q_lst = []
k_lst = []
v_lst = []
for infer_param in tp_data:
    q, k, v = infer_param.chunk(3)
    q_lst.append(q)
    k_lst.append(k)
    v_lst.append(v)
q = torch.cat(q_lst, dim=0)
k = torch.cat(k_lst, dim=0)
v = torch.cat(v_lst, dim=0)

进阶技巧与常见问题

LoRA适配器提取

当合并包含LoRA（Low-Rank Adaptation）参数的检查点时，工具会自动检测并提取LoRA适配器，保存为标准的PEFT格式：

lora_params_names = [name for name in state_dict.keys() if "lora_" in name]
if len(lora_params_names) > 0:
    # 提取并保存LoRA参数...
    peft_config = peft.LoraConfig(**peft_dict).to_dict()

提取的LoRA适配器将保存在目标目录的lora_adapter子文件夹中。

合并后模型验证

为确保合并正确性，可使用测试模式与原始Hugging Face模型进行比对：

python scripts/legacy_model_merger.py test \
    --backend fsdp \
    --local_dir /path/to/fsdp_checkpoints \
    --test_hf_dir /path/to/original_hf_model

测试会验证参数名称、形状、数据类型及数值精度，确保合并后的模型与原始模型一致。