Hugging Face 发布 Smol2Operator：将 SmolVLM2-2.2B 训练为 GUI Agent 的完整配方

TL;DR： 这项工作展示了轻量级视觉语言模型如何获得基于 GUI 的技能，并演变为具备代理能力的 GUI 编码器。我们发布了所有训练配方、数据处理工具、所得模型、演示和数据集，以实现完全可复现性并促进进一步研究 🫡。在此处查找合集 here。

目录

• 引言
• 1. Data Transformation and Unified Action Space
  • 动作空间不一致的挑战
  • 我们的统一方法
  • 数据转换示例
  • 使用动作空间转换器适配自定义动作空间
  • 关键特性
  • 使用示例
  • 转换并发布的数据集
• 2. Phase 1: From Zero to Perception
  • 训练数据
  • 优化实验
  • 图像分辨率与坐标系分析
  • 关键发现
  • 第一阶段结果
• 3. Phase 2: From Perception to Cognition
  • 训练数据
  • 第二阶段结果
• 4. 你只需要开源
• 5. 结论
• 下一步是什么？

引言

图形用户界面（GUI）自动化是计算机视觉中最具挑战性的前沿领域之一。开发能够看到并与用户界面交互的模型，使 AI 代理能够导航移动端、桌面端和网页平台。这将重塑数字交互的未来。

在这篇博客文章中，我们提出了一种通过多阶段训练策略为 GUI 自动化训练视觉语言模型的综合方法。我们展示了如何将一个零定位能力的模型转变为能够理解并与图形界面交互的代理编码器。

我们的目标不是追求 SOTA 模型，而是展示从数据处理到模型训练的整个过程，并借此展示如何解锁 VLM 中的 GUI 定位能力。

GUI 能力结合了对界面的理解和精确的元素定位。这些能力使模型能够将高层任务转化为低层 GUI 操作，如点击、输入……

我们的方法利用 SmolVLM2-2.2B-Instruct 作为基线模型，这是一个小型但强大的视觉语言模型，最初不具备 GUI 任务的定位能力。这使其成为展示我们训练方法有效性的理想候选。通过我们的两阶段训练过程，我们首先向模型灌输定位能力，然后使用监督微调（SFT）增强其代理推理能力。

我们在一个成熟的感知基准上评估我们的方法：ScreenSpot-v2，它测试模型理解和定位屏幕截图中元素的能力。我们的过程受到 AGUVIS 论文的启发，并利用他们精心整理的数据集，在其基础工作上构建。

基础模型 SmolVLM2-2.2B-Instruct 训练阶段 ScreenSpot-v2 性能的演变。

1. 数据转换与统一动作空间

本节说明我们如何将来自多个数据集的异构 GUI 动作格式转换为单一统一格式。通过标准化函数名、签名和参数，我们创建了一致、高质量的数据，为有效的模型训练奠定基础。

动作空间不一致的挑战

在处理多个 GUI 自动化数据集时，主要挑战之一是动作表示缺乏标准化。不同数据集使用不同的函数签名、参数命名约定和动作分类法，使得难以跨多样化的数据源训练统一模型。

我们的统一方法

我们采用了最初由 AGUVIS 使用的开源数据集（xlangai/aguvis-stage1、xlangai/aguvis-stage2），并实现了一个全面的数据转换流水线，以创建统一的动作空间。我们的方法包括：

1. 函数解析与规范化：我们开发了一个函数解析器（见 utils/function_parser.py），可以从所有数据集中的各种格式中提取并解析函数调用。该解析器支持任何函数签名格式，处理复杂的参数结构，并能够以正确的参数顺序重建函数调用。
2. Action Space Unification: We implemented a comprehensive action conversion system (see preprocessing/action_conversion.py) that transforms all original action representations into a standardized function naming and argument structure. This process highlighted the significant inconsistencies in function signatures across different datasets and allowed us to:
   • 移除不需要或冗余的动作
   • 标准化参数命名约定
   • 创建一致的动作词汇表
3. (Bonus) Flexible Adaptation Framework: Our transformation pipeline includes utilities that allow users to:
   • 使用 utils/action_space_converter.py 工具将整个数据集适配到其自身的动作空间命名约定
   • 提取并分析当前的动作空间结构

数据转换示例

以下是我们动作转换系统（preprocessing/action_conversion.py）中的真实示例，展示了我们如何将异构动作表示转换为统一格式（grounding 坐标归一化到 [0,1]）：

转换前（原始动作数据集格式）：

# Mobile Actions
mobile.home()
mobile.open_app(app_name='drupe')
mobile.swipe(from_coord=[0.581, 0.898], to_coord=[0.601, 0.518])
mobile.long_press(x=0.799, y=0.911)
mobile.terminate(status='success')
# Desktop Actions
pyautogui.click(x=0.8102, y=0.9463)
pyautogui.doubleClick(x=0.8102, y=0.9463)
pyautogui.hotkey(keys=['ctrl', 'c'])
pyautogui.scroll(page=-0.1)
pyautogui.write(message='bread buns')
pyautogui.dragTo(from_coord=[0.87, 0.423], to_coord=[0.8102, 0.9463])

转换后（统一动作数据集格式）：

# Unified Mobile Actions
navigate_home()
open_app(app_name='drupe')
swipe(from_coord=[0.581, 0.898], to_coord=[0.601, 0.518])
long_press(x=0.799, y=0.911)
final_answer('success')
# Unified Desktop Actions
click(x=0.8102, y=0.9463)
double_click(x=0.8102, y=0.9463)
press(keys=['ctrl', 'c'])
scroll(direction='up', amount=10)  # Smart direction detection
type(text='bread buns')
drag(from_coord=[0.87, 0.423], to_coord=[0.8102, 0.9463])

这一统一过程对于创建连贯的训练数据至关重要，使模型能够在多样化的 GUI 环境中学习一致的动作模式。

💡 为什么要使用归一化坐标？
在文本-动作数据点中使用原始像素坐标（例如 click(x=302, y=63)）会将其绑定到单一图像尺寸。视觉语言模型（VLM）通常会调整图像大小，导致像素坐标失效并需要调整。归一化坐标（相对于图像尺寸）在任何分辨率下都保持有效，并保持数据集的一致性。

（附加）使用 Action Space Converter 进行自定义动作空间适配

为了最大限度地提高不同用例的灵活性，我们开发了 Action Space Converter（utils/action_space_converter.py），这是一个允许用户轻松地从某个动作空间适配到自己的自定义动作词汇表和命名约定的工具。

你可以使用此工具将一个动作签名（函数名、参数名以及参数值变化等）转换为另一个：

转换前

assistant_message: "Action: click(x=0.5, y=0.3)"

转换后

assistant_message: "Action: touch(x_coord=200, y_coord=300)"

主要特性

Action Space Converter 提供：

1. 可配置映射：在统一动作和你偏好的动作名称之间定义自定义映射
2. 参数转换：重命名参数、应用值转换并设置默认值
3. 灵活架构：同时支持简单的参数映射和复杂的自定义转换函数
4. 验证：内置验证以确保映射配置有效

使用示例

from utils.action_space_converter import ActionSpaceConverter, ActionMapping, ParameterMapping
from utils.function_parser import parse_function_call

# Create custom mappings
mappings = [
    ActionMapping(
        source_function="click",
        target_function="touch",
        parameter_mappings=[
            ParameterMapping(source_name="x", target_name="x_coord"),
            ParameterMapping(source_name="y", target_name="y_coord")
        ],
        description="Touch screen at coordinates"    ),
    ActionMapping(
        source_function="type", # source_function is the name of the function in the original function call
        target_function="write", # target_function is the name of the function in the target function call        
        parameter_mappings=[
            ParameterMapping(source_name="text", target_name="content")
            # source_name is the name of the parameter in the original function call            
            # target_name is the name of the parameter in the target function call        
        ],
        description="Input text"    
    )
]

assistant_message = "I'll interact at those coordinates for you. click(x=0.5, y=0.3) Now I'll input the text. type(text='hello world')"

# Parse function calls
parsed_function_calls = parse_function_call(text)

# Initialize converter
converter = ActionSpaceConverter(mappings)

# Convert actions
converted_actions = converter.convert_actions(parsed_function_calls)
for new_function_call, old_function_call in zip(converted_actions, parsed_function_calls):
    text = text.replace(old_function_call.to_string(), new_function_call.to_string())

print(text)
# Output: I'll interact at those coordinates for you. touch(x_coord=0.5, y_coord=0.3) Now I'll input the text. write(content='hello world')

该工具使研究人员和从业者能够：

• 自定义训练数据：调整数据集以匹配其特定的动作词汇需求
• 领域适应：为不同平台（移动端 vs. 桌面端 vs. 网页端）转换动作
• 框架集成：轻松将训练数据与现有自动化框架对齐
• 快速实验：快速测试不同的动作空间配置
• 发布准备：通过一致的命名约定标准化动作空间，以便生产部署

动作空间转换器对于准备训练数据集特别有价值，因为它确保了不同部署环境中的动作词汇一致，同时保持与现有自动化框架的兼容性。

转换和发布的数据集

通过这个流程，我们将开源数据集 xlangai/aguvis-stage1、xlangai/aguvis-stage2 转换为我们的统一动作空间（参见此处）。此过程的输出作为两个新的完全格式化的数据集发布：smolagents/aguvis-stage-1 和 smolagents/aguvis-stage-2。

2. 第一阶段：从零到感知

训练数据

第一阶段利用 smolagents/aguvis-stage-1 数据集，通过将低级指令与多样化的可执行动作（以代码形式表达）配对，引入GUI 基础。例如，smolagents/aguvis-stage-1 中的用户/助手轮次遵循以下结构：

{
  "user": "click on more button",
  "assistant": "click(x=0.8875, y=0.2281)",
}

每个样本将截图与多轮用户/助手交互链接起来，使模型能够在对话轮次中学习细粒度的动作基础。在微调期间，数据整理器在计算损失时屏蔽除助手答案之外的所有内容。

优化实验

在进行全面第一阶段训练之前，我们进行了全面的消融研究，以确定最佳训练配置

图像分辨率和坐标系分析

我们尝试了不同的图像尺寸和坐标表示系统，以确定 SmolVLM2 的最佳配置：

• 测试的图像尺寸：384px、768px、1152px
• 坐标系：像素坐标 vs. 归一化坐标（0-1 范围）
• 训练数据：来自 Aguvis 数据集的 400K 样本

一些 SOTA GUI VLMs（例如 Qwen-VL）似乎也使用不同的归一化范围（0–1000），本实验未测试。

表 1： 基于 HuggingFaceTB/SmolVLM2-2.2B-Instruct 的基线（400k 样本，aguvis-stage-1）。越高越好。

正如我们的基准测试结果所示，SmolVLM2-2.2B-Instruct 基础模型最初在 ScreenSpot-v2 等感知基准上实现了 0% 的性能。这种完全缺乏基础能力的情况为我们评估训练方法的有效性提供了一个干净的起点。

关键发现

从我们的实验中，我们确定：

• 图像尺寸：1152px
• 坐标系：归一化坐标（0-1 范围）被证明对 SmolVLM2 最有效
• 注意：像素坐标与归一化坐标之间的最优选择可能因基础模型的预训练方式而异

第一阶段结果

使用最优配置（1152px 分辨率配合归一化坐标），我们在 smolagents/aguvis-stage-1 数据集上训练了 2 个 epoch。结果非常显著，在 ScreenSpot-v2 上相比基线提升了 +41%

这一显著提升表明，我们的第一阶段训练成功地为模型注入了基础的定位能力，使其能够理解并定位截图中的视觉元素。

表 2：基于 HuggingFaceTB/SmolVLM2-2.2B-Instruct 的基线（2 个 epoch，aguvis-stage-1）。

3. 第二阶段：从感知到认知

第一阶段提供了定位能力，而第二阶段则针对智能体推理，即在行动前进行思考和规划的能力。这一阶段将模型从识别 GUI 元素的被动系统转变为能够执行复杂、多步交互的主动智能体。

训练数据

第二阶段使用 smolagents/aguvis-stage-2 数据集，该数据集引入了智能体场景：

• 对即将执行的动作进行显式推理

• 跨多个交互步骤的上下文一致性

• 高层指令需要多步、低层动作。

例如，smolagents/aguvis-stage-2 的聊天消息如下所示：

{
  "system": "You are a helpful GUI agent. ...",
  "user": "Please generate the next move according to the UI screenshot, instruction and previous actions.\n\nInstruction: What information does the site provide about Judith Lauand's career, works and exhibitions?\n\nPrevious actions:\nNone",
  "assistant": "<think>\nClick on the link labeled 'Judith Lauand: Brazilian 1922-2022' to explore more about her career and exhibitions.\n</think>\n<code>\nclick(x=0.41, y=0.178)\n</code>",
}

每个样本将一张截图与一个 system/user/assistant 轮次关联起来。在微调期间，数据整理器在计算损失时会屏蔽除 assistant 回答之外的所有内容。

第二阶段结果

从第一阶段的检查点（1152 px 分辨率，归一化坐标）出发，我们在 smolagents/aguvis-stage-2 上对模型进行了两个 epoch 的微调。ScreenSpot-v2 上的准确率从 41% 提升至 61%，表明显式推理改善了 GUI 定位性能。

表 2：基于 HuggingFaceTB/SmolVLM2-2.2B-Instruct 在第一阶段微调后的基线（2 个 epoch，aguvis-stage-1）。

💡 我们还在一个小得多的 VLM（nanoVLM-460M）上复现了两阶段训练。尽管其容量有所降低，该模型仍在 ScreenSpot-v2 上达到了约 58%，表明该训练策略能够有效向下扩展，使其在该模型规模（460M 参数）下成为 ScreenSpot-v2 上的 SOTA。此外，aguvis-stage-1 已包含在 FineVision Dataset 中！

4. 你需要的只是开源

所有训练代码、数据处理流水线、数据集和模型均已开源！

1. 训练配方（recipe.ipynb）：涵盖第一阶段和第二阶段完整训练流水线，包括数据集混合配置和训练编排。我们利用 TRL 库来训练我们的模型。
2. 数据集（smolagents/aguvis-stage-1、smolagents/aguvis-stage-2）：所使用的所有数据集均为开源。
3. 模型（smolagents/SmolVLM2-2.2B-Instruct-Agentic-GUI）：通过应用上述训练配方所产出的模型。
4. Preprocessing Tools:
   • Function Parser（utils/function_parser.py）：用于从多种数据集格式中解析、规范化和重建函数调用的实用工具。支持复杂参数结构、位置参数以及多种函数调用提取。
   • Action Conversion System（preprocessing/action_conversion.py）：核心统一引擎，将移动端和 PyAutoGUI 桌面操作转换为标准化 API 格式。具备智能坐标处理、滚动操作的方向检测以及全面的参数规范化功能。
   • Action Space Converter（utils/action_space_converter.py）：灵活的工具，用于将统一动作空间适配到自定义词表和命名约定。通过可配置的参数映射实现特定领域的定制。

💡 我们还发布了一个 Space，用于体验该模型的智能体 grounding 能力：A-Mahla/Smol2Operator

5. 结论

我们的实验表明，高质量、面向推理的数据可以显著提升 GUI grounding，即使对于小型 VLM，也仅需使用监督微调（SFT）。除了原始性能提升之外，这些结果还表明，GUI grounding 能力在很大程度上取决于数据质量。精心整理的数据集教会模型用户界面的结构和语义，为准确的动作预测提供了所需的 grounding。

为支持 GUI 智能体的发展，我们开源了一切：完整的流水线、数据集和训练好的模型。你可以复现我们的结果，尝试不同的模型和架构，或将我们的方法适配到新的领域。智能体 AI 的未来取决于像你这样的研究者不断突破边界！

下一步是什么？

虽然 SFT 在监督任务中表现出色，但强化学习（RL）或直接偏好优化（DPO）等新兴方法有助于培养更强的推理能力，并实现实时适应。这些进展指向新一代 GUI 智能体，它们通过交互来学习和改进，而不是仅仅依赖静态数据集。

让我们一起构建 GUI 智能体的未来 🤗