简介verl是火山引擎开源的大模型强化学习框架本资源提供该框架的完整源码包面向希望在LLM强化学习领域快速上手的中高级开发者。包内共1058个文件主体为578个Python脚本、212个Shell脚本和72个YAML配置分别对应训练算法实现、一键部署与集群操作、环境及超参定义另有Markdown、RST文档及少量JSON、Dockerfile覆盖从环境准备、首个RL训练实验、性能优化与调参到分布式训练部署和生产级最佳实践的完整链路。压缩包仅2.64MB轻量易用已有142人学习下载。源码中包含单机与多机训练的启动示例、SGLang/vLLM推理后端适配、Megatron模型并行配置、Dockerfile等配合“7天掌握verl”的学习路径可帮助读者快速搭建开发环境理解PPO等强化学习流程并逐步扩展到千万级参数模型的分布式训练适合作为框架学习和二次开发的基础参考。1. 为什么源码阅读要锁定 verl先解决“值不值得读”verl 是近年来 LLM 强化学习里绕不开的一个训练框架源码它把 rollout 采样、经验传输、策略更新这几段最容易出问题的主干流程全部收在一个项目里。很多人从两三年前的 RLHF 代码过渡到 new 的时候发现光会调配置不够loss 曲线一不对就只能“玄学调参”因为真正决定行为的逻辑都在源码里。这篇笔记的定位很直接用 7 天把 verl 源码从“黑匣子”变成“看得见的流水线”。7 天能完成什么以我读这类训练框架源码的经验前 3 天能跑通最小 demo 并画清目录中间 2 天追完 rollout 到 loss 的主链路后面 2 天把关键模块读透并且能自己动手改一小段策略逻辑。如果你是做 LLM 训练应用、想转向强化学习方向的工程师或者已经在分布式训练上踩过坑但没彻底搞懂“数据到底怎么在两个 worker 之间流动”的人这 7 天值得投进去。反过来如果手上没有任何 GPU 和能跑的模型权重我劝你先别碰 verl。它的核心运行离不开真正执行 rollout 的推理引擎只看代码不跑起来读到的只是接口层级谈不上掌握。下面从最小可运行开始一天一天往源码深处走。2. 在开始读源码之前把 verl 跑出一个最小训练流程2.1 环境准备的三个前提Python 版本、源码安装、推理引擎常见做法是把项目源码克隆到本地后以 editable 模式安装这样import verl指向的永远是你正在读的这份代码而不是装进 site-packages 里的陈年版本。# conda 只负责隔离 Python 版本依赖交给 uv 解析更快 conda create -n verl-rl python3.11 -y conda activate verl-rl # 克隆后的路径在后续所有阅读中都是根目录以下用 verl-src 占位 cd verl-src # editable 安装让 import 入口与源码目录绑定 uv pip install -e .[py] # rollout 侧需要能承载并发的推理引擎调度侧需要分布式执行环境 uv pip install vllm0.6.0 ray2.9这段命令里三件事都不能省。Python 3.11 是当前训练栈兼容性最好的版本某些 3.12 下三方库的编译期容易翻车不建议在这个阶段冒险。editable 安装保证后面改源码里的函数代码能立刻被训练进程读到。vllm 和 ray 分别是 rollout 响应和 worker 编排的底座版本上和 verl 的声明保持一致即可不要装 nightly 版twice 踩过这种雷nightly 的 API 变化会让入门第一天废掉。2.2 用最小命令跑通一个 GRPO 训练记住日志里的三根主线不需要准备超大数据集verl 的 examples 里通常会带很小的训练数据文件。先用单机环境跑通再谈源码。# 最小 demo单机训练用 GRPO 做策略优化 # pretrain 路径给一个小规模的 base model 即可不必追求效果目标是让流程完整走完 python -m verl.trainer.main \ --config-name grpo \ debug.pretrain/data/model/base-7b \ data.train_filesexamples/data/tiny_train.parquet \ data.val_filesexamples/data/tiny_val.parquet \ algorithm.adv_estimatorgrpo \ trainer.default_local_dir/tmp/verl-demo--config-name grpo是入口处的配置选择方式verl 用配置组管理不同训练目标grpo 是最常作为入门的那一个。algorithm.adv_estimatorgrpo显式指定优势估计器这个参数决定后面源码里你会走哪一段分支。trainer.default_local_dir是结果与 checkpoint 路径建议第一次就放到/tmp下避免后面反复调整路径。跑起来后你要盯着日志里三根主线第一ray 是否成功拉起多个 worker 角色出现失败时多半是端口或资源池问题第二每个 training step 打印出来的采样数、时长、loss 是不是在稳定变化第三是否能在trainer.default_local_dir下看到 checkpoint 目录生成。三条都满足说明这条代码主链路是通的后面读源码时遇到任何分支都有一份“正常状态”可以对照。2.3 运行前设置好可见性配置别让训练在后台闷头跑很多源码阅读者失败在跑 demo 这一步不是因为代码报错而是日志太安静让人分不清到底卡在哪。我一般会在启动前写入一组环境变量让训练循环的中间状态全部暴露出来export TOKENIZERS_PARALLELISMfalse export VLLM_WORKER_MULTIPROC_METHODspawn export CUDA_VISIBLE_DEVICES0,1,2,3TOKENIZERS_PARALLELISMfalse是为了避免数据处理阶段因为并行分词产生不可控的 CPU 争抢VLLM_WORKER_MULTIPROC_METHODspawn在部分 Linux 环境下能规避 fork 带来的 CUDA context 泄漏CUDA_VISIBLE_DEVICES显式限制可见卡防止调度组件把进程打到你不期望的设备上。这一章做完你已经有了一条能跑通的最小训练链路。接下来别急着看论文公式对应的实现先打开源码目录把项目的骨架搭在脑子里。3. verl 源码图谱入口、目录与配置读取顺序3.1 从源码根目录分四块读懂分工verl 源码的目录结构在不同版本里会有微调但大分区基本稳定。初次阅读不建议从文件数量最少的顶层开始而是按照“训练入口、远程 worker、协议定义、示例配置”四条线索去看。verl/ ├── trainer/ # 训练主入口与循环最值得第一周细读 ├── workers/ # actor、rollout、critic 等角色的分布式实现 ├── protocols/ # worker 之间通信的数据结构定义 ├── core/ # 分布式上下文、资源池、跟踪工具 └── examples/ # 可直接跑的配置与数据样例trainer 是整列火车的车头你通过python -m verl.trainer.main启动的就是它。workers 目录里每一个子模块都对应一个独立角色比如负责更新策略的 actor worker、负责采样的 rollout worker。第一次读代码最容易的误区是先读 worker 的实现因为你尚不清楚各角色之间怎么被组织起来读到的只是孤立的类方法。protocols 目录值得在入门阶段通读一遍因为 worker 之间传递的不是普通 Python 对象而是按协议定义封装的数据块。理解这块后面读经验缓冲时就不会觉得字段跳来跳去。3.2 trainer.main 到 WorkerGroup 的调用主线调用主线不复杂但层级多。展开后的顺序一般是main 解析配置 → 构造资源池 → 根据配置创建 WorkerGroup → 进入训练循环。我建议你在 IDE 里给这几个函数加断点或临时日志直观地看到调用顺序。# 用 grep 找到训练循环主体文件 grep -rn def run_training\|def fit\|class Trainer verl-src/verl/trainer/常见实现里会有一个 Trainer 类它的初始化函数里创建资源池和 worker 分组真正的训练步进放在另一个方法中循环内部会调用类似step()的方法完成一次数据采样和策略更新。你只要能看到“初始化时创建了什么角色、每一步循环时哪些角色的方法被调用”这两点主骨架就算拿下了。关键理解在与资源池的抽象含义verl 把 CPU、GPU 和内存都视为可调度的资源不同的 worker 种类被要求部署到不同资源槽上。这样做的好处是 rollout 这类纯耗 GPU 的任务与训练这类需要 CPU 预处理的任务可以同时运行训练流程不会因为等待采样而整体空转。3.3 用配置反向定位 5 个承担主线的函数光看目录还不够更实用的是用你刚才跑的 grpo 配置字段反查源码。任意挑 config 里一个字段比如actor_rollout.rollout.name在源码里搜索它你会自然找到 rollout worker 的构建点。按这个方式我一般会带读者定位下面 5 个函数配置对象定义看每个字段怎么被解析成内部结构资源池构建看哪些角色被绑定到 GPU 资源rollout 数据请求看采样阶段如何调用推理引擎经验缓冲写入看一条样本从生成到入库的字段映射损失计算看策略梯度或 PPO/GRPO 公式的代码落地。这 5 个函数定位完主线基本清晰。此时你不需要读懂每个类只需要做到给一个配置参数能说出它最终作用在哪个 worker 的哪一步。这个能力是后面读任何 RL 框架源码的通用钥匙。4. 追一条数据从 prompt 到 lossrollout、经验缓冲与 PPO/GRPO4.1 数据从 dataset 到 rollout worker 的投递路径训练数据不是一次性全部加载进内存的。verl 常见做法是起一个数据 worker按 batch 生成 prompt再通过分布式调度把数据投递给 rollout worker。一条 prompt 的生命周期可以拆成四步数据 worker 从本地 parquet 文件读取并完成 tokenizetoken 序列被包装成协议规定的请求结构请求被发送到 rollout worker 所在设备rollout worker 以 vllm 为后端执行生成拿到下一段 token。理解这四步你就明白了为什么 verl 的网络传输会成为训练吞吐的瓶颈。这里要纠正一个常见误区很多人以为 rollout 和训练共用同一个模型副本代码里是“同步等待”的。实际上 rollout worker 与 actor worker 各自持有模型参数的副本每一步训练结束后新权重通过通信协议从 actor 侧传播到 rollout 侧。源码里这段逻辑通常是异步的也就是说训练循环进入下一步时rollout 侧的模型可能是上一步的版本。这是分布式 RL 训练中最容易让人对日志产生误读的地方。4.2 经验缓冲里的数据拼接与时序问题rollout worker 生成的原始序列并不能直接送进损失函数。经验缓冲在这中间承担的是数据整理与时序对齐的工作。verl 里常见的经验结构至少包含 prompt 序列、response 序列、每个位置的 log_prob、reward 以及时序掩码。你可能觉得直接把列表拼起来就行但实际实现里还要对齐每个样本的长度并且区分哪些位置属于 prompt、哪些属于 response因为在计算策略损失时prompt 位置的 token 通常会被 mask 掉。这个阶段另一个需要关注的点是权重复制时机。如果 rollout 侧拿到的还是旧权重而经验缓冲里存的是用旧权重采样的数据策略更新公式里就必须保留对应的旧 log_prob 字段。移除了这个字段后面 PPO/GRPO 的 ratio 计算就会失真损失曲线会出现跳变。4.3 PPO/GRPO 损失在源码里的落点与算式到这一步你已经把数据从采样端追到了更新端。损失计算是源码阅读的高潮也是最能体现框架设计思路的位置。找到它的常见入口方式是搜索 loss 关键字或 actor worker 里的 update 方法。先说公式上的对应关系。PPO 的策略损失核心是对新旧策略的 ratio 做 clipped 操作而 GRPO 在此基础上进一步把 advantage 的来源换成组内回报归一化。两者的实现在源码里通常分属不同分支base 版本的策略梯度直接使用回报加权 log_probPPO 版本加入 ratio 与 clip 范围GRPO 版本去掉 critic 网络改用同一 prompt 的多个采样结果计算均值与方差得到 advantage。verl 里 GRPO 的实现中你会看到对每个 prompt 的一组 rollout 输出做统计运算。这个组的大小就是配置里的采样数。如果这个数量是 1GRPO 退化成不带 baseline 的 REINFORCE效果往往很不稳定。源码里这部分不会直接告诉你“采样数太小会崩”但逻辑里隐含了这一点。4.4 源码符号与论文公式的对齐表我建议把下列对应关系抄在笔记里再入源码。论文概念源码常见位置/字段说明策略旧 log_probold_log_prob采样时固定不参与梯度advantageadvantagesGRPO 下由组内回报归一化得到clip 范围clip_range通常配置成 0.2KL 惩罚系数beta控制新策略偏离参考策略的程度参考模型ref_policy不更新只做前向计算把这些对应关系列出来之后你读损失函数的时候就不需要边看代码边翻公式。源码里函数名可能不叫loss_grpo但内部的字段名与上述表格基本一致因为框架之间互相借鉴了这套命名习惯。到此你已追完一条数据从文件到损失的全部路程。后面两周真正上手改代码时这个全局视野能帮你省掉大量 debug 时间。5. verl 源码阅读与调试的 5 个常见卡点现象 · 原因 · 排查5.1 训练每一步的间隙从几秒突然跳成几分钟现象日志显示 step 完成但下一步迟迟不开始GPU 利用率下降。原因策略更新完成后新权重需要传播给 rollout worker但如果 rollout worker 上还挂着未结束的采样请求权重同步会等待这些请求处理完形成隐性阻塞。解决先看 rollout worker 的并发数是否过大。把配置里的 rollout 并发调低并为权重同步设置日志确认卡点是发生在传出还是传入。实践里这个现象最容易出现在长时间运行后的某一步视作正常但需监控。5.2 改了配置里的 beta 值训练日志完全无感现象调大 KL 惩罚系数后kl 日志项数值几乎不动。原因配置字段写到了外层 trainer 参数里但 worker 启动时读取的是另一份通过协议下发的内部配置。两边没有共享同一对象修改没有抵达实际计算节点。解决不要在启动脚本里反复追加命令行覆盖直接在默认配置文件中修改对应字段然后检查日志中打印的有效配置内容是否与预期一致。排查这类问题最快的方法是临时在损失计算函数里打印 beta 的实际值。5.3 训练中途手动中断重启后损失值跳到异常范围现象clean checkpoint 恢复后第一轮 loss 比正常值高出一个量级。原因经验缓冲目录里残留了上一轮未消费完的样本恢复训练时这批旧数据被重新送入更新器而对应的旧 log_prob 可能来自未完成同步的模型权重。解决重启前把临时缓冲目录清空保持 checkpoint 与数据完成状态一致。习惯上我会在训练脚本里加一个启动时清理临时目录的动作避免手动操作遗漏。5.4 一个很小的模型跑出极慢的处理吞吐换后端依旧没有起色现象vllm 后端启动成功但每秒生成 token 数远低于模型规模应有的水平。原因这通常不是推理引擎本身的问题而是 rollout worker 的输入批大小与推理引擎的调度不匹配。小模型显存占用低但框架默认按大模型场景分配资源导致设备并未被充分利用。解决查看启动日志中打印的模型显存预估与 worker 分配显存必要时手动指定 rollout worker 的张量并行数。这个坑很容易让人误以为源码有 bug实际是资源配置层的问题。5.5 混合精度下训练产生 NaN但切换到全精度恢复正常现象打开 fp16 后跑若干步出现 NaN回退到 fp32 后稳定。原因优势值或回报值在 fp16 下数值范围有限当优势分布出现极端值时发生溢出部分实现里没有对 loss 计算前的 advantage 做 clip导致梯度异常。解决先避免在入门阶段开启混合精度确认逻辑正确后再尝试。如果想定位可以直接打印 advantage 的统计分布看最大值是否已逼近当前精度上限。把 advantage 的归一化逻辑移到更低精度之前是常见修复方向。6. 7 天源码阅读的具体安排表和最后留给自己的验证实验天次目标可验收的结果Day 1搭环境、跑通最小训练、记录日志格式能说出训练循环打印的每个核心字段来源Day 2读完 trainer 主入口与资源池构建能画出 WorkerGroup 各角色的启动顺序Day 3读 rollout worker 与数据投递路径能解释采样请求如何跨角色传输Day 4读经验缓冲与数据拼接能列举缓冲中的关键字段及其作用Day 5读 PPO/GRPO 损失实现能定位 policy loss 的三处核心计算Day 6自己改动一部分策略逻辑在源码中加入一个新的正则项并观测效果Day 7回归主链路写一页架构笔记能不看笔记向同事讲清一条数据从文件到 loss 的完整路径第 6 天的自定义改动实验是整个计划里最有价值的一步。常见做法是给损失函数增加一个可控的额外惩罚项例如把某一段 response 的 token 平均熵乘上一个系数加入总损失。具体操作是在损失计算函数里找到 loss 汇总的位置新增一行total_loss policy_loss self.extra_beta * entropy_mean然后通过配置把extra_beta传进来。自己亲手验证一次远比读十遍注释理解得透彻。我个人的习惯是每天阅读结束后在源码里加一条临时日志或者断言强迫自己确认当天的理解。比如读经验缓冲那天我在数据入库后打印old_log_prob的 shape 与均值看到它与日志输出匹配才继续往下。这种“边读边验”的方式让我在 Day 7 结束时可以完整地复述整个架构不需要再翻笔记。如果你按照这张表走完一遍verl 对你就不再是“某个能跑 RL 训练的库”而是一个由入口、角色、协议、缓冲和损失函数组成的清晰结构。再遇到生产环境的训练问题你能直接判断该看哪一段源码而不是靠猜配置。希望这些落地方法对你有帮助7 天后等你好消息。本文还有配套的精品资源点击获取