# OpenRLHF
**Repository Path**: goddessluboyan/OpenRLHF
## Basic Information
- **Project Name**: OpenRLHF
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
[ English | 中文 | 日本語 ]
OpenRLHF 是**首个**结合 **Ray + vLLM 分布式架构**与**统一 Agent 设计范式**的高性能、生产就绪的开源 RLHF 框架，用于可扩展和可扩展的人类反馈强化学习。
📚 **了解更多**：[文档](https://openrlhf.readthedocs.io/) | [PPT](https://docs.google.com/presentation/d/1JRhB1d7csofx0PIZBmfyBdMluxNd5JLPpUHrrvVhGnk/edit?usp=sharing) | [技术报告](https://www.researchgate.net/publication/393414548_OpenRLHF_An_Easy-to-use_Scalable_and_High-performance_RLHF_Framework) | [视频](https://www.bilibili.com/video/BV1dv2jBxEQG/)
## 📖 目录
- [🗞️ 新闻](#新闻)
- [🏗️ 架构基础](#架构基础ray--vllm-分布式) - Ray + vLLM + DeepSpeed 分布式基础设施
- [🎯 设计范式](#设计范式基于-agent-的执行) - 统一的 Agent 执行流程
- [🚀 RL 算法](#最先进的-rl-算法) - PPO、REINFORCE++、GRPO、RLOO
- [📋 特性概览](#全面特性) - 完整的 RLHF 流程能力
- [🎬 快速开始](#快速开始) - 安装和典型工作流
- [🎓 训练指南](#监督微调) - SFT、奖励模型、RL 训练
- [🎯 单轮 Agent](#单轮-agent强化微调与自定义奖励) - 自定义奖励函数
- [🤖 多轮 Agent](#多轮-agent复杂环境交互) - 复杂环境
- [🔧 高级主题](#高级主题) - LoRA、性能调优
---
## 新闻
展开新闻
- [2026/4] OpenRLHF 0.10 新增 **多轮 VLM RL** — 支持 prompt 和环境反馈（如截图）中均包含图像的多步交互。示例：[vlm_multiturn_agent.py](./examples/python/vlm_multiturn_agent.py)
- [2026/4] OpenRLHF 0.10 新增 **VLM（视觉语言模型）RLHF 支持** — 支持 Qwen3.5 等 VLM 的端到端图像输入训练。训练脚本：[train_vlm_math_hybrid_engine.sh](./examples/scripts/train_vlm_math_hybrid_engine.sh)
- [2026/2] [ProRL V2](https://developer.nvidia.com/blog/scaling-llm-reinforcement-learning-with-prolonged-training-using-prorl-v2/) 使用 REINFORCE++-baseline 通过长期 RL 训练训练最先进的 1.5B 推理模型。训练脚本：[train_prorlv2_math_hybrid_engine.sh](./examples/scripts/train_prorlv2_math_hybrid_engine.sh)
- [2026/10] [ScaleRL](https://arxiv.org/abs/2510.13786) 验证了 REINFORCE++-baseline 在大规模训练场景中的有效性。发布 [REINFORCE++ PPT](https://docs.google.com/presentation/d/1stieP_3PM1z4Hq1YWR3GywFkxcHEAlstXMaS23KlGN4)
- [2026/6] [Magistral](https://mistral.ai/static/research/magistral.pdf) 使用与 REINFORCE++-baseline 非常相似的方法训练推理模型。
- [2026/5] [MARTI](https://github.com/TsinghuaC3I/MARTI) 作为 OpenRLHF 的分支发布。它旨在通过集成中心化多智能体交互与分布式策略训练来训练基于 LLM 的多智能体系统。
- [2026/5] OpenRLHF 0.8.0 支持通过 `--train.async_enable` 启用异步 RLHF 训练，并通过 `--train.agent_func_path` 启用异步 Agent RLHF。可运行示例见 [train_reinforce_baseline_ray_agent_async.sh](./examples/scripts/train_reinforce_baseline_ray_agent_async.sh)。
- [2026/4] 发布博客 [Accelerating RLHF with vLLM, Best Practice from OpenRLHF](https://blog.vllm.ai/2026/04/23/openrlhf-vllm.html)
- [2026/4] Clean OpenRLHF：基于单控制器和统一打包样本重构了源代码
- [2026/3] CMU [高级自然语言处理 2026 春季](https://cmu-l3.github.io/anlp-spring2026/)课程使用 OpenRLHF 作为 RLHF 框架教学案例。
- [2026/2] [Logic-RL](https://arxiv.org/abs/2502.14768) 和 [PRIME](https://arxiv.org/abs/2502.01456) 证明 REINFORCE++ 相比 GRPO 更稳定，比 PPO 更快。
- [2026/2] [LMM-R1](https://github.com/TideDra/lmm-r1) 是 OpenRLHF 的分支，旨在为多模态任务上的 DeepSeek-R1 复现提供高性能 RL 基础设施。
- [2026/2] MIT 和微软使用 OpenRLHF 提出 [On the Emergence of Thinking in LLMs I: Searching for the Right Intuition](https://arxiv.org/pdf/2502.06773)
- [2026/1] HKUST 使用 OpenRLHF 复现了[小模型上的 DeepSeek-R1-Zero 和 DeepSeek-R1 训练](https://github.com/hkust-nlp/simpleRL-reason)
- [2024/12] 我们"提出"了😊 [REINFORCE++: A Simple and Efficient Approach for Aligning Large Language Models](https://www.researchgate.net/publication/387487679_REINFORCE_An_Efficient_RLHF_Algorithm_with_Robustnessto_Both_Prompt_and_Reward_Models)。
- [2024/12] 我们在 [Notion 博文](https://hijkzzz.notion.site/unraveling-rlhf-and-its-variants-engineering-insights#147d9a33ecc9806090f3d5c749d31f05)中分析了 PPO、REINFORCE++、GRPO 和 RLOO。
- [2023/8] OpenRLHF 开源。
---
## 🏗️ 架构基础：Ray + vLLM 分布式
OpenRLHF 是**首个**基于 Ray + vLLM 分布式架构构建的 RLHF 框架，可高效地跨 GPU 编排多个组件：
### 核心基础设施组件
**Ray - 分布式调度器和控制器**
OpenRLHF 利用 [Ray](https://github.com/ray-project/ray) 实现高效的分布式调度。它将 Actor、Reward、Reference 和 Critic 模型分布到不同的 GPU 上，支持训练高达 **70B+ 参数**的模型。
**混合引擎调度**：所有模型和 vLLM 引擎可以共享 GPU 资源，最大限度地减少空闲时间并提高 GPU 利用率。这允许在有限的硬件上运行完整的 RLHF 流程。
**vLLM - 高性能推理引擎**
RLHF 训练中 **80% 的时间**花在样本生成上。通过 [vLLM](https://github.com/vllm-project/vllm) 与自动张量并行（AutoTP）和流水线并行（PP），OpenRLHF 提供高吞吐量、内存高效的生成。
**DeepSpeed - 内存高效训练**
基于 [DeepSpeed](https://github.com/deepspeedai/DeepSpeed) ZeRO-3、[deepcompile](https://github.com/deepspeedai/DeepSpeed/blob/master/blogs/deepcompile/README.md)、[AutoTP](https://github.com/deepspeedai/DeepSpeed/blob/master/blogs/huggingface-tp/README.md) 和 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 等 │
└───────────────────┘
```
### 核心设计原则
展开核心设计原则
| 原则 | 描述 | 优势 |
|------|------|------|
| **Token-in-Token-out** | 所有采样产生 token 级轨迹 | 零文本级不匹配 |
| **统一接口** | 所有模式使用相同的 `AgentExecutorBase` API | 一个标志切换模式 |
| **算法无关** | RL 算法（PPO、REINFORCE++ 等）与 Agent 执行器解耦 | 任何算法适用于任何模式 |
| **可扩展** | 轻松插入自定义奖励/环境 | 快速实验 |
| **生产就绪** | 支持同步/异步/混合引擎 | 从研究到部署 |
### 两种执行模式（与 RL 算法正交）
Agent 执行模式与您选择的 RL 算法**独立**。您可以将**任何算法**（PPO、REINFORCE++、GRPO 等）与**任何执行模式**配合使用：
| 模式 | 使用场景 | 接口 | 复杂度 |
|------|---------|------|--------|
| **单轮** | 标准 RLHF、自定义奖励函数 | 可选 `reward_func()` | ⭐ 默认（99% 用例）|
| **多轮** | 多步推理、交互式环境 | `reset()` + `step()` | ⭐⭐ 高级 |
---
## 🚀 最先进的 RL 算法
OpenRLHF 实现了 **PPO、REINFORCE++、REINFORCE++-baseline、GRPO、RLOO**，采用受实践指南和社区最佳实践启发的高级优化技巧。
**关键设计**：RL 算法与 Agent 执行模式**解耦**。所有算法都可以与单轮和多轮 Agent 执行器无缝配合，通过统一的 token-in-token-out 流程运行，确保行为一致。
展开算法对比表
| 算法 | `--algo.advantage.estimator` | 关键特性 | 最佳用例 |
|------|-------------------------|---------|---------|
| **PPO** | (默认) | 完整 critic 网络 | 稳定训练，成熟结果 |
| **REINFORCE++** | `reinforce` | 无 critic 的 PPO 技巧 | 高效训练，更少内存 |
| **REINFORCE++-baseline** | `reinforce_baseline` | 均值奖励基线 | 推理任务（RLVR），对奖励尺度鲁棒 |
| **RLOO** | `rloo` | Per-token KL + PPO-clip | 多样本训练 |
| **GRPO** | `group_norm` | 组归一化 | 基于批次的训练 |
| **Dr. GRPO** | `dr_grpo` | 简化的 GRPO | 移除局部 `/std` 归一化 |
参考：[知乎文章](https://zhuanlan.zhihu.com/p/622134699) | [Notion 最佳实践](https://hijkzzz.notion.site/rlhf-implementation-tricks?v=158d9a33ecc98132bf9e000c39227361)
---
## 📋 全面特性
OpenRLHF 提供完整的 RLHF 流程，具有基于 Agent 的灵活性：
### 🎯 基于 Agent 的 RL 训练（核心创新）
展开基于 Agent 的 RL 训练细节
**单轮模式**（默认 - 99% 的用例）
- 每个提示单次生成
- 适用于所有 RL 算法：[PPO](./examples/scripts/train_ppo_ray_hybrid_engine.sh)、[REINFORCE++/baseline/GRPO/RLOO](./examples/scripts/train_reinforce_baseline_hybrid_engine.sh)
- [自定义奖励函数](./examples/scripts/train_ppo_with_reward_fn.sh)（`--reward.remote_url`）
- [混合引擎](./examples/scripts/train_ppo_ray_hybrid_engine.sh)以最大化 GPU 利用率
**多轮模式**（高级 - 交互式任务）
- 与环境反馈的多步交互
- 适用于所有 RL 算法
- [自定义 Agent 函数](./examples/scripts/train_reinforce_baseline_ray_agent_async.sh)（`--train.agent_func_path`）
- OpenAI 兼容服务器：参见 `examples/python/agent_func_openai_server_executor.py`（将 vLLM 封装为本地 OpenAI 服务器的 agent executor 示例）
- 异步流水线（`--train.async_enable`）提高吞吐量：[train_reinforce_baseline_ray_agent_async.sh](./examples/scripts/train_reinforce_baseline_ray_agent_async.sh)
### 🎓 监督训练和偏好学习
展开监督训练与偏好学习表
| 方法 | 脚本 | 描述 |
|------|------|------|
| **SFT** | [train_sft.sh](./examples/scripts/train_sft.sh) | 带打包的监督微调 |
| **DPO/IPO/cDPO** | [train_dpo_llama.sh](./examples/scripts/train_dpo_llama.sh) | 直接偏好优化 |
| **奖励模型** | [train_rm.sh](./examples/scripts/train_rm.sh) | 训练奖励模型 |
### ⚡ 高级能力
展开高级能力
**效率优化**
- 所有训练模式的样本打包（`--ds.packing_samples`）
- 快速生成的 vLLM 加速（`--vllm.num_engines`）
- DAPO [动态过滤](./examples/scripts/train_dapo_ray_hybrid_engine.sh)（`--algo.dynamic_filtering_enable`）
- 🎲 Dynamic Sampling：对每个 prompt 生成多条响应，并根据奖励函数/Agent 返回的 **0–1 `scores`** 信号进行过滤
- 开启：`--algo.dynamic_filtering_enable`
- 设置分数范围：`--algo.dynamic_filtering_range 0.0 1.0`
- 前置条件：`--rollout.n_samples_per_prompt > 1`，并提供 `--reward.remote_url`（奖励函数）或 `--train.agent_func_path`（Agent）
- 示例：`./examples/scripts/train_dapo_ray_hybrid_engine.sh`
**可扩展性**
- 张量并行的 DeepSpeed AutoTP（参见训练脚本中的 `--ds.tensor_parallel_size`）
- 长上下文的 [RingAttention](./examples/test_scripts/train_dpo_ring_llama.sh)（`--ds.ring_attn_size`）
- 使用 [SLURM](./examples/scripts/train_ppo_ray_slurm.sh) 的多节点训练
**模型支持**
- [VLM（视觉语言模型）](./examples/scripts/train_vlm_math_hybrid_engine.sh) — 支持单轮和[含图像反馈的多轮交互](./examples/python/vlm_multiturn_agent.py)（`--data.image_key`、`--data.max_images_per_prompt`）
- [LoRA/QLoRA](./examples/scripts/train_sft_mixtral_lora.sh)（`--ds.lora.rank`、`--ds.load_in_4bit`）
- [专家混合（MoE）](./examples/test_scripts/train_sft_moe.sh)（`--actor.aux_loss_coef`）
- FlashAttention（`--ds.attn_implementation`）
- HuggingFace 聊天模板（`--data.apply_chat_template`）
**优化器**
- AdamW（默认）：`--{actor,critic}.optim adam --{actor,critic}.adam.lr 2e-6`
- [Muon](https://kellerjordan.github.io/posts/muon/)（需 DeepSpeed ≥ 0.18.2，仅作用于 2D 权重；embedding / head / 1D 参数走辅助 AdamW）：`--{actor,critic}.optim muon --{actor,critic}.muon.lr 1e-4 --{actor,critic}.muon.momentum 0.95`。Newton-Schulz 输出是尺度无关的，因此需通过 `--{actor,critic}.max_norm 0` 关闭全局梯度裁剪（Adam 默认的 `1.0` 会把 Muon 更新裁没）。
**奖励塑形**
- DAPO 风格超长惩罚（`--reward.overlong_buffer_len`、`--reward.overlong_penalty_factor`）——对超过 `max_new_tokens - overlong_buffer_len` 的响应进行软惩罚
- ProRL 风格截断惩罚（`--reward.stop_properly_penalty_coef`）——对 `finish_reason='length'` 的样本：`coef ∈ [0, 1]` 表示乘法缩放奖励；`coef < 0` 表示将奖励直接覆盖为该固定值（例如 `-0.5`）
**生产特性**
- Wandb（`--logger.wandb.key`）和 TensorBoard（`--logger.tensorboard_dir`）日志
- 检查点恢复（`--ckpt.load_enable`、`--ckpt.save_steps`）
- 基于评估指标保存最佳检查点（`--ckpt.best_metric_key`）
- 评估数据集（`--eval.dataset`、`--eval.temperature`、`--eval.n_samples_per_prompt`）——支持异步训练中的评估
- 多进程数据加载（`--data.dataloader_num_workers`，PPO/SFT/RM/DPO 均支持）
- PPO 可观测性：actor/critic grad-norm 以及各阶段耗时细分（`timing/make_experience`、`timing/ppo_train`、`timing/broadcast`、`timing/generation`、`timing/step_total`）
---
## 🎬 快速开始
### 安装
**推荐**：使用 Docker 以实现无忧设置
```bash
# 1. 启动 Docker 容器
docker run --runtime=nvidia -it --rm --shm-size="10g" --cap-add=SYS_ADMIN \
-v $PWD:/openrlhf nvcr.io/nvidia/pytorch:25.11-py3 bash
# 2. 清理冲突包
sudo pip uninstall xgboost transformer_engine flash_attn pynvml -y
# 3. 安装 OpenRLHF（选择一个）
pip install openrlhf # 基础
pip install openrlhf[vllm] # + vLLM 0.19.1（推荐）
pip install openrlhf[vllm_latest] # + 最新 vLLM
pip install openrlhf[vllm,ring,liger] # + 所有优化
```
**替代方案：从源码安装**
```bash
git clone https://github.com/OpenRLHF/OpenRLHF.git
cd OpenRLHF
pip install -e .
```
> [!TIP]
> 我们推荐 **vLLM 0.19.1+** 以获得最佳性能。参见 [Dockerfiles](./dockerfile/) 和 [Nvidia-Docker 安装脚本](./examples/scripts/nvidia_docker_install.sh)。
### 准备数据集
OpenRLHF 提供灵活的数据处理方法：
**关键参数**：
- `--data.input_key`：指定输入数据的 JSON 键名
- `--data.apply_chat_template`：使用 HuggingFace tokenizer 的[聊天模板](https://huggingface.co/docs/transformers/main/en/chat_templating)
- `--data.input_template`：自定义模板字符串（聊天模板的替代方案）
- `--data.prompt_probs` / `--data.dataset_probs`：混合多个数据集（例如 `0.1,0.4,0.5`）
- `--eval.dataset`：指定评估数据集路径
**聊天模板示例**：
```python
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)
# 输出: "[INST] Hello, how are you? [/INST]I'm doing great... [INST] I'd like to show off... [/INST]"
```
> [!NOTE]
> JSON 键选项因数据集类型而异。参见[奖励数据集](https://github.com/OpenRLHF/OpenRLHF/blob/main/openrlhf/datasets/reward_dataset.py#L10)、[SFT 数据集](https://github.com/OpenRLHF/OpenRLHF/blob/main/openrlhf/datasets/sft_dataset.py#L9)和[提示数据集](https://github.com/OpenRLHF/OpenRLHF/blob/main/openrlhf/datasets/prompts_dataset.py#L6)
### 监督微调
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](https://huggingface.co/OpenRLHF) 上提供了一些预训练检查点和数据集。
然后您可以使用我们在 [examples/scripts](./examples/scripts/) 目录中提供的启动脚本，或使用以下命令开始训练。
SFT 命令
```bash
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 # 继续预训练模式
```
### 奖励模型训练
奖励模型训练命令
```bash
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` 加载模型：
```python
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 执行（默认模式）以获得最佳性能：
```bash
# 在容器中启动 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'）
```
> [!TIP]
> **对于推理任务（RLVR）**：使用 `--algo.advantage.estimator reinforce_baseline` 用于 REINFORCE++-baseline——它对不同的奖励尺度具有鲁棒性。
> [!NOTE]
> **Ray 环境设置**：让 Ray 使用 `--runtime-env-json='{"setup_commands": ["pip install openrlhf[vllm]"]}'` 自动部署
> [!NOTE]
> **GPU 索引错误故障排除**：如果遇到 DeepSpeed GPU 设备设置问题，请设置 `export RAY_EXPERIMENTAL_NOSET_CUDA_VISIBLE_DEVICES=1`。
📚 **更多示例**：参见 [example/scripts](./examples/scripts/) 和[文档](https://openrlhf.readthedocs.io/en/latest/usage.html)
---
## 🎯 单轮 Agent：强化微调与自定义奖励
**单轮 Agent 执行**（默认模式）支持自定义奖励函数——非常适合无需训练奖励模型的强化微调。您可以提供一个 Python 函数来即时计算奖励，而不是使用预训练的奖励模型。
**适用于**：
- 基于规则的奖励（长度、格式、代码执行、数学验证）
- 外部 API 奖励（评判模型、编译器、测试套件）
- 混合奖励（组合多个信号）
### 示例：自定义奖励函数
```python
# 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(),
},
}
```
### 使用方法
```bash
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`。
> [!TIP]
> **使用案例**：代码生成（执行测试）、数学（验证解决方案）、格式化（检查结构）、多目标（组合多个信号）
📖 **完整示例**：[examples/scripts/train_ppo_with_reward_fn.sh](./examples/scripts/train_ppo_with_reward_fn.sh)
---
## 🤖 多轮 Agent：复杂环境交互
对于需要**多步交互**（推理链、带反馈的编码、游戏）的任务，OpenRLHF 提供**多轮 Agent 执行**模式。
### 构建自定义多轮 Agent
使用 `reset/step` 方法实现 `AgentInstanceBase`：
```python
# 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"
if done
else "\n\nHuman: [INCORRECT]\nPlease analyze the issues and try again.\n\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)
```
然后启动：
```bash
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`）
> [!NOTE]
> 对于完全自定义的 token 级执行，继承 `AgentExecutorBase` 并实现 `execute()`。此设计强制执行 **token-in-token-out 原则**以保持采样和训练一致。
> [!WARNING]
> 异步训练可能会影响训练稳定性。仅在吞吐量至关重要且收敛已验证时使用。
📚 **示例**：
- 单轮：[train_ppo_ray_hybrid_engine.sh](./examples/scripts/train_ppo_ray_hybrid_engine.sh)
- 自定义奖励：[train_ppo_with_reward_fn.sh](./examples/scripts/train_ppo_with_reward_fn.sh)
- 多轮：[train_reinforce_baseline_ray_agent_async.sh](./examples/scripts/train_reinforce_baseline_ray_agent_async.sh)
- 多轮 VLM（图像反馈）：[vlm_multiturn_agent.py](./examples/python/vlm_multiturn_agent.py)
- OpenAI Agent Server：[agent_func_openai_server_executor.py](./examples/python/agent_func_openai_server_executor.py)
---
## 🔧 高级主题
### LoRA：合并适配器
使用 LoRA/QLoRA 时，OpenRLHF 仅保存适配器权重。要部署或继续训练，请将适配器与基础模型合并：
```bash
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 提供清晰的取舍旋钮：
| 模式 | 相关参数 | 特性 | 适用场景 |
|------|---------|------|---------|
| **混合引擎（colocated）** | `--train.colocate_all`
`--vllm.enable_sleep`
`--ds.enable_sleep` | **最稳定** ——严格 on-policy，每次 rollout 使用最新权重，生成→训练串行执行 | 研究、对 off-policy 敏感的 RL 算法、复现、配方验证 |
| **异步训练** | `--train.async_enable`
`--train.async_queue_size N` | **最快** ——生成与训练并行执行，通过 `--train.async_queue_size` 调控异步程度（越大越 off-policy） | 收敛已验证后的生产吞吐场景 |
| **异步 + 部分 rollout** | `--train.async_enable`
`--train.partial_rollout_enable` | **最大化重叠** ——使用 vLLM pause/resume 替代加锁，in-flight 样本可能混合新旧权重；异步程度最激进 | 进一步压榨异步吞吐；建议搭配 `--algo.advantage.is_correction_enable` |
#### ⚡ 其他速度优化
| 优化 | 标志 | 何时使用 |
|------|------|---------|
| **样本打包** | `--ds.packing_samples` | 始终（尤其是训练） |
| **动态批次** | `--train.dynamic_batch_enable` | 可变序列长度 |
| **DeepCompile** | `--ds.deepcompile` | PyTorch 2.0+ |
| **重叠通信** | `--ds.overlap_comm` | GPU 内存充足 |
| **前缀缓存** | vLLM 配置 | `n_samples_per_prompt` > 1 |
| **生成过采样** | `--rollout.vllm_generate_batch_size > --rollout.batch_size` | 异步模式下摊薄生成开销 / 喂养动态过滤 |
#### 💾 内存管理
**当您有足够内存时**：
- ✅ 禁用 `--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`
> [!TIP]
> **快速开始模板**：对于 8x A100（80GB），尝试混合引擎 + `--vllm.gpu_memory_utilization 0.5` + `--train.colocate_all`
📖 **更多详情**：[性能调优文档](https://openrlhf.readthedocs.io/en/latest/performance.html)
## 使用 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](https://github.com/OpenRLHF)。请包含以下详细信息：
- 您的姓名
- 您的 GitHub 用户名
- 您感兴趣的领域
- 您与 NLP 和/或 AI 相关的技能和经验
2. 您也可以通过官方 GitHub [OpenRLHF ↗](https://github.com/OpenRLHF/OpenRLHF) 项目页面加入我们。只需创建一个关于您贡献兴趣的 issue，我们会回复您。
**您可以做什么？**
1. 加入团队并参与 OpenRLHF 项目的开发。
2. 通过提交 pull request 为项目做出贡献。
3. 帮助改进文档、修复错误或创建新功能。
4. 分享项目并帮助我们发展社区。
## 赞助我们
您的赞助可以帮助我们维护和改进 OpenRLHF。如果您觉得这个项目有用，请考虑赞助我们。您可以在 [Open Collective ↗](https://opencollective.com/OpenRLHF) 上赞助我们。
## Star 历史
[](https://star-history.com/#OpenRLHF/OpenRLHF&Date)
## 贡献者
非常感谢所有贡献者！如果您想贡献，请随时提交 pull request 或创建 issue。
## 参考文献与致谢
我们要感谢以下项目和组织对 AI 和 NLP 领域的贡献：
- [Hugging Face Transformers ↗](https://github.com/huggingface/transformers)
- [OpenAI GPT ↗](https://github.com/openai/gpt-3)
- [LLaMA ↗](https://llama.meta.com/)
- [DeepSpeed ↗](https://github.com/microsoft/DeepSpeed)
- [Ray ↗](https://github.com/ray-project/ray)
我们的项目还要感谢 [ColossalChat](https://github.com/hpcaitech/ColossalAI/tree/main/applications/ColossalChat) 和 [DeepSpeedChat](https://github.com/microsoft/DeepSpeedExamples/tree/master/applications/DeepSpeed-Chat)。在项目早期，我们参考了他们的代码设计。我们的项目要感谢 [Netmind.AI](https://www.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.*
