🇨🇳 中文 | 🇬🇧 English | 🇪🇸 Español | 🇯🇵 日本語
基于 ReAct Agent + arXiv 工具的 Agentic RL 训练环境 支持 SFT/DPO/GRPO/OPD 训练路径与可验证奖励(RLVR),用于研究 LLM Agent 强化学习。 终极目标:端侧部署的轻量多模态论文助手——从检索、下载、翻译到总结、识图的端到端论文阅读模型。
将 arXiv 论文检索/下载/翻译/解读任务改造为可训练的强化学习环境,专注于:
- Verifiable Reward:基于规则化奖励(工具调用准确度、任务完成度、解析错误等),无需人类标注
- 渐进式训练:SFT → DPO → GRPO(另提供 OPD on-policy 蒸馏路线;PPO 在当前依赖下不可用)
- 轻量级工程:纯 Python + JSONL 存储,无数据库、无前端,专注离线训练
非目标:生产级 arXiv 应用与实时翻译服务。AgenticArxivWeb/ 保留在本仓库,将改造为 RSI 环境协同进化的沙盒载体(见 Roadmap P3);历史原版见 AgenticArXiv。环境改造的完整设计文档见 docs/rl_building.md。
默认关闭的判别式 next-tool router(TOOL_ROUTER=jev):在小样本结构验证中 strict success 40%→60%、本地 Qwen token −74%,不接入 GRPO 训练。
展开:Jev 路由机制、回退策略与实验详情
普通 ReAct 推理支持默认关闭的 Jev next-tool router:Jev 选择下一步工具,guided 模式
用确定性解析器处理显式参数,含糊参数仍交给策略模型,环境继续执行工具。默认
TOOL_ROUTER=policy 完全保留原行为;显式设为 jev 后,低置信度、API 故障或参数
验证失败都会回退原策略路径。该功能不接入 GRPO 训练。配置、baseline、81 条
routing-only pilot、限制与复现方式见
JEV_ROUTER.md,可复制的开关/API 配置见
jev_config.example.env。另有无需 GPU/网络的 project-interface
smoke,验证 policy/Jev 两条路径可经过同一 ReAct、环境和 benchmark 接口互换。真实
GRPO Qwen 的 mixed 10-task、repeat=3 小样本中,guided Jev 将 strict success 从 40%
提高到 60%,本地 Qwen token 减少 74.01%,总延迟增加 36.96%。该结果是小样本结构
验证,不代表完整 81 题总体胜率。
# 1. 克隆并安装(Python 3.9+)
git clone https://github.com/Algorineko/AgenticArXiv-RL.git
cd AgenticArXiv-RL
python3 -m venv .venv && source .venv/bin/activate
pip install -r AgenticArxiv/requirements.txt
# 2. 配置 LLM API(API rollout 需要;本地模型训练/评测不需要)
cat > AgenticArxiv/.env << 'EOF'
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-api-key
MODEL=gpt-4-turbo
EOF
# 3. 测试 Rollout(奖励范围 [-1, 1],随轨迹变化)
python -m AgenticArxiv.rl.rollout search_01 traces/train/
# ✅ Task search_01 rollout 完成 Reward: 1.00批量 rollout:python -m AgenticArxiv.rl.rollout --all --output_dir traces/train/。后续命令默认在仓库根目录执行。
论文任务改造为 MDP:10 工具动作空间 + 五分量可验证奖励(RLVR)+ 轨迹间隔离,全部规则可判、离线可复现。
展开:MDP 设计 · 动作空间(10 工具)· 五分量可验证奖励 · Rollout 隔离
| 维度 | 定义 |
|---|---|
| State | 任务描述 + 对话历史 + 工具结果 |
| Action | 10 个工具(见下)+ FINISH |
| Reward | 五分量多粒度可验证奖励(format / tool / argument / process / outcome) |
| Transition | execute_tool(action) → observation(MockArxivEnv 离线快照回放,确定性可复现) |
get_recently_submitted_cs_papers(aspect, days, max_results)— 按子领域+时间窗浏览search_arxiv_papers(query, max_results, days=None)— 关键词/标题/作者检索download_arxiv_pdf(ref, session_id)— 下载 PDFtranslate_arxiv_pdf(ref, session_id)— 翻译 PDF(pdf2zh)get_paper_cache_status(ref, session_id)— 查询缓存状态get_paper_content(ref, session_id, section=None)— 读取摘要或指定章节(确定性抽取)summarize_paper(ref, style, max_words)— env 侧摘要(tldr / structured / bullet)extract_paper_figures(ref)— 抽出图表文件与 captionanalyze_figure(ref, figure_no, question=None)— 图表分析:env 侧调本地 VLM 读图(多模态环境启用)get_translated_content(ref, session_id, page=1)— 按页读取译文(翻译后的中文 PDF,确定性抽取;第 1 页通常是标题与摘要)
「检索 → 下载 → 阅读 → 总结 → 抽图 → 识图」解读闭环已全部打通:识图由本项目后训练的 FigureQA VLM 在 env 侧完成并录制快照,策略侧有学会该四步链的 SFT-T5 权重。 准入原则:动作空间不是越大越好——新增工具的准入标准是「能开启一类新任务」,而不是「可能有用」。设计决策链见 工具集演进设计。
多粒度可验证奖励(rl/reward.py)。五个分量归一化到 [-1, 1],另有诊断分量与不可补偿的失败上限:
| 分量 | 默认权重 | 信号 |
|---|---|---|
format |
1 | 每步 action 是否为合法 JSON 工具调用或终止符 |
tool |
3 | 预测与期望工具序列的顺序感知 LCS-F1 |
argument |
2 | 参数键召回率 × 精确值准确率 |
process |
1 | 合法步骤加分 − 解析/执行失败/多余调用惩罚 |
outcome |
3 | 正确完成 +1、路径错误完成 +0.25、强制停止 −0.5、错误 −1 |
result_quality / efficiency |
诊断 gate | observation 是否真实成功;严重冗余触发 reward 上限 |
- 课程学习:前 30 步将
tool/argument/outcome权重乘 1/3(RewardCalculator.schedule)。实测结论:SFT 起点已学会 ReAct 结构(format 起点 0.983),课程两臂对照不可区分——从 SFT 起点请直接--reward_curriculum_steps 0,该档位留给冷启动场景。 - 非补偿性失败:解析失败、执行失败、虚假 FINISH 最多得负奖励,不得靠格式分抵消;
analyze_figure缺有效答案时总奖励上限 −0.75。 - 所有奖励 rule-based 可验证(RLVR),每条轨迹记录
reward_components明细,便于审计。判定细则见 多粒度奖励文档。
rl/sandbox.py 的 RolloutSandbox 在每条轨迹前记录环境/Store/产物目录基线,轨迹后恢复并清理——多轮 GRPO、rollout 与 benchmark 共用该 reset 契约,杜绝轨迹间状态串联。
SFT → DPO → GRPO 渐进式训练,OPD on-policy 蒸馏与 GRPO 互替,PPO 在当前依赖下不可用;GSPO / Dr.GRPO / DAPO 目标变体已接线并完成对照训练发布。
展开:各阶段训练命令与说明(SFT · DPO · GRPO 及变体 · OPD · 多模态 VLM)
python scripts/generate_parametric_sft_data.py # 参数化派生专家轨迹(无需 API)
python -m AgenticArxiv.rl.train_sft # 产出 outputs/sft/final已发布:AgenticArXiv-RL-Qwen2.5-1.5B-SFT(Qwen2.5-1.5B 全参,2 epoch / 2628 条专家轨迹,loss 0.079;只覆盖前 8 个工具)。
python scripts/generate_dpo_data.py --model outputs/sft/final --num_rollouts_per_task 8
python -m AgenticArxiv.rl.train_dpo # 产出 outputs/dpo/final偏好对来自 SFT 模型本地采样(无需 LLM_API_KEY);有快照时自动离线回放,仅奖励差超过 --min_reward_gap 且首工具不同的轨迹组成对。
python -m AgenticArxiv.rl.build_snapshot # 生成离线快照(唯一联网步骤)
python -m AgenticArxiv.rl.train_grpo --model outputs/sft/final --max_turns 4
# DAPO 预设(loss_type=dapo + clip-higher + overlong filtering + dynamic sampling)
python -m AgenticArxiv.rl.train_grpo --model outputs/sft/final --dapo
# 序列级重要性采样(GSPO)与 Dr.GRPO 无偏变体
python -m AgenticArxiv.rl.train_grpo --model outputs/sft/final --importance_sampling_level sequence
python -m AgenticArxiv.rl.train_grpo --model outputs/sft/final --loss_type dr_grpo
# 多卡(DDP 双卡实测跑通;FSDP 需 torch>=2.6)
accelerate launch --config_file configs/accelerate/ddp_2gpu.yaml \
-m AgenticArxiv.rl.train_grpo --model outputs/sft/final --no-qlora
# 训练曲线
python -m AgenticArxiv.rl.train_grpo --report_to tensorboard
tensorboard --logdir outputs/grpo/logs已发布:AgenticArXiv-RL-Qwen2.5-1.5B-GRPO(33 条信号任务,全程离线快照回放)。离线评测(seed 45 / repeat 3,严格成功率 pass³)SFT → GRPO:rl_train 0.081→0.636,dev 0.000→0.375,iid_test 0.056→0.444,ood_test 0.000→0.500。
目标变体对照(seed 42 / 60 步,pass³,权重均已发布见下表):GSPO 与基线逐位持平(轨迹分化、行为收敛一致);Dr.GRPO rl_train 0.657 略优、ood 工具准确率最优;DAPO 三切分最优(0.667 / 0.500 / 0.481 / 0.500)。实现注记见 docs/rl_paradigm_comparison.md。奖励权重消融框架:
--reward_config支持 9 组单变量权重设计(docs/ablation_reward_weights.md,🟡 设计完成待执行)。
多轮 rollout 与打分(rl/grpo_reward.py):每轮由当前 policy 生成 ReAct 动作,独立 MockArxivEnv 执行并把 observation 插回上下文;assistant token 进 loss,环境 token 经 env_mask=0 只作上下文;完整轨迹交五分量 RewardCalculator 打分,与 rollout / benchmark 同一标准。
训练质量保障(静默失败 → 响亮报错):生成长度体检、零方差守护(RewardVarianceGuard)、Canary 中途评估早停、阶段验证阈值(SFT 可解析率 ≥ 0.3、DPO 奖励 ≥ −0.3、GRPO 奖励 ≥ −0.2)、混合精度自适应、日志后端预校验。曲线除 TRL 自带指标外记录 reward_components/*(分量明细)、reward_weights/*(课程权重)、rollout/*(turns / finished / parse_error_rate)。
python -m AgenticArxiv.rl.train_opd --model outputs/sft/final \
--teacher Qwen/Qwen2.5-7B-Instruct --max_turns 4 --snapshot data/mock_arxiv_snapshot.json学生在任务 prompt 上 on-policy 采样,教师给逐 token logprob,损失取 reverse-KL(mode-seeking)。与 GRPO 的关系:
| 维度 | GRPO | OPD |
|---|---|---|
| 学习信号 | 可验证奖励(稀疏、轨迹级) | 教师逐 token logprob(稠密) |
| 额外模型 | 无 | 教师模型(需本地权重) |
| 上限 | 可探索超越教师 | 收敛到教师行为 |
| 适用 | 有可验证奖励 | 有强教师、想省探索成本 |
TRL 已移除经典 PPOTrainer(trl>=0.28.0 上不存在),train_ppo.py 会在 import 阶段给出明确说明后退出。有可验证奖励走 GRPO、有强教师走 OPD,两者都比 PPO 省显存。
python scripts/build_figure_qa_dataset.py # 图表 QA 种子数据
python -m AgenticArxiv.rl.train_vlm_figure_qa # Qwen3-VL-4B LoRA 后训练
# 将 /path/to/figureqa 替换为本地 FigureQA 模型目录
FIGURE_ANALYSIS_BACKEND=vlm VLM_MODEL_PATH="/path/to/figureqa" \
python -m AgenticArxiv.rl.backfill_figure_analysis --snapshot data/mock_arxiv_snapshot.json已发布:AgenticArXiv-RL-Qwen3-VL-4B-FigureQA(451 图 / 73 论文,按论文切分防泄漏;留出 94 图 ROUGE-1 0.105→0.126、ROUGE-L 0.081→0.102)。8B / 27B 策略侧 VLM 的全链路成果见下文「🏆 端侧 VLM 后训练成果」。
| 模型 | 基座 | 说明 |
|---|---|---|
| AgenticArXiv-RL-Qwen2.5-1.5B-SFT | Qwen2.5-1.5B | 阶段1 全参 SFT(前 8 工具) |
| AgenticArXiv-RL-Qwen2.5-1.5B-GRPO | Qwen2.5-1.5B | 阶段3 GRPO(四切分评测见上) |
| AgenticArXiv-RL-Qwen2.5-1.5B-GRPO-GSPO | Qwen2.5-1.5B | GRPO + 序列级重要性采样(四切分与基线持平,见范式对比文档) |
| AgenticArXiv-RL-Qwen2.5-1.5B-GRPO-DrGRPO | Qwen2.5-1.5B | GRPO 无偏变体(rl_train 0.657 / dev 0.375 / iid 0.444 / ood 0.500,pass³) |
| AgenticArXiv-RL-Qwen2.5-1.5B-GRPO-DAPO | Qwen2.5-1.5B | DAPO 目标、无动态采样(rl_train 0.667 / dev 0.500 / iid 0.481 / ood 0.500,pass³,三变体最优) |
| AgenticArXiv-RL-Qwen2.5-1.5B-SFT-T5 | Qwen2.5-1.5B | SFT + analyze_figure 四步链(rl_train 0.485 / dev 0.250 / iid 0.278 / ood 0.250,pass³) |
| AgenticArXiv-RL-Qwen3-VL-4B-FigureQA | Qwen3-VL-4B | env 侧图表分析 VLM |
| AgenticArXiv-RL-Qwen3-VL-8B-GRPO | Qwen3-VL-8B | 端侧论文助手主模型:策略侧多模态,SFT→DPO→GRPO 全链路(81 任务 strict 72.8%,base 2.9 倍;图表 ROUGE-1 +32%) |
| AgenticArXiv-RL-Qwen3.8-27B-SFT | Qwen3.8-27B | 图表理解特化研究版(clean-val ROUGE +60%/+87%;工具决策未达标准,见实验文档) |
全部托管于 ModelScope(Algorineko/AgenticArXiv-RL-*),model card 含离线评测表与诚实限制说明。
在 4×64GB 海光 DCU 上完成 Qwen3-VL-8B 的 SFT → DPO → GRPO 全链路后训练,以及 Qwen3.8-27B(原生多模态)的图表理解特化 SFT。数据经 clipart 过滤与工具手册规范化两轮 治理;评测统一 greedy 确定性协议、81 任务离线 benchmark + clean-val 图表 ROUGE。
| 阶段 | 81 任务 strict | 完成率 | 工具准确率 | 假结束 | clean ROUGE-1 |
|---|---|---|---|---|---|
| 8B base | 24.7% | 80.2% | 32.1% | 22.2% | 0.1139 |
| 8B SFT v3 | 66.7% | 95.1% | 72.8% | 8.6% | 0.1446(+27%) |
| 8B DPO v3 | 65.4% | 97.5% | 74.1% | 11.1% | 0.1435 |
| 8B GRPO v3(主模型) | 72.8% | 97.5% | 82.7% | 6.2% | 0.1509(+32%) |
| 27B base(对照) | 24.7% | 80.2% | 32.1% | 22.2% | 0.1349 |
| 27B cap SFT(研究版) | 21.0% | 66.7% | 25.9% | 4.9% | 0.2164(+60%) |
主模型:8B GRPO(strict 72.8%)= 27B base 的 2.9 倍,strict 成功率和工具准确率在上表中最高, 两次独立运行的 strict 分别为 71.6% 和 72.8%(任务翻转率 4.9%);图表识别 clean-val ROUGE-1 相比 8B base 提升 32%。 27B 容量升级版(r128)图表识别 +60%/+87%(全项目最优)作为研究版一并发布—— 小数据 LoRA 在 27B 强先验上的适配边界与三轮根因分析(clipart 污染 / 注册表漂移 / 采样协议) 完整记录(选型 / 数据演进 / 四轮实验 / 根因分析)见 docs/edge-vlm-posttrain.md。
- 冒烟集(
benchmark/tasks.py):8 条(search / download / translate / cache / composite) - 扩展集(
benchmark/tasks_expanded.py):86 条、十四类模板(search / keyword_search / ref_form / composite / state / optional / constraint / long_chain / infeasible / paper_reading / paper_summary / figure_extraction / figure_analysis / translation_reading),run_benchmark.py --task-set expanded启用。两套任务统一走TaskSpec:expected_tools/expected_tool_args由同一份steps派生,不出现两份手写列表漂移。 - 切分:按模板切 train / iid_test / ood_test(
benchmark/splits.py,固化于data/splits/);rl_train只取成功率中间带(两端组内方差为零、不产生梯度)。换模型后需重新测量 rates,不能沿用旧档位。 - 评测口径:
pass^k可靠性(tau-bench 口径)、false_finish(退化策略always_finish91.5% vsreference0%)、ref_score(比paper_id而非ref写法)、代价按成功次数归一。 - 区分度闸门(
run_baselines.py):确定性退化策略逐类目卡门槛——「永远搜 cs.AI」在检索类 0.833→0.446,「本该不调工具却调了」+0.165→−0.235。 - 坏例回放(
eval/badcase_replay.py+eval/eval_cases.jsonl,17 条):失败轨迹冻成永久回归用例,回放只跑打分器,pytest即闸门;hack/*记录骗分形态并配阈值断言,兼作 reward hacking 案例库。
python -m AgenticArxiv.benchmark.run_benchmark --task-set expanded --split iid_test --offline核心依赖(AgenticArxiv/requirements.txt):torch>=2.0、transformers>=4.45、trl>=0.28.0(已在 0.29.1 验证;下限由多轮 GRPO 的 rollout_func 路径决定)、peft、bitsandbytes(QLoRA)、datasets、accelerate、arxiv、requests、python-dotenv、loguru、pydantic>=2、fire、PyMuPDF>=1.24.0、Pillow。
可选依赖(AgenticArxiv/requirements-extra.txt):pdf2zh(真实 PDF 翻译)、fastapi/uvicorn/sqlalchemy/pymysql(归档的 Web 兼容层)、mcp(归档的 MCP 兼容层)、tensorboard/wandb(曲线后端)、matplotlib/numpy/pandas(绘图脚本)。
- 文档:工具集演进设计 · 多粒度奖励 · 指标统计 · Roadmap 调研笔记 · TRL 文档
- 方法论文:RLVR;DPO (Stanford, 2023);On-Policy Distillation (Thinking Machines, 2025);GKD (arXiv:2306.13649)
- 原版:AgenticArXiv(Web 应用版,FastAPI + Vue3 + MySQL)
欢迎 Issue 与 PR!流程:Fork → feature 分支 → pytest AgenticArxiv/tests/ → feat: 前缀提交 → PR。详见 CONTRIBUTING.md。
MIT License
展开:常见问题(与原版区别 · 为何 GRPO · 质量为何不进奖励)
Q: 与原 AgenticArXiv 的区别? 原版是生产级 Web 应用(FastAPI+Vue3+MySQL,三种 Agent 架构);本项目是纯 Python + JSONL 的 RL 训练环境,只保留 ReAct 单策略,核心是 SFT/DPO/GRPO 训练与可验证奖励。
Q: 为什么选 GRPO 不用 PPO? GRPO 无需 value model(显存开销小)、适合 1.5B 量级小模型、实现简单易调试;PPO 更适合生产级大模型训练。
Q: 摘要/识图的质量为什么不进奖励? 质量打分需要 LLM-as-judge,引入非确定性与 hacking 面。设计上把解读收敛为工具调用决策问题(何时调、对谁调、参数对不对)——全部规则可判、可复现,这是 RLVR 的前提。
完整论据与引入路径见 docs/roadmap_notes.md。已完成项已融入正文各章节。欢迎认领(见 🤝 贡献)。
展开:开发路线图(P0 端侧闭环 · P1 新算法 · P2 Jev · P3 协同进化 · ⛔ 阻塞项)
- 端到端阅读链:检索 → 下载 → 翻译 → 总结 → 识图在单模型内闭环,面向端侧推理(量化 + 2–4B 量级)优化。翻译环节已具备(
get_translated_content按页确定性读取 pdf2zh 译文 +build_snapshot --translate-max-ref N快照回放);策略侧多模态化已完成 8B 全链路(见「🏆 端侧 VLM 后训练成果」与 VLM 后训练记录),剩余核心是把全链压进端侧预算
- SAO 式异步训练:迁移 verl
fully_async_policy/ AReaL,先引入 skip-observation 掩码与 DIS 双边裁剪(arXiv:2607.07508,官方代码未开源) - 跨步信用分配:GiGPO / ARPO 式组内跨步优势,缓解长程链的轨迹级稀疏信号(自研研究项)
- Agentic TTT(测试时训练/适应):TTT 在具身智能已广泛应用,LLM Agent 层面是否成立是开放问题。本仓库形态:单篇论文 episode 内自生成 QA/摘要尝试 → 多数票/验证器伪奖励(TTRL,arXiv:2504.16084)→ 少步 LoRA 更新 → 复答,与长上下文 ICL 基线对照验证「即时特化」是否划算。约束:端侧延迟预算、灾难性遗忘、TTT 非确定性与 RLVR 可复现评测的冲突、离线快照下「在测试分布上训练」的口径界定
- Jev 式判别头:非自回归结构化决策(choice/score,成本 ~LLM 的 1/400),候选落点:①
result_quality判别头替代规则 ② 奖励分量路由器(替代固定课程表)③ 工具选择的结构化解码(封闭枚举天然适合判别式)。约束:确定性推理或只作诊断信号,保持 RLVR 可复现 - RLCD 自训 Jev:正/负对比信号(成功 vs 失败的工具决策轨迹,可验证奖励免标注)+ 对比损失训练判别头,替代外部 TypeSafe API。双臂对照已验证(docs/jev_rlcd.md):对比项对纯 CE 基线四 suite 全胜(992 冻结点,McNemar p<0.0001,Δ +33.0pp);链中步 91.0%、0.80 门控内高准确;首步复合链 53.1% 为已知短板(门控下安全回退)。待做:首步定向增强、
TOOL_ROUTER=local接线
- 自进化数据闭环:留出评测暴露弱点 → 坏例库自动扩容 → 参数化派生针对性数据 → 再训练 → 冻结新留出集(复用现有评测/数据/训练管线,前置件已齐);验收:每轮四切分 pass³ 不回退、坏例库只增不减(arXiv:2609.11873 四步循环)。编排器已落地(
AgenticArxiv/rl/self_evolve.py:diagnose → mine → select → synthesize → freeze → gate,纯 JSON、无需模型;generate_parametric_sft_data.py --only-parents定向补数据),真实一轮训练与四切分对照待跑(见 docs/roadmap_notes.md) - Harness + environment 协同进化:自进化不止于权重(数据闭环见上条)——Harness 侧:提示词 / 工具路由 / 工作流的 DGM 式自改与 archive(Darwin Gödel Machine, arXiv:2505.22954);environment 侧:任务分布 / 奖励函数自生成(Absolute-Zero 式 self-play,arXiv:2505.03335),环境载体 = 改造
AgenticArxivWeb/为可演化任务/奖励沙盒。bounded 纪律不变:manifest SHA256 审计、四切分留出闸门、人工晋升
- vLLM 加速采样:TRL 0.29 要求 vLLM 0.10.2–0.12.0,本机平台定制版 0.6.2 装在一起会让 GRPOTrainer import 失败。属环境依赖而非代码改动,待平台提供匹配构建。
开始你的 Agentic RL 训练之旅! 🚀
感谢每一位让本项目变得更好的贡献者:
