UI-S1 半在线强化学习实战指南基于 MLLM 的 GUI 自动化代理训练、推理与评估【免费下载链接】MobileAgentMobile-Agent: The Powerful GUI Agent Family项目地址: https://gitcode.com/GitHub_Trending/mo/MobileAgentUI-S1 是 MobileAgent 家族中专注于GUI 自动化代理GUI Agent训练的开源项目其核心贡献是提出**半在线强化学习Semi-online RL**范式——利用离线轨迹模拟在线强化学习过程从而以接近离线训练的成本高效训练基于多模态大语言模型MLLM的 GUI 代理并显著增强其多轮交互能力。本文以 UI-S1/README_zh.md 为主线结合仓库内的训练脚本、verl 训练框架配置与核心算法实现完整讲解半在线 RL 的原理、环境搭建、AndroidControl 数据处理、DAPO uis1 优势估计的训练流程以及基于 vLLM 的推理与 SOP 评测方案读者可据此从零复现 UI-S1-7B 的训练与评估全链路。半在线强化学习用离线轨迹模拟在线交互传统的 GUI 代理强化学习训练主要面临两种困境离线 RLOffline RL仅基于静态轨迹做单轮优化训练成本低但模型难以掌握多轮交互能力面对真实环境的多步任务时表现受限在线 RLOnline RL在动态交互环境中按 K 轮 Rollout 训练模型多轮能力强但需要真实环境持续反馈训练效率低、数据多样性也难以保证。UI-S1 提出的半在线强化学习核心思想是利用离线轨迹模拟在线强化学习一方面沿用静态轨迹K-turn Rollout保证训练高效可控另一方面引入步骤级优势Step-Level Advantage、补丁模块Patch Module与回合级优势Episode-Level Advantage动态改进策略在不解耦真实环境的情况下逼近在线 RL 的优化效果。三种范式的差异可直观对比下图这种设计使得基于 Qwen2.5-VL-7B-Instruct 微调的UI-S1-7B能在半在线指标SOP与在线指标AndroidWorld上同时取得开源 7B 模型中的领先性能SOTA——即半在线训练的模型其在线部署能力同样出色。项目论文展示了关键佐证离线指标AC-High与在线指标AndroidWorld相关性较弱而半在线指标SOP与在线指标呈强正相关说明半在线范式训练的收益能够有效迁移到真实在线环境中环境搭建与依赖安装UI-S1 的训练基于 verl 框架改造而来推荐使用 conda 创建独立 Python 3.11 环境按以下顺序安装conda create -n ui-s1 python3.11 conda activate ui-s1 cd UI-S1 pip install -e . pip install vllm0.8.2 pip install flash-attn2.7.4.post1 --no-build-isolation # 或从 flash-attention v2.7.4.post1 release 安装预编译 wheel # pip install flash_attn-2.7.4.post1cu12torch2.6cxx11abiFALSE-cp311-cp311-linux_x86_64.whl其中pip install -e .会以可编辑模式安装 UI-S1/setup.py 声明的项目依赖其中内置了针对 GUI 多轮任务的 verl 改造代码verl/目录以及训练所需的数据处理与评估工具链。训练可视化项目使用 swanlab 记录训练指标。训练前需要在 UI-S1/verl/utils/tracking.py 中替换你自己的 swanlab API 密钥与主机名之后在训练命令中通过trainer.logger[console,swanlab]开启日志。数据准备AndroidControl 多轮轨迹训练与评估均基于AndroidControl数据集需要准备两部分内容# 1. 将 AndroidControl 截图下载到 datasets/AndroidControl/images # 2. 将训练集标注文件放到 datasets/android_control_train_example.jsonl仓库在 UI-S1/datasets/android_control_train_example.jsonl 提供了训练样例UI-S1/evaluation/dataset/android_control_evaluation_std.jsonl 提供了评测标准集。每一行的 JSON 结构为字段说明goal任务目标自然语言描述如 Id like to publish my sculpture art from the gallery.is_successful该轨迹是否成功完成steps有序的操作步骤数组episode_id轨迹唯一编号其中每个step包含action_content动作本身如{action:click,coordinate:[540,2273]}、{action:type,text:...}、{action:open,text:...}、{action:wait,time:2}、{action:system_button,button:Back}、{action:swipe,coordinate:[...],coordinate2:[...]}、screenshot当前屏幕截图路径、step_instruction该步指令、以及check_options含candidate_bbox候选标注框供评估阶段匹配动作是否正确。值得说明的是训练阶段使用的TrajDataset定义于 UI-S1/verl/utils/dataset/rl_dataset.py在读取样本时会为每条steps补全check_options与annotation默认GOOD用于对齐动作与候选框、并为轨迹打上语义标注同时其stratified_sample工具函数支持按优势正负分层抽样轨迹片段供训练动态平衡正负样本。训练半在线 RL 的完整实现1. 启动脚本与多机集群环境训练入口为 UI-S1/scripts/train_example.sh脚本开头设置了完整的分布式调试环境变量并支持单机/多机两种运行形态export NCCL_DEBUGINFO # 输出详细 NCCL 日志定位分布式问题 export TORCH_NCCL_ASYNC_ERROR_HANDLING1 # 启用异步错误处理机制 export PYTHONFAULTHANDLER1 # 开启 Python 层错误堆 export HYDRA_FULL_ERROR1 conda activate ui-s1 export PYTHONPATH. export VLLM_USE_V11 cd UI-S1 ENGINE${1:-vllm} # Rollout 引擎默认 vllm脚本通过判断MASTER_ADDR是否已设置来区分主节点与工作节点主节点RANK0会ray start --head启动 Ray 头节点并拉起训练其余节点ray start --address$MASTER_ADDR:6379加入集群并轮询等待训练结束。未显式设置时默认单机运行WORLD_SIZE1, RANK0。训练的超参通过命令行覆盖Hydra 参数传给verl.trainer.main_dapo使用--config-nametraj_grpo配置并显式指定algorithm.adv_estimatoruis1启用半在线优势估计。核心参数含义如下表参数示例值说明data.train_files/datasets/android_control_train_example.jsonl训练轨迹数据data.val_files/datasets/android_control_evaluation_std.jsonl验证数据data.train_batch_sizeWORLD_SIZE * 8训练 batch 随卡数线性扩展data.max_prompt_length12288最长提示长度含历史截图 tokensdata.max_response_length512单步动作输出最大长度data.truncationerror超长样本直接报错而非截断actor_rollout_ref.model.path/checkpoints/Qwen/Qwen2.5-VL-7B-Instruct基座多模态模型actor_rollout_ref.actor.optim.lr1e-6学习率actor_rollout_ref.rollout.n8每个提示采样的轨迹数组规模actor_rollout_ref.rollout.limit_images2每次推理最多保留的历史截图数actor_rollout_ref.rollout.gpu_memory_utilization0.6vLLM 显存占用比例actor_rollout_ref.rollout.max_model_len32678vLLM 最大模型长度actor_rollout_ref.actor.use_kl_lossTruekl_loss_coef0.0001使用 low_var_kl 抑制策略漂移actor_rollout_ref.model.enable_gradient_checkpointingTrue激活梯度检查点节省显存actor_rollout_ref.actor.fsdp_config.param_offload/optimizer_offloadTrueFSDP 参数与优化器 CPU offloadalgorithm.gamma0.5步骤级未来回报折扣因子algorithm.uis1.step_advantage_w1.0步骤级优势权重algorithm.uis1.modemean_std_norm优势归一化方式algorithm.patch_threshold2单条轨迹允许的错误步数阈值algorithm.filter_groups.enableTrueDAPO动态采样过滤开关trainer.total_epochs3训练轮数trainer.save_freq/test_freq5/10检查点保存与验证频率2. 配置文件轨迹数据集与 rollout 参数基础配置 UI-S1/examples/qwen_gui_static_grpo/config/traj_grpo.yaml 继承 verl 的ppo_trainer默认配置并针对 GUI 轨迹任务做了三处关键定制data: max_prompt_length: 8192 max_response_length: 1024 train_batch_size: 2 return_raw_chat: False data.filter_overlong_prompts: True reward_fn_key: data_source custom_cls: path: verl/utils/dataset/rl_dataset.py name: TrajDataset # 使用支持多轮轨迹步骤切分的数据集 actor_rollout_ref: rollout: max_num_batched_tokens: 32768custom_cls指向 UI-S1/verl/utils/dataset/rl_dataset.py 中的TrajDataset——它继承自Qwen25VLNoRolloutDataset将 JSONL 中的多步轨迹按每步一个样本展开并在读取时补充check_options、annotation与candidate_bbox字段从而让模型在每个时间步只看到当前截图与历史上下文limit_images2控制截图张数同目录还提供static_grpo.yaml使用Qwen25VLDataset的静态 GRPO 基线与static_grpo_rlhf.yaml用于对照实验均设置了clip_ratio_low: 0.2 / clip_ratio_high: 0.28 / clip_ratio_c: 10的裁剪范围与algorithm.kl_ctrl.kl_coef: 0KL 系数由训练命令中的kl_loss_typelow_var_kl控制。3. 半在线优势估计的核心实现半在线 RL 区别于静态 GRPO 的核心在于 UI-S1/uis1/core_uis1.py 中实现的步骤级折扣回报与双粒度优势合成并通过 UI-S1/verl/trainer/config/ppo_trainer.yaml 中的algorithm.uis1配置节暴露algorithm: gamma: 1.0 adv_estimator: gae # 训练时被覆盖为 uis1 patch_threshold: 0 uis1: episode_advantage_w: 1.0 step_advantage_w: 1.0 mode: mean_norm # 或 mean_std_norm其原理分三步第一步分段折扣未来回报compute_step_discounted_returns。真实 GUI 轨迹中并非每一步都正确——模型偶尔会输出一个错误动作后纠正。该函数从轨迹末尾向前计算带折扣的未来回报一旦遇到extract_matchFalse该步动作不匹配标注就断开区间、重置 running_return因此单步奖励只从连续的、正确的动作片段中累积避免错误步骤之后的噪声污染前序动作的信用分配for t in reversed(range(len(traj_rewards))): if traj_extract_matches[t]: running_return traj_rewards[t] gamma * running_return traj_returns[t] running_return else: running_return 0.0 traj_returns[t] traj_rewards[t]第二步双粒度优势合成compute_uis1_outcome_advantage。最终优势 episode_advantage_w × episode 级优势 step_advantage_w × step 级优势episode_norm_reward将每条轨迹的 token 级奖励求和作为回合得分在同一 prompt 的 N 条采样轨迹内做组级 mean / mean-std 归一化得到回合级优势鼓励整局成功step_norm_reward将step_rewards第一步算出的分段折扣回报按(prompt_index, step_id)分组做相同的组内归一化得到步骤级优势鼓励每一步都走在正确的道路上。mode参数决定归一化方式mean_std_norm使用(score - mean) / (std eps)mean_norm仅减均值remove_stdTrue数值更稳定。两者分别对应组内方差敏感型与稳健型策略。第三步接入训练循环。在 UI-S1/verl/trainer/ppo/dapo_ray_trainer.py 中MultiRoundGenerator以patch_threshold为容错阈值把轨迹逐步喂给 vLLM 生成动作rollout.n8条路径并行采样当adv_estimator AdvantageEstimator.UIS1枚举定义见 UI-S1/verl/trainer/ppo/core_algos.py时调用compute_step_discounted_returns计算step_rewards随后计算回合级与步骤级优势并叠加完成一轮策略更新。4. DAPO 动态采样过滤训练默认开启 DAPOalgorithm.filter_groups.enableTrue用于剔除组内奖励方差过低的无效采样组稳定训练。关键配置为algorithm.filter_groups.metricseq_future_reward以步骤 0 的分段折扣未来回报作为组内指标对应代码中step_id0时收集seq_future_rewardalgorithm.filter_groups.std_threshold0.3仅保留组内指标标准差大于阈值或组内只有一条轨迹的 prompt 组否则跳过该组When prompts after filtering is less than train batch size, we skip to the next generation batch。5. 训练检查点合并verl 训练产出的是 FSDP或 Megatron分片检查点需通过 UI-S1/scripts/model_merger.py 合并为可直接部署的 HuggingFace 格式模型bash scripts/train_example.sh python scripts/model_merger.py merge --local_dir checkpoints/XXXmodel_merger.py支持--backend fsdp|megatron两种后端FSDP 路径会从model_world_size_{N}_rank_{i}.pt分片文件名推断 world size读取 DTensor 的分片布局device_mesh、mesh_dim_names并按 replicate/shard 语义合并随后重建 Qwen2.5-VL 的 Vision2Seq 架构连同 tokenizer/processor 一起save_pretrained到目标目录。合并结果可通过test子命令与参考 HF 模型逐参数比对验证。推理与 SOP 评估1. 启动 vLLM 推理服务训练合并完成后先用 vLLM 以 OpenAI 兼容协议启动服务注意 GUI 任务需要限制每轮 prompt 内的图片数量vllm serve /checkpoints-7B --served-model-name UI-S1-7B \ --tensor_parallel_size 1 --trust-remote-code --limit-mm-per-prompt image2--served-model-name指定模型对外名称供评估脚本以model_name引用--limit-mm-per-prompt image2与训练时的rollout.limit_images2保持一致即每轮最多携带 2 张历史截图兼顾上下文信息量与显存开销。2. SOP 半在线评测SOPSemi-online metric评测以 UI-S1/evaluation/eval_qwenvl.py 为代表实现通过--model_name指向 vLLM 服务python /evaluation/eval_qwenvl.py --model_name UI-S1-7B评估流程对应 UI-S1/evaluation/eval_qwenvl.py 的process_line为逐条读取标准评测集android_control_evaluation_std.jsonl使用JsonFormat来自 UI-S1/x/data/agent/json.py将 goal 与历史截图组装成多轮 messages并通过slim_messages(..., num_image_limit2)限制历史图片数调用 vLLM 服务得到模型预测动作pred_action经parse_response解析为结构化动作通过evaluate_android_control_action与当前步的check_optionscandidate_bbox等比对type_match与extract_match——动作类型不匹配或坐标未命中候选框即中断该轨迹全部步骤命中则task_successTrue。main中使用ThreadPoolExecutor(max_workers4)并行请求结果逐条写入model_name.jsonl最终输出两项核心指标Success Rate成功率成功轨迹数 / 总轨迹数 × 100%Average Progress平均进度所有轨迹最终完成步数 / 总步数的均值——即使未完全成功也能度量模型走对了几步。命令行参数包括--jsonl_file默认指向评测集、--output_dir、--n_history_image_limit默认 2与--max_workers默认 4。3. 评估其他对比模型为便于横向对比仓库提供了多个评测脚本均以相同的 SOP 协议驱动不同基座python /evaluation/eval_qwenvl.py --model_name Qwen2.5-VL-7B python /evaluation/eval_agentcpm.py --model_name AgentCPM-GUI-8B python /evaluation/eval_os-atlas-7b.py --model_name OS-Atlas-7B python /evaluation/eval_os-genesis-7b.py --model_name OS-Genesis-7B python /evaluation/eval_ui-tars-7b.py --model_name UI-TARS-7B各脚本通过不同的工具函数封装如qwenvl_utils.py、ui_tars_utils.py、os_atlas_utils.py等均位于 UI-S1/evaluation/ 目录适配各自模型的动作空间但评测口径逐步骤匹配check_options、统计成功率与进度保持一致确保对比公平。4. 详细结果UI-S1/assets/result.png 给出了与闭源模型如 GPT-4o、开源 7B/8B 模型Qwen2.5-VL-7B、AgentCPM-GUI-8B 等以及更大规模开源模型在SOP、AITW-Gen、AITW-Web、MiniWob、AndroidWorldAW多任务上的完整对比UI-S1-7B 在 SOP 与 AndroidWorld 上均为开源 7B 模型中的最优且相比 Base 模型Qwen2.5-VL-7B-Instruct提升显著验证了半在线 RL 在离线训练、在线部署场景下的有效性。复现建议与注意事项显存与算力训练默认按 8 卡 GPU 布局trainer.n_gpus_per_node8并启用 FSDP 参数/优化器 offload 与梯度检查点若 vLLM 版本低于 0.6.3 遇到注意力后端问题可按脚本注释设置export VLLM_ATTENTION_BACKENDXFORMERS路径替换脚本中的模型权重路径/checkpoints/Qwen/Qwen2.5-VL-7B-Instruct、数据路径/datasets/...均为示例绝对路径需按实际位置修改数据准备完成后训练与评估两侧的数据集路径要严格一致评测口径SOP 依赖check_options.candidate_bbox做动作匹配因此fix_line会为缺失candidate_bbox的样本补空列表避免解析异常半在线超参gamma默认 0.5、patch_threshold默认 2、step_advantage_w与episode_advantage_w默认 1.0共同决定步骤级信用分配的强度是影响多轮能力的核心调节旋钮。引用若你的研究工作使用了 UI-S1欢迎引用其论文article{lu2025ui, title{UI-S1: Advancing GUI Automation via Semi-online Reinforcement Learning}, author{Lu, Zhengxi and Ye, Jiabo and Tang, Fei and Shen, Yongliang and Xu, Haiyang and Zheng, Ziwei and Lu, Weiming and Yan, Ming and Huang, Fei and Xiao, Jun and others}, journal{arXiv preprint arXiv:2509.11543}, year{2025} }该项目实现上真诚致谢 verl 目录即为在 verl 基础上针对 GUI 半在线 RL 的深度改造阅读 UI-S1/verl/trainer/ppo/dapo_ray_trainer.py 与 UI-S1/uis1/core_uis1.py 可进一步追踪 uis1 优势估计的完整计算链路。【免费下载链接】MobileAgentMobile-Agent: The Powerful GUI Agent Family项目地址: https://gitcode.com/GitHub_Trending/mo/MobileAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考