从下载到运行：verl完整流程图文教程

从下载到运行：verl完整流程图文教程

verl 是一个专为大型语言模型（LLMs）后训练设计的强化学习（RL）训练框架，由字节跳动火山引擎团队开源，是 HybridFlow 论文的工程落地实现。它不是面向终端用户的“开箱即用”工具，而是一个面向算法工程师和训练系统的生产级 RL 训练基础设施——这意味着它不提供网页界面或一键点击式操作，但提供了高度模块化、可扩展、与主流 LLM 生态深度兼容的底层能力。

本教程将带你从零开始，完成 verl 的本地环境准备、源码获取、依赖安装、基础验证，到成功运行一个最小可运行示例（mini PPO 训练循环）的全过程。全程不跳过任何关键细节，所有命令均可直接复制粘贴执行，所有报错均有对应排查说明。你不需要提前掌握强化学习理论，也不需要熟悉 PyTorch 分布式原理——只要你会用 Python 和命令行，就能走通这条路径。

重要提示：verl 是一个训练框架，不是推理模型或聊天应用。它不生成文本、不回答问题、不画图。它的核心价值在于：让你能高效地、可控地、规模化地对 LLM 进行 RLHF/GRPO 等后训练优化。请带着“我要训练自己的大模型”的目标来阅读本文。

1. 环境准备与系统要求

在动手前，请先确认你的硬件和软件环境是否满足基本门槛。verl 对资源有一定要求，但本教程会优先选择最低可行配置，确保绝大多数开发者工作站都能跑通。

1.1 硬件要求（最低可行）

• GPU：1 块 NVIDIA GPU（推荐 RTX 3090 / A10 / A100），显存 ≥ 24GB
  为什么？verl 默认启用 3D-HybridEngine，需同时加载 Actor、Critic、Ref Model、Reward Model 四个模型副本（即使共享权重），单卡 24GB 是启动 mini 示例的底线。
• CPU：≥ 8 核，主频 ≥ 2.5GHz
• 内存：≥ 64GB RAM
• 存储：≥ 100GB 可用空间（用于缓存 HuggingFace 模型、日志、临时数据）

注意：不支持 macOS 或 Windows 本地训练。verl 依赖 PyTorch 的 CUDA 后端、vLLM 的 GPU 推理引擎以及 FSDP 的分布式原语，这些组件在非 Linux 系统上无法稳定工作。请在 Ubuntu 22.04/20.04 或 CentOS 7+ 环境中操作。

1.2 软件依赖清单

快速验证命令（逐条执行，任一失败请暂停并解决）：

# 检查 Python 版本 python --version # 应输出 3.10.x 或 3.11.x # 检查 CUDA 是否可用 nvidia-smi # 应显示 GPU 列表和驱动版本 # 检查 PyTorch CUDA 支持 python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())" # 最后一行应输出 True

若torch.cuda.is_available()返回False，请立即检查：CUDA 驱动版本是否 ≥ 525、PyTorch 安装命令是否指定了cu121（如pip install torch==2.3.1+cu121 --index-url https://download.pytorch.org/whl/cu121）。

2. 下载 verl 源码与模型资源

verl 以开源项目形式发布，所有代码、配置、文档均托管在 GitCode（国内镜像）和 GitHub（主站）。由于模型权重文件较大（单个可达数 GB），我们采用分步下载策略，避免网络中断导致重试。

2.1 克隆主仓库（含代码与配置）

打开终端，执行以下命令：

# 创建工作目录 mkdir -p ~/verl-tutorial && cd ~/verl-tutorial # 克隆 verl 主仓库（使用国内 GitCode 镜像加速） git clone https://gitcode.com/GitHub_Trending/ve/verl.git cd verl # 初始化 Git LFS 并拉取大文件（关键！否则后续会报错找不到模型） git lfs install git lfs pull

为什么必须git lfs pull？
verl 仓库中examples/configs/目录下存放了预置的 YAML 配置文件，其中引用了 HuggingFace 上的模型 ID（如Qwen/Qwen2.5-VL-7B-Instruct）。但git clone默认只下载文本配置，不下载实际模型权重。git lfs pull会根据.gitattributes规则，从远程 LFS 服务器下载所有被标记为大文件的模型缓存索引，确保后续transformers库能正确定位并自动下载模型。

2.2 验证仓库完整性

执行以下命令，检查关键目录是否存在：

ls -l examples/configs/ppo/ # 应看到 ppo_mini.yaml, ppo_qwen2.yaml 等配置文件 ls -l verl/trainer/ # 应看到 main_ppo.py, main_grpo.py 等训练入口 ls -l verl/data/ # 应看到 dataset.py, sampler.py 等数据模块

若examples/configs/ppo/为空或报错No such file or directory，说明git lfs pull失败，请检查网络连接，并重试：

git lfs fetch --all && git lfs checkout

3. 安装 verl 及其核心依赖

verl 采用标准 Python 包管理方式，但因其深度集成 vLLM、FSDP、HuggingFace Transformers 等重型库，安装过程需格外注意依赖冲突。我们采用pip install -e（开发模式安装）确保代码修改即时生效，并规避全局包污染。

3.1 创建隔离虚拟环境（强烈推荐）

# 返回项目根目录 cd ~/verl-tutorial/verl # 创建并激活虚拟环境（Python 3.10） python -m venv .venv-verl source .venv-verl/bin/activate # 升级 pip，避免旧版 pip 无法解析复杂依赖 pip install --upgrade pip

3.2 安装 verl 本体（含子模块）

# 在 verl 项目根目录下执行 pip install -e ".[dev]"

该命令含义：
-e表示“editable mode”，即链接安装，修改verl/目录下的代码会立即反映在 Python 导入中；
".[dev]"表示安装setup.py中定义的dev依赖组，包含pytest,black,pre-commit等开发工具。

3.3 手动安装关键第三方依赖（规避版本冲突）

pip install -e ".[dev]"会自动安装大部分依赖，但以下三个库因版本敏感性高，需手动指定版本以确保兼容：

# 安装与 CUDA 12.1 兼容的 vLLM（verl 的 rollout 引擎） pip install vllm==0.6.3.post1 # 安装支持 FSDP 的 PyTorch 分布式扩展（verl 的 actor/critic 并行基础） pip install torchtune==0.2.4 # 安装最新版 HuggingFace Transformers（确保多模态模型支持） pip install transformers==4.45.0

版本选择依据：

• vllm==0.6.3.post1是目前唯一通过 verl CI 测试的 vLLM 版本，更高版本存在generateAPI 不兼容问题；
• torchtune==0.2.4提供了FSDPWrapPolicy的稳定实现，与 verl 的HybridEngine内存管理逻辑匹配；
• transformers==4.45.0修复了 Qwen2-VL 模型的图像预处理 bug，避免RuntimeError: expected scalar type Half but found Float。

3.4 验证安装结果

执行 Python 交互式命令，测试核心模块导入：

python -c "import verl; print(' verl 导入成功'); print('版本:', verl.__version__)" python -c "import vllm; print(' vllm 导入成功')" python -c "from torch.distributed.fsdp import FullyShardedDataParallel; print(' FSDP 导入成功')"

若全部输出... 成功，说明环境安装完成。若某条报错，请根据错误信息回溯：常见问题包括 CUDA 版本不匹配（重装 PyTorch）、vLLM 编译失败（重装并加--force-reinstall）、或torchtune与 PyTorch 版本不兼容（核对 torchtune 官方兼容表）。

4. 运行最小可验证示例（Mini PPO）

现在进入最激动人心的环节：让 verl 真正“动起来”。我们将运行examples/configs/ppo/ppo_mini.yaml—— 这是 verl 官方提供的最小化 PPO 训练配置，它仅使用 1 个 GPU、极小的 batch size（4）、且不加载真实大模型，而是用facebook/opt-125m（1.25 亿参数）作为占位模型进行全流程验证。它不产生高质量结果，但能 100% 走通从数据加载、rollout 生成、reward 计算、loss 计算到梯度更新的全部环节。

4.1 准备配置文件

进入配置目录，复制并编辑最小配置：

cd ~/verl-tutorial/verl/examples/configs/ppo/ cp ppo_mini.yaml ppo_mini_local.yaml

用你喜欢的编辑器（如nano或vim）打开ppo_mini_local.yaml，重点修改以下三处（其他保持默认）：

# === 修改点 1：指定本地模型路径（避免首次运行时联网下载大模型）=== actor_rollout_ref: model: path: "facebook/opt-125m" # ← 保持此行不变，opt-125m 是轻量模型 # ... 其他字段无需改动 # === 修改点 2：强制使用 CPU 进行 reward 计算（避免小模型在 GPU 上报错）=== reward_model: model: path: "facebook/opt-125m" device: "cpu" # ← 新增此行，将 reward model 放在 CPU 上 dtype: "float32" # === 修改点 3：关闭多卡并行（单卡模式）=== trainer: fsdp_config: use_fsdp: false # ← 设为 false，禁用 FSDP（单卡无需） ddp_config: use_ddp: false # ← 设为 false，禁用 DDP（单卡无需）

为什么这样改？
ppo_mini.yaml默认配置为多卡 FSDP 训练，但在单卡环境下会因process_group初始化失败而卡死。将其设为false后，verl 会自动降级为单进程训练，完美适配个人工作站。

4.2 执行训练命令

返回 verl 项目根目录，执行训练脚本：

cd ~/verl-tutorial/verl python -m verl.trainer.main_ppo \ --config-path examples/configs/ppo/ppo_mini_local.yaml \ --config-name ppo_mini_local

⏳预期耗时：首次运行约需 3–5 分钟（主要耗时在下载opt-125m模型权重，约 500MB）。后续运行秒级启动。

4.3 观察运行日志与关键输出

成功运行时，终端将滚动输出类似以下日志（已精简）：

[INFO] 2024-12-15 10:23:45,123 - verl.trainer.main_ppo - Starting PPO training... [INFO] 2024-12-15 10:23:47,456 - verl.data.dataset - Loading dataset from local path... [INFO] 2024-12-15 10:23:48,789 - verl.trainer.ppo_trainer - Initializing Actor model: facebook/opt-125m [INFO] 2024-12-15 10:23:52,334 - verl.trainer.ppo_trainer - Initializing Reward model on cpu [INFO] 2024-12-15 10:23:55,678 - verl.trainer.ppo_trainer - Starting rollout generation... [INFO] 2024-12-15 10:24:01,221 - verl.trainer.ppo_trainer - Generated 4 responses in 5.3s (throughput: 0.75 resp/s) [INFO] 2024-12-15 10:24:02,890 - verl.trainer.ppo_trainer - Calculating rewards... [INFO] 2024-12-15 10:24:03,455 - verl.trainer.ppo_trainer - Computing PPO loss... [INFO] 2024-12-15 10:24:04,112 - verl.trainer.ppo_trainer - Step 1 | Loss: 2.143 | KL: 0.012 | Reward: 0.87 [INFO] 2024-12-15 10:24:04,113 - verl.trainer.ppo_trainer - Saving checkpoint to outputs/ppo_mini_local/step_1

关键成功标志：

• 日志中出现Generated X responses in Y.s（表示 rollout 引擎正常工作）；
• 出现Step 1 | Loss: ...（表示 PPO 优化循环已启动）；
• 最后一行Saving checkpoint to ...（表示模型权重已成功保存）。

若卡在Initializing Actor model...超过 2 分钟，大概率是网络问题导致opt-125m下载失败。此时可手动下载：

# 创建 HuggingFace 缓存目录 mkdir -p ~/.cache/huggingface/hub/models--facebook--opt-125m # 从 HuggingFace 手动下载（使用浏览器访问以下链接并保存为 `resolve` 文件） # https://huggingface.co/facebook/opt-125m/resolve/main/config.json # https://huggingface.co/facebook/opt-125m/resolve/main/pytorch_model.bin # 保存至 ~/.cache/huggingface/hub/models--facebook--opt-125m/snapshots/xxxxxx/

5. 常见问题排查与调试技巧

在真实环境中，90% 的 verl 运行失败都源于环境配置偏差。以下是高频问题及一招解决法：

5.1 “ImportError: cannot import name 'xxx' from 'verl.xxx'”

原因：Python 解释器未在verl/目录下执行，或虚拟环境未激活。
解决：

cd ~/verl-tutorial/verl # 确保在项目根目录 source .venv-verl/bin/activate # 确保虚拟环境激活 python -c "from verl.trainer import main_ppo; print('OK')"

5.2 “RuntimeError: Expected all tensors to be on the same device”

原因：Actor 模型在 GPU，Reward 模型在 CPU（或反之），verl 未自动做设备同步。
解决：在配置文件中显式指定所有模型的device字段：

actor_rollout_ref: model: device: "cuda:0" reward_model: model: device: "cuda:0" # ← 与 actor 保持一致

5.3 “ConnectionResetError: [Errno 104] Connection reset by peer”（发生在 rollout 阶段）

原因：vLLM 的Engine初始化失败，通常因 CUDA 版本与 vLLM 不兼容。
解决：

• 降级 vLLM：pip install vllm==0.5.3（更稳定）；
• 或升级 CUDA 驱动至 535+，再重装vllm==0.6.3.post1。

5.4 训练速度极慢（< 0.1 resp/s）

原因：opt-125m模型虽小，但默认配置启用了flash_attn，在某些 GPU 上反而变慢。
解决：在配置文件中禁用：

actor_rollout_ref: rollout: engine_kwargs: vllm: enable_flash_attn: false # ← 新增此行

5.5 如何查看 verl 的详细架构图？

verl 项目根目录下有docs/文件夹，其中docs/architecture.md以 Mermaid 语法绘制了完整的 HybridFlow 数据流图。在 VS Code 中安装 Mermaid Preview 插件，即可实时渲染查看。

6. 下一步：从验证走向真实训练

恭喜你已成功运行 verl！但这只是万里长征第一步。接下来，你可以按此路径进阶：

6.1 替换为真实大模型（如 Qwen2.5-VL）

将ppo_mini_local.yaml中的模型路径改为：

actor_rollout_ref: model: path: "Qwen/Qwen2.5-VL-7B-Instruct" # ← 需要 7B 模型 reward_model: model: path: "Qwen/Qwen2.5-VL-7B-Instruct"

并确保 GPU 显存 ≥ 48GB（推荐双卡 A100）。首次加载会触发 HuggingFace 自动下载，约 15GB。

6.2 使用真实数据集（如 GSM8K）

替换配置中的data字段：

data: train_dataset_path: "gsm8k" # ← 直接使用 HuggingFace 数据集名 prompt_key: "question" response_key: "answer"

verl 会自动调用datasets.load_dataset("gsm8k")加载。

6.3 启用多卡训练（FSDP）

将配置中trainer.fsdp_config.use_fsdp设为true，并使用torchrun启动：

torchrun --nproc_per_node=2 -m verl.trainer.main_ppo \ --config-path examples/configs/ppo/ppo_qwen2.yaml

6.4 监控训练过程

verl 原生支持 TensorBoard。训练启动后，在另一终端执行：

tensorboard --logdir outputs/ppo_mini_local/tb/ --bind_all

然后浏览器访问http://localhost:6006，即可查看 loss、reward、KL 散度等实时曲线。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。