VeRL-Omni 是一个专注于多模态生成模型的强化学习训练框架，核心能力是为扩散模型（Diffusion）和全模态模型（Omni）提供稳定、快速的 RL 后训练。如果你想在社区贡献一个新模型、一套新策略梯度算法，或一个 Omni 多模态模型，本文会用通俗的语言带你走通三条集成路径——从目录结构、注册机制到冒烟测试，帮你在动手写代码前建立完整的 mental model，避免踩坑。

一、先看懂架构：三层设计决定了集成方式

VeRL-Omni 的代码组织遵循清晰的三层结构，理解它才能知道"新代码该放在哪"：

关键认知：模型与算法是正交的两个维度。一个算法可以配任意多个模型，一个模型也可以被多种算法训练。这也是为什么框架用"字符串注册表"做分发——你只需声明(架构名, 算法名)二元组，框架会自动找到对应实现。

📌 想深入理解各层职责，可参考 README.md 中的 Model and Algorithm Support 支持矩阵。

二、集成新扩散模型的完整步骤

完整文档见 integrating_a_diffusion_model.md。以 Qwen-Image 的 FlowGRPO 集成为范例，核心流程只有三步：

2.1 前置条件：上游必须先支持

• diffusers提供 transformer 与参考推理 pipeline（训练侧依赖）；
• vllm-omni提供 rollout 侧的<Name>Pipeline（采样侧依赖）。

两者缺一不可，缺少时请先向上游提 PR。

2.2 三文件 + 两处注册

新建一个包，结构固定：

verl_omni/pipelines/<你的模型>_flow_grpo/ ├── __init__.py # 导出两个适配器 ├── diffusers_training_adapter.py # 训练侧：DiffusionModelBase 子类 └── vllm_omni_rollout_adapter.py # 采样侧：VllmOmniPipelineBase 子类

然后在 verl_omni/pipelines/init.py 中加一行 star-import，让注册表在导入时"认识"你的模型。

2.3 两个适配器必须对齐的契约

• 架构字符串：必须与模型目录model_index.json中的_class_name完全一致（如"QwenImagePipeline"）；
• 调度器：默认复用 FlowMatchSDEDiscreteScheduler，保证采样与训练侧 log-prob 可比较；
• 字段命名：prompt_embeds、prompt_embeds_mask等字段名由 diffusion_agent_loop.py 原样读取，不能改名。

2.4 交付示例脚本 + 冒烟测试

• 在examples/flowgrpo_trainer/下放一个可运行启动脚本（参考 run_qwen_image_ocr_lora.sh）；
• 在tests/special_e2e/增加冒烟测试，并注册进 run_gpu_smoke_diffusion_e2e.sh。

💡 若你的模型不能被 diffusers 加载，请改走非 diffusers 路径，见 integrating_a_non_diffusers_model.md。

三、集成新策略梯度算法：四件套

完整文档见 integrating_a_new_policy_gradient_algorithm_for_diffusion_model.md。以 FlowGRPO 为参考实现，新算法需要补齐四个注册点：

1. SDE 步长公式—— 通常是给 flow_match_sde.py 增加一个sde_type分支，除非族系不同才写全新 scheduler；
2. 优势估计器—— 在 diffusion_algos.py 用@register_diffusion_adv_est(...)注册；
3. 损失函数—— 同文件用@register_diffusion_loss(...)注册，并加入DiffusionLossConfig的合法名单；
4. 每对 (架构, 算法) 一个适配器—— 复用第二节的两个适配器，装饰器里的algorithm=换成新算法名即可。

✨亮点设计：框架通过 OmegaConf 模板把四个注册点全部绑到actor_rollout_ref.model.algorithm这一个 CLI 标志上。也就是说，启动时只要传一个算法名，训练适配器、采样适配器、优势估计器、损失函数会被一次性联动选中——这是 VeRL-Omni 配置系统最优雅的地方。

如果新算法复用了现有估计器或损失（例如 MixGRPO 直接复用 FlowGRPO），有两种做法：在启动脚本中显式回指旧名字，或在diffusion_algos.py中给旧函数注册别名。

四、集成新 Omni 模型：阶段拆分是核心

完整文档见 integrating_an_omni_model.md。以 Qwen3-Omni Thinker 为运行示例，Omni 模型与扩散模型的最大区别是：它产生离散 token，且常由多阶段组成（thinker → talker → code2wav）。

4.1 先想清楚三件事

• 训练哪个阶段：RL 后训练通常只训一个自回归阶段（如 thinker），其余组件在 FSDP 包裹前剥离以省显存；
• 编码器冻结：视觉/音频编码器通常freeze_vision_tower=True；
• 算法解耦：GSPO、GRPO、RLOO 等算法通过标准 verl 配置字段选择，适配器本身与算法无关。

4.2 训练适配器：OmniModelBase 子类

需要实现的核心钩子（参考 thinker_training_adapter.py）：

• get_strip_modules：声明要在 FSDP 包裹前删除的子模块；
• configure_processor/configure_tokenizer：加载多模态处理器与分词器；
• configure_model：重定向forward、设置_no_split_modules（错名字会让整个模块被当成单叶，参数分片失效）。

4.3 Rollout 适配器：OmniRolloutPipelineBase 子类

实现build_stage_configs、rollout_flags、get_pipeline_id三个方法，参考 omni_rollout_adapter.py。部署配置 YAML 会从pipeline_name自动生成，无需手写。

4.4 注册与启动

注册同样用装饰器，架构键对应 HuggingFace config 的architectures[0]。启动时设置环境变量VERL_USE_EXTERNAL_MODULES=verl_omni，适配器会通过 Python 导入自动完成注册，不需要external_lib参数。完整示例见 run_qwen3_omni_thinker_gspo_lora_v1.sh。

五、常见陷阱：这些坑前人替你踩过

集成完成后，务必通读 common_pitfalls.md。最容易中招的几个：

• float32 精度损失：scheduler 的step()若把prev_sample截断回 bfloat16，会在第 1 步就出现ratio_mean < 1.0的系统性偏差。规则：scheduler 全程 fp32 返回 latent，rollout 适配器在 forward 前才转回模型 dtype；
• 分词一致性：数据预处理脚本的 chat template、special tokens 必须与上游_encode_prompt逐字节一致，不一致会导致奖励静默崩塌——这是最隐蔽的 bug；
• 条件跳过的编码器：FSDP2 下若某 micro-batch 跳过已分片的 tower，各 rank 的集合通信顺序会错位，最终表现为"晚来的 hang 或垃圾梯度"，需通过get_fsdp_ignored_module_names声明。

六、提交前检查清单与资源导航

📋 打开 PR 前，确认以下事项全部满足：

• 架构字符串与model_index.json::_class_name一致，algorithm=与目标算法匹配；
• verl_omni/pipelines/init.py 已 star-import 新包；
• 新配置字段同时镜像到 diffusion_rollout.yaml 与 diffusion_model.yaml；
• 示例脚本 + 数据预处理 + 冒烟测试三者齐全；
• 本地pre-commit run通过（见 CONTRIBUTING.md）。

延伸阅读速查表

💡 记住一条心法：代码即权威参考。文档描述契约，verl_omni/pipelines/ 下的现有实现（Qwen-Image、SD3、Qwen3-Omni）才是最佳模板。动手前先读一遍参考实现，能省下数天调试时间。