文章
verl 实战:从训练数据到 Hugging Face 模型导出
串联数据准备、dry-run、smoke test、正式训练、checkpoint、合并与离线验证。
专题 verl 源码解读与面试指南 第 14 篇 / 共 16 篇
这一章不承诺一条命令适配所有硬件,而是给出不会迷路的操作顺序。具体 CUDA/NPU、PyTorch、vLLM/SGLang 版本组合应按 docs/start/install.rst、对应容器和当前 example 核查;仓库 quickstart 也明确推荐优先使用项目提供的 Docker 环境。main 新增的 uv lock 路径只覆盖 Linux x86_64/Python 3.12/CUDA 13.0 组合,不能外推到 NPU/ROCm/aarch64/TRT-LLM。
全流程
1. 先固定版本和硬件事实
记录:verl commit/tag、recipe commit、容器 tag、GPU/NPU 型号与数量、driver、PyTorch、训练后端、rollout 后端和基础模型 revision。只写“使用最新版”无法复现,且推理后端支持矩阵可能比 Trainer API 更快变化。
若使用 uv,额外记录 uv.lock hash、选择的 extras 和 manage_envs.py 命令,并确认 Ray runtime_env.py_executable 与 driver 指向同一环境。一个常见错误是 driver 在 .venv、远程 Ray worker 却从系统 Python 启动。
启动前做最小检查:
- 每节点设备数量与
trainer.n_gpus_per_node一致; - 模型能被 tokenizer/processor 加载;
- Ray 在所有节点看到预期资源;
- NCCL/HCCL 网络和共享 checkpoint 路径可用;
- rollout backend 的模型、dtype、多模态与热更新路径被当前 example 覆盖。
2. 把数据整理为当前 schema
GSM8K 示例可以直接运行:
python3 examples/data_preprocess/gsm8k.py --local_save_dir ~/data/gsm8k
生成 train.parquet 和 test.parquet。当前脚本的一条记录核心形态是:
data_source: "openai/gsm8k"
prompt: [{role: "user", content: "..."}]
ability: "math"
reward_model: {style: "rule", ground_truth: "42"}
extra_info: {split: "train", index: ..., answer: ..., question: ...}
自己的任务应至少明确 prompt/messages、data_source、嵌套的 reward ground truth 和业务 extra info;工具/VLM 再加入相应字段。schema 不是纯数据工程细节,它决定 RewardLoop 路由和评测分层。
3. 训练前做四个 dry-run
- 数据:读取几十条,确认 train/val 无泄漏、字段类型一致。
- 模板/token:查看最终 prompt token、长度、EOS/特殊 token;多轮以 AgentLoop 实际 token 为准。
- reward:用正确、错误、格式异常、超长和恶意答案测试 component 与失败类型。
- 分组:GRPO/RLOO 检查同一
uid的n条回答确实成组,组内 reward 能产生差异。
不要用“训练 loss 能算出来”代替这四项。reward 或 mask 错误常不会报异常,却会稳定优化错误目标。
4. 从现成脚本开始
文本 GRPO 的当前入口之一是:
bash examples/grpo_trainer/run_qwen3_8b_fsdp.sh
它通过环境变量暴露常用旋钮,并将剩余参数作为 Hydra override 传入。典型用法形态:
MODEL_PATH=/path/to/model \
NNODES=1 NGPUS_PER_NODE=8 \
INFER_BACKEND=vllm \
ROLLOUT_N=5 TRAIN_BATCH_SIZE=1024 \
bash examples/grpo_trainer/run_qwen3_8b_fsdp.sh \
"data.train_files=['/path/train.parquet']" \
"data.val_files=['/path/val.parquet']" \
'trainer.logger=["console"]'
这些数值只是脚本形态示例,不是硬件建议。第一次应按模型/显存显著缩短 response、batch、epoch 和保存间隔;同时保证 group size、mini-batch 整除和模型并行约束。若只有 24GB 单卡,仓库 docs/start/quickstart.rst 的 0.5B PPO 示例比 8B GRPO 更适合作为安装验证。
更新后的许多 example 会优先通过 uv extras 启动,并把对应 uv run --frozen ... 传给 Ray;需要沿用已有系统环境时显式设置 VERL_USE_UV=0,而不是同时混用两套解释器。
5. 会解释脚本中的六组参数
以 run_qwen3_8b_fsdp.sh 为例:
DATA:estimator、train/val files、逻辑 prompt batch、长度与截断策略。MODEL:基础模型、remove padding、gradient checkpointing。ACTOR:学习率、PPO mini-batch、dynamic batch、KL loss、FSDP offload。ROLLOUT:vLLM/SGLang/TRT-LLM、TP、KV cache 比例、每 prompt 采样数。REF:reference log-prob 的 dynamic batch、token budget 与 offload。TRAINER:节点/GPU、logger、checkpoint、validation、epoch。
面试时不要逐项背值,而要说明哪个角色消费这个参数、影响显存还是算法统计、改动后应观察什么指标。
6. Smoke test 的通过标准
短跑 2~5 step,至少确认:
- 初始化日志显示预期 V1 mode、训练 engine 和 rollout backend;
- rollout 文本、response mask 与 reward 正常;
- GRPO 组内有正负/不同 advantage,或 GAE value/return 尺度合理;
- old/ref/current log-prob 对应相同 token,首轮 ratio 没有异常漂移;
- actor grad norm 非零,参数更新后 rollout 权重版本推进;
- checkpoint 能保存,并能从一个短 run 恢复;
- validation 能输出目标 data source 的指标和样例。
如果任一正确性条件失败,先停在单机/sync;不要靠多机或异步掩盖问题。
7. 正式训练观察什么
每个实验保存 resolved config、git/model/data/reward 版本和硬件拓扑。Dashboard 至少分四组:
- 学习:train/val reward components、advantage/return、KL、clip、entropy、grad norm。
- 数据:长度/截断、失败组、tool/verifier error、过滤/refill。
- 性能:各 stage time、tokens/s/GPU、MFU、KV cache、rank imbalance。
- 版本:rollout/old/current span、weight sync、异步 drop/wait/IS/rejection。
定期保存 rollout 样例;纯标量曲线无法发现格式投机、reward hacking 和模板错误。
8. Checkpoint 先服务于恢复
默认路径形如:
checkpoints/<project>/<experiment>/global_step_<N>/actor/
里面可能是 FSDP/Megatron 分片和 optimizer/extra 状态。它用于恢复训练,不一定能直接由 Transformers/vLLM 加载。恢复演练应在正式长跑前完成:保存一个短 checkpoint、重启、核对 global step、数据位置、权重版本和首个 validation。
如果需要上传对象存储、注册模型版本或触发评测,可实现 CheckpointCallback 并配置 trainer.checkpoint_callback_class。它在 driver 端保存 RPC 后执行,异常默认终止训练。尤其要检查 async_save:Megatron 异步保存时 callback 到达并不代表 shard 已全部写完或 latest marker 已提交,外部流程必须等待真正的 durable 条件。
9. 导出 Hugging Face 模型
FSDP 示例:
python -m verl.model_merger merge \
--backend fsdp \
--local_dir checkpoints/<project>/<experiment>/global_step_<N>/actor \
--target_dir /path/to/exported_hf_model
Megatron 必须先看 checkpoint layout:当前默认/推荐 mbridge 通常已经产出可直接加载的 model/huggingface/,无需 merger。只有纯 Megatron distributed checkpoint 的 model/dist_ckpt/ 才使用 --backend megatron,必要时加 --tie-word-embedding;超大模型可按 docs/advance/checkpoint.rst 使用多节点 torchrun 分布式 merge。实际以 manifest、save_contents 和 use_mbridge 为准。
不要在未经确认时使用 --hf_upload_path:它会写远端 Hugging Face 仓库,属于单独的发布动作。
10. 导出后验证
至少检查:
- config、tokenizer/processor 和特殊 token 完整。
- 模型可用 Transformers 加载,参数 shape/dtype 正确。
- 对固定 prompts 比较 merge 前 checkpoint 路径的可信参考与 merge 后 logits/greedy generation。
- 跑独立 validation/benchmark,而不是只看训练 reward。
- 若使用 LoRA,确认导出的是 adapter、merged model,还是 base + adapter 组合。
verl.model_merger 支持 FSDP/Megatron merge,并提供 test/验证相关入口;2026-08 起还内置了输出校验(#7193,verl/model_merger/output_validation.py),merge 后会核对导出产物。实现位于 verl/model_merger/,完整参数见 docs/advance/checkpoint.rst。
面试中的项目叙述模板
我先固定模型、verl/recipe 和训练/推理后端版本,把数据转为带
data_source、prompt、嵌套 ground truth 的 Parquet。训练前分别验证模板、reward、mask 和 GRPO 分组。先用 V1 sync 做 2~5 step smoke test,确认 rollout→reward→advantage→actor update→weight sync 全链正确,再依据 stage timing 扩 batch、多机或异步。正式训练同时看学习、数据质量、性能和模型版本指标。checkpoint 先做恢复演练,结束后用 model merger 把 FSDP/Megatron 分片导出为 HF 模型,并用固定生成和独立评测验证,而不是直接把训练 reward 当作交付结果。
若面试官继续追问环境与运维,可补一句:我会把容器/driver/uv.lock/extras/Ray worker interpreter 一起固定;checkpoint callback 只负责外部动作,异步保存仍要独立确认持久化完成。