UI-TARS 桌面自动化实战：从视觉识别到精准点击

UI-TARS 桌面自动化实战：从视觉识别到精准点击

【免费下载链接】UI-TARSPioneering Automated GUI Interaction with Native Agents项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS

UI-TARS 是一套 GUI 桌面自动化管线：多模态模型看懂截图并输出 Thought+Action，配套 ui-tars 包将动作指令解析为可执行的 pyautogui 脚本。本文覆盖部署、动作解析与坐标校准，面向需要自动化桌面或移动 GUI 操作的开发者。

一、项目定位与适用场景

仓库由两部分组成：模型侧的部署与推理指南（HuggingFace Inference Endpoints 部署加首次推理），以及 ui-tars 解析包（Python ≥3.10，无强制第三方依赖）。三个典型场景可以帮你判断是否适用：

• 桌面任务闭环执行：让模型驱动虚拟机或真实桌面，完成"打开文档 → 输入文字 → 保存"这类多步操作，对应 OSWorld 一类评测环境。
• 把现成 VLM 输出转成 GUI 动作：已有视觉语言模型但输出格式混乱时，可复用本仓库的 action_parser 与 prompt 模板 统一动作空间。
• 移动端 / Android 模拟器自动化：MOBILE_USE 提示词扩展了 long_press、open_app、press_home、press_back 等动作。

与通用 LLM Agent 相比，它的差异点在统一动作空间（点击 / 快捷键 / 输入 / 滚动 / 拖拽全覆盖）和内置 Thought 推理链，推理能力经强化学习增强。官方 benchmark（引自 README.md 数据表）：OSWorld（100 步）UI-TARS-1.5 得 42.5 分，OpenAI CUA 36.4，Claude 3.7 28；GUI 定位 ScreenSpot-V2 94.2、ScreenSpotPro 61.6（上代 SOTA 为 91.6 与 43.6）。

二、核心能力拆解

GUI 感知与统一动作空间

模型侧负责"看懂屏幕"：从截图中理解元素、组织推理链，最后给出标准 Action。动作空间由 prompt.py 里三套模板定义：

• COMPUTER_USE：桌面环境（Windows / Linux / macOS），支持 click、left_double、right_single、drag、hotkey、type、scroll、wait、finished
• MOBILE_USE：移动端与 Android 模拟器，额外支持 long_press、open_app、press_home、press_back
• GROUNDING：只输出 Action 不输出 Thought，用于定位能力评测与模型训练

动作解析与 pyautogui 脚本生成

解析侧入口是 parse_action_to_structure_output：把模型原始输出（Thought: ...\nAction: click(start_box='(100,200)')格式）解析为含 action_type、action_inputs 等字段的字典，支持同一次响应中按)\n\n分隔的多个动作。

parsing_response_to_pyautogui_code 再把结构化结果转成 pyautogui 代码，几个细节值得注意：

• 快捷键与方向键名自动映射（arrowleft → left、space → 空格）
• type 默认走"剪贴板 + Ctrl+V"粘贴，避免逐字符按键的慢速输入
• 动作是 finished 时直接输出 DONE，作为任务结束标记

坐标映射与校准方法

点击准不准取决于坐标换算：Qwen2.5-VL 系模型输出绝对像素坐标（放大后图像中的像素值），解析器用 smart_resize（对齐因子 28）反推回原图分辨率；旧版 Qwen2-VL 输出 0–999 相对坐标，用 factor=1000 处理。README_coordinates.md 给出完整校准流程：把解析出的坐标画回截图，肉眼确认落点。

三、快速上手：安装解析包并跑通首个示例

环境要求：Python ≥3.10（见 pyproject.toml）；若要在本地执行生成的脚本，需另装 pyautogui 与 pyperclip。

git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS cd UI-TARS pip install ui-tars

最小示例：以一条点击指令为输入，传入截图分辨率，输出 pyautogui 代码：

from ui_tars.action_parser import parse_action_to_structure_output, parsing_response_to_pyautogui_code response = "Thought: Click the button\nAction: click(start_box='(100,200)')" width, height = 1920, 1080 parsed = parse_action_to_structure_output( response, factor=1000, origin_resized_width=width, origin_resized_height=height, model_type="qwen25vl", ) code = parsing_response_to_pyautogui_code(parsed, image_height=height, image_width=width) print(code)

完整部署与推理流程见 README_deploy.md，请求 messages 可直接用 data/test_messages.json 作为起点。

四、典型工作流演示

场景一：云端部署 7B 模型并完成首次推理

想以 API 形式运行 UI-TARS-1.5-7B 并让它执行第一个 GUI 任务。

1. 在 HuggingFace Inference Endpoints 导入 7B 模型，硬件选 GPU L40S 48G（Nvidia L4 / A100 亦可）
2. 设置 Max Input Length、Max Batch Prefill Tokens 为 65536，Max Number of Tokens 为 65537
3. 添加环境变量：CUDA_GRAPHS=0（避免部署失败）、PAYLOAD_LIMIT=8000000（防止大图请求失败）
4. 创建容器后把 Container URI 改为 text-generation-inference:3.2.1 并更新
5. 按 README_deploy.md 示例调用：OpenAI 兼容接口，temperature=0.0，stream=True

实际效果：给定截图与任务指令，模型返回推理链和标准动作，例如：

Thought: Preferences 窗口已打开，我需要在左侧列表中找到 "Color Management" 选项。 Action: click(start_box='(177,549)')

场景二：桌面任务闭环执行（截图 → 动作 → 执行）

以架构图中"打开文档、输入文字、保存"的例子走通整个循环。

1. 对桌面截图（如 1920x1080），用 COMPUTER_USE 提示词构造 messages
2. 调用端点获得 Thought/Action；遇到 wait() 则睡眠 5 秒后重新截图确认状态变化
3. 用 parse_action_to_structure_output（model_type="qwen25vl"）把坐标映射回原始分辨率
4. 由 parsing_response_to_pyautogui_code 生成 pyautogui 代码并执行，或交给模拟器执行
5. 执行后把新截图追加进历史，循环直到模型输出 finished

实际效果：多步跨窗口的操作可闭环运行，每步都有 Thought 记录可供回溯审计。

五、性能与精度调优参数清单

• model_type：Qwen2.5-VL 系模型用 "qwen25vl"（内部走 smart_resize 反推）；旧版 Qwen2-VL 用相对坐标，factor 保持 1000。两者混用会产生系统性点击偏移
• origin_resized_width / origin_resized_height：必须与送入模型的截图实际分辨率一致，这是最常见的精度损失来源
• max_pixels / min_pixels：解析器默认 16384×28×28 与 100×28×28；若部署时改过模型缩放策略，需同步传入
• 推理参数：temperature=0.0、max_tokens=400 为仓库示例采用的配置，保证动作格式稳定
• 服务端：截图较大时把 PAYLOAD_LIMIT 调到 8000000，避免请求被截断失败

六、常见坑与排查

现象：点击位置系统性偏移可能原因：model_type 与实际模型不符（qwen25vl 输出绝对坐标，旧模型输出 0–999 相对坐标，映射方式用错会整体错位）；或 origin_resized 分辨率与实际截图不一致。 解法：按 README_coordinates.md 流程把解析坐标画回截图确认落点，再逐项核对 model_type 与分辨率参数。

现象：端点部署失败可能原因：CUDA graphs 与模型不兼容。 解法：设置环境变量 CUDA_GRAPHS=0 后重新部署。

现象：大图请求失败可能原因：截图 payload 超过默认上限。 解法：设置 PAYLOAD_LIMIT=8000000，或发送前压缩截图尺寸。

现象：解析抛出 "Action can't parse"可能原因：模型输出的 Action 行格式不完整，括号未闭合，或 type(content='...') 内含未转义引号。 解法：走 action_parser.py 的 escape_single_quotes 处理引号；确认输出包含完整的 "Action: " 行；codes/tests/action_parser_test.py 中有对应用例可对照输入格式。

现象：smart_resize 抛出 ValueError: absolute aspect ratio must be smaller than 200可能原因：截图长宽比极端（超长条状窗口）。 解法：发送前裁剪或补齐截图，使最长边与最短边之比小于 200。

七、进阶方向与生态

两个值得投入的扩展方向：一是把"生成 pyautogui 代码"这一步替换为自己的执行器，或接入 OSWorld 一类真实操作系统模拟器（README 提到可用 OSWorld 官方推理脚本复现结果）；二是面向游戏与工具调用场景扩展动作空间，官方后续版本 UI-TARS-2 已在该方向整合 GUI、游戏、代码与工具调用能力。

仓库内资源入口：部署指南、坐标处理指南、单元测试目录、论文 PDF。相关配套项目：UI-TARS-desktop（运行在本地个人设备上的桌面 Agent）与 Midscene（浏览器自动化方向），与本仓库分别覆盖桌面、本机与浏览器三类场景。

UI-TARS 的核心价值在于把"模型看懂屏幕"与"代码执行动作"解耦：模型侧只负责输出标准 Thought/Action，解析、坐标映射与脚本生成交给 ui-tars 包完成。动手前建议先通读 README_deploy.md 与 README_coordinates.md，它们分别覆盖部署与校准这两个最容易踩坑的环节。

【免费下载链接】UI-TARSPioneering Automated GUI Interaction with Native Agents项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS