【免费下载链接】axrl
AxisRL is an agentic RL post-training framework built on SGLang rollout, Megatron training, and real-world agent workflows.
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 恰好全中：
| 维度 | GSM8K 的特点 |
|---|---|
| 数据量 | 约 7.5K 训练题，小规模机器也能跑 |
| 奖励信号 | 答案唯一，规则匹配即可验证，无需奖励模型 |
| 交互轮数 | 单轮生成（step-by-step 推理后输出答案），逻辑清晰 |
| 模型规模 | 官方 recipe 默认 Qwen2.5-1.5B-Instruct，8 卡即可 |
AxisRL 将每个任务封装为一个recipe（配方），任务特定的数据集加载、环境循环、验证器、奖励计算都集中在 axis_recipe/ 目录，而 rollout 调度、样本构造、权重同步等系统层由框架统一处理。GSM8K 的两个 recipe 就是最理想的入门路径。
认识 AxisRL 的数据流架构：5 步闭环
在动手之前，花 2 分钟理解 AxisRL 的一次训练循环长什么样，后面看日志就不迷路了：
- Rollout Actors领取任务，驱动环境（GSM8K 场景下就是"出题 → 生成 → 判分"）；
- SGLang Workers提供高吞吐的模型生成服务；
- 环境 / 验证器产生交互记录和 reward；
- Megatron Workers消费训练样本，执行 GRPO 或 PPO 训练；
- 更新后的权重同步回 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_gsm8k/run-train-pipeline-grpo-GSM8K.log |
| TensorBoard | logger_type: tensorboard，按project_name/group_name归档 |
| 权重 checkpoint | 由checkpoint_every_n_global_updates控制（脚本默认拉长，验证时不触发） |
读懂 GRPO 配置文件的 4 个关键参数
打开 pipeline_config.yaml，新手重点关注这 4 处：
- 模型与数据：
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； - GRPO 组采样：
num_rollouts_per_conversation: 8—— 每道题采 8 条回复组成一个组，用组内相对收益估计 advantage，这正是 GRPO 省掉 value 模型的秘诀（配置第 282–301 行）； - 训练目标：
grpo.loss_type: grpo，附带clip_ratio_high/low: 0.2的 PPO 式裁剪和 dual-clip 负 advantage 因子（配置第 192–220 行）； - 权重同步节奏：
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 中：
| 配置项 | GRPO recipe | PPO recipe | 含义 |
|---|---|---|---|
grpo.loss_type | grpo | ppo | advantage 估计方式：组内相对 vs value 模型 |
value_worker | null | 完整 worker（model_role: value） | PPO 需要独立的 value 模型估计 V(s)，见配置第 114–119 行 |
grpo.ppo_value | null | gamma: 1.0, gae_lambda: 1.0, value_clip: 0.2 | GAE 参数与 value loss 裁剪，见配置第 378–384 行 |
也就是说：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 个点
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 启动时报 GPU 资源不足 | 默认tp=2, pp=2+ rollouttp=2colocated，需 8 卡 | 换 8 卡机器，或用--rollout_worker.tp_size=1等方式降并行度 |
| 模型 / 数据找不到 | 未跑download_data.py，或路径不匹配 | 手动下载后修改megatron_worker.model.name与train_datasets的data_path |
| reward 始终为 0 | 模型还没学会####输出格式 | 正常现象：先观察训练若干步后格式是否出现，这是奖励塑形前的冷启动 |
| 训练速度比预期慢 | 默认global_batch_size: 512、每题 8 条 rollout | 验证阶段把max_global_updates调小即可；正式训练再放开 |
🔧 通用技巧：任何配置字段都可用--path.to.field=value命令行覆盖，不需要改 YAML 文件；完整的配置解析规则见 docs/config-parsing.md。
下一步：从 GSM8K 走向真正的 Agent 任务
跑通这两个 recipe 后，AxisRL 还为你准备好了进阶路线：
- Search-R1：多轮、带检索工具的 white-box agent 任务，入口 axis_recipe/search_r1/run_train.sh，需要额外启动一个 retrieval server；
- Black-Box RL：OpenHands + E2B 沙箱的 black-box 集成，通过 OpenAI 兼容 proxy 捕获任意 agent harness 的交互轨迹，见 axis_recipe/blackbox_rl/README.md；
- 一致性调试：如果正式训练中遇到 loss 尖峰或 rollout/trainer 不一致，参考 skills/axrl-spike-replay/ 下的排查清单。
总结：AxisRL 把"高吞吐 rollout、大规模训练、权重同步、可观测性"封装成一条闭环，你只需关注 recipe 中的环境、奖励与训练配置。从bash axis_recipe/grpo_gsm8k/run_train.sh开始，3 条命令就能看到你第一个 Agent RL 训练循环完整转起来。
【免费下载链接】axrl
AxisRL is an agentic RL post-training framework built on SGLang rollout, Megatron training, and real-world agent workflows.
相关推荐
AReaL 快速入门：用 GRPO + 函数奖励在 GSM8K 上完成首个 RL 训练实验
AReaL 快速入门：用 GRPO + 函数奖励在 GSM8K 上完成首个 RL 训练实验 导读 AReaL 是一个面向 LLM Agent 应用的强化学习桥接
人工智能大模型强化学习分布式训练AxisRL Black-Box RL 实战：在 E2B 沙箱中用 LeetCode 题目训练 Coding Agent
AxisRL Black Box RL 实战：在 E2B 沙箱中用 LeetCode 题目训练 Coding Agent AxisRL 是一个基于 SGLang
openJiuwen Agent RL 强化学习训练扩展完全指南：从离线 PPO/GRPO 训练到在线轨迹采集
openJiuwen Agent RL 强化学习训练扩展完全指南：从离线 PPO/GRPO 训练到在线轨迹采集 openjiuwen.agent_evolvin
人工智能大模型AI Agent工具调用工作流编排提示工程
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
