快速上手：单机 GRPO 例子

3.1 选哪个 example 跑

examples/grpo_trainer/ 下大约 20+ 个启动脚本，命名规则统一：

run_<模型>_<后端>.sh

新手首选 run_qwen3_4b_fsdp.sh：4B 模型在 8 张 A100/H100 上能跑、依赖最少、报错最容易看懂。

3.2 准备数据：GSM8K

verl 内置了 GSM8K（小学数学题）的预处理脚本，是 GRPO 训练的"hello world"：

# 在 verl 目录里
cd /Users/zjw/Documents/LLM/train/repos/verl

# 用 verl 自带预处理脚本把 HF datasets 转 parquet（带 prompt 模板）
python examples/data_preprocess/gsm8k.py --local_dir ~/data/gsm8k

# 看产出
ls ~/data/gsm8k/
# train.parquet  test.parquet

每条样本包含：

• prompt —— 拼好对话模板的输入；
• data_source —— 标识 reward 应该用哪种打分器（这里是 "openai/gsm8k"，verl 自带规则 reward）；
• reward_model —— ground truth 答案，用于自动验证。

3.3 启动训练

cd /Users/zjw/Documents/LLM/train/repos/verl

# 单机 8 卡 H100/A100；脚本会自动 ray start --head
bash examples/grpo_trainer/run_qwen3_4b_fsdp.sh

第一次启动会做：

1. ray start --head 起 Ray head；
2. 从 HuggingFace 下载 Qwen/Qwen3-4B（约 8 GB）；
3. 在每张 GPU 上 init FSDP；
4. 起 vLLM rollout worker（ROLLOUT_TP=2 时占 2 卡）；
5. 跑数据预处理、tokenize；
6. 正式进入训练循环。

10 分钟左右你会看到 step 0 的输出：

step:1 - reward: 0.12, kl: 0.00, response_length: 256, ...
step:2 - reward: 0.14, ...

3.4 启动脚本是怎么组织的

打开 examples/grpo_trainer/run_qwen3_4b_fsdp.sh，会看到它本质上是一长串 Hydra override。脚本分这几段：

最后一行非常长，类似：

python3 -m verl.trainer.main_ppo \
    "${DATA[@]}" \
    "${MODEL[@]}" \
    "${ACTOR[@]}" \
    "${ROLLOUT[@]}" \
    ...

这就是 verl 的入口范式：python -m verl.trainer.main_ppo + 一堆 key=value。

3.5 训练时的进程拓扑

单机 8 卡 + ROLLOUT_TP=2 的运行时长这样：

这种"controller + 多 worker group"的样子，就是 HybridFlow 架构，第 4 章会展开。

3.6 训练过程中关注什么

启动后，verl 会输出标准日志 + 写到 WandB / TensorBoard（看 trainer.logger 配置）。重点关注：

3.7 看完这章你应该能做什么

• 跑通一个单机 GRPO 训练，loss 曲线可见；
• 能看懂 run_*.sh 的 Hydra override 风格；
• 知道训练时的进程拓扑（controller + 多 worker group）；
• 知道关注哪几个指标判断训练是否正常；
• 还不需要懂 worker group 的实现细节——第 4-5 章会讲。

3.8 跑完 GSM8K 之后

4B + GSM8K + 15 epoch 大约 1-3 小时（视硬件）。跑完后可以：

1. 用 verl 自带的 main_eval.py 跑测试集打分；
2. 用 verl/model_merger/ 把 ZeRO / FSDP shard 合成 HF 格式；
3. 挂到 vLLM 起 OpenAI 兼容服务；
4. 换其他数据集（MATH / DAPO-Math-17K / 自家业务）继续玩。

这套流程在第 12 章"案例：长思考链 GRPO"会完整演示一次。

3.9 入口背后：main_ppo.py 调用栈

把 run_qwen3_4b_fsdp.sh 最后那行 python -m verl.trainer.main_ppo ... 拆开看，从命令行到训练循环之间发生了什么：

3.10 TaskRunner 角色：driver-side 装配工

TaskRunner（main_ppo.py:111 起的 Ray Actor）做的事是把 controller 需要的所有 WorkerGroup 都注册好，然后调 fit() 开始训练。关键方法：

这套设计意味着：controller 不在 head 节点的 Python 进程里，而是在 TaskRunner 这个 Ray Actor 里运行。Ray dashboard 上能看到一个长寿命的 actor 名字带 "TaskRunner"，它就是 controller。

3.11 同步 vs 异步：main_ppo_sync.py

verl/trainer/main_ppo_sync.py 是一个并行存在的"同步 PPO"入口（line 14–22 注释里写得很清楚）。它和 main_ppo.py 的差异：

初次跑训练用 main_ppo 即可；做 agent loop / 长 R1 风格再切 main_ppo_sync。第 12 章会用到。