RAGEN — 架构与原理

30 秒导读： RAGEN 是一个训练“会推理的 agent”的强化学习（RL）框架。它让 LLM 在一个 环境里多轮交互（每轮输出 <think>…</think><answer>…</answer>），把整条轨迹当作一个训练样本 来优化（这套做法叫 StarPO）。RAGEN-2 又加了两件诊断工具：用奖励方差筛掉学不到东西的 prompt，用互信息探测“推理崩塌成模板”。

---

1. 这是什么（零基础也能懂）

一句话定义。 RAGEN（Reasoning AGENT）是一个用强化学习训练 LLM agent 的框架：让模型 在环境里一边推理、一边行动，然后用“这条轨迹最终得了多少分”去反向优化它的推理与动作。

解决什么问题 / 给谁用。 假设你是一个 RL 研究者，想让 Qwen 学会解 Sokoban（推箱子）、走迷宫、 做数学题、写代码、搜索答题——这些都是“多轮、需要推理”的任务。你不光想要它“答对”，还想 看清楚训练为什么会崩、能不能修。RAGEN 就是为这个场景造的。

它能做什么（功能）。

• 用 StarPO 统一优化多轮 agent，同时支持 PPO 和 GRPO 两种估优势的方式。
• 内置 10+ 个 Gym 式环境（Sokoban、FrozenLake、Sudoku、Countdown、MetaMathQA、DeepCoder、Search、Lean、Bandit、2048、魔方…）。
• （V2）用奖励方差过滤挑掉“组内全对或全错”的无信息 prompt，只拿高信号的样本更新。
• （V2）用互信息诊断检测“模板崩塌”——推理看起来还很多样，但其实跳过了输入、变成了套话。

用起来什么样。 训练和评估都是一行命令（来自 README）：

# 训练（不过滤，默认）
python train.py --config-name _2_sokoban

# 训练（开 V2 的 SNR-Adaptive Filtering，Top-p）
python train.py --config-name _2_sokoban \
  actor_rollout_ref.rollout_filter_strategy=top_p \
  actor_rollout_ref.rollout.rollout_filter_value=0.9

# 评估
python -m ragen.llm_agent.agent_proxy --config-name _2_sokoban

配置靠 Hydra 组装：config/base.yaml 是默认底座，config/_2_sokoban.yaml 这种按环境覆盖（ 见 train.py:172 的 @hydra.main(… config_name="base")）。

一句话直觉 / 类比。 把它想成“给 LLM 请个教练 + 一套体检仪”：教练（StarPO）让模型反复下棋 并根据胜负调整棋风；体检仪（V2 诊断）随时抽血化验，看选手是不是“表面努力但脑子已经僵化成背诵”。

---

2. 顶层全景（它大概怎么转）

RAGEN 不是从零写一个 RL 库。它把 veRL（火山引擎的 RLHF 基础设施，FSDP 分布式训练 + vLLM 生成）当子模块，自己只负责“环境 ↔ LLM 的多轮缝合”这一层。

三大模块是主角。 README 明确说架构拆为三块：

模块	一句话职责	在哪个文件 / 类
Environment State Manager	管一大批并行环境：reset / step / 收集指标	ragen/llm_agent/es_manager.py · EnvStateManager
Context Manager	在“环境输出”和“LLM token 输入”之间双向翻译，管 loss mask / 奖励	ragen/llm_agent/ctx_manager.py · ContextManager
Agent Proxy	调度两者 + 调 LLM 生成，跑出一批轨迹	ragen/llm_agent/agent_proxy.py · LLMAgentProxy
RayAgentTrainer	StarPO 主循环：调 rollout → 过滤 → 算优势 → 更新	ragen/trainer/agent_trainer.py · RayAgentTrainer

一张顶层图（一个训练 step 的数据流）。 从上往下读，上半是 rollout（采样），下半是 update（更新）：

  RayAgentTrainer.fit()   一个 step
         │
         ▼
  ┌───────────────── rollout 阶段 ──────────────┐
  │  Agent Proxy.rollout()                       │
  │     ├─▶ EnvStateManager.reset()  → 初始状态    │
  │     │   ── 重复 max_turn 轮 ──                 │
  │     ├─▶ CtxManager.get_lm_inputs()  状态→token │
  │     ├─▶ LLM.generate_sequences()   token→回复  │
  │     ├─▶ CtxManager.get_env_inputs() 解析出动作  │
  │     └─▶ EnvStateManager.step()    动作→新状态+奖励│
  │  CtxManager.formulate_rollouts() → DataProto  │
  └──────────────────────────────────────────────┘
         │  (一批轨迹，带 input_ids/loss_mask/rm_scores)
         ▼
  ┌───────────────── update 阶段 ──────────────┐
  │  （V2）collapse_detector → MI / 检索准确率指标  │
  │  rollout_filter.filter() → 按奖励方差筛掉低信号组│
  │  compute_log_prob / compute_advantage         │
  │  actor_rollout_wg.update_actor() → 梯度下降    │
  └──────────────────────────────────────────────┘

主线走一遍（高层、不进代码）。 输入是“空的训练指令”，RayAgentTrainer.fit() 调 agent_proxy.rollout() 跑出一批多轮轨迹 → （V2）先算崩塌指标、再按奖励方差过滤 → 算出优势 → 调 veRL 的 actor worker 做梯度更新 → 输出是更新过的模型权重。

一个贯穿全场的数据结构：DataProto。 这是 veRL 的容器，同时装张量（batch，是一个 TensorDict）和非张量（non_tensor_batch，如 env_ids/group_ids/messages_list）。三大模块全靠它 传递状态（ragen/llm_agent/ctx_manager.py:380 的 _build_dataproto）。

---

3. 阅读地图（建议顺序）

这是一个多子系统项目，拆成了四章，按“先结构、再主循环、最后两个 V2 诊断点”由浅入深。

1. 01-three-managers.md — 三大模块。先看清“环境状态管理器 / 上下文管理器 / Agent 代理” 各干什么、数据怎么在他们之间流。这是看懂其他三章的前提。
2. 02-starpo-loop.md — StarPO 主循环。rollout 怎么采一批轨迹，loss mask / 奖励怎么贴到 token 上， update 阶段怎么算优势（GRPO / PPO）。
3. 03-rollout-filtering.md — V2：SNR-Adaptive Filtering。为什么用组内奖励方差做信号代理， top_p / top_k / min_p 怎么选组，过滤后怎么接回训练。
4. 04-collapse-mi.md — V2：模板崩塌诊断。为什么 entropy 看不出模板崩塌，怎么用交叉 log-prob 算出 I(X;Z) 和检索准确率。

如果你只想快速拓展一个新环境：看 ragen/env/base.py 的 BaseEnv 接口 + ragen/env/sokoban/env.py 作为范例，再在 config/envs.yaml 里注册一个 custom_envs 条目即可。

---

4. 代码地图（顶层入口）

主题	文件	符号
训练入口 / Ray 启动	train.py	main · run_ppo · TaskRunner.run
配置校验 + 依赖推导	train.py	add_dependency_and_validate_config
StarPO 主循环	ragen/trainer/agent_trainer.py	RayAgentTrainer.fit
一批多轮轨迹采样	ragen/llm_agent/agent_proxy.py	LLMAgentProxy.rollout
环境池管理	ragen/llm_agent/es_manager.py	EnvStateManager.reset · .step · .get_rollout_states
状态↔token 双向翻译	ragen/llm_agent/ctx_manager.py	ContextManager.get_lm_inputs · .get_env_inputs
V2 过滤器	ragen/trainer/rollout_filter.py	build_rollout_filter · RewardRolloutFilter
V2 崩塌诊断	ragen/trainer/collapse_metrics.py	CollapseDetector.compute_collapse_metrics
GRPO 优势（带 episode 去重）	ragen/trainer/core_algos.py	compute_grpo_outcome_advantage
环境注册表	ragen/env/__init__.py	REGISTERED_ENVS · REGISTERED_ENV_CONFIGS

本文所有引用 as-of commit 20daedc4。注：verl 是 git 子模块，本次 clone 中 verl/ 为空， 凡是涉及 veRL 内部（FSDP worker、PPO actor loss、GAE 基础实现）的论断均为从调用点 (inferred)， 非读过 veRL 源码。