OpenRLHF/OpenRLHF · 上手攻略

• 仓库：OpenRLHF/OpenRLHF
• 链接：https://github.com/OpenRLHF/OpenRLHF
• 分类：ai（llm-infra / agent）
• 作者：Jay
• 更新：2026-07-10

一、是什么

OpenRLHF 是一个基于 Ray + vLLM 分布式架构的高性能 RLHF（从人类反馈中强化学习）训练框架，同时首创了统一的 Agent 执行范式。它能将 PPO、REINFORCE++、GRPO、RLOO 等 RL 算法，与单轮/多轮 Agent 执行模式自由组合，支持 70B+ 参数模型的分布式训练，并可通过 vLLM 加速生成阶段（RLHF 中耗时占比最高的环节）。

官方定位：第一个生产就绪、开源、高性能的 Agentic RL 框架。

核心定位对比： - 传统 RLHF 框架（如 TRL、COLA）多基于单进程，扩展性有限 - OpenRLHF 以 Ray 做分布式调度、vLLM 做推理引擎、DeepSpeed ZeRO-3 做训练，三层解耦 - Agent 执行层（AgentExecutorBase）与 RL 算法层完全解耦，任意组合

二、解决什么问题

1. RLHF 训练慢：RLHF 80% 时间花在 sample generation（生成阶段），OpenRLHF 用 vLLM 的 AutoTP/AutoPP 并行生成，加速显著
2. 多卡扩展难：Ray 负责 Actor/Critic/Reward/Reference 模型跨 GPU 调度，支持 Hybrid Engine（同 GPU 共用显存，睡模式切换）
3. 算法选型僵化：传统框架中算法与执行模式强绑定；OpenRLHF 中只需改一个 --algo.advantage.estimator 参数即可切换算法
4. 多轮 Agent 训练：原生支持多轮交互环境（图片反馈、外部 Agent Server），适用于 VLMs、复杂推理任务
5. 异步训练：Overlap 生成与训练、权重同步与生成，支持 Partial Rollout，提高 GPU 利用率

三、快速安装

推荐：Docker（一键环境）

docker run --runtime=nvidia -it --rm --shm-size="10g" --cap-add=SYS_ADMIN \
  -v $PWD:/openrlhf nvcr.io/nvidia/pytorch:26.03-py3 bash

# 清理冲突包
sudo pip uninstall xgboost transformer_engine flash_attn pynvml -y

# 安装 OpenRLHF（二选一）
pip install openrlhf                              # 基础版
pip install openrlhf[vllm]                        # + vLLM（推荐）
pip install openrlhf[vllm_latest]                 # + 最新 vLLM
pip install openrlhf[vllm,ring,liger]             # + 全量优化

源码安装

git clone https://github.com/OpenRLHF/OpenRLHF.git
cd OpenRLHF
pip install -e .

⚠️ Python ≥ 3.9，CUDA 11+ / ROCm 5+；推荐使用 Docker 省去依赖地狱

四、核心用法

4.1 数据准备

OpenRLHF 支持 HuggingFace 格式数据集，关键参数：

--data.input_key <json_key>          # 指定输入字段名
--data.output_key <json_key>          # 指定输出字段名
--data.input_template $'User: {}\nAssistant: '   # 自定义模板
--data.apply_chat_template            # 使用 HF tokenizer chat template
--data.max_samples 500000             # 最大样本数
--data.prompt_probs 0.1,0.4,0.5       # 多数据集混合权重

格式示例（Chat Template）：

dataset = [{"input_key": [
  {"role": "user", "content": "Hello!"},
  {"role": "assistant", "content": "Hi, how can I help?"},
]}]
tokenizer.apply_chat_template(dataset[0]["input_key"], tokenize=False)

4.2 SFT（有监督微调）

deepspeed --module openrlhf.cli.train_sft \
  --data.max_len 4096 \
  --data.dataset Open-Orca/OpenOrca \
  --data.input_key question \
  --data.output_key response \
  --data.input_template $'User: {}\nAssistant: ' \
  --train.batch_size 256 \
  --train.micro_batch_size 2 \
  --actor.model_name_or_path meta-llama/Meta-Llama-3-8B \
  --ckpt.output_dir ./checkpoint/llama3-8b-sft \
  --ds.zero_stage 2 \
  --ds.packing_samples \
  --ds.param_dtype bf16 \
  --adam.lr 5e-6 \
  --actor.gradient_checkpointing_enable \
  --logger.wandb.key {wandb_token}

4.3 Reward Model（奖励模型）

deepspeed --module openrlhf.cli.train_rm \
  --ckpt.output_dir ./checkpoint/llama3-8b-rm \
  --actor.model_name_or_path OpenRLHF/Llama-3-8b-sft-mixture \
  --data.dataset OpenRLHF/preference_dataset_mixture2_and_safe_pku \
  --data.apply_chat_template \
  --chosen_key chosen \
  --rejected_key rejected \
  --train.batch_size 256 \
  --ds.zero_stage 3 \
  --ds.packing_samples \
  --adam.lr 9e-6

4.4 RL 训练（PPO / REINFORCE++ / GRPO / RLOO）

PPO（稳定，default）：

# 需要预先准备好 RM checkpoint
deepspeed --module openrlhf.cli.train_ppo_ray \
  --actor.model_name_or_path meta-llama/Meta-Llama-3-8B \
  --reward.model_name_or_path ./checkpoint/llama3-8b-rm \
  --ref.model_name_or_path meta-llama/Meta-Llama-3-8B \
  --critic.model_name_or_path ./checkpoint/llama3-8b-rm \
  --train.train_funcs PPO \
  --vllm.num_engines 2 \
  --train.micro_batch_size 1

REINFORCE++（推荐，效率高）：

deepspeed --module openrlhf.cli.train_ppo_ray \
  --actor.model_name_or_path meta-llama/Meta-Llama-3-8B \
  --reward.model_name_or_path ./checkpoint/llama3-8b-rm \
  --train.train_funcs REINFORCE++ \
  --algo.advantage.estimator reinforce_baseline \
  --rollout.n_samples_per_prompt 8 \
  --vllm.tensor_parallel_size 2

关键 RL 算法切换参数 --algo.advantage.estimator：

4.5 DAPO（动态采样）

# 配合 --rollout.n_samples_per_prompt > 1 使用
--algo.dynamic_filtering_enable \
--algo.dynamic_filtering_range 0.0 1.0

根据 reward/agent score 过滤低质量样本，适合推理任务。

4.6 LoRA / QLoRA

--ds.lora.rank 8 \
--ds.load_in_4bit

4.7 VLM（视觉-语言模型）RLHF（v0.10+）

# 单轮图像输入
./examples/scripts/train_vlm_math_hybrid_engine.sh

# 多轮图像反馈（截图环境）
./examples/scripts/train_vlm_multiturn_ray_agent.sh
# 或直接用 Python
python examples/python/vlm_multiturn_agent.py

关键参数：--data.image_key、--data.max_images_per_prompt

五、典型适用场景

1. LLM 对齐训练：将 base model 通过 RLHF / DPO / SFT 对齐到人类偏好（对话质量、数学推理、代码生成）
2. 推理模型训练：REINFORCE++-baseline 是训练 DeepSeek-R1 类推理模型的轻量方案，已被 ProRL V2、MAGISTRAL 等采用
3. VLM 多模态对齐：Qwen3.5-VL 等视觉-语言模型的端到端 RLHF 训练
4. 多轮 Agent 训练：在外部环境（截图、API）反馈下训练多轮决策 Agent
5. 生产级分布式训练：需要多卡/多节点扩展的 RLHF 训练管线

六、坑与注意

1. 显存规划：Hybrid Engine 规则——生成引擎共享 GPU 时，睡模式下只保留模型权重；建议先看官方 memory rule of thumb，不确定先从单卡小模型开始
2. Muon 优化器：需 DeepSpeed ≥ 0.18.2；Muon 下 max_norm 要设为 0（不梯度裁剪），否则会把更新裁掉
3. vLLM 版本：推荐用 pip install openrlhf[vllm]，不要混用不同版本 vLLM
4. Async 模式：不适用于短训练（如单 epoch SFT），仅在长 RL 训练中收益明显
5. Flag 迁移：从 0.9.x / early 0.10 升级后，注意 --adv_estimate_method 等旧参数已改名为 --algo.advantage.estimator
6. NCCL / Ray 初始化：多节点时注意 NCCL 版本一致性；Ray runtime environment 问题参考 Troubleshooting 文档
7. 第三方依赖冲突：Docker 中需先卸载 xgboost、transformer_engine、flash_attn、pynvml，避免与框架内置版本冲突

七、与同类对比

结论：如果你需要训练 70B+ 模型、追求高吞吐、或需要多轮 Agent / VLM 支持，OpenRLHF 是目前最完整的选择；如果只是小模型快速实验，TRL 更轻量。

八、一句话推荐结论

OpenRLHF 是目前开源最完整的生产级 RLHF 框架，Ray+vLLM 分布式架构解决了大模型训练效率瓶颈，Agent 范式让 RL 算法与执行模式彻底解耦，是训练推理模型、VLM 对齐和多轮 Agent 的首选基础设施。

来源： - GitHub README（https://github.com/OpenRLHF/OpenRLHF） - OpenRLHF 官方文档（https://openrlhf.readthedocs.io/） - vLLM Blog（https://blog.vllm.ai/2025/04/23/openrlhf-vllm.html）