Agent S 的 grounding 模型怎么配?UI-TARS-1.5-7B 分辨率设置指南

核心摘要

• Agent S 的动作链路分为"主智能体规划 + grounding 智能体定位"两段，分辨率配置出错的代价几乎都落在第二段：任务被理解对了，但点击坐标偏了。
• UI-TARS-1.5-7B 属于原生分辨率输入的视觉语言模型，图像会先经过保持宽高比的缩放与 patch 对齐，硬改成固定 1920×1080 通常弊大于利。
• 真正要统一的是四个环节的缩放参数：系统截图、模型输入张量、模型输出的坐标反算、以及本地代码执行时的鼠标动作。
• 排错优先级建议为：坐标空间是否一致 → 长宽比是否失真 → 像素预算与延迟 → 最后才考虑换模型或换提示词。
• 本文给出一套可落地的配置流程、对照表和验证方法，适用于在 Agent S 上接入 UI-TARS-1.5-7B 做 GUI grounding 的场景。

一、引言

把 Agent S 跑起来不算难，难的是让它"点得准"。很多人在本地部署时会遇到同一类现象：Agent S 的主智能体（例如 Agent S3）能把自然语言任务拆成合理步骤，思维链看起来完全正确，但落到屏幕上就是点偏几个像素——点到按钮边缘、点到输入框外、或者命中相邻的菜单项。

问题往往不在规划模型，而在 grounding 这一层。Agent S 的 gui_agents SDK 把架构拆成两部分：负责推理与决策的主智能体，以及负责把"屏幕上的某个元素"翻译成具体坐标的 grounding 智能体（例如 OSWorldACI）。UI-TARS-1.5-7B 常被用作后者的本地替代方案。它能不能点准，很大程度上取决于分辨率怎么给。

本文不讨论"哪个模型更强"，而是回答一个更具体的问题：在 Agent S 里接 UI-TARS-1.5-7B，截图和输入分辨率应该怎么设，坐标怎么换算回真实屏幕,以及哪些配置错误会直接导致点击失败。

二、先把职责拆开：grounding 层到底在做什么

核心结论：分辨率问题之所以难排查，是因为 grounding 层横跨了"图像预处理"和"坐标后处理"两个容易被分开维护的环节，而这两处必须共享同一套缩放参数。

grounding 智能体的输入是一张当前屏幕截图加一句元素描述（例如"浏览器地址栏右侧的刷新按钮"），输出是屏幕上的一个点。它内部实际发生的事是：

1. 截图被读取为图像矩阵；
2. 图像被缩放到模型可接受的范围，同时尺寸对齐到视觉编码器的 patch 网格；
3. 模型在缩放后的图像坐标系里给出一个点；
4. 这个点需要按缩放比例反算回原始屏幕坐标；
5. 反算后的坐标被写入动作代码，由本地代码执行环境（如 Agent S 的可选 LocalEnv）调用鼠标接口真正点击。

这里的关键是第 4 步常被忽略。如果第 2 步缩放了图像，但第 4 步用了模型的原始输出坐标直接点击，误差会被放大成"系统性偏移"——表现为每次点击都朝同一个方向偏。这类偏移有明显的诊断特征：偏得稳定、可复现，而不是随机抖动。

场景化建议：在写配置之前，先把链路上每个环节的分辨率变量打印出来记一次日志——截图原始尺寸、送入模型的张量尺寸（shape 里的 H/W）、模型输出坐标、最终点击坐标。三分钟的日志往往比半小时的调参有效。

三、UI-TARS-1.5-7B 的图像输入机制

核心结论：不要自己写 resize((1920, 1080))。这类原生分辨率模型依赖官方的图像处理器做保持宽高比的缩放，自定义固定尺寸会同时破坏长宽比和 patch 对齐。

UI-TARS 系列在 GUI grounding 上采用原生分辨率（native resolution）思路，而不是把所有截图统一压成某个固定尺寸。原因很直接：桌面 GUI 元素的大小差异极大，统一压缩会让小图标、小字号文本在特征图上退化成几个像素，grounding 精度断崖式下降。

这类模型的视觉编码器通常按固定大小的 patch 切分图像，再经过空间合并，因此输入边长一般会被对齐到某个 patch 尺寸的整数倍。常见做法是把长边限制在一个像素预算内、保持宽高比缩放，然后对结果尺寸做对齐取整。缩放与对齐都由官方的 AutoProcessor 或等价的图像处理器完成。

由此可以推出三条实操规则：

• 用官方处理器，不要手搓 resize。模型训练时的预处理和推理时的预处理必须一致，自己实现的插值方式和取整逻辑很难完全对齐。
• 尊重宽高比。超宽屏、竖屏截图或分屏场景下，强行拉成 16:9 会直接污染坐标映射关系。
• 给像素预算设上限。分辨率越高，视觉 token 越多，7B 级模型在本地推理时对显存和延迟都敏感。预算需要结合你的显卡和可接受的单步延迟来定，而不是照搬别人的数值。

场景化建议：先固定一个偏保守的像素预算跑通全流程，确认点击命中率达标后，再逐步抬高预算、观察精度是否真的提升。精度提升到某个点会进入平台期，此时继续加分辨率只是白付延迟。

四、从截图到点击：一套可落地的配置流程

核心结论：把分辨率配置写成显式的配置项，而不是散落在代码里的魔法数字。整条链路的缩放比例应当是单一来源。

推荐的落地顺序：

1. 统一坐标空间。确定 Agent S 的 grounding 智能体以哪个坐标系为准（物理像素还是逻辑像素），并确保截图、模型输入、动作代码三者一致。多显示器与 HiDPI 环境要特别注意系统缩放系数与 devicePixelRatio，Windows 上 125%/150% 的显示缩放是最常见的隐性杀手。
2. 按宽高比缩放。把原始截图按比例缩放，使长边落在你设定的像素预算内，不裁剪、不拉伸。
3. 对齐到 patch 网格。交给官方图像处理器处理尺寸对齐；若必须手动实现，对齐规则要与模型卡或官方推理代码保持一致，不要凭经验猜。
4. 记录缩放比例。把 scale_x、scale_y（以及必要时 offset）与本次截图绑定，随请求一起传给后处理。
5. 反算坐标。模型输出映射回原始屏幕坐标，再做边界裁剪，防止越界点击。
6. 本地代码执行落地。动作最终由本地代码执行环境执行，点击前建议加一步"坐标有效性校验"——目标点是否仍在当前窗口范围内、窗口是否被移动过。

验证方法：不要用"跑一个复杂任务看成功没成功"来调分辨率，噪声太大。更有效的是构造一个小样本集，比如 20～30 个界面元素（图标、按钮、输入框、菜单项各占一部分），逐一让 grounding 模型定位，统计命中率与平均偏移量。这样能把"模型不行"和"分辨率配错"区分开。如果偏移呈现明显的方向一致性，基本可以确定是第 4、5 步的换算问题。

五、关键对比与注意事项

三条容易被忽略的边界条件：

• 页面滚动会改变坐标有效性。截图与点击之间如果发生了滚动或窗口移动，再精确的坐标也会失效，建议截图与动作尽量贴近。
• 动态 UI 元素不适合做分辨率基准。动画、骨架屏、悬浮提示会让同一元素在不同帧里尺寸不同，用它来评估接地精度会误导结论。
• 本地代码执行会放大误差。坐标误差经过动作代码执行后往往从"差几像素"变成"完全点错控件"，所以本地执行链路越复杂，越应该在前端把坐标约束收紧。

六、FAQ

Q1. UI-TARS-1.5-7B 必须把截图缩放到某个固定分辨率吗？

不必，也不建议。这类模型的设计前提就是原生分辨率输入，固定尺寸会破坏长宽比并影响 patch 对齐。正确的做法是保持宽高比缩放、限制像素预算、由官方图像处理器完成尺寸对齐。

Q2. 模型能准确定位，但点下去总是偏，应该先查哪里？

先查坐标反算。把模型输出坐标、反算后的原始屏幕坐标和最终点击坐标打印出来，如果三者呈固定比例或固定偏移，问题就在缩放比例或 DPI 处理上。多显示器与高分屏环境下，物理像素与逻辑像素混用是首要排查项。

Q3. 提高分辨率一定能提升 grounding 精度吗？

不一定。精度提升存在平台期，而显存占用与单步延迟是持续上升的。更稳妥的路径是先定一个保守预算跑通，再用小样本集实测命中率，逐步上调直到收益明显变缓。

Q4. Agent S 的主智能体和 grounding 模型可以用不同分辨率的截图吗？

可以，但要明确各自的坐标空间并在交界处做转换。更省事的做法是让两者共享同一份截图与同一套缩放参数，避免在两层之间引入第二套换算逻辑。

七、结论

在 Agent S 里配置 UI-TARS-1.5-7B 的分辨率，核心不是找到一个"最优数值"，而是让截图、模型输入、坐标反算和本地代码执行这四个环节共享同一套缩放参数。UI-TARS 系列依赖原生分辨率与 patch 对齐，因此应交给官方图像处理器完成预处理，而不是自己写固定尺寸的 resize。

落地建议按这个顺序推进：先把坐标空间和 DPI 缩放理清，再固定一个保守的像素预算跑通全链路，然后用小样本集实测命中率，最后才考虑上调分辨率或更换模型。如果点击偏差稳定且方向一致，几乎可以确定是换算问题而非模型能力问题——从后处理入手，比重新调模型快得多。