一键部署verl：快速搭建属于你的AI模型强化学习环境

1. 引言

大型语言模型（LLMs）在预训练之后，通常需要通过**后训练（post-training）**进一步优化其在特定任务上的表现。这一阶段主要包括监督微调（SFT）和基于人类反馈的强化学习（RLHF），而近年来，随着GRPO等新型强化学习算法的兴起，对高效、灵活且可扩展的训练框架需求日益增长。

在此背景下，verl应运而生。作为字节跳动火山引擎团队开源的强化学习训练框架，verl 是 HybridFlow 论文的官方实现，专为 LLMs 的后训练设计。它不仅支持 SFT 和多种 RL 算法（如 PPO、GRPO），还具备与主流 LLM 基础设施无缝集成的能力，兼顾灵活性与高性能。

本文将围绕“如何一键部署 verl 并快速构建 AI 模型强化学习环境”展开，涵盖安装验证、SFT 实践、RL 训练流程、配置优化及模型导出等核心环节，帮助开发者从零开始高效上手 verl 框架。

2. verl 核心特性解析

2.1 架构设计理念

verl 采用模块化设计思想，解耦了计算逻辑与数据流依赖，使其能够灵活适配不同的并行策略和底层框架。其核心架构基于Hybrid 编程模型，融合了单控制器与多控制器范式的优点，允许用户以极简代码构建复杂的后训练数据流。

该设计使得 verl 在以下方面表现出色：

高吞吐生成能力：通过集成 vLLM、FSDP 等先进推理与训练系统，显著提升样本生成效率。
低通信开销：借助 3D-HybridEngine 实现 Actor 模型重分片，减少训练与生成阶段切换时的显存冗余与通信成本。
良好的可扩展性：支持跨 GPU 组的灵活设备映射，适用于从小规模实验到大规模集群部署的各种场景。

2.2 关键优势一览

特性	描述
多样化 RL 支持	内置 PPO、GRPO 等主流算法，易于扩展自定义策略
无缝集成 HuggingFace	可直接加载 Transformers 风格模型与 tokenizer
兼容主流训练框架	支持 PyTorch FSDP、Megatron-LM、vLLM 等
高效的并行机制	支持数据并行（DP）、序列并行（SP）及混合并行
轻量级配置管理	使用 Hydra 进行动态配置加载，支持 YAML 文件驱动

这些特性共同构成了 verl 的技术竞争力，使其成为当前大模型后训练领域的重要工具之一。

3. 安装与环境验证

3.1 环境准备

建议使用 Python 3.10+ 环境，并确保已安装 CUDA 12.x 及对应版本的 PyTorch。推荐使用 Conda 创建独立虚拟环境：

conda create -n verl python=3.10 conda activate verl

安装基础依赖：

pip install torch==2.4.0+cu124 torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu124 pip install transformers==4.47.1 peft==0.14.0 datasets accelerate pandas numpy ray==2.42.1 pip install flash-attn==2.5.9.post1 --no-build-isolation pip install vllm==0.5.4

注意：flash-attn和vllm需要正确配置 CUDA 环境，否则可能编译失败。

3.2 安装 verl 框架

推荐从源码安装，便于后续自定义修改：

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

此方式会将 verl 以可编辑模式安装，方便调试和二次开发。

3.3 验证安装结果

进入 Python 解释器执行以下命令：

import verl print(verl.__version__)

若输出版本号（如0.1.0），则表示安装成功。

4. 监督微调（SFT）实践指南

4.1 SFT 基本流程

SFT 是 post-training 的第一步，目标是让模型更好地适应下游任务格式。verl 提供了fsdp_sft_trainer.py脚本用于实现基于 FSDP 的高效微调。

主要组件说明：

Data Loader：读取 parquet/json 格式数据集，支持 prompt/response 字段提取。
Model Wrapper：封装 HuggingFace 模型，支持 LoRA 微调或全参数训练。
Trainer：基于 FSDP 实现分布式训练，自动处理梯度同步与参数更新。

4.2 配置文件详解

默认配置位于verl/trainer/config/sft_trainer.yaml，关键字段如下：

data: train_files: ~/data/gsm8k/train.parquet val_files: ~/data/gsm8k/test.parquet prompt_key: question response_key: answer max_length: 1024 micro_batch_size_per_gpu: 4 model: partial_pretrain: Qwen/Qwen2.5-0.5B-Instruct lora_rank: 32 target_modules: all-linear optim: lr: 1e-4 weight_decay: 0.01 trainer: default_local_dir: /tmp/sft_model project_name: gsm8k-sft total_epochs: 1

4.3 自定义 YAML 配置启动

为提高可维护性，建议将所有参数集中于一个 YAML 文件中。为此需修改fsdp_sft_trainer.py中的主函数入口：

def load_config(config_path): from omegaconf import OmegaConf return OmegaConf.load(config_path) def main(args): config = load_config(args.config_path) local_rank, rank, world_size = initialize_global_process_group() device_mesh = init_device_mesh('cuda', (world_size,), ('fsdp',)) dp_size = world_size // config.ulysses_sequence_parallel_size sp_mesh = init_device_mesh('cuda', (dp_size, config.ulysses_sequence_parallel_size), ('dp', 'sp')) trainer = FSDPSFTTrainer(config, device_mesh, sp_mesh) trainer.fit() if __name__ == '__main__': import argparse parser = argparse.ArgumentParser() parser.add_argument('--config_path', type=str, required=True) args = parser.parse_args() main(args)

随后可通过如下脚本启动训练：

torchrun --nnodes=1 --nproc_per_node=8 \ -m verl.trainer.fsdp_sft_trainer \ --config_path ./configs/sft.yaml

4.4 移除验证步骤（可选）

若仅需训练无需验证，可在FSDPSFTTrainer.fit()方法中注释掉self.val_dataloader相关逻辑，或设置val_files=null并跳过评估回调。

5. 强化学习训练（以 GRPO 为例）

5.1 GRPO 算法简介

GRPO（Group Relative Policy Optimization）是一种改进型强化学习算法，通过对多个响应进行组内比较来估计优势函数，避免依赖外部奖励模型（RM）。其核心思想是：在同一 prompt 下生成多个 response，根据相对排序分配奖励信号。

verl 对 GRPO 的支持体现在algorithm.adv_estimator=grpo配置项中，结合rollout.n > 1实现多采样策略。

5.2 启动 GRPO 训练

参考示例脚本examples/grpo_trainer/run_qwen2-7b.sh：

export VLLM_ATTENTION_BACKEND=XFORMERS python3 -m verl.trainer.main_ppo \ algorithm.adv_estimator=grpo \ data.train_files=$HOME/data/gsm8k/train.parquet \ actor_rollout_ref.model.path=Qwen/Qwen2-7B-Instruct \ actor_rollout_ref.actor.optim.lr=1e-6 \ data.train_batch_size=1024 \ data.max_prompt_length=512 \ data.max_response_length=1024 \ actor_rollout_ref.rollout.name=vllm \ actor_rollout_ref.rollout.n=8 \ trainer.total_epochs=3

关键参数说明：

rollout.n=8：每个 prompt 生成 8 条 response，用于 GRPO 计算相对奖励。
vllm推理后端：提供高吞吐生成能力，适合大规模 rollout。
adv_estimator=grpo：启用 GRPO 优势估计器，无需 critic 或 reward model。

5.3 配置文件结构分析

完整配置见ppo_trainer.yaml，重点部分包括：

actor_rollout_ref: model: path: Qwen/Qwen2-7B-Instruct rollout: name: vllm n: 8 dtype: bfloat16 gpu_memory_utilization: 0.5 tensor_model_parallel_size: 2 actor: ppo_mini_batch_size: 256 optim: lr: 1e-6

同样可改造main_ppo.py支持外部 YAML 输入：

def main(args): config = load_config(args.config_path) run_ppo(config) # 替换原 @hydra.main 装饰器

启动命令简化为：

python3 -m verl.trainer.main_ppo --config_path ./configs/grpo.yaml

6. 自定义奖励函数实现

6.1 Reward Manager 扩展机制

verl 允许用户自定义奖励计算逻辑，主要通过继承RewardManager类实现。默认情况下，若未启用 reward model，则调用内置评分函数。

6.2 编写 CustomRewardManager

创建文件verl/workers/reward_manager/custom.py：

from verl import DataProto import torch class LengthBasedRewardManager: def __init__(self, tokenizer, num_examine=1) -> None: self.tokenizer = tokenizer self.num_examine = num_examine def __call__(self, data: DataProto): reward_tensor = torch.zeros_like(data.batch['responses'], dtype=torch.float32) for i in range(len(data)): item = data[i] prompt_ids = item.batch['prompts'] response_ids = item.batch['responses'] valid_mask = item.batch['attention_mask'] prompt_len = prompt_ids.shape[-1] resp_valid_len = valid_mask[prompt_len:].sum().item() response_str = self.tokenizer.decode(response_ids[:resp_valid_len]) # 示例：以 response 长度作为奖励 score = float(len(response_str.split())) # 单词数奖励 reward_tensor[i, resp_valid_len - 1] = score return reward_tensor

在配置中引用该类（需注册 import）：

reward_manager: custom

并在初始化时传入 tokenizer。

7. 模型保存与格式转换

7.1 Checkpoint 存储格式

verl 默认保存的是 FSDP 分片状态字典，包含模型、优化器、调度器等完整信息，路径结构如下：

checkpoints/ └── project_name/ └── experiment_name/ └── global_step_50/ └── actor/ ├── model_world_size_8_rank_0.pt ├── model_world_size_8_rank_1.pt ...

7.2 转换为 HuggingFace 格式

为便于后续推理或部署，需将分片模型合并并转为标准 HF 格式。使用以下脚本完成转换：

#!/usr/bin/env python from transformers import AutoConfig, AutoModelForCausalLM, AutoTokenizer import torch from collections import defaultdict import os def convert_fsdp_to_hf(fsdp_ckpt_dir, hf_model_path, output_dir, step, world_size=8): os.makedirs(output_dir, exist_ok=True) state_dict = defaultdict(list) for rank in range(world_size): ckpt_file = f"{fsdp_ckpt_dir}/model_world_size_{world_size}_rank_{rank}.pt" print(f"Loading {ckpt_file}") shard = torch.load(ckpt_file) for k, v in shard.items(): state_dict[k].append(v.to_local()) merged_state_dict = {k: torch.cat(v, dim=0) for k, v in state_dict.items()} config = AutoConfig.from_pretrained(hf_model_path) model = AutoModelForCausalLM.from_config(config) model.load_state_dict(merged_state_dict) model.save_pretrained(output_dir, max_shard_size="10GB") tokenizer = AutoTokenizer.from_pretrained(hf_model_path) tokenizer.save_pretrained(output_dir) print(f"Model saved to {output_dir}") if __name__ == "__main__": convert_fsdp_to_hf( fsdp_ckpt_dir="/path/to/global_step_50/actor", hf_model_path="/path/to/huggingface/model", output_dir="/path/to/hf_checkpoint/checkpoint_global_step_50", step="50" )

运行后即可获得标准 HF 结构模型，可用于pipeline或vLLM部署。