安装与依赖

2.1 装之前要先承认的事

verl 不是装一个 pip 包就完事的"应用层框架"，它本质上是一组 Ray Actor 编排 + 训练后端 + 采样后端的集成器。这件事带来两个后果：

• 必须有一个能跑的 Ray 集群（单机也可以）；
• 必须先装好 训练后端（FSDP-based PyTorch 或 Megatron-Core）和 采样后端（vLLM / SGLang）。

仓库的依赖矩阵很复杂，docker/ 目录下针对不同组合都有现成 Dockerfile：

docker/
├── Dockerfile.stable.sglang
├── Dockerfile.stable.trtllm
├── Dockerfile.stable.vllm
├── verl0.4-cu124-torch2.6-fa2.7.4
├── verl0.5-cu126-torch2.7-fa2.7.4
├── verl0.5-cu126-torch2.7.1-fa2.8.0
├── verl0.5-preview-cu128-torch2.7.1-fa2.8.0
├── verl0.6-cu128-torch2.8.0-fa2.7.4
├── verl0.6.1-experimental
├── ascend/         # 昇腾 NPU
├── aws/            # AWS 优化版
└── rocm/           # AMD ROCm

对新手强烈建议直接拉对应 Docker 镜像，不要自己装。

2.2 硬性依赖（来自 requirements.txt）

2.3 推荐安装路线

路线 A：Docker 镜像（最省心）

# 拉最新稳定版 vLLM 后端
docker pull verlai/verl:app-verl0.6-cu128-torch2.8.0-fa2.7.4

# 启动容器（共享主机 IPC / GPU / 网络）
docker run --gpus all -it --rm --ipc=host --net=host \
  -v $(pwd):/workspace \
  verlai/verl:app-verl0.6-cu128-torch2.8.0-fa2.7.4 bash

# 进容器后克隆代码（如果镜像没自带）
cd /workspace
git clone https://github.com/verl-project/verl.git
cd verl
pip install -e .

路线 B：源码 + venv

# 1. 装 PyTorch（CUDA 12.4 / 12.6 / 12.8 三选一）
pip install torch==2.7.1 torchvision --index-url https://download.pytorch.org/whl/cu126

# 2. 装 FlashAttention
pip install flash-attn==2.8.0 --no-build-isolation

# 3. 克隆 verl 并装
git clone https://github.com/verl-project/verl.git
cd verl
git submodule update --init --recursive recipe       # ★ recipe 是独立子仓
pip install -e .

# 4. 装采样后端（任选其一）
pip install vllm==0.8.4                              # vLLM
# 或
pip install "sglang[all]"                            # SGLang

# 5. 训练后端如要走 Megatron 路径
pip install megatron-core                            # 详见第 6 章

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

本项目已克隆 verl 到 repos/verl/（commit 9c38b8bb1876）：

cd /Users/zjw/Documents/LLM/train/repos/verl
git submodule update --init --recursive recipe
pip install -e .

2.4 NPU / ROCm / AWS 特殊镜像

2.5 recipe 子仓库

README 提到 recipe/ 已经被拆成独立仓库 + git submodule。这意味着：

• clone verl 后必须 git submodule update --init --recursive recipe 才能拿到 recipe；
• recipe 里有大量"业界 R1/DAPO/RLHF 训练 recipe"参考。新手通常先从这看起。

2.6 验证安装

# 1. import 不报错
python -c "import verl; print(verl.__version__)"

# 2. Ray 能起来
python -c "import ray; ray.init(); print(ray.available_resources())"

# 3. 训练入口能识别
python -m verl.trainer.main_ppo --help | head -20

# 4. vLLM 后端能 import
python -c "import vllm; print(vllm.__version__)"

# 5. 跑 unit test（约 5 分钟）
pytest tests/test_protocol.py -x

2.7 启动期 / 第一次跑训练前的最小自检

2.8 装不上的常见原因

2.9 真实 import 体检脚本

ds_report 那种"一键体检"verl 没有等价物，但下面这串 import 检测可以代替。把它存成 check_verl_env.py：

import importlib, sys

CORE = [
    ("verl",                  None,  "✗ 核心包没装"),
    ("ray",                  "2.40", "✗ ray[default] 缺；分布式起不来"),
    ("hydra",                 None,  "✗ Hydra 没装；配置系统不可用"),
    ("tensordict",            None,  "✗ tensordict 缺；DataProto 用不了"),
    ("torch",                 "2.6", "✗ torch 缺或太老"),
    ("transformers",          None,  "✗ HF 模型加载缺"),
]
ROLLOUT = [
    ("vllm",                  None,  "○ vLLM 后端未装"),
    ("sglang",                None,  "○ SGLang 后端未装"),
    ("tensorrt_llm",          None,  "○ TRT-LLM 后端未装"),
]
TRAIN = [
    ("torch.distributed.fsdp", None, "○ FSDP 不可用（torch 太老）"),
    ("megatron.core",          None, "○ Megatron-Core 未装；用不了 megatron 路径"),
    ("liger_kernel",           None, "○ liger_kernel 未装；fused 算子缺"),
    ("flash_attn",             None, "○ flash-attn 未装；Attention 慢"),
]

def chk(group, items):
    print(f"\n== {group} ==")
    for mod, ver, msg in items:
        try:
            m = importlib.import_module(mod)
            v = getattr(m, "__version__", "?")
            print(f"  {mod:<28} [OK] {v}")
        except Exception as e:
            print(f"  {mod:<28} {msg}   ({e.__class__.__name__})")

chk("Core (必须 OK)", CORE)
chk("Rollout 后端（至少一个）", ROLLOUT)
chk("训练后端 / 加速", TRAIN)

运行 python check_verl_env.py，关注：

• Core 段必须全 OK，缺一个都跑不起来；
• Rollout 段至少一个 OK，vllm 是最常见选择；
• flash_attn 不装训练也能跑，但 attention 慢 2-4×，强烈建议装。

2.10 关键环境变量速查

verl 启动期会去读一组环境变量。第一次跑训练前先扫一眼这张表，省得后面跟着 hang / OOM 撞墙：

这些变量被 verl/trainer/constants_ppo.py 里 PPO_RAY_RUNTIME_ENV 注入到所有 Ray worker 里——本地 shell 设了的会优先（get_ppo_ray_runtime_env() line 50 起会跳过已存在的）。