Mobile Agent RL

面向长链路 Agent 的强化学习复现实验：在 WebShop 交互环境中，用逐步进度归因（Stepwise Progress Attribution, SPA）缓解稀疏终局奖励带来的 credit assignment 问题。

为什么做这个项目

传统 Agent 在 WebShop、手机 GUI 等长链路任务中，往往需要连续完成搜索、筛选、查看详情和提交等多个动作。环境只在任务结束时给出成功或失败奖励，会产生两个直接问题：

• 早期动作很难获得明确的学习信号；
• 无效点击、不可执行动作和页面状态误判会不断累积。

这个实验把终局奖励重新分配为逐步进度信号，再结合环境可执行性反馈优化策略，让 Agent 不只知道“最终是否成功”，也能学习“哪一步推动了任务”。

Agent 在系统中的作用

flowchart LR
    U["用户目标"] --> P["Planner / Policy"]
    P --> A["结构化动作<br/>search / click"]
    A --> E["WebShop 环境"]
    E --> O["新 observation<br/>可执行动作集合"]
    O --> P
    E --> R["终局奖励"]
    P --> PE["Progress Estimator"]
    PE --> SR["逐步进度奖励"]
    R --> SR
    SR --> PPO["PPO 策略优化"]
    PPO --> P

Planner 根据目标、历史轨迹和当前 observation 生成下一步动作；环境负责执行并返回页面状态。Progress Estimator 估计每一步对最终任务完成度的增量贡献，PPO 使用稠密奖励更新策略。

我完成的复现与工程化工作

• 串联 SFT、轨迹探索、进度估计、奖励标注、PPO 与评测流程；
• 增加 FastChat controller、vLLM worker 和 WebShop exploration/evaluation 启动脚本；
• 增加 Progress Estimator 的 FP16 与 LoRA 训练变体，降低本地实验的显存门槛；
• 修复空有效 token 时的计算图中断风险，并统一标签精度；
• 将 PPO 输入整理为逐样本扁平 JSON，便于训练器直接消费；
• 调整小显存实验配置，并保留样例轨迹用于检查数据流。

关键入口：

快速开始

推荐环境为 Linux、CUDA GPU、Python 3.9/3.10。完整训练需要下载模型和 WebShop 数据，不适合在普通笔记本上直接运行。

conda create -n spa python=3.9 -y
conda activate spa
pip install -r requirements.txt

cd envs/webshop
pip install -e .
python -m spacy download en_core_web_lg

根据本机路径修改以下脚本中的模型目录：

sft/webshop_llama3b.sh
sft/merge_lora.py
prm/train_our_progress_model*.py
ppo/train_ppo.sh
eval/run_eval*.sh

启动 WebShop 推理服务与轨迹采集：

bash exploration/webshop/run_controller.sh
bash exploration/webshop/run_vllm.sh
bash exploration/webshop/run_explo.sh

训练进度估计器并生成 PPO 数据：

python prm/data_org.py
python prm/train_our_progress_model_lora.py
python prm/inference_prm.py
python prm/rl_data_org.py
bash ppo/train_ppo.sh

数据与模型

WebShop 原始数据、搜索索引、模型权重、完整训练日志和视频没有提交到 Git：

• 原始压缩包约 1.2 GB；
• 搜索索引压缩包约 2.8 GB；
• 模型权重需要按各基础模型的许可证单独下载；
• 本地演示视频超过 GitHub 普通文件上限。
• 原实验包中的 OpenAI 配置含本地凭据，因此整体排除；如需启用对应 Agent，请自行使用环境变量或本地忽略配置。

下载方法沿用 上游项目说明。仓库仅保留代码和少量脱敏样例。

实验结论与边界

本仓库验证的重点是训练链路与数据流，而不是声称已经交付真实手机控制产品。

• 当前代码环境是文本化 WebShop，不直接读取手机截图或操作 Android/iOS；
• 将其迁移到手机 GUI Agent，需要额外的视觉理解、UI grounding、执行器、安全确认与失败恢复模块；
• 项目材料中记录的业务指标没有附带可独立复算的完整日志，因此不在本 README 中作为已验证结果引用；
• 代码默认使用 Llama-3.2-3B 系列路径；项目构想中的 Qwen3-8B 版本需要重新适配和复现实验。

更完整的设计判断、踩坑与手机 Agent 映射见 docs/EXPERIMENT_NOTES.md。

项目结构

.
├── exploration/       # 环境探索、controller 与 worker 启动
├── prm/               # 轨迹整理、进度估计器训练与推理
├── ppo/               # step-level PPO
├── sft/               # 基础 Agent 的 LoRA SFT
├── eval_agent/        # Agent、任务、prompt 与环境抽象
├── eval/              # WebShop / ALFWorld / VirtualHome 评测脚本
├── envs/webshop/      # WebShop 环境代码
├── fastchat/          # 本地模型服务依赖代码
└── docs/              # 实验说明与边界

参考与致谢

• Hanlin Wang et al., SPA-RL: Reinforcing LLM Agents via Stepwise Progress Attribution, 2025.
• SPA-RL-Agent
• WebShop

如果引用 SPA-RL 方法或复用上游实现，请使用原论文给出的 citation。