安装与依赖：Ray + DeepSpeed + vLLM 三件套

装 OpenRLHF 比装 LLaMA-Factory / TRL 难一档，原因是它把 RLHF 训练拆成三种异构进程 （训练 / 采样 / 调度），每种进程都要依赖各自的底层库。任何一个版本对不上，启动就会 crash。 本章给你一份"版本钉死 + 三条安装路径"的最稳法。

2.1装之前要承认的事

OpenRLHF 不是单个 pip 包能装好的"应用层框架"，它是把三种进程 orchestrate 在一起的胶水：

这三家的版本要同时满足各自的 CUDA / PyTorch / Python 矩阵。仓库 requirements.txt 已经把关键版本钉死，不要随便升。

2.2硬性依赖（钉死的版本）

requirements.txt 关键行：

deepspeed==0.18.9
flash-attn==2.8.3
ray[default]==2.55.0
transformers==5.7.0
torch                # 不限制版本，跟着 PyTorch 自己装
peft
accelerate
huggingface_hub>=1.0.0
optree>=0.15.0
pynvml>=12.0.0
wandb
tensorboard

vLLM 没列在 requirements.txt，但 OpenRLHF 强依赖。需要单独装一个和 OpenRLHF 兼容的 vLLM 版本。当前基线版本对应：

2.3三条安装路线

路线 A：官方 Docker 镜像（推荐第一次用）

仓库 dockerfile 是官方维护的镜像构建脚本。最快的用法是直接 pull：

# Hugging Face 上有官方发的镜像
docker pull openrlhf/openrlhf:latest

# 启动容器
docker run --gpus all -it --rm --ipc=host --net=host \
    -v $(pwd):/workspace \
    -v ${HOME}/.cache/huggingface:/root/.cache/huggingface \
    openrlhf/openrlhf:latest bash

# 进容器后克隆代码
cd /workspace
git clone https://github.com/OpenRLHF/OpenRLHF.git
cd OpenRLHF
pip install -e .

路线 B：源码 pip 安装

# 1. 装好对应版 PyTorch
pip install torch==2.5.1 torchvision \
    --index-url https://download.pytorch.org/whl/cu126

# 2. 装 flash-attn（耗时 15-30 分钟）
MAX_JOBS=4 pip install flash-attn==2.8.3 --no-build-isolation

# 3. 装 vLLM（CUDA 版本要和 PyTorch 一致）
pip install vllm==0.10.0

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

# 5. 装 wandb（可选，但强烈建议）
wandb login

路线 C：从本地已克隆 repo 装

本项目已克隆到 repos/openrlhf/（commit 6c6056daa522）：

cd /Users/zjw/Documents/LLM/train/repos/openrlhf
pip install -e .

2.4验证安装

# 1. 包能 import
python -c "import openrlhf; print('OpenRLHF OK')"
python -c "import ray; print(ray.__version__)"
python -c "import vllm; print(vllm.__version__)"
python -c "import deepspeed; print(deepspeed.__version__)"
python -c "import flash_attn; print(flash_attn.__version__)"

# 2. Ray 单机能起来
ray start --head
ray status               # 看是否打印出 GPU 资源
ray stop

# 3. vLLM 能 generate
python -c "
from vllm import LLM
llm = LLM(model='Qwen/Qwen3-0.6B', gpu_memory_utilization=0.5)
print(llm.generate(['hello'])[0].outputs[0].text)
"

# 4. CLI 能识别
python -m openrlhf.cli.train_ppo_ray --help | head -30
python -m openrlhf.cli.train_sft --help | head -30

2.5硬件要求

注意：PPO 需要同时驻留 4 个模型（policy / reference / critic / reward），加上 vLLM rollout 的 KV cache， 显存峰值很容易是 SFT 的 4-6 倍。后面第 8 章会讲三种部署模式怎么省显存。

2.6装不上的常见原因

2.7装完后要扫一眼的几个文件

装好后第一次跑训练前，对照这些位置心里有数，能省后续大量时间：

2.8examples/scripts/ 速查（18 个生产级脚本）

OpenRLHF 不像 LLaMA-Factory 用 YAML，每个训练配置是一份 .sh 文件。先扫一眼有哪些，挑最像自己业务的那份直接改：

2.9examples/python/ 速查（自定义扩展）

"我想在训练中插自己的逻辑"——不动 OpenRLHF 源码，写这两类 .py 即可：

2.10关键环境变量

2.11Docker 用法（强烈推荐）

# 拉官方镜像（已装好 CUDA / DeepSpeed / vLLM / Ray）
docker pull openrlhf/openrlhf:latest

# 启动容器
docker run --rm -it --gpus=all --network host --ipc=host \
    -v $(pwd):/workspace \
    openrlhf/openrlhf:latest bash

# 容器里直接跑
cd /workspace
bash examples/scripts/train_ppo_ray_hybrid_engine.sh

"为什么强烈推荐 docker？" → OpenRLHF 的依赖关系（DeepSpeed/Flash-attn/vLLM/Ray 四件套）版本对齐极其严格，0.1.x 版本之间也常踩兼容性坑。镜像里这套已经过 CI 验证。

2.12这章带走的

• OpenRLHF 是"训练 + 采样 + 调度"三件套的胶水；
• 版本钉死：deepspeed==0.18.9、flash-attn==2.8.3、ray==2.55.0、transformers==5.7.0；
• 第一次用强烈建议拉 docker 镜像，不要自己装；
• 装完跑 4 条 import + Ray + vLLM 自检，都过了再开始训练；
• PPO 显存峰值 ≈ SFT 的 4-6 倍，做硬件规划要预留。