2. 清理冲突包

[ English | 中文 | 日本語 ]

OpenRLHF 是首个结合 Ray + vLLM 分布式架构与统一 Agent 设计范式的高性能、生产就绪的开源 RLHF 框架，用于可扩展和可扩展的人类反馈强化学习。

📚 了解更多：文档 | PPT | 技术报告 | 视频

📖 目录

• 🗞️ 新闻
• 🏗️ 架构基础 - Ray + vLLM + DeepSpeed 分布式基础设施
• 🎯 设计范式 - 统一的 Agent 执行流程
• 🚀 RL 算法 - PPO、REINFORCE++、GRPO、RLOO
• 📋 特性概览 - 完整的 RLHF 流程能力
• 🎬 快速开始 - 安装和典型工作流
• 🎓 训练指南 - SFT、奖励模型、RL 训练
• 🎯 单轮 Agent - 自定义奖励函数
• 🤖 多轮 Agent - 复杂环境
• 🔧 高级主题 - LoRA、性能调优

新闻

🏗️ 架构基础：Ray + vLLM 分布式

OpenRLHF 是首个基于 Ray + vLLM 分布式架构构建的 RLHF 框架，可高效地跨 GPU 编排多个组件：

核心基础设施组件

Ray - 分布式调度器和控制器
OpenRLHF 利用 Ray 实现高效的分布式调度。它将 Actor、Reward、Reference 和 Critic 模型分布到不同的 GPU 上，支持训练高达 70B+ 参数的模型。

混合引擎调度：所有模型和 vLLM 引擎可以共享 GPU 资源，最大限度地减少空闲时间并提高 GPU 利用率。这允许在有限的硬件上运行完整的 RLHF 流程。

vLLM - 高性能推理引擎
RLHF 训练中 80% 的时间花在样本生成上。通过 vLLM 与自动张量并行（AutoTP）和流水线并行（PP），OpenRLHF 提供高吞吐量、内存高效的生成。

DeepSpeed - 内存高效训练
基于 DeepSpeed ZeRO-3、deepcompile、AutoTP 和 RingAttention。支持大模型训练而无需重量级框架，直接与 HuggingFace 模型配合使用。

Transformers - 模型接口
与 HuggingFace Transformers 原生集成，可无缝加载模型、状态管理和微调预训练模型。

NCCL / CUDA IPC - 高速通信
高效的 GPU 间通信，用于分布式训练和推理。

🎯 设计范式：基于 Agent 的执行

在 Ray 分布式架构之上，OpenRLHF 是首个实现统一 Agent 范式的 RLHF 框架。无论是标准 PPO 还是复杂的多轮推理，每次训练运行都遵循一致的 Agent 执行流程。

为什么采用 Agent 范式？

OpenRLHF 通过 token-in-token-out 的 Agent 执行统一生成和训练，确保完美一致性、轻松的单轮/多轮扩展，以及零文本级别不匹配。

Agent 架构

                 ┌─────────────────────────────┐
                 │    AgentExecutorBase        │
                 │  (Token-in-Token-out 核心)  │
                 └─────────────────────────────┘
                              │
                 ┌────────────┴────────────┐
                 ↓                         ↓
         SingleTurnExecutor        MultiTurnExecutor
                 │                         │
      ┌──────────┴──────────┐   ┌─────────┴──────────┐
      ↓                     ↓   ↓                    ↓
  标准 RLHF          自定义奖励    多步推理        外部环境
  (单次生成)           函数                      (OpenAI Agent Server)
      ↓                     ↓           ↓                ↓
      └─────────────────────┴───────────┴────────────────┘
                              │
                    一致的 Token 轨迹
                              │
                    ┌─────────┴─────────┐
                    │  RL 算法          │
                    │  (解耦)           │
                    │                   │
                    │  PPO, REINFORCE++ │
                    │  GRPO, RLOO 等    │
                    └───────────────────┘

核心设计原则

两种执行模式（与 RL 算法正交）

Agent 执行模式与您选择的 RL 算法独立。您可以将任何算法（PPO、REINFORCE++、GRPO 等）与任何执行模式配合使用：

🚀 最先进的 RL 算法

OpenRLHF 实现了 PPO、REINFORCE++、REINFORCE++-baseline、GRPO、RLOO，采用受实践指南和社区最佳实践启发的高级优化技巧。

关键设计：RL 算法与 Agent 执行模式解耦。所有算法都可以与单轮和多轮 Agent 执行器无缝配合，通过统一的 token-in-token-out 流程运行，确保行为一致。

参考：知乎文章 | Notion 最佳实践

📋 全面特性

OpenRLHF 提供完整的 RLHF 流程，具有基于 Agent 的灵活性：

🎯 基于 Agent 的 RL 训练（核心创新）

🎓 监督训练和偏好学习

⚡ 高级能力

🎬 快速开始

安装

推荐：使用 Docker 以实现无忧设置

# 1. 启动 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

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

# 3. 安装 OpenRLHF（选择一个）
pip install openrlhf                    # 基础
pip install openrlhf[vllm]              # + vLLM 0.22.1（推荐）
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 .

准备数据集

OpenRLHF 提供灵活的数据处理方法：

关键参数：

• --data.input_key：指定输入数据的 JSON 键名
• --data.apply_chat_template：使用 HuggingFace tokenizer 的聊天模板
• --data.input_template：自定义模板字符串（聊天模板的替代方案）
• --data.prompt_probs / --data.dataset_probs：混合多个数据集（例如 0.1,0.4,0.5）
• --eval.dataset：指定评估数据集路径

聊天模板示例：

dataset = [{"input_key": [
  {"role": "user", "content": "Hello, how are you?"},
  {"role": "assistant", "content": "I'm doing great. How can I help you today?"},
  {"role": "user", "content": "I'd like to show off how chat templating works!"},
]}]

tokenizer.apply_chat_template(dataset[0]["input_key"], tokenize=False)
# 输出: "<s>[INST] Hello, how are you? [/INST]I'm doing great...</s> [INST] I'd like to show off... [/INST]"

监督微调

OpenRLHF 的模型检查点与 HuggingFace 模型完全兼容。您可以使用 --actor.model_name_or_path {name or path}、--reward.model_name_or_path {name or path} 和 --critic.model_name_or_path {name or path} 指定模型名称或路径。我们在 HuggingFace OpenRLHF 上提供了一些预训练检查点和数据集。

然后您可以使用我们在 examples/scripts 目录中提供的启动脚本，或使用以下命令开始训练。

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 \
   --data.max_samples 500000 \
   --actor.model_name_or_path meta-llama/Meta-Llama-3-8B \
   --ckpt.output_dir ./checkpoint/llama3-8b-sft \
   --ckpt.save_steps -1 \
   --logger.logging_steps 1 \
   --eval.steps -1 \
   --ds.zero_stage 2 \
   --train.max_epochs 1 \
   --ds.packing_samples \
   --ds.param_dtype bf16 \
   --adam.lr 5e-6 \
   --actor.gradient_checkpointing_enable \
   --logger.wandb.key {wandb_token}

# 附加选项：
# --data.apply_chat_template                # 使用 HF tokenizer 聊天模板
# --ds.ring_attn_size 2                      # 启用 RingAttention（先安装 ring_flash_attn）
# --data.multiturn                          # 多轮微调损失
# --actor.pretrain_mode_enable                      # 继续预训练模式

奖励模型训练

deepspeed --module openrlhf.cli.train_rm \
   --ckpt.output_dir ./checkpoint/llama3-8b-rm \
   --ckpt.save_steps -1 \
   --logger.logging_steps 1 \
   --eval.steps -1 \
   --train.batch_size 256 \
   --train.micro_batch_size 1 \
   --actor.model_name_or_path OpenRLHF/Llama-3-8b-sft-mixture \
   --ds.param_dtype bf16 \
   --train.max_epochs 1 \
   --data.max_len 8192 \
   --ds.zero_stage 3 \
   --adam.lr 9e-6 \
   --data.dataset OpenRLHF/preference_dataset_mixture2_and_safe_pku \
   --data.apply_chat_template \
   --chosen_key chosen \
   --rejected_key rejected \
   --ds.packing_samples \
   --actor.gradient_checkpointing_enable \
   --logger.wandb.key {wandb_token}

建议将奖励模型的 --value_prefix_head 选项设置为 score，以便我们可以使用 AutoModelForSequenceClassification 加载模型：

reward_model = AutoModelForSequenceClassification.from_pretrained(
              reward_model_path,
              num_labels=1,
              torch_dtype=torch.bfloat16,
              attn_implementation="flash_attention_2",
              use_cache=False,
          )
inputs = xxxx (左填充输入 Tokens)
reward = reward_model.model(*inputs).last_hidden_state
reward = reward_model.score(reward)[:, -1]

RL 训练：使用 Ray 和 vLLM 的 PPO/REINFORCE++

OpenRLHF 中的所有 RL 训练都通过 Agent 执行流程运行。以下示例展示了使用混合引擎的单轮 Agent 执行（默认模式）以获得最佳性能：

# 在容器中启动 ray 的主节点
ray start --head --node-ip-address 0.0.0.0 --num-gpus 8

# 如果要在更多节点上启动 ray，使用
ray start --address {MASTER-NODE-ADDRESS}:6379  --num-gpus 8

ray job submit --address="http://127.0.0.1:8265" \
   --runtime-env-json='{"working_dir": "/openrlhf"}' \
   -- python3 -m openrlhf.cli.train_ppo_ray \
   --ref.num_nodes 1 \
   --ref.num_gpus_per_node 8 \
   --reward.num_nodes 1 \
   --reward.num_gpus_per_node 8 \
   --critic.num_nodes 1 \
   --critic.num_gpus_per_node 8 \
   --actor.num_nodes 1 \
   --actor.num_gpus_per_node 8 \
   --vllm.num_engines 4 \
   --vllm.tensor_parallel_size 2 \
   --train.colocate_all \
   --vllm.gpu_memory_utilization 0.5 \
   --actor.model_name_or_path OpenRLHF/Llama-3-8b-sft-mixture \
   --reward.model_name_or_path OpenRLHF/Llama-3-8b-rm-700k \
   --ckpt.output_dir /openrlhf/examples/test_scripts/final/llama3-8b-rlhf \
   --ckpt.path /openrlhf/examples/test_scripts/ckpt/llama3-8b-rlhf \
   --ckpt.save_hf \
   --train.batch_size 128 \
   --rollout.batch_size 1024 \
   --train.dynamic_batch_enable \
   --rollout.n_samples_per_prompt 1 \
   --train.max_epochs 1 \
   --prompt_max_len 1024 \
   --data.max_samples 100000 \
   --generate_max_len 1024 \
   --ds.zero_stage 3 \
   --ds.param_dtype bf16 \
   --actor.adam.lr 5e-7 \
   --critic.adam.lr 9e-6 \
   --algo.kl.init_coef 0.01 \
   --data.prompt_dataset OpenRLHF/prompt-collection-v0.1 \
   --data.input_key context_messages \
   --data.apply_chat_template \
   --reward.normalize_enable \
   --actor.gradient_checkpointing_enable \
   --ds.packing_samples \
   --vllm.sync_backend nccl \
   --vllm.enforce_eager \
   --vllm.enable_sleep \
   --ds.enable_sleep \
   --logger.wandb.key {wandb_token}

# 算法变体（所有算法都使用单轮 Agent 执行）：
# --algo.advantage.estimator reinforce        # REINFORCE++
# --algo.advantage.estimator rloo             # RLOO
# --algo.advantage.estimator reinforce_baseline  # REINFORCE++-baseline（RLVR 最佳）
# --algo.advantage.estimator group_norm       # GRPO
# --algo.advantage.estimator dr_grpo          # Dr. GRPO

# 高级选项：
# --algo.kl.init_coef 0                                    # 无参考模型
# --reward.remote_url http://host:5000/get_reward         # HTTP 奖励模型
# --rollout.n_samples_per_prompt 4                            # 每个提示多个样本
# --rollout.vllm_generate_batch_size 2048                     # 生成阶段过采样（> rollout_batch_size）；需要配合 --train.async_enable
# --algo.advantage.is_correction_enable                         # vLLM 重要性采样修正，用于 off-policy rollout
# --algo.advantage.is_correction_type tis                       # 修正类型：tis（token clamp）| icepop（token 过滤）| seq-mask-tis（序列级几何平均）
# --algo.advantage.is_correction_threshold 0.5 5.0               # IS 截断区间：[low, high]
# --ckpt.best_metric_key eval_default_pass1                # 按评估指标保存最佳检查点（留空自动探测首个 pass1，'none' 禁用）
# --actor.policy_loss_type gspo                             # 使用 GSPO 策略损失变体（默认为 'ppo'）

📚 更多示例：参见 example/scripts 和文档

🎯 单轮 Agent：强化微调与自定义奖励

单轮 Agent 执行（默认模式）支持自定义奖励函数——非常适合无需训练奖励模型的强化微调。您可以提供一个 Python 函数来即时计算奖励，而不是使用预训练的奖励模型。

适用于：

• 基于规则的奖励（长度、格式、代码执行、数学验证）
• 外部 API 奖励（评判模型、编译器、测试套件）
• 混合奖励（组合多个信号）

示例：自定义奖励函数

# reward_func.py
import torch

def reward_func(queries, prompts, labels):
    """
    计算生成响应的自定义奖励。
    
    参数：
        queries: List[str] - 完整文本（提示 + 响应）
        prompts: List[str] - 仅原始提示
        labels: List[str] - 真实标签（来自 --label_key）
    
    返回：
        包含以下内容的字典：
            - rewards: 用于优势计算的张量
            - scores: 用于动态过滤的张量（0-1 范围）
            - extra_logs: 用于 wandb 日志的字典
    """
    batch_size = len(queries)
    
    # 示例：随机奖励（替换为您的逻辑）
    # 真实示例：代码执行、数学验证、格式检查
    reward = torch.randint(0, 2, (batch_size,)).float()
    
    return {
        "rewards": reward,           # 用于 RL 优势计算
        "scores": reward,            # 用于动态过滤（--dynamic_filtering）
        "extra_logs": {              # 记录到 wandb
            "custom_metric": reward.mean().item(),
        },
    }

使用方法

ray job submit --address="http://127.0.0.1:8265" \
  --runtime-env-json='{"working_dir": "/openrlhf"}' \
  -- python3 -m openrlhf.cli.train_ppo_ray \
  --actor.model_name_or_path meta-llama/Meta-Llama-3-8B \
  --train.dynamic_batch_enable \
  --reward.remote_url /path/to/reward_func.py \
  --data.label_key answer \
  --data.prompt_dataset your_prompt_dataset \
  ... # 其他训练参数

关键参数：--data.label_key answer 将数据集中的"answer"字段传递给 reward_func 作为 labels。

📖 完整示例：examples/scripts/train_ppo_with_reward_fn.sh

🤖 多轮 Agent：复杂环境交互

对于需要多步交互（推理链、带反馈的编码、游戏）的任务，OpenRLHF 提供多轮 Agent 执行模式。

构建自定义多轮 Agent

使用 reset/step 方法实现 AgentInstanceBase：

# agent_func.py
import random
from typing import Any, Dict

import torch
from openrlhf.utils.agent import AgentInstanceBase, MultiTurnAgentExecutor


# 一个简单的 n 步随机环境
class AgentInstance(AgentInstanceBase):
    async def __init__(self, *args, **kwargs):
        self.step_idx = 0
        self.max_steps = random.randint(1, 3)  # 1-3 步

    async def reset(self, states: dict, **kwargs):
        return {"observation": states["observation"]}  # 返回原始文本观察

    async def step(self, states: dict, **kwargs) -> Dict[str, Any]:
        print(f"step_idx: {self.step_idx}, max_steps: {self.max_steps}")

        observation_text = states["observation_text"]
        action_text = states["action_text"]
        label = states["label"]

        # 检查回合是否结束
        done = self.step_idx >= self.max_steps
        reward = torch.randint(0, 2, (1,)).float() if done else torch.tensor(0)

        # 根据回合是否结束生成环境反馈
        environment_feedback = (
            "\n\nHuman: [CORRECT]\n</s>"
            if done
            else "\n\nHuman: [INCORRECT]\nPlease analyze the issues and try again.\n</s>\n\nAssistant: "
        )

        self.step_idx += 1

        return {
            "rewards": reward,  # 用于优势计算的奖励
            "scores": reward,  # 用于动态过滤的分数（0-1 奖励）
            "environment_feedback": environment_feedback,  # 环境反馈文本
            "done": done,  # 指示回合是否完成的布尔值
            "sampling_params": states.get("sampling_params", None),  # 下一步 vLLM 采样参数
            "extra_logs": {"dummy_scores": reward},  # 额外的日志信息
        }


class AgentExecutor(MultiTurnAgentExecutor):
    def __init__(self):
        super().__init__(AgentInstance)

然后启动：

ray job submit --address="http://127.0.0.1:8265" \
  --runtime-env-json='{"working_dir": "/openrlhf"}' \
  -- python3 -m openrlhf.cli.train_ppo_ray \
  ...
  --train.dynamic_batch_enable \
  --train.agent_func_path /path/to/agent_func.py \
  --train.async_enable  # 可选：启用异步流水线

配置选项

异步流水线（提高吞吐量）：

• 启用：--train.async_enable
• 缓冲区大小：--train.async_queue_size 1（越大 = 越多 off-policy，默认 1）

训练模式：

• 同步：默认，更好的稳定性
• 异步：更高吞吐量，可能影响收敛
• 混合引擎：使用 --train.colocate_all 实现最佳 GPU 利用率（移除 --train.async_enable）

📚 示例：

• 单轮：train_ppo_ray_hybrid_engine.sh
• 自定义奖励：train_ppo_with_reward_fn.sh
• 多轮：train_reinforce_baseline_ray_agent_async.sh
• 多轮 VLM（图像反馈）：vlm_multiturn_agent.py
• OpenAI Agent Server：agent_func_openai_server_executor.py

🔧 高级主题

LoRA：合并适配器

使用 LoRA/QLoRA 时，OpenRLHF 仅保存适配器权重。要部署或继续训练，请将适配器与基础模型合并：

python -m openrlhf.cli.lora_combiner \
    --model_path meta-llama/Meta-Llama-3-8B \
    --lora_path ./checkpoint/llama3-8b-rm \
    --output_path ./checkpoint/llama-3-8b-rm-combined \
    --is_rm \
    --ds.param_dtype bf16

性能调优指南

通过以下建议针对您的硬件和工作负载优化 OpenRLHF：

🎯 执行模式：吞吐 vs. 稳定性

根据优先级选择执行模式——OpenRLHF 提供清晰的取舍旋钮：

⚡ 其他速度优化

💾 内存管理

当您有足够内存时：

• ✅ 禁用 --ds.adam_offload
• ✅ 启用 --ds.overlap_comm
• ✅ 使用 --train.colocate_critic_reward 和 --train.colocate_actor_ref

遇到 OOM 时：

• ❌ 禁用所有 --colocate_* 选项
• ✅ 减少批次大小
• ✅ 启用梯度检查点

🎮 批次大小调优

1. 生成阶段：最大化 --rollout.micro_batch_size，最小化 vLLM TP 大小
2. 训练阶段：最大化 --train.micro_batch_size，启用 --ds.packing_samples
3. vLLM：始终使用 --vllm.sync_backend nccl

📖 更多详情：性能调优文档

使用 OpenRLHF 的公司和组织

• Google
• ByteDance
• Tencent
• Alibaba
• Baidu
• China Telecom
• Vivo
• Allen AI
• NexusFlow
• Jülich Supercomputing Centre (JSC)
• Berkeley Starling Team
• M-A-P
• ...

加入我们

如何加入？

1. 发送电子邮件至 janhu9527@gmail.com 或加入 GitHub Organization。请包含以下详细信息：
   • 您的姓名
   • 您的 GitHub 用户名
   • 您感兴趣的领域
   • 您与 NLP 和/或 AI 相关的技能和经验
2. 您也可以通过官方 GitHub OpenRLHF ↗ 项目页面加入我们。只需创建一个关于您贡献兴趣的 issue，我们会回复您。

您可以做什么？

1. 加入团队并参与 OpenRLHF 项目的开发。
2. 通过提交 pull request 为项目做出贡献。
3. 帮助改进文档、修复错误或创建新功能。
4. 分享项目并帮助我们发展社区。

赞助我们

您的赞助可以帮助我们维护和改进 OpenRLHF。如果您觉得这个项目有用，请考虑赞助我们。您可以在 Open Collective ↗ 上赞助我们。

Star 历史

贡献者

非常感谢所有贡献者！如果您想贡献，请随时提交 pull request 或创建 issue。

参考文献与致谢

我们要感谢以下项目和组织对 AI 和 NLP 领域的贡献：

• Hugging Face Transformers ↗
• OpenAI GPT ↗
• LLaMA ↗
• DeepSpeed ↗
• Ray ↗

我们的项目还要感谢 ColossalChat 和 DeepSpeedChat。在项目早期，我们参考了他们的代码设计。我们的项目要感谢 Netmind.AI 为开发 ring attention 提供的 GPU 支持。

（2024/7）我们的 GitHub 组织已从 OpenLLMAI 更改为 OpenRLHF。

引用

OpenRLHF

@article{hu2024openrlhf,
  title={OpenRLHF: An Easy-to-use, Scalable and High-performance RLHF Framework},
  author={Jian Hu and Xibin Wu and Zilin Zhu and Xianyu and Weixun Wang and Dehao Zhang and Yu Cao},
  journal={arXiv preprint arXiv:2405.11143},
  year={2024}
}

REINFORCE++-baseline

@article{hu2026reinforce++,
  title={Reinforce++: A simple and efficient approach for aligning large language models},
  author={Hu, Jian},
  journal={arXiv preprint arXiv:2501.03262},
  year={2026}
}

OpenRLHF © 2026 OpenRLHF. All Rights Reserved.