🚀 verl 框架安装与环境配置全攻略（避坑实践版）

1. 前言：为什么选择 verl？

verl 是一个高性能的大模型强化学习训练框架，特别适用于复现类似 Qwen3-4B Agent RL 的项目。它支持 DAPO 等前沿算法，并能与 SandboxFusion 物理沙箱深度集成，训练模型调用工具的能力。

---

2. 环境要求与基座搭建

在开始之前，确保你的硬件和基础软件满足以下要求，以获得最佳兼容性：

组件	推荐配置	说明
Python	3.12	官方推荐版本，性能更佳
CUDA	12.8	适配最新的算子编译
显卡	RTX 4090 或以上	建议显存 $\ge$ 24GB
存储	数据盘 $\ge$ 50GB	系统盘通常较小，建议将环境装在数据盘

第一步：建立数据盘软链接（保护系统盘）

很多云服务器系统盘仅 30GB。为了防止环境和模型挤爆系统盘，务必先在数据盘建立目录并重定向路径。

Bash

# 在数据盘建立目录
mkdir -p /root/rivermind-data/miniconda3
mkdir -p /root/rivermind-data/pip_cache
mkdir -p /root/rivermind-data/hf_cache

# 设置 Pip 缓存路径
export PIP_CACHE_DIR="/root/rivermind-data/pip_cache"
# 设置 HuggingFace/ModelScope 路径
export HF_HOME="/root/rivermind-data/hf_cache"
export MODELSCOPE_CACHE="/root/rivermind-data/hf_cache"

第二步：创建虚拟环境

Bash

conda create -n verl_env python=3.12 -y
conda activate verl_env

---

3. 核心工具链安装（按顺序执行）

安装顺序至关重要！ 错误的顺序会导致依赖库反复覆盖，最终引发算子报错。

第三步：安装 CUDA 编译器 (nvcc)

verl 的高性能算子（如 Flash-Attention）需要现场编译。如果系统不带 nvcc，直接在环境内安装：

Bash

conda install -c nvidia cuda-nvcc=12.8 cuda-toolkit=12.8 -y
# 必须手动指定 CUDA_HOME，否则编译时找不到编译器
export CUDA_HOME=$CONDA_PREFIX
export PATH=$CUDA_HOME/bin:$PATH

第四步：安装 vLLM (推理后端)

必须先安装 vLLM。它会自动匹配并下载最合适的 PyTorch 版本。

Bash

# 使用清华源加速
pip install vllm==0.8.3 --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple

第五步：编译 Flash-Attention（最难关口）

针对小容量系统盘，必须重定向临时编译目录，并限制并行线程以防宕机。

Bash

mkdir -p /root/rivermind-data/tmp
export TMPDIR=/root/rivermind-data/tmp

# 限制使用 8 个线程编译（防止内存溢出或 SSH 断连）
MAX_JOBS=8 pip install flash-attn --no-build-isolation --no-cache-dir

---

4. verl 框架源码安装

为了方便调试算法或自定义环境，建议以可编辑模式安装源码。

第六步：克隆并安装框架

Bash

cd /root/rivermind-data
git clone https://github.com/volcengine/verl.git
cd verl

# 使用 --no-deps 确保不会覆盖我们之前装好的 vLLM 和 Torch
pip install -e . --no-deps

# 手动补齐 verl 运行所需的轻量级依赖
pip install tensordict ray hydra-core pandas pyarrow transformers accelerate uvloop httpx -i https://pypi.tuna.tsinghua.edu.cn/simple

5. 项目实战：数据与模型准备

第七步：极速模型下载

使用 ModelScope（魔搭） 代替 HuggingFace，显著提升国内服务器下载速度。

Python

# 下载 Qwen3-4B 模型到数据盘
python -c "from modelscope import model_download; model_download('qwen/Qwen3-4B-Instruct', cache_dir='/root/rivermind-data/hf_cache')"

第八步：数据集预处理

运行 verl 自带脚本处理 ReTool-SFT 冷启动数据集：

Bash

python3 recipe/retool/retool_sft_preprocess.py \
    --local_dir /root/rivermind-data/datasets/raw/ReTool-SFT \
    --output_dir /root/rivermind-data/datasets/processed/sft

---

💡 避坑总结（CSDN 专属 Tips）

1. 504 Timeout 错误：通常是因为编译 flash-attn 时 CPU 负载过高或系统盘（/tmp）被塞满。解决方法是限流编译线程（MAX_JOBS）并重定向 TMPDIR。

2. No platform detected：无卡开机时 vLLM 报此警告是正常的，只要 nvcc -V 能显示 12.8 版本，训练时有 GPU 即可正常运行。

3. 可编辑模式安装：使用 pip install -e . 极大方便了研究者修改算法逻辑，而无需重新安装框架。