ScreenAgent ：由视觉语言大模型驱动的计算机控制代理

查看 ScreenAgent 论文 arxiv:2402.07945

中文版 Readme

新闻

• (2024-4-17) ScreenAgent 论文已被 IJCAI 2024 接收并将在会议上展示！
• (2024-5-19) ScreenAgent Web 客户端 发布，提供了一种更简便的方式，让用户通过大模型体验桌面控制。

我们构建了 ScreenAgent 项目，为视觉语言模型代理（VLM Agent）创建了一个与真实计算机屏幕交互的环境。在这个环境中，代理可以通过观察屏幕截图，并输出鼠标和键盘操作来操控图形用户界面。我们还设计了一套自动控制流程，包括规划、执行和反思三个阶段，引导代理持续与环境互动，完成多步骤任务。此外，我们还构建了 ScreenAgent 数据集，收集了完成各种日常计算机任务时的屏幕截图及操作序列。

为了引导 VLM 代理持续与计算机屏幕交互，我们构建了一个包含“规划-执行-反思”的流程。在规划阶段，代理需要将用户任务分解为子任务。在执行阶段，代理会观察屏幕截图，并给出具体的鼠标和键盘操作来执行这些子任务。控制器会执行这些操作，并将执行结果反馈给代理。在反思阶段，代理会观察执行结果，判断当前状态，并决定是继续执行、重试，还是调整计划。这一过程将持续进行，直到任务完成。

我们参考了 VNC 远程桌面连接协议来设计代理的动作空间，这些动作都是最基本的鼠标和键盘操作。大多数鼠标点击操作都需要代理给出精确的屏幕坐标位置。与调用特定 API 来完成任务相比，这种方法更具通用性，可以应用于各种桌面操作系统和应用程序。

教会代理使用计算机并非易事。这要求代理具备任务规划、图像理解、视觉定位和工具使用等多种综合能力。为此，我们手动标注了 ScreenAgent 数据集。该数据集涵盖了多种日常计算机任务，包括文件操作、网页浏览、游戏娱乐等场景。我们按照上述“规划-执行-反思”流程构建了一个个会话。

该项目主要包括以下几个部分：

ScreenAgent
├── client # 控制器客户端代码
│   ├── prompt # 提示模板
│   ├── config.yml # 控制器客户端配置文件模板
│   └── tasks.txt # 任务列表
├── data # 包含 ScreenAgent 数据集及其他视觉定位相关数据集
├── model_workers # VLM 推理服务
└── train # 模型训练代码

准备工作

第一步，准备待控制的桌面

首先，您需要准备一台安装了 VNC 服务器的待控制桌面操作系统，例如 TightVNC。或者您也可以使用带有 GUI 的 Docker 容器。我们已经准备了一个名为 niuniushan/screenagent-env 的容器。您可以使用以下命令拉取并启动该容器：

docker run -d --name ScreenAgent -e RESOLUTION=1024x768 -p 5900:5900 -p 8001:8001 -e VNC_PASSWORD=<VNC_PASSWORD> -e CLIPBOARD_SERVER_SECRET_TOKEN=<CLIPBOARD_SERVER_SECRET_TOKEN> -v /dev/shm:/dev/shm niuniushan/screenagent-env:latest

请将 <VNC_PASSWORD> 替换为您新的 VNC 密码，将 <CLIPBOARD_SERVER_SECRET_TOKEN> 替换为您剪贴板服务的密码。由于输入较长文本或 Unicode 字符依赖于剪贴板，如果未启用剪贴板服务，则只能通过依次按键输入 ASCII 字符串，而无法输入中文及其他 Unicode 字符。本镜像已内置剪贴板服务，默认监听 8001 端口。您需要设置密码以保护您的剪贴板服务。niuniushan/screenagent-env 是基于 fcwu/docker-ubuntu-vnc-desktop 构建的。有关该镜像的更多信息，请参阅 这里。

如果您希望使用现有的桌面环境，如 Windows、Linux 桌面或其他任何桌面环境，您需要运行任意 VNC 服务器，并记下其 IP 地址和端口号。若要启用剪贴板服务，请在您的桌面环境中执行以下步骤：

# 安装依赖
pip install fastapi pydantic uvicorn pyperclip 
# 设置环境变量中的密码
export CLIPBOARD_SERVER_SECRET_TOKEN=<CLIPBOARD_SERVER_SECRET_TOKEN>
# 启动剪贴板服务
python client/clipboard_server.py

clipboard_server.py 将监听 8001 端口，接收来自控制器的长字符串键盘输入指令（文本形式）。

服务启动后，您可以测试剪贴板是否正常工作，例如：

curl --location 'http://localhost:8001/clipboard' \
--header 'Content-Type: application/json' \
--data '{
    "text":"Hello world",
    "token":"<CLIPBOARD_SERVER_SECRET_TOKEN>"
}'

如果一切正常，您将收到响应 {"success": True, "message": "Text copied to clipboard"}。如果遇到错误“Pyperclip could not find a copy/paste mechanism for your system.”，请在运行 python client/clipboard_server.py 前添加一个指定 X 服务器位置的环境变量：

export DISPLAY=:0.0

请根据您的系统环境进行相应调整。如果仍然遇到问题，请参考 这里。

请将上述信息填写到客户端配置文件 client/config.yml 中的 remote_vnc_server 项中。

第2步，准备控制器代码的运行环境

您需要运行控制器代码，它具有三项任务：首先，控制器将连接到VNC服务器，采集屏幕截图，并发送鼠标和键盘等命令；其次，控制器内部维护一个状态机，实现规划、行动和反思的自动化控制流程，引导智能体与环境持续交互；最后，控制器会根据提示词模板构建完整的提示信息，将其发送至大模型推理API，并解析大模型生成回复中的控制命令。控制器是一个基于PyQt5的程序，您需要安装一些依赖项：

pip install -r client/requirements.txt

第3步，准备大模型推理器或API

请为智能体选择一个视觉语言模型（VLM）。我们在model_workers中提供了4种模型的推理器，分别是：GPT-4V、LLaVA-1.5、CogAgent和ScreenAgent。您也可以自行实现推理器，或使用第三方API。您可以参考client/interface_api中的代码来实现新的API调用接口。

请参照client/config.yml中的llm_api部分准备配置文件，仅保留llm_api下的一个模型。

llm_api:

  # 从以下模型中选择一个使用：

  GPT4V:
    model_name: "gpt-4-vision-preview"
    openai_api_key: "<YOUR-OPENAI-API-KEY>"
    target_url: "https://api.openai.com/v1/chat/completions"

  LLaVA:
    model_name: "LLaVA-1.5"
    target_url: "http://localhost:40000/worker_generate"

  CogAgent:
    target_url: "http://localhost:40000/worker_generate"

  ScreenAgent:
    target_url: "http://localhost:40000/worker_generate"

  # 所有模型的通用设置
  temperature: 1.0
  top_p: 0.9
  max_tokens: 500
  

如果您使用GPT-4V作为智能体

请在client/config.yml中将llm_api设置为GPT4V，并填写您的OpenAI API Key，请务必注意您的账户余额。

如果您使用LLaVA-1.5作为智能体

请参考LLaVA项目下载并准备LLaVA-1.5模型，例如：

git clone https://github.com/haotian-liu/LLaVA.git
cd LLaVA
conda create -n llava python=3.10 -y
conda activate llava
pip install --upgrade pip  # 启用PEP 660支持
pip install -e .

model_workers/llava_model_worker.py提供了一个用于LLaVA-1.5的非流式输出推理器。您可以将其复制到llava/serve/model_worker目录下，并使用以下命令启动：

cd llava
python -m llava.serve.llava_model_worker --host 0.0.0.0 --port 40000 --worker http://localhost:40000 --model-path liuhaotian/llava-v1.5-13b --no-register

如果您使用CogAgent作为智能体

请参考CogVLM项目下载并准备CogAgent模型。从这里下载CogAgent权重的压缩版cogagent-chat.zip，解压后放置在train/saved_models/cogagent-chat目录下。 train/cogagent_model_worker.py提供了一个用于CogAgent的非流式输出推理器。您可以使用以下命令启动它：

cd train
RANK=0 WORLD_SIZE=1 LOCAL_RANK=0 python ./cogagent_model_worker.py --host 0.0.0.0  --port 40000 --from_pretrained "saved_models/cogagent-chat" --bf16 --max_length 2048

如果您使用ScreenAgent作为智能体

ScreenAgent是在CogAgent基础上训练的。从这里下载ScreenAgent-2312.zip格式的权重文件，解压后放置在train/saved_models/ScreenAgent-2312目录下。您可以使用以下命令启动它：

cd train
RANK=0 WORLD_SIZE=1 LOCAL_RANK=0 python ./cogagent_model_worker.py --host 0.0.0.0  --port 40000 --from_pretrained "./saved_models/ScreenAgent-2312" --bf16 --max_length 2048

运行

准备工作完成后，您可以运行控制器：

cd client
python run_controller.py -c config.yml

控制器界面如下所示。您需要先双击左侧选择一个任务，然后按下“开始自动化”按钮。控制器将按照规划-行动-反思的流程自动运行。它会采集当前屏幕图像，填充提示词模板，将图像和完整提示词发送到大模型推理器，解析大模型的回复，向VNC服务器发送鼠标和键盘控制命令，并重复这一过程。

如果屏幕卡住，可以尝试点击“重新连接”按钮。控制器将尝试重新连接到VNC服务器。

数据集

所有数据集及数据处理代码均位于data目录下。我们使用了三个现有的数据集：COCO2014、Rico & widget-caption以及Mind2Web。

COCO数据集

我们使用COCO 2014验证集图片作为视觉定位能力的训练数据。您可以从这里下载COCO 2014训练集图片。我们在此使用的标注信息是refcoco，由unc划分。

├── COCO
   ├── prompts # 用于训练智能体视觉定位能力的提示词模板
   ├── train2014 # COCO 2014训练集
   └── annotations # COCO 2014标注

Rico & widget-caption数据集

Rico数据集包含大量Android应用的屏幕截图和控件信息。您可以从这里下载Rico数据集的“1. UI Screenshots and View Hierarchies (6 GB)”部分，文件名为unique_uis.tar.gz。请将解压后的combined文件夹放入data/Rico目录下。 widget-caption是基于Rico的控件信息标注。请将https://github.com/google-research-datasets/widget-caption项目克隆到data/Rico目录下。 最终的目录结构如下：

├── Rico
   ├── prompts # 用于训练智能体视觉定位能力的提示词模板
   ├── combined # Rico数据集的屏幕截图
   └── widget-caption
       ├── split
       │   ├── dev.txt
       │   ├── test.txt
       │   └── train.txt
       └── widget_captions.csv

Mind2Web 数据集

Mind2Web 是一个真实的模拟网页浏览数据集。您需要下载原始数据集并进行处理。首先，使用 Globus 工具从这里下载原始网页截图。文件夹名为 raw_dump，放置在 data/Mind2Web/raw_dump 目录下，然后使用以下命令处理数据集：

cd data/Mind2Web
python convert_dataset.py

这段代码会从 Hugging Face 数据集中下载 osunlp/Mind2Web 数据集的处理后版本。请确保网络畅通。同时，这一步骤将涉及将英文指令翻译成中文指令。

cd data/Mind2Web
python convert_dataset.py

这段代码会从 Hugging Face 数据集中下载 osunlp/Mind2Web 数据集的处理后版本。请确保网络畅通。这一步骤将涉及将英文指令翻译成中文指令。您需要在 data/Mind2Web/translate.py 中调用您自己的翻译 API。 目录结构如下：

├── Mind2Web
   ├── convert_dataset.py
   ├── translate.py
   ├── prompts # 用于训练 Agent 网页浏览能力的提示词模板
   ├── raw_dump # 从 Globus 下载的 Mind2Web 原始数据
   └── processed_dataset # 由 convert_dataset.py 创建

ScreenAgent 数据集

ScreenAgent 是本文中标注的数据集，分为训练集和测试集，目录结构如下：

├── data
    ├── ScreenAgent
        ├── train
        │   ├── <session id>
        │   │   ├── images
        │   │   │   ├── <timestamp-1>.jpg
        │   │   │   └── ...
        │   │   ├── <timestamp-1>.json
        │   │   └── ...
        │   ├── ...
        └── test

JSON 文件中各字段的含义：

• session_id：会话 ID
• task_prompt：任务总体目标
• task_prompt_en：任务总体目标（英文）
• task_prompt_zh：任务总体目标（中文）
• send_prompt：发送给模型的完整提示
• send_prompt_en：发送给模型的完整提示（英文）
• send_prompt_zh：发送给模型的完整提示（中文）
• LLM_response：模型给出的原始回复文本，即 RLHF 中的拒绝响应
• LLM_response_editer：人工修正后的回复文本，即 RLHF 中的选择响应
• LLM_response_editer_en：人工修正后的回复文本（英文）
• LLM_response_editer_zh：人工修正后的回复文本（中文）
• video_height, video_width：图像的高度和宽度
• saved_image_name：截图文件名，位于每个会话的 images 文件夹下
• actions：从 LLM_response_editer 中解析出的动作序列

训练 ScreenAgent

如果您想训练自己的模型，或复现 ScreenAgent 模型，请先准备好上述数据集，并检查 train/dataset/mixture_dataset.py 文件中的所有数据集路径。如果您只想使用部分数据集或添加新的数据集，请修改 train/dataset/mixture_dataset.py 中的 make_supervised_data_module 函数。请从这里下载 CogAgent 权重的单机版 cogagent-chat.zip，解压后放置在 train/saved_models/ 目录下。

您需要关注并检查以下文件：

train
├── data -> ../data
├── dataset
│   └── mixture_dataset.py
├── finetune_ScreenAgent.sh
└── saved_models
    └── cogagent-chat # 解压 cogagent-chat.zip
        ├── 1
        │   └── mp_rank_00_model_states.pt
        ├── latest
        └── model_config.json

请根据您的设备情况修改 train/finetune_ScreenAgent.sh 中的参数，然后运行：

cd train
bash finetune_ScreenAgent.sh

最后，如果您想将单机分布式训练的权重合并为一个单独的权重文件，请参考 train/merge_model.sh 代码。请确保该文件中的模型并行度 MP_SIZE 与 train/finetune_ScreenAgent.sh 中的 WORLD_SIZE 一致。将 --from-pretrained 后的参数修改为训练过程中保存的检查点位置。合并后的权重文件将保存为 train/saved_models/merged_model 文件夹。

待办事项

• 提供 Hugging Face Transformers 权重。
• 简化控制器设计，提供无渲染模式。
• 集成 Gym。
• 添加技能库，以支持更复杂的函数调用。

相关项目

• Mobile-Agent：具有视觉感知能力的自主多模态移动设备代理 http://arxiv.org/abs/2401.16158
• UFO：面向Windows操作系统交互的UI导向型代理 http://arxiv.org/abs/2402.07939
• ScreenAI：用于理解UI和信息图表的视觉语言模型 http://arxiv.org/abs/2402.04615
• AppAgent：作为智能手机用户的多模态代理 http://arxiv.org/abs/2312.13771
• CogAgent：用于GUI代理的视觉语言模型 http://arxiv.org/abs/2312.08914
• Screen2Words：基于多模态学习的自动移动UI摘要 http://arxiv.org/abs/2108.03353
• 具有规划、长上下文理解和程序合成能力的真实世界Web代理 http://arxiv.org/abs/2307.12856
• 用于智能手机GUI自动化的综合认知LLM代理 http://arxiv.org/abs/2402.11941
• 通往通用计算机控制之路：以《荒野大镖客2》为例的多模态代理 https://arxiv.org/abs/2403.03186
• 在多个模拟世界中扩展可指令代理 技术报告链接
• Android in the Zoo：用于GUI代理的动作链思维 http://arxiv.org/abs/2403.02713
• OmniACT：一个数据集和基准，旨在支持桌面和网页上的多模态通用自主代理 http://arxiv.org/abs/2402.17553
• 用于智能手机GUI自动化的综合认知LLM代理 http://arxiv.org/abs/2402.11941
• 从截图中提升语言理解能力 http://arxiv.org/abs/2402.14073
• AndroidEnv：一个针对Android的强化学习平台 http://arxiv.org/abs/2105.13231
• SeeClick：利用GUI接地机制构建先进的视觉GUI代理 https://arxiv.org/abs/2401.10935
• AgentStudio：用于构建通用虚拟代理的工具包 https://arxiv.org/abs/2403.17918
• ReALM：将指代消解视为语言建模 https://arxiv.org/abs/2403.20329
• AutoWebGLM：自举并强化基于大型语言模型的网页导航代理 https://arxiv.org/abs/2404.03648
• Octopus v2：用于超级代理的设备端语言模型 https://arxiv.org/pdf/2404.01744.pdf
• Mobile-Env：一个用于评估LLM与GUI交互的平台和基准 https://arxiv.org/abs/2305.08144
• OSWorld：在真实计算机环境中对多模态代理进行开放式任务的基准测试 https://arxiv.org/abs/2404.07972
• Ferret-UI：利用多模态LLM实现 grounded移动UI理解 https://arxiv.org/abs/2404.05719
• VisualWebBench：多模态LLM在网页理解和接地方面已经发展到何种程度？ https://arxiv.org/abs/2404.05955
• OS-Copilot：迈向具备自我改进能力的通用计算机代理 https://arxiv.org/abs/2402.07456
• VisualWebBench：多模态LLM在网页理解和接地方面已经发展到何种程度？ https://arxiv.org/abs/2404.05955
• AutoDroid：基于LLM的Android任务自动化 https://arxiv.org/abs/2308.15272
• 通过强化学习微调大型视觉语言模型，使其成为决策代理 https://rl4vlm.github.io
• WebArena：一个用于构建自主代理的真实网络环境 https://arxiv.org/abs/2307.13854
• Synapse：基于轨迹示例提示的记忆增强型计算机控制方法 https://openreview.net/pdf?id=Pc8AU1aF5e
• gpt-computer-assistant https://github.com/onuratakan/gpt-computer-assistant
• Mobile-Agent：强大的移动设备操作助手系列 https://github.com/X-PLUG/MobileAgent
• GUI Odyssey：一个用于移动设备跨应用GUI导航的综合数据集 https://github.com/OpenGVLab/GUI-Odyssey
• ASSISTGUI：面向任务的PC图形用户界面自动化 https://showlab.github.io/assistgui/
• You Only Look at Screens：多模态动作链代理 https://arxiv.org/abs/2309.11436 https://github.com/cooelf/Auto-GUI
• E-ANT：一个用于高效自动GUI导航的大规模数据集 https://arxiv.org/pdf/2406.14250
• AndroidWorld https://github.com/google-research/android_world
• AppWorld：一个可控的应用和人物世界，用于基准测试交互式编码代理 https://arxiv.org/abs/2407.18901 https://appworld.dev/
• Read Anywhere Pointed：基于树状透镜接地的布局感知GUI屏幕阅读 https://arxiv.org/abs/2406.19263
• Cradle：赋能基础代理迈向通用计算机控制 https://arxiv.org/abs/2403.03186
• 针对语言模型代理的树搜索 https://arxiv.org/abs/2407.01476
• LaVague：面向开发者的Web代理框架 https://github.com/lavague-ai/LaVague
• WebLlama：https://github.com/McGill-NLP/webllama
• AutoCrawler：一种渐进式理解型Web代理，用于生成网络爬虫 https://arxiv.org/abs/2404.12753

引用

@article{niu2024screenagent,
      title={ScreenAgent：一种由视觉语言模型驱动的计算机控制代理}, 
      author={牛润良、李金东、王世奇、付亚丽、胡西宇、冷雪源、孔赫、常毅、王琪},
      year={2024},
      eprint={2402.07945},
      archivePrefix={arXiv},
      primaryClass={cs.HC}
}

许可证

代码许可证：MIT
数据集许可证：Apache-2.0
模型许可证：CogVLM许可证

ScreenAgent 快速上手指南

ScreenAgent 是一个由视觉语言大模型（VLM）驱动的计算机控制智能体。它能够通过观察屏幕截图，自动规划并执行鼠标和键盘操作，从而完成多步骤的桌面任务。

环境准备

系统要求

• 操作系统：Linux, Windows, 或 macOS（作为控制器端）
• 被控端环境：
  • 安装了 VNC Server 的桌面系统（如 TightVNC），或
  • 支持 GUI 的 Docker 容器
• Python 版本：推荐 Python 3.8+

前置依赖

• Docker（可选，用于快速部署被控端环境）
• Git
• PyQt5 及相关 Python 库

---

安装步骤

第一步：准备被控桌面环境

你可以选择使用现有的桌面系统，或使用官方提供的 Docker 镜像快速启动一个包含 VNC 和剪贴板服务的环境。

方案 A：使用 Docker（推荐）

拉取并启动预置环境的容器：

docker run -d --name ScreenAgent -e RESOLUTION=1024x768 -p 5900:5900 -p 8001:8001 -e VNC_PASSWORD=<VNC_PASSWORD> -e CLIPBOARD_SERVER_SECRET_TOKEN=<CLIPBOARD_SERVER_SECRET_TOKEN> -v /dev/shm:/dev/shm niuniushan/screenagent-env:latest

注意：请将 <VNC_PASSWORD> 替换为你的 VNC 密码，<CLIPBOARD_SERVER_SECRET_TOKEN> 替换为剪贴板服务密码。启用剪贴板服务对于输入中文或非 ASCII 字符至关重要。

方案 B：使用现有桌面

1. 在目标机器上安装并运行任意 VNC Server，记录其 IP 和端口。
2. 若需支持长文本或中文输入，需在目标机器上安装依赖并启动剪贴板服务：

pip install fastapi pydantic uvicorn pyperclip 
export CLIPBOARD_SERVER_SECRET_TOKEN=<CLIPBOARD_SERVER_SECRET_TOKEN>
# 若遇到 Pyperclip 错误，可能需要设置 DISPLAY 变量
export DISPLAY=:0.0
python client/clipboard_server.py

第二步：安装控制器依赖

克隆项目代码并安装控制器所需的 Python 依赖：

git clone https://github.com/niuzaisheng/ScreenAgent.git
cd ScreenAgent
pip install -r client/requirements.txt

第三步：配置大模型接口

编辑 client/config.yml 文件，配置你要使用的视觉语言模型（VLM）。目前支持 GPT-4V, LLaVA-1.5, CogAgent 和 ScreenAgent。

选项 1：使用 GPT-4V

在 config.yml 中保留 GPT4V 部分，填入你的 API Key：

llm_api:
  GPT4V:
    model_name: "gpt-4-vision-preview"
    openai_api_key: "<YOUR-OPENAI-API-KEY>"
    target_url: "https://api.openai.com/v1/chat/completions"
  # 其他模型请注释掉

选项 2：使用本地模型 (LLaVA / CogAgent / ScreenAgent)

你需要先启动本地模型推理服务（监听端口 40000），然后在 config.yml 中将 target_url 指向 http://localhost:40000/worker_generate 并仅保留对应模型配置。

以启动 ScreenAgent 模型为例：

1. 下载权重文件 ScreenAgent-2312.zip 并解压至 train/saved_models/ScreenAgent-2312。
2. 启动推理服务：

cd train
RANK=0 WORLD_SIZE=1 LOCAL_RANK=0 python ./cogagent_model_worker.py --host 0.0.0.0 --port 40000 --from_pretrained "./saved_models/ScreenAgent-2312" --bf16 --max_length 2048

3. 修改 client/config.yml，仅保留 ScreenAgent 配置项。

---

基本使用

完成上述配置后，即可启动控制器进行自动化任务演示。

1. 启动控制器： 进入 client 目录并运行：

   cd client
   python run_controller.py -c config.yml
   

2. 执行任务：

   • 程序启动后会弹出图形界面。
   • 在界面左侧列表中双击选择一个预设任务（如文件操作、网页浏览等）。
   • 点击 "Start Automation" 按钮。

3. 运行过程： 控制器将自动执行“规划 - 执行 - 反思”循环：

   • 截取当前屏幕画面。
   • 结合提示词模板发送给大模型。
   • 解析大模型返回的鼠标/键盘指令并发送至 VNC Server。
   • 根据执行结果判断是否继续、重试或调整计划，直到任务完成。

提示：如果界面卡住或连接断开，可尝试点击界面上的 "Re-connect" 按钮重新连接 VNC 服务。