企业官网建设流程全解析

在 VeRL-Omni（面向 diffusion 与 omni 模型的多模态强化学习训练框架）中，奖励（Reward）是训练能否收敛的命脉：模型生成一张图或一段视频后，必须有"评委"给出分数，策略更新才知道往哪个方向走。本指南带你快速上手 VeRL-Omni 的三种自定义奖励接入方式——HTTP Scorer 外部评分服务、HPSv3 人类偏好奖励、以及命名奖励模型（Named Reward Models），并给出可运行的配置示例与官方示例脚本路径，让你按需选择最合适的方案。

如上图所示，VeRL-Omni 将"多模态生成与奖励（Multi-modal Generation & Reward Layer）"独立成一层：Rollout Engine 负责生成轨迹，Reward Engine 负责打分，打出的 Trajectories & Feedback 再经由 TransferQueue 回传给 Actor Engine 做权重更新。本文介绍的所有奖励接入，都发生在 Reward Engine 这一层。

三种奖励接入方式怎么选？

💡 简单记：外部服务走 HTTP，轻量打分走自定义函数，多模型组合走命名奖励模型。

方式一：接入外部 HTTP Scorer 评分服务

当你的奖励模型太大无法与训练同机共存、或需要独立 GPU 资源池、或想在多个实验间共享同一个评分服务时，HTTP Scorer 是最省心的方案。它由通用客户端 verl_omni/utils/reward_score/http_scorer_client.py 实现：训练过程中把生成图转成 JPEG 字节，连同 prompt 一起 POST 给你的评分服务，服务返回分数。

评分服务协议（极简三步）

1. 客户端把图片张量转成 JPEG 字节（放到线程池，不阻塞异步事件循环）；
2. 与 prompt 一起打包成{"images": [...], "prompts": [...], "metadata": {}}通过 HTTP POST 发送；
3. 服务返回{"scores": [float, ...]}，每张图一个分数。

⚠️ 只要你的服务（PaddleOCR、HPSv3、美学评分、CLIP 评分……任何框架都行）实现了这个接口，就能直接作为 VeRL-Omni 的奖励函数使用，且完全不与训练环境冲突。

训练侧配置步骤

在启动脚本中把奖励函数指向http_scorer_client，并传入server_url即可：

python3 -m verl_omni.trainer.main_diffusion \ ... \ "+reward.reward_functions.my_reward.path=pkg://verl_omni.utils.reward_score.http_scorer_client" \ '+reward.reward_functions.my_reward.name=compute_score' \ '+reward.reward_functions.my_reward.weight=1.0' \ '+reward.reward_functions.my_reward.required=true' \ "+reward.reward_functions.my_reward.server_url=http://<scorer-host>:<port>" \ '+reward.reward_functions.my_reward.max_retries=2' \ '+reward.reward_functions.my_reward.retry_backoff=0.5'

关键参数速查：

• path：模块路径（pkg://前缀或本地.py路径）；
• weight：多奖励组合时的权重；
• required：评分失败时是否终止训练。true直接停训，false（默认）记 0 分继续；
• max_retries/retry_backoff：重试次数与初始退避间隔（延迟逐次翻倍）；
• 额外添加的任意键值对会作为**kwargs透传给compute_score。

客户端只对瞬时网络错误、超时、HTTP 408/429/5xx 重试；批内所有样本通过asyncio.gather并发请求，没有串行瓶颈。🎯

完整示例：Qwen-Image + 外部 OCR 奖励服务器

官方示例脚本：examples/flowgrpo_trainer/qwen_image/run_qwen_image_ocr_reward_server.sh，配套数据预处理：examples/flowgrpo_trainer/data_process/qwenimage_ocr_http_service.py

# 1. 先启动外部 OCR 评分服务（独立进程/机器） # 2. 准备数据（把完整 prompt 存为 ground_truth 供 HTTP 服务使用） python examples/flowgrpo_trainer/data_process/qwenimage_ocr_http_service.py \ --input_dir ~/dataset/ocr/ --output_dir ~/data/ocr_http # 3. 运行训练 OCR_REWARD_SERVER_URL=http://<server-ip>:19082 \ bash examples/flowgrpo_trainer/qwen_image/run_qwen_image_ocr_reward_server.sh

📖 详细协议说明见官方文档：docs/start/http_scorer.md（音频场景使用 audio_http_scorer_client.py）。

方式二：接入 HPSv3 人类偏好奖励

HPSv3（Human Preference Score v3）是一个基于 Qwen2-VL 的奖励模型，从视觉质量（合理性、清晰度、细节、美学、安全性）和文本对齐（主体相关性、风格、属性还原度等）两个大维度对生成内容打 0~10 分，是视频/图像 RL 中最常用的"人类偏好代理"。

VeRL-Omni 已内置该奖励函数：verl_omni/utils/reward_score/hpsv3_reward.py，入口函数为compute_score_hpsv3，并自带微批处理（把并发请求按 checkpoint + device + batch size 聚合成批推理，默认max_batch_size=4，队列上限 64），显著提升打分吞吐。

官方示例：Wan2.2 + DanceGRPO + HPSv3

参考脚本 examples/dancegrpo_trainer/wan22/run_wan22_5b_t2v_hpsv3_v1.sh，核心配置只有三行：

# 通过环境变量提供 HPSv3 权重路径 export custom_reward_model_path=$WORKSPACE/CKPT/HPSv3/HPSv3.safetensors reward.custom_reward_function.path=verl_omni/utils/reward_score/hpsv3_reward.py \ reward.custom_reward_function.name=compute_score_hpsv3 \ +reward.custom_reward_function.reward_kwargs.max_batch_size=4

要点：

• HPSv3 权重路径通过环境变量custom_reward_model_path传入（也可直接写model_name参数）；
• reward.reward_model.enable=False——因为 HPSv3 是直接加载的自定义函数，不走 vLLM 奖励模型通道；
• 批大小、reward_scale等参数均可通过reward_kwargs透传。

更多奖励函数实现（PickScore、HPSv2、CLAP、ImageBind、jpeg_compressibility 等）都在 verl_omni/utils/reward_score/ 目录下，可以直接复用或参考其写法。

方式三：命名奖励模型（Named Reward Models）——多奖励组合的正规军

当你需要一个训练任务里同时挂多个模型级奖励（例如 OCR 准确率 + 图像质量），推荐升级到reward.models命名奖励模型机制。它的核心思想是推理与打分解耦：

• 命名模型拥有资源、推理通道与生命周期（唤醒/睡眠/卸载）；
• 奖励函数只负责"样本 → 模型输入"和"模型输出 → 分数"；
• MultiRewardManager负责分发、失败处理与加权聚合，最终分数为final_reward = sum(term.weight * term.score)。

配置时必须指定带输入契约的 manager：

reward: reward_manager: name: MultiVisualRewardManager

engine 与 native 两种后端

命名绑定的妙处：奖励项自动绑定同名模型——reward_functions.ocr自动使用models.ocr，名字不同或需共享模型时才显式写model:字段。

示例：4 卡父池同时跑 vLLM OCR + 原生质量模型

reward: reward_model: enable: false enable_resource_pool: true n_gpus_per_node: 4 nnodes: 1 models: ocr: backend: engine offload: true model_path: /models/ocr n_gpus_per_node: 2 nnodes: 1 rollout: name: vllm tensor_model_parallel_size: 2 quality: backend: native offload: true model_path: /models/quality placement: devices: [2, 3] executor: model: my_package.reward_model:TransformersRewardModel reward_functions: ocr: path: pkg://my_package.ocr_reward name: compute_score weight: 0.4 quality: path: pkg://my_package.reward_score name: compute_quality_score weight: 0.6

几个实用细节：

• offload: true（默认）：评分前唤醒、评分后睡眠，不占用训练显存；设为false可常驻；
• required: true：该项评分失败即终止训练；false则记 0 分继续（模型装配/生命周期失败则始终致命）；
• native 副本调度：默认按静态均分切批；对副本速度不均的原生模型可设置dispatch_batch_size启用"完成驱动"的动态微批分发（详见文档 Native replica scheduling）；
• ⚠️ 旧版单模型配置（reward.reward_model.enable=true+custom_reward_function）迁移时，两者不可同时启用。

官方可直接运行的参考配方：SD3.5 OCR 引擎后端示例 examples/flowgrpo_trainer/sd35/run_sd35_medium_ocr_lora_v1.sh，多奖励组合示例 examples/flowgrpo_trainer/qwen_image/run_qwen_image_ocr_multi_reward.sh（OCR 0.5 + JPEG 压缩率 0.5 加权混合）。

常见坑与排错

1. required设错导致"幽灵分数"：required=false时外部服务挂了训练照样跑，奖励会悄悄全 0。关键奖励务必设true；
2. HTTP 服务必须"先于训练启动"：OCR_REWARD_SERVER_URL指向的服务不可达时，只有瞬时错误会重试，4xx 与格式错误会快速失败；
3. 命名模型与旧通道互斥：配置了reward.models就不要同时开reward.reward_model.enable=true；
4. native 模型不支持 FSDP/张量并行，每个placement.devices条目是一份完整副本，副本数 = 条目数；
5. 调试奖励分数：先用小批量trainer.test_freq验证奖励曲线是否随训练上升，再看是否需要调weight平衡多奖励。

小结与延伸阅读

VeRL-Omni 的奖励体系可以概括为一句话：HTTP Scorer 管"外置"，自定义函数管"轻量"，reward.models管"多模型组合"。三种方式可自由混搭，覆盖从 OCR 判读到人类偏好的绝大多数多模态 RL 场景。

📚 更多资料：

• HTTP Scorer 完整协议：docs/start/http_scorer.md
• 命名奖励模型指南：docs/algo/named_reward_models.md
• 异步奖励与奖励循环：docs/algo/async_reward.md、verl_omni/reward_loop/
• 内置奖励函数库：verl_omni/utils/reward_score/
• 训练示例总览：docs/examples/overview.md