AxisRL 是一个构建在 SGLang rollout 和 Megatron 训练之上的 agentic RL post-training 框架，负责协调多轮 rollout、环境交互、奖励计算、样本构造与权重同步。本文带你用最短路径跑通 AxisRL 上的第一个 Agent RL 训练任务——GSM8K 数据集上的 GRPO 训练，并切换到 PPO 对比两种目标函数的配置差异，最后讲解训练产物的查看与常见问题排查。

📌先明确目标：读完本文，你将能在 8 卡 GPU 机器上，用一条命令启动 GSM8K GRPO 训练，看懂核心配置项的含义，并知道如何切换到 PPO。

为什么选 GSM8K 作为 Agent RL 入门

对于第一次接触强化学习后训练（RL post-training）的读者，任务选择应遵循"数据小、奖励可验证、逻辑简单"三个原则。GSM8K 恰好全中：

AxisRL 将每个任务封装为一个recipe（配方），任务特定的数据集加载、环境循环、验证器、奖励计算都集中在 axis_recipe/ 目录，而 rollout 调度、样本构造、权重同步等系统层由框架统一处理。GSM8K 的两个 recipe 就是最理想的入门路径。

认识 AxisRL 的数据流架构：5 步闭环

在动手之前，花 2 分钟理解 AxisRL 的一次训练循环长什么样，后面看日志就不迷路了：

1. Rollout Actors领取任务，驱动环境（GSM8K 场景下就是"出题 → 生成 → 判分"）；
2. SGLang Workers提供高吞吐的模型生成服务；
3. 环境 / 验证器产生交互记录和 reward；
4. Megatron Workers消费训练样本，执行 GRPO 或 PPO 训练；
5. 更新后的权重同步回 rollout 侧，进入下一轮。

如上图所示，重数据（例如 routing replay 张量）不经过中心 driver，而是走本地存储的 handle 数据通道，由训练 worker 按需读取——这是 AxisRL 保持控制面轻量、支持大规模训练的关键设计。

环境安装步骤：Docker 镜像 + 一键依赖

AxisRL 依赖 SGLang、Megatron Core、MagiAttention、Ray 和 CUDA 栈，手动装依赖非常容易踩坑，官方强烈推荐使用项目提供的 Docker 镜像（Dockerfile 见 docker/cuda/cu130-sgl0.5.14-mcore0.18-magi.Dockerfile）：

# 1. 拉取预构建镜像（含 SGLang / Megatron Core / Ray / CUDA 依赖） docker pull leejunjie/sglang-mcore:cu130-sgl0.5.14-mcore0.18-magi # 2. 克隆仓库并安装 git clone https://gitcode.com/gh_mirrors/ax/axrl.git cd axrl pip install -e .

接着准备模型和数据。官方提供了一键下载脚本 axrl/example/download_data.py：

python axrl/example/download_data.py

⚠️ 注意：完整下载包含多 B 参数模型，体量很大。如果只想跑 GSM8K recipe，手动下载Qwen/Qwen2.5-1.5B-Instruct模型和openai/gsm8k数据集，再把 recipe 配置里的路径指过去即可，不必全量下载。

🖥️硬件建议：两个 GSM8K recipe 的默认并行配置（Megatron 侧tp_size=2, pp_size=2，SGLang 侧tp_size=2，rollout 与训练 colocated 共享 GPU），按 8 卡 GPU 机器准备最稳妥。

3 条命令跑通第一个 GSM8K GRPO 训练

GRPO recipe 的入口是三件套：启动脚本 axis_recipe/grpo_gsm8k/run_train.sh、配置 axis_recipe/grpo_gsm8k/pipeline_config.yaml 和训练管线 axis_recipe/grpo_gsm8k/train_pipeline.py。

最快启动方法（只训 4 个 global update，用于验证环境跑通）：

AXRL_OUTPUT_DIR_NAME=grpo_gsm8k \ bash axis_recipe/grpo_gsm8k/run_train.sh \ --online_rl_train.max_global_updates=4

这条命令做了三件事：

• 先调用 generate_configs.py 校验并落盘默认配置；
• 启动PipelineController拉起 rollout 与训练 worker，把配置写入 pipeline_config.yaml；
• 通过--path.to.field=value形式的参数覆盖任意配置项（这里把总步数从默认 600 降到 4，快速验证）。

日志和产物统一落在$AXRL_OUTPUT_DIR（默认~/axrl-data/outputs）下：

读懂 GRPO 配置文件的 4 个关键参数

打开 pipeline_config.yaml，新手重点关注这 4 处：

1. 模型与数据：megatron_worker.model.name为Qwen/Qwen2.5-1.5B-Instruct；训练集openai/gsm8k/train、测试集openai/gsm8k/test（配置第 160–169 行）。数据集加载时会把题目包装成"step by step 推理、最终答案写在####之后"的提示，见 axrl/datasets/gsm8k.py；
2. GRPO 组采样：num_rollouts_per_conversation: 8—— 每道题采 8 条回复组成一个组，用组内相对收益估计 advantage，这正是 GRPO 省掉 value 模型的秘诀（配置第 282–301 行）；
3. 训练目标：grpo.loss_type: grpo，附带clip_ratio_high/low: 0.2的 PPO 式裁剪和 dual-clip 负 advantage 因子（配置第 192–220 行）；
4. 权重同步节奏：model_sync_every_n_global_updates: 4—— 每 4 步把新权重同步给 SGLang，保持 rollout 与策略接近 on-policy。

训练在"框架内"发生了什么

recipe 的 rollout 逻辑非常短，值得看一眼 train_pipeline.py：它构建一个MathEnv（axrl/envs/math_env.py）负责"生成 → 判分 → 结束"的单步循环，配合两个本地 processor——GSM8KVerifier（从回答末尾提取####后的数字并与标准答案比对，见 axrl/verifier/gsm8k.py）和ConversationTokenizer。判分是 0/1 规则奖励，没有任何黑盒成分，非常适合调试期确认奖励链路是否正常。

切换到 PPO：增加 value worker 的实战配置

PPO recipe 与 GRPO 的目录结构几乎一一对应，入口是 axis_recipe/ppo_gsm8k/run_train.sh。启动方式相同：

AXRL_OUTPUT_DIR_NAME=ppo_gsm8k \ bash axis_recipe/ppo_gsm8k/run_train.sh \ --online_rl_train.max_global_updates=4

两者配置上的核心差异只有三处，都在 axis_recipe/ppo_gsm8k/pipeline_config.yaml 中：

也就是说：PPO = GRPO 的 rollout 链路 + 一个额外训练并同步的 value 模型 + GAE 优势估计。代价是显存和训练时间上升（checkpoint 会分成 actor 与 value 两份，脚本里分别写到checkpoints/megatron_actor和checkpoints/megatron_value）；收益是对长程、多轮 reward 场景下更平滑的 value 估计。GSM8K 这种单轮任务上两者都能用，而 AxisRL 面向的多轮 agent 场景正是 PPO 更有优势的地方。

训练产物与可观测性：如何判断训练在正常推进

AxisRL 把"可观测性"当一等公民设计。判断你的第一个训练是否健康，看三个地方就够了：

• 控制台 / TensorBoard：log_every_k_steps: 1表示每步都打印；关注 reward 均值是否缓慢抬升、loss 是否平稳，eval_on_start: true会在训练开始前先跑一轮 test 集评估，给你一个基线分数；
• rollout 原文：save_eval_rollouts: true会保留评估阶段的完整生成文本，可以人工抽查模型是否在"学会####格式"；
• mismatch 分析：对于进阶用户，AxisRL 提供 rollout 与 trainer 两条路径的 token 级 KL 对比工具。下图中，启用 R3 routing replay（橙线）后 KL mismatch 的量级和尾部离群点都明显收敛——这类图是排查"rollout 与训练不一致导致 loss 尖峰"的利器。

更多稳定性工具（spike replay、sequence masking、TIS 等）在 docs/README-cn.md 的"核心技术思路"一节有完整介绍。

常见问题排查：新手最容易卡住的 4 个点

🔧 通用技巧：任何配置字段都可用--path.to.field=value命令行覆盖，不需要改 YAML 文件；完整的配置解析规则见 docs/config-parsing.md。

下一步：从 GSM8K 走向真正的 Agent 任务

跑通这两个 recipe 后，AxisRL 还为你准备好了进阶路线：

1. Search-R1：多轮、带检索工具的 white-box agent 任务，入口 axis_recipe/search_r1/run_train.sh，需要额外启动一个 retrieval server；
2. Black-Box RL：OpenHands + E2B 沙箱的 black-box 集成，通过 OpenAI 兼容 proxy 捕获任意 agent harness 的交互轨迹，见 axis_recipe/blackbox_rl/README.md；
3. 一致性调试：如果正式训练中遇到 loss 尖峰或 rollout/trainer 不一致，参考 skills/axrl-spike-replay/ 下的排查清单。

总结：AxisRL 把"高吞吐 rollout、大规模训练、权重同步、可观测性"封装成一条闭环，你只需关注 recipe 中的环境、奖励与训练配置。从bash axis_recipe/grpo_gsm8k/run_train.sh开始，3 条命令就能看到你第一个 Agent RL 训练循环完整转起来。