Multimodal tool-use RL on ChartQA: a Qwen2.5-VL-3B agent learns to call visual tools (highlight / mask / box-select), re-reads the edited chart in a second rollout pass, and is optimized with three generations of reward design (rule → shaped → gated Dr.GRPO) on verl/EasyR1 + Ray/FSDP + vLLM.
Mini ChartQA 是一个端到端的多模态工具强化学习项目:模型先对图表生成视觉工具调用(高亮 / 遮罩 / 框选行列),把编辑后的图像拼入第二轮 rollout 再作答,用 rule reward 或 LLM judge reward 做 RL 优化。项目覆盖了从数据工程、两阶段 rollout、三代 reward 设计、分布式训练到对角评测与可视化复盘的完整闭环。
- 三代 reward 演进,每一代都有设计文档 + 假设判据 + 实验复盘:v1 rule / LLM judge → v2 软 shaping(format / length / tool 三项可关停 delta)→ v3 G-RA 门控 + Dr.GRPO(docs/v2_design.md · docs/v3_design.md)。
- 对角验证证明无 reward hacking:同一份 v2 ckpt 在 rule scorer 和 LLM judge scorer 下打分仅差 0.001——模型学到的是真本事,不是"对 rule scorer 友好"的 reward 体操(docs/v2_results.md §3.1)。
- 诚实的实验复盘:no-tool 基线在 val 上至今领先(差距三代收窄 0.091→0.073→0.065 但未翻转)、v3 test 评测闭环未完成——这些边界都如实写进报告,口径见 docs/project_audit.md。
- 工程可信度:127 个单测、CPU-only 五阶段自检(scripts/validate.sh)、幂等环境安装脚本、batch 整除性等踩坑根因分析(docs/batch_sizing.md)。
- 14 个实验系列的交互式报告:reports/experiments_comparison/index.html(Chart.js,数据在同目录 metrics.json)。
训练 val(Qwen2.5-VL-3B,ChartQA):
| 系列 | reward | val acc 末段 | 峰值 | tool_success 末段 |
|---|---|---|---|---|
| v1 e1 | rule | 0.562@68 | 0.567 | 0.815 |
| v2 e6 | rule + shaping | 0.572@78 | 0.577 | 0.834 |
| v3 e10 | G-RA + Dr.GRPO | 0.584@146 | 0.598 | 0.879 |
| no-tool 基线(各代) | — | 0.645–0.653 | — | — |
Test(ChartQA test split,8 卡正式评测):
| 评测点 | scorer | accuracy | tool_call_ratio |
|---|---|---|---|
| v1@65 | rule | 0.424 | 0.757 |
| v1@215 | judge | 0.452 | 0.696 |
| v2@80 | rule | 0.432 | 0.760 |
| v2@80(对角) | judge | 0.433 | 0.760 |
三行关键结论:(1) v3 训练曲线三代最高,但同步数对比下增量主要来自训练更长;(2) 对角漂移 0.001,无 reward hacking;(3) v3 的 8 卡 test 评测(e13/e14)未闭环,不能宣称 v3 已证明优于 v2——完整边界见 docs/v3_results.md。
├── verl/ # 修改版 verl/EasyR1:两阶段工具 rollout、Dr.GRPO、token 级 reward 对齐
├── examples/
│ ├── format_prompt/ # 工具调用 prompt 模板(6 个视觉工具函数)
│ ├── reward_function/ # refocus v1 / llm / v2 / v3 / judge_panel 五代 reward
│ └── config.yaml # 训练默认配置
├── data/ # ChartQA + ReFocus 数据预处理(→ parquet,含 bbox 元数据)
├── scripts/ # validate.sh、extract_metrics.py、shortcut filter、SCS/VisualPRM reranker
├── tests/ # 127 个单测(reward invariants、Dr.GRPO advantage、filter)
├── judge/ # LLM judge 配置与 prompt(key 一律走环境变量)
├── acp-commands/ # v1/v2/v3 全部实验的可复制启动命令 + 环境安装脚本
├── docs/ # 设计文档、结果报告、审计、复现指南
├── reports/ # 交互式实验对比报告(index.html + metrics.json)
└── train.sh # 训练入口
pip install -r requirements.txt完整环境(CUDA / vLLM / 模型下载)见 docs/复现指南.md;一键幂等安装脚本见 acp-commands/install_env_v3.sh。
cd data
bash preprocess_data.sh # 生成 train/val/test 三个 parquet split规则 reward 主实验:
bash train.shLLM judge reward 实验:
JUDGE_OPENROUTER_API_KEY=<your-key> \
REWARD_TYPE=llm_batch \
REWARD_FUNCTION=./examples/reward_function/refocus_llm.py:compute_score \
EXPERIMENT_NAME=mini_chartQA_llm_judge_reward \
bash train.sh默认输出:日志 logs/<EXPERIMENT_NAME>-<RUN_ID>.log,checkpoint experiments/<EXPERIMENT_NAME>/<RUN_ID>/checkpoints/。可通过 EXPERIMENT_NAME、RUN_ID、TRAIN_FILES、VAL_FILES、FORMAT_PROMPT、VAL_ONLY、LOAD_CHECKPOINT_PATH 等环境变量覆盖,完整列表见 train.sh。
bash scripts/validate.sh # py_compile + bash -n + 127 个单测 + reward invariant smoke全部实验的可复制启动命令按代数维护:
| 代 | 实验 | 命令文档 | 设计 | 结果 |
|---|---|---|---|---|
| v1 | e1–e5:rule / judge / no-tool / test 评测 | acp-commands/1.md | — | 报告页 |
| v2 | e6–e9:shaping reward + 对角验证 | acp-commands/2.md | v2_design | v2_results |
| v3 | e10–e14:G-RA + Dr.GRPO + judge panel | acp-commands/3.md | v3_design | v3_results |
跑完训练后,把日志接入分析报告:
python3 scripts/extract_metrics.py \
--name <series_name> \
--log logs/<EXPERIMENT_NAME>-<RUN_ID>.log \
--out reports/experiments_comparison/metrics.json --merge
# 单步 test 评测加 --test-eval浏览报告:
cd reports/experiments_comparison && python3 -m http.server 8080
# 打开 http://127.0.0.1:8080/| 文档 | 内容 |
|---|---|
| docs/项目说明.md | 完整项目叙述:工具函数、数据、算法、reward,含示例图 |
| docs/项目专业说明报告.md | 浓缩版技术报告:研究背景、架构、设计决策 |
| docs/复现指南.md | 从零搭环境的完整步骤 |
| docs/project_audit.md | 项目审计:已完成 / 证据边界 / 遗留问题,对外表述口径 |
| docs/v2_design.md · docs/v2_results.md | v2 shaping reward 设计与 8 判据复盘 |
| docs/v3_design.md · docs/v3_results.md | v3 Dr.GRPO + G-RA 设计与结果(含未闭环边界) |
| docs/batch_sizing.md | 8 卡 batch 整除性 ValueError 根因推导 |
仓库只管理源码、配置、文档、报告数据和小型示例图片;checkpoints/、experiments/、logs/、datasets/、大型压缩包等高体量内容由 .gitignore 排除。
所有 API key 一律走环境变量(SWANLAB_API_KEY、JUDGE_OPENROUTER_API_KEY / OPENROUTER_API_KEY),不写入任何文件;本地私有配置可放入被忽略的 judge/judge_info.local.json(模板见 judge/judge_info.local.example.json)。