verl 多模态 RL 训练实战指南基于 Geo3K 的 GRPO 图像推理训练全流程【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verlverlHybridFlow现已原生支持多模态强化学习训练可对视觉语言模型VLM执行 GRPO/PPO 等后训练任务。本文以 Geo3K 几何推理数据集 Qwen2.5-VL-7B-Instruct 为例完整讲解从数据集预处理、模型下载到 FSDP × vLLM/SGLang 多模态 GRPO 训练的三个核心步骤并结合仓库源码与脚本深入拆解多模态数据格式、关键训练参数及其底层实现帮助读者在 NVIDIA GPU 与 Ascend NPU 上快速复现多模态 RL 流水线。多模态 RL 支持现状根据 multi_modal_example.rst 的说明verl 已支持多模态训练目前可通过FSDPactor 训练后端 vLLM/SGLangrollout 推理后端的组合启动多模态 RL 任务Megatron 支持也已进入实现阶段。这意味着图像、视频等视觉输入可以与文本一起参与 RL 后训练——模型不仅要在think推理过程中给出逐步推理还要把最终答案放入\boxed{}中由规则奖励函数进行评判。仓库中与多模态训练直接相关的配套资源包括用途文件数据集预处理geo3k.py、openr1mm.py、tinyllava_video_r1.pyFSDP 训练脚本run_qwen2_5_vl_7b_fsdp.sh、run_qwen3_vl_8b_fsdp.shMegatron 训练脚本run_qwen2_5_vl_7b_megatron.sh多模态数据加载rl_dataset.pyimage_key/video_key与视觉信息处理训练入口main_ppo.py快速开始三步启动多模态 GRPO 训练Step 1准备数据集Geo3K 预处理运行仓库提供的预处理脚本将 Hugging Face 上的hiyouga/geometry3k数据集转换为 verl 标准 parquet 格式# it will be saved in the $HOME/data/geo3k folder python examples/data_preprocess/geo3k.py从源码看该脚本的核心逻辑在 geo3k.py 中完成数据源默认从hiyouga/geometry3k加载 train/test 两个 split若已存在本地原始数据可通过--local_dataset_path直接指定本地路径加载避免重复下载。指令注入为每个问题拼接统一的推理指令模板——要求模型先以内部独白形式思考推理过程必须放在think /think标签内最终答案必须放入\boxed{}中。字段重组将原始problem、answer、images重组为 verl 的 RL 数据集 schema其中prompt是包含 role/content 的对话结构images存放原始图像字节reward_model标注为 rule 风格、以ground_truth为评分依据。并行加速使用num_proc8并行执行 map最终输出train.parquet与test.parquet。可选 HDFS 导出传入--hdfs_dir时会将本地 parquet 拷贝到 HDFS适合大规模多机训练场景底层使用 hdfs_io.py 的copy/makedirs工具。注意脚本参数--local_dir已废弃推荐使用--local_save_dir默认~/data/geo3k。Step 2下载模型通过 transformers 的 pipeline 触发模型下载将 Qwen2.5-VL-7B-Instruct 拉取到本地缓存# download the model from huggingface python3 -c import transformers; transformers.pipeline(modelQwen/Qwen2.5-VL-7B-Instruct)之后即可在训练脚本中通过MODEL_PATH环境变量指向该模型默认Qwen/Qwen2.5-VL-7B-Instruct也支持替换为本地已下载的模型路径。Step 3执行 GRPO 多模态训练运行仓库自带的训练脚本即会通过 Ray 拉起 actorFSDP 训练与 rolloutvLLM/SGLang 推理等分布式角色完成整个多模态 GRPO 训练流程# run the task bash examples/grpo_trainer/run_qwen2_5_vl_7b_fsdp.sh该脚本兼容 NVIDIA GPU 与 Ascend NPUDEVICE通过探测torch_npu自动识别推理后端通过INFER_BACKEND环境变量在vllm | sglang | trtllm之间切换默认vllm。训练脚本参数全解run_qwen2_5_vl_7b_fsdp.sh 将全部配置组织为若干参数数组最终以python3 -m verl.trainer.main_ppo的 Hydra 覆盖参数形式传入。以下按功能组拆解其默认值与含义数据组DATA参数默认值说明algorithm.adv_estimatorgrpo优势估计器本示例使用 GRPOalgorithm.use_kl_in_rewardFalseKL 项不并入奖励由 actor 侧use_kl_loss单独控制data.train_files/data.val_files$HOME/data/geo3k/train.parquet/test.parquet训练/验证数据路径data.image_keyimages多模态样本中图像字段的 key与预处理脚本输出的列名对应data.train_batch_size512每个训练 step 的样本数data.max_prompt_length/data.max_response_length1024 / 2048prompt 与 response 的最大 token 长度data.filter_overlong_promptsTrue过滤超长 prompt 样本data.truncationerror截断策略设为error表示超出长度直接报错而非静默截断模型组MODELactor_rollout_ref.model.path模型路径可被MODEL_PATH覆盖actor_rollout_ref.model.use_remove_paddingTrue训练时去除 padding与动态 batch 配合节省显存actor_rollout_ref.model.enable_gradient_checkpointingTrue开启梯度检查点用计算换显存对 7B 级 VLM 尤为关键。Actor 训练组ACTORactor_rollout_ref.actor.strategyfsdp2EXTRA 组使用 FSDP2 作为 actor 分布式策略actor_rollout_ref.actor.optim.lr1e-6学习率actor_rollout_ref.actor.ppo_mini_batch_size128PPO mini-batch 大小actor_rollout_ref.actor.use_dynamic_bszTrue与ppo_max_token_len_per_gpu24576按 token 而非样本数动态分配 batch最大化显存利用率actor_rollout_ref.actor.use_kl_lossTrue、kl_loss_coef0.01、kl_loss_typelow_var_kl低方差 KL 惩罚稳定策略更新actor_rollout_ref.actor.fsdp_config.param_offloadFalse/optimizer_offloadFalseGPU 上不 offload 参数与优化器NPU 场景会在 EXTRA 中开启 offload。Rollout 推理组ROLLOUTactor_rollout_ref.rollout.name${INFER_BACKEND}推理后端vllm/sglang/trtllmactor_rollout_ref.rollout.tensor_model_parallel_size2vLLM 的 TP 并行度actor_rollout_ref.rollout.gpu_memory_utilization0.6推理引擎可用的显存比例actor_rollout_ref.rollout.n5每个 prompt 采样的 rollout 条数GRPO 依赖组内多条样本计算相对优势log_prob_use_dynamic_bszTrue与log_prob_max_token_len_per_gpu对 actor/ref 的 log-prob 计算同样启用动态 batch。训练器组TRAINERtrainer.logger[console,wandb]同时输出到控制台与 wandbtrainer.project_nameverl_grpo_geo3k、trainer.experiment_nameqwen2_5_vl_7b_${INFER_BACKEND}_fsdp实验命名trainer.n_gpus_per_node8、trainer.nnodes1单机 8 卡NPU 场景自动调整为 16trainer.total_epochs15、save_freq20、test_freq5总轮数、checkpoint 保存频率与验证频率。设备差异与启动方式脚本针对 GPU/NPU 做了差异化配置NPU 场景下会将mm_processor_cache_gb设为 0不缓存视觉 processor降低显存占用、关闭 fused kernels 与多阶段唤醒、调低显存利用率至 0.5 并调整log_prob_micro_batch_size_per_gpu。启动时默认通过uv run --frozen --all-packages --extra backend --extra fsdp运行以匹配 uv.lock 中的依赖组合若需使用系统 Python 可设置VERL_USE_UV0。多模态数据格式与底层处理图像数据Geo3K / OpenR1-MM预处理脚本产出的样本包含data_source、prompt、images、ability、reward_model、extra_info六个字段。其中prompt是标准对话结构prompt: [ { role: user, content: prompt, # 文本问题 推理指令 } ], images: images, # 与图像占位符对应的图像字节 reward_model: {style: rule, ground_truth: answer},openr1mm.py 展示了另一种图像数据处理细节对lmms-lab/multimodal-open-r1-8k-verified图像以原始字节 dict{bytes: ...}形式保留在 parquet 中不做解码、不做 resize——Qwen 视觉 processor 会在运行时按需缩放既避免有损重编码也让 RL 阶段的动态 batch 处理更高效。该脚本还会以seed42做 90/10 的 train/test 切分并只保留 6 个目标列。视频数据TinyLLaVA-Video-R1tinyllava_video_r1.py 展示了 verl 对视频输入的支持方式prompt 中使用video占位符videos字段记录视频绝对路径并附带采样参数video_entry {video: video_path} video_entry[fps] video_fps # 默认 1视频采样帧率 video_entry[max_frames] video_max_frames # 默认 32最大帧数该脚本同时演示了完整的视频数据集准备流程下载 → 解压 → 预处理并在 map 过程中对缺失视频文件给出 WARN 提示。数据集加载源码视角多模态数据在训练时由 rl_dataset.py 中的RLHFDataset处理字段名通过image_key默认images与video_key默认videos配置读取与训练脚本中data.image_keyimages一一对应样本进入训练前调用_process_multi_modal_info统一抽取图像/视频/音频并通过process_vision_info内部在线程池中执行交给视觉 processor 完成 tokenize 与张量化在处理对话式多模态输入时会依据image/video占位符与多模态内容的顺序对应关系维护image_offset/video_offset游标确保每个占位符替换为正确的视觉 token并在处理结束后断言所有视觉内容都被消费image_offset len(images)防止占位符与资源错位处理完成后从原始行中移除image_key/video_key列避免视觉原始数据混入后续特征字典。进阶扩展Qwen3-VL 与 Megatron 后端Qwen3-VL 基线GPU/NPU 通用run_qwen3_vl_8b_fsdp.sh 是仓库中 Qwen3-VL-8B 在 Geo3K 上的标准基线脚本其整体结构与此前脚本一致差异点包括模型默认Qwen/Qwen3-VL-8B-Instruct实验名自动附加时间戳训练/验证数据路径通过TRAIN_FILE/TEST_FILE单独可配NPU 分支额外导出HCCL_CONNECT_TIMEOUT、HCCL_HOST_SOCKET_PORT_RANGE等集合通信环境变量并设置RAY_EXPERIMENTAL_NOSET_ASCEND_RT_VISIBLE_DEVICES1NPU 场景可通过SP_SIZE配置 Ulysses 序列并行GPU 场景则开启 fused kernels 与free_cache_engine释放推理缓存引擎以降低显存碎片。Megatron 训练后端run_qwen2_5_vl_7b_megatron.sh 展示了多模态 Megatron 的组合通过model_enginemegatron切换训练后端并新增actor_rollout_ref.actor.megatron.*系列参数tensor_model_parallel_size2、pipeline_model_parallel_size2Megatron 的张量/流水线并行度use_mbridgeTrue启用 Megatron 与推理引擎之间的通信桥megatron bridge负责 actor 权重与 rollout 后端之间的高效同步ref 策略模型配置同样的 TP/PP 与use_mbridge保证 rollout 阶段的 log-prob 计算与 actor 并行方案一致。该脚本要求启动时使用--extra vllm --extra megatron的依赖组合uv.lock 中对应 extra。常见问题与调优提示显存不足优先检查data.filter_overlong_prompts、enable_gradient_checkpointing、use_remove_padding并确认rollout.gpu_memory_utilization未超过实际空闲显存NPU 场景建议跟随脚本默认值0.5并开启 actor/ref 的参数 offload。动态 batch 报错ppo_max_token_len_per_gpu需根据单卡显存与 VLM 视觉 token 开销调整图像会使单条 prompt 的实际 token 数显著大于纯文本估计。视觉 token 对齐失败若出现image_offset len(images)之类的断言错误说明样本中image占位符数量与images列表长度不匹配请检查预处理脚本中占位符与图像列的对应关系。多卡/多机扩展设置trainer.nnodes与trainer.n_gpus_per_node即可横向扩展数据量大时可在预处理阶段通过--hdfs_dir将 parquet 上推到 HDFS 供所有节点读取。小结通过geo3k.py数据预处理、模型下载与run_qwen2_5_vl_7b_fsdp.sh训练脚本三个步骤即可在 verl 中完成一次完整的视觉语言模型 GRPO 后训练。verl 的多模态支持统一了图像images与视频videos两类输入的处理路径并以image_key/video_key字段解耦数据 schema 与训练逻辑训练端既支持 FSDP2GPU/NPU 通用也支持 MegatronTP/PP 并行推理端可在 vLLM/SGLang/TRTLLM 间切换。对于想要深入多模态 RL 研究的开发者上述源码与脚本是绝佳的起点。【免费下载链接】verlverl/HybridFlow: A Flexible and Efficient RL Post-Training Framework项目地址: https://gitcode.com/GitHub_Trending/ve/verl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
