VeRL-Omni 是面向 diffusion 与 omni 多模态生成模型的强化学习训练框架，内置的ModelMerger工具可以把 FSDP 分布式检查点直接导出为可部署的 Diffusers pipeline 或独立 transformer，同时支持 LoRA 适配器导出与权重融合，覆盖 Qwen-Image、Flux、SD3.5、Wan2.2、LTX2、MiniMax-H3 等 8 种架构，全程自动校验、开箱即用。

为什么 FSDP 检查点无法直接部署

多卡训练时，FSDP2 会把模型权重按 rank 切片存成多个文件：

actor/ fsdp_config.json model_world_size_2_rank_0.pt model_world_size_2_rank_1.pt huggingface/config.json

这类分片权重既不能被from_pretrained()直接加载，也不能上传给推理服务——你必须先把所有 rank 的 DTensor 分片精确重组回完整权重，再打包成标准模型目录。ModelMerger 自动完成了这三件事：

1. 自动识别架构：读取model_index.json/config.json中的_class_name，失败即报错，绝不做模糊猜测；
2. 重建并回验：逐个重组 DTensor 分片，并与原始分片做往返比对，确保一个数值都不差；
3. 审计式发布：输出 SHA256 清单merge_manifest.json，Linux 上通过原子 rename 发布，不会覆盖已有目录。

一步导出：merge 命令快速上手

准备好三个互不重叠的本地目录：训练保存的 actor 检查点、与训练时同源的 base 模型、一个尚不存在的输出目录。然后执行：

python -m verl_omni.model_merger merge \ --backend fsdp \ --local_dir "$ACTOR_CHECKPOINT" \ --target_dir "$OUTPUT" \ --base_model "$BASE_PIPELINE" \ --trust-checkpoint

命令成功后会打印 JSON，包含输出目录与 manifest 路径。常用选项：

也可以直接调用 Python API（入口定义在 model_merger/init.py）：

from verl_omni.model_merger import ModelMergerConfig, merge_model result = merge_model(ModelMergerConfig( operation="merge", backend="fsdp", local_dir=checkpoint_dir, target_dir=output_dir, base_model=base_pipeline_dir, trust_checkpoint=True, ))

支持哪些架构：8 种模型全覆盖

导出器与训练算法无关——FlowGRPO、DiffusionNFT、DPO 只要保存的是完整的 transformer，就用同一个发布器。当前注册的架构见 architectures.py：

值得一提的是 MiniMax H3：导出 pipeline 时，ModelMerger 会自动完成 Diffusers 命名到原生MiniMaxH3DiTModel的 QKV/GEGLU 布局转换，并合成校验rope.inv_freq（转换逻辑见 fsdp_model_merger.py）。

LoRA 检查点：导出适配器还是融合成完整模型

LoRA 训练产物有两条导出路径：

• 默认：自动检测 LoRA 权重。LoRA-only 检查点只导出lora_adapter/（adapter_config.json+adapter_model.safetensors），无需本地 base 模型；完整检查点则按选定 layout 导出全模型，并额外附上适配器目录。
• 加--fuse-lora：把选定适配器按W + (lora_alpha / r) * B @ A融合进完整权重（fp32 计算后回写原精度），导出即部署，推理端不需要 PEFT 支持。

python -m verl_omni.model_merger merge \ --backend fsdp \ --local_dir "$LORA_ACTOR_CHECKPOINT" \ --target_dir "$OUTPUT" \ --base_model "$BASE_PIPELINE" \ --adapter-name default \ --fuse-lora \ --trust-checkpoint

融合计划会写入 manifest 的lora_fusion字段，记录适配器名、rank、alpha、缩放系数和被排除的其他适配器；计划校验逻辑在 lora.py。注意：pissa、olora等会改写 base 权重的初始化方式，必须使用完整 state 布局的检查点，LoRA-only 布局会被明确拒绝。

导出后如何验证：test 命令与 merge_manifest.json

发布前，导出器会完成四层校验：pipeline 组件与配置比对、DTensor 分片往返校验、逐 safetensors 分片重开核对值/形状/精度、输入不变性与输出索引核对。结果记录在merge_manifest.json中。

发布完成后，随时可用独立命令复核产物，无需重新加载源检查点（校验实现见 output_validation.py）：

python -m verl_omni.model_merger test \ --backend fsdp \ --test_hf_dir "$OUTPUT"

手动做加载级检查也很简单：

from diffusers import QwenImagePipeline pipeline = QwenImagePipeline.from_pretrained(output_dir, local_files_only=True)

常见问题速查

• 报错Pickled rank checkpoints require explicit trust_checkpoint=True：FSDP 检查点是 pickle 格式，必须显式加--trust-checkpoint确认你信任该文件。它不是沙箱，请只对可信产物开启。
• 只想要 transformer 组件：加--output_format transformer，此时--base_model指向 standalone transformer 目录即可。
• 目标目录已存在：导出采用原子 no-replace 发布，直接失败以保护已有产物，先移走旧输出再执行。
• 基础模型含 Python 代码（如原生 MiniMax H3、部分 Boogu 版本）：需追加--trust-remote-code才能复制这些本地资产。
• 显存/内存：rank 文件以 mmap 方式逐个重建张量，不需要驻留完整模型，但也不是硬性 RSS 上限，超大模型请预留余量。

相关文件索引 📚

VeRL-Omni ModelMerger 把"FSDP 分布式检查点 → 可部署模型"收敛成了一条命令：自动识别架构、精确重建权重、多层校验加审计清单，让训练成果真正落地部署变得简单、快速、可靠。