安装

要求

Python: 版本 >= 3.10
CUDA: 版本 >= 12.1

verl 支持多种后端。目前，提供以下配置：

FSDP 和 **Megatron-LM**（可选）用于训练。
SGLang, vLLM 和 TGI 用于推理生成。

后端引擎选择

训练：

我们推荐使用 FSDP 后端来研究、探索和原型化不同的模型、数据集和 RL 算法。FSDP 后端的使用指南可以在 FSDP Workers 中找到。

对于追求更高可扩展性的用户，我们推荐使用 Megatron-LM 后端。目前，我们支持 Megatron-LM v0.12.2。Megatron-LM 后端的使用指南可以在 Megatron-LM Workers 中找到。

推理：

对于推理，vllm 0.8.3 及更高版本已通过稳定性测试。我们建议开启环境变量 VLLM_USE_V1=1 以获得最佳性能。

对于 SGLang，请参阅 SGLang Backend 以获取详细的安装和使用说明。SGLang 推理正在大量开发中，并提供许多高级功能和优化。我们鼓励用户通过 SGLang Issue Tracker 报告任何问题或提供反馈。

对于 huggingface TGI 的集成，它通常用于调试和单 GPU 探索。

从 Docker 镜像安装

我们提供预编译的 Docker 镜像以方便快速设置。从这个版本开始，我们采用新的镜像发布层级以提高生产力和稳定性。

镜像类型分为三大类：

基础镜像 (Base Image)：不包含推理和训练框架，仅安装了基本依赖。可以直接在此基础上安装 vllm 或 SGLang，无需重新安装 torch 或 CUDA。
应用镜像 (Application Image)：稳定版本，预装了推理和训练框架。
社区镜像 (Community Image)：不稳定版本，包含最新的框架和功能。

前两种镜像托管在 dockerhub verlai/verl 仓库，而预览镜像托管在社区仓库。

Note

镜像版本与 verl 版本对应，例如，标签为 verl0.4 的镜像构建于 verl 版本 v0.4.x。

基础镜像

适用于 vLLM 和 sglang 的稳定基础镜像为 verlai/verl:base-verl0.5-cu126-cudnn9.8-torch2.7.1-fa2.7.4。已安装的包版本可以在标签中找到，Dockerfile 位于 docker/verl[version]-[packages]/Dockerfile.base。

基础镜像的更新不频繁，并且应用镜像可以在不重新安装基础包的情况下在其上构建。

应用镜像

从这个版本开始，我们区分了为 vLLM 和 SGLang 构建的镜像，因为像 Pytorch 和 FlashInfer 这样的依赖包存在差异。

提供 2 种类型的应用镜像：

vLLM 配合 FSDP 和 Megatron: verlai/verl:app-verl0.5-transformers4.55.4-vllm0.10.0-mcore0.13.0-te2.2
SGLang 配合 FSDP 和 Megatron: verlai/verl:app-verl0.5-transformers4.55.4-sglang0.4.10.post2-mcore0.13.0-te2.2

包含 Megatron 后端的 Docker 镜像可用于运行大型语言模型，如 Qwen/Qwen3-235B-A22B、deepseek-ai/DeepSeek-V3-0324 的后训练。有关更多详细信息，请参阅 Large Language Model Post-Training documentation。

应用镜像可以频繁更新，Dockerfile 位于 docker/verl[version]-[packages]/Dockerfile.app.[frameworks]。基于基础镜像，可以轻松构建具有所需推理和训练框架的自定义应用镜像。

社区镜像

社区镜像由社区提供，包括 vLLM 和 SGLang 的最新版本，可能包含实验性功能或配置。也适用于 AMD GPU（带 ROCM）或 AWS EFA 和 Sagemaker 等其他硬件或平台。

对于最新的 vLLM 配合 FSDP，请参阅 hiyouga/verl 仓库，最新版本为 hiyouga/verl:ngc-th2.6.0-cu126-vllm0.8.4-flashinfer0.2.2-cxx11abi0。

对于最新的 SGLang 配合 FSDP，请参阅 hebiaobuaa/verl 仓库，最新版本为 hebiaobuaa/verl:app-verl0.5-sglang0.4.9.post6-mcore0.12.2-te2.2，由 SGLang RL Group 提供。

对于最新的 vLLM 配合 Megatron，请参阅 iseekyan/verl 仓库，最新版本为 iseekyan/verl:nemo.gptoss_vllm0.11.0。

请查看 docker/ 目录下的文件以了解 NGC 基础镜像或如果您想自行构建。

请注意，对于带有 EFA 网络接口的 AWS 实例（Sagemaker AI Pod），您需要安装 EFA 驱动程序，如 docker/Dockerfile.extenstion.awsefa 所示。

通过 Docker 安装

拉取所需的 Docker 镜像并安装所需的推理和训练框架后，您可以按照以下步骤运行：

启动所需的 Docker 镜像并进入容器：

docker create --runtime=nvidia --gpus all --net=host --shm-size="10g" --cap-add=SYS_ADMIN -v .:/workspace/verl --name verl <image:tag> sleep infinity
docker start verl
docker exec -it verl bash

如果您使用提供的镜像，则只需安装 verl 本身，无需安装依赖项：

# 安装 nightly 版本（推荐）
git clone https://github.com/volcengine/verl && cd verl
pip3 install --no-deps -e .

[可选] 如果您希望在不同框架之间切换，可以使用以下命令安装 verl：

# 安装 nightly 版本（推荐）
git clone https://github.com/volcengine/verl && cd verl
pip3 install -e .[vllm]
pip3 install -e .[sglang]

从自定义环境安装

我们推荐使用 Docker 镜像以获得便利。但是，如果您的环境与 Docker 镜像不兼容，您也可以在 Python 环境中安装 verl。

Note

Dockerfile 提供了比本安装说明更详细的信息。您可以在每个 Dockerfile 中找到示例，例如 verl0.6-cu128-torch2.8.0-fa2.7.4 Dockerfile.base 。

先决条件

为了使训练和推理引擎能够更好地利用更快的硬件支持，需要 CUDA/cuDNN 和其他依赖项，其中一些依赖项在安装其他包时容易被覆盖，因此我们将它们放在安装后步骤中。

Note

以下安装步骤是最新 verl 版本的推荐配置。

如果您尝试自定义自己的环境，请忽略严格的限制。

我们需要安装以下先决条件：

CUDA: 版本 >= 12.4
cuDNN: 版本 >= 9.8.0
Apex

推荐使用高于 12.4 的 CUDA 版本，您可以参考 Docker 镜像，有关其他 CUDA 版本，请参阅 NVIDIA 官方网站。

# 切换到任何您喜欢的位置，不推荐在 verl 源代码目录中操作
wget https://developer.download.nvidia.com/compute/cuda/12.4.1/local_installers/cuda-repo-ubuntu2204-12-4-local_12.4.1-550.54.15-1_amd64.deb
dpkg -i cuda-repo-ubuntu2204-12-4-local_12.4.1-550.54.15-1_amd64.deb
cp /var/cuda-repo-ubuntu2204-12-4-local/cuda-*-keyring.gpg /usr/share/keyrings/
apt-get update
apt-get -y install cuda-toolkit-12-4
update-alternatives --set cuda /usr/local/cuda-12.4

cuDNN 可以通过以下命令安装，有关其他 cuDNN 版本，请参阅 NVIDIA 官方网站。

# 切换到任何您喜欢的位置，不推荐在 verl 源代码目录中操作
wget https://developer.download.nvidia.com/compute/cudnn/9.8.0/local_installers/cudnn-local-repo-ubuntu2204-9.8.0_1.0-1_amd64.deb
dpkg -i cudnn-local-repo-ubuntu2204-9.8.0_1.0-1_amd64.deb
cp /var/cudnn-local-repo-ubuntu2204-9.8.0/cudnn-*-keyring.gpg /usr/share/keyrings/
apt-get update
apt-get -y install cudnn-cuda-12

NVIDIA Apex 是 Megatron-LM 和 FSDP 训练所必需的。您可以通过以下命令安装它，但请注意此步骤可能花费很长时间。建议设置 MAX_JOBS 环境变量以加速安装过程，但不要设置得太大，否则内存会过载，您的机器可能会挂起。

# 切换到任何您喜欢的位置，不推荐在 verl 源代码目录中操作
git clone https://github.com/NVIDIA/apex.git && \
cd apex && \
MAX_JOB=32 pip install -v --disable-pip-version-check --no-cache-dir --no-build-isolation --config-settings "--build-option=--cpp_ext" --config-settings "--build-option=--cuda_ext" ./

安装依赖项

Note

我们建议使用一个全新的 conda 环境来安装 verl 及其依赖项。

请注意，推理框架通常对您的 pytorch 版本有严格限制，并且如果您不足够注意，它们会直接覆盖您已安装的 pytorch。

作为对策，建议先安装推理框架及其所需的 pytorch。对于 vLLM，如果您希望使用现有的 pytorch，请遵循其官方说明 Use an existing PyTorch installation 。

首先，为了管理环境，我们推荐使用 conda：

conda create -n verl python==3.10
conda activate verl

然后，在 verl 中执行我们提供的 install.sh 脚本：

# 确保您已激活 verl conda 环境
# 如果您需要与 megatron 一起运行
bash scripts/install_vllm_sglang_mcore.sh
# 或者如果您只需要与 FSDP 一起运行
USE_MEGATRON=0 bash scripts/install_vllm_sglang_mcore.sh

如果在这一步遇到错误，请检查脚本并手动按照脚本中的步骤进行。

安装 verl

要安装最新版本的 verl，最好的方法是克隆并从源代码安装。然后您可以修改我们的代码来自定义自己的后训练作业。

git clone https://github.com/volcengine/verl.git
cd verl
pip install --no-deps -e .

安装后

请确保已安装的包在安装其他包时未被覆盖。

值得检查的包包括：

torch 和 torch 系列
vLLM
SGLang
pyarrow
tensordict
nvidia-cudnn-cu12: 用于 Magetron 后端

如果在运行 verl 时遇到有关包版本的问题，请更新过时的包。

安装 AMD GPU - ROCM 内核支持

当您在 AMD GPU（MI300）上使用 ROCM 平台运行时，您不能使用之前的快速入门来运行 verl。您应该按照以下步骤构建 Docker 镜像并运行它。如果您在使用 AMD GPU 运行 verl 时遇到任何问题，请随时与我联系 - Yusheng Su。

查找 AMD ROCm 的 Dockerfile：docker/Dockerfile.rocm 

# 在 repo 目录中构建 Docker 镜像：
# docker build -f docker/Dockerfile.rocm -t verl-rocm:03.04.2015 .
# docker images # 您可以找到已构建的 Docker 镜像
FROM rocm/vllm:rocm6.2_mi300_ubuntu20.04_py3.9_vllm_0.6.4

# 设置工作目录
# WORKDIR $PWD/app

# 设置环境变量
ENV PYTORCH_ROCM_ARCH="gfx90a;gfx942"

# 安装 vllm
RUN pip uninstall -y vllm && \
    rm -rf vllm && \
    git clone -b v0.6.3 https://github.com/vllm-project/vllm.git && \
    cd vllm && \
    MAX_JOBS=$(nproc) python3 setup.py install && \
    cd .. && \
    rm -rf vllm

# 复制整个项目目录
COPY . .

# 安装依赖项
RUN pip install "tensordict<0.6" --no-deps && \
    pip install accelerate \
    codetiming \
    datasets \
    dill \
    hydra-core \
    liger-kernel \
    numpy \
    pandas \
    datasets \
    peft \
    "pyarrow>=15.0.0" \
    pylatexenc \
    "ray[data,train,tune,serve]" \
    torchdata \
    transformers \
    wandb \
    orjson \
    pybind11 && \
    pip install -e . --no-deps

构建镜像

docker build -t verl-rocm .

启动容器

docker run --rm -it \
  --device /dev/dri \
  --device /dev/kfd \
  -p 8265:8265 \
  --group-add video \
  --cap-add SYS_PTRACE \
  --security-opt seccomp=unconfined \
  --privileged \
  -v $HOME/.ssh:/root/.ssh \
  -v $HOME:$HOME \
  --shm-size 128G \
  -w $PWD \
  verl-rocm \
  /bin/bash

如果您不想使用 root 模式并要求将您自己分配为用户，请在上面的 docker 启动脚本中添加 -e HOST_UID=$(id -u) 和 -e HOST_GID=$(id -g)。

目前，为 AMD GPU 运行的 verl 支持 FSDP 作为训练引擎，vLLM 和 SGLang 作为推理引擎。未来我们将支持 Megatron。

安装

要求

后端引擎选择

从 Docker 镜像安装

基础镜像

应用镜像

社区镜像

通过 Docker 安装

从自定义环境安装

先决条件

安装依赖项

安装 verl

安装后

安装 AMD GPU - ROCM 内核支持

查找 AMD ROCm 的 Dockerfile：docker/Dockerfile.rocm

构建镜像

启动容器

查找 AMD ROCm 的 Dockerfile：docker/Dockerfile.rocm 