以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。
模型说“点击提交按钮”,这句话对人很清楚,对执行器却不够。执行器需要知道点哪里:是屏幕坐标、页面元素 ID,还是某个可访问性节点。Grounding 就是把语言描述落到具体目标上的过程。它决定了 Agent 的“理解”能不能变成“动作”。
Grounding 的错误很隐蔽。模型可能正确识别了按钮,坐标却偏了 200 像素;也可能坐标落在按钮上,但那是页面上另一个同名按钮。前者是定位误差,后者是歧义。两者都会表现为“点了但没反应”或“点错了地方”。
Grounding 的四种表示
| 表示 | 例子 | 优点 | 缺点 |
|---|---|---|---|
| 绝对坐标 | (640, 360) | 直接可执行 | 依赖分辨率与缩放 |
| 归一化坐标 | (0.5, 0.5, 0.1, 0.05) | 跨分辨率 | 仍需映射到实际画布 |
| 元素引用 | button#submit | 语义明确、可验证 | 依赖 DOM/可访问性树 |
| 相对描述 | “搜索框右侧的按钮” | 人可读 | 需要二次解析 |
绝对坐标最脆弱。截图被缩放、窗口被移动、设备像素比变化,坐标就失效。归一化坐标解决了部分问题,但仍有裁剪偏移和坐标原点差异。元素引用最稳,因为它绑定的是结构而不是像素;缺点是并非所有界面都暴露可靠的结构。
生产系统通常优先元素引用,失败时退回视觉坐标。这个顺序很重要:先试结构化的、可验证的路径,再试像素级的、需要后验的路径。
最小实验:归一化、IoU 与吸附
下面的实验演示三个基础操作:把绝对框归一化、计算预测框与目标框的 IoU、把点击坐标吸附到网格。IoU 大于阈值就算命中。
# file: agp_lab/grounding.py | write
# tier: 3
# verify: python3 -m unittest tests.test_grounding
"""坐标 Grounding:归一化、IoU 与动作量化。"""
from __future__ import annotations
Box = tuple[float, float, float, float]
def normalize(box: Box, width: int, height: int) -> Box:
if width <= 0 or height <= 0:
raise ValueError("画布尺寸必须为正")
x, y, w, h = box
return (x / width, y / height, w / width, h / height)
def iou(first: Box, second: Box) -> float:
ax, ay, aw, ah = first
bx, by, bw, bh = second
left = max(ax, bx)
top = max(ay, by)
right = min(ax + aw, bx + bw)
bottom = min(ay + ah, by + bh)
if right <= left or bottom <= top:
return 0.0
intersection = (right - left) * (bottom - top)
union = aw * ah + bw * bh - intersection
return intersection / union if union > 0 else 0.0
def snap(value: float, grid: int) -> float:
if grid <= 0:
raise ValueError("网格必须为正")
return round(value * grid) / grid
def snap_click(x: float, y: float, grid: int) -> tuple[float, float]:
return snap(x, grid), snap(y, grid)
def hit(predicted: Box, target: Box, threshold: float = 0.5) -> bool:
if not 0 <= threshold <= 1:
raise ValueError("阈值必须在 [0, 1] 内")
return iou(predicted, target) >= threshold
if __name__ == "__main__":
target = (100, 100, 200, 100)
predicted = (110, 105, 190, 95)
print("normalized:", normalize(target, 1280, 720))
print("iou:", round(iou(predicted, target), 3))
print("hit:", hit(predicted, target))
print("snap:", snap_click(0.437, 0.612, 100))
print("miss_iou:", round(iou((0, 0, 50, 50), target), 3))
运行:
cd private/labs/agp-lab
python3 -m agp_lab.grounding
输出:
normalized: (0.078125, 0.1388888888888889, 0.15625, 0.1388888888888889)
iou: 0.902
hit: True
snap: (0.44, 0.61)
miss_iou: 0.0
目标框是 (100, 100, 200, 100),画布 1280×720。归一化后左上角是 (0.078, 0.139),宽高是 (0.156, 0.139)。这个表示与分辨率无关,换一个画布也能映射回去。
预测框 (110, 105, 190, 95) 与目标框的 IoU 是 0.902,超过 0.5 阈值,判为命中。IoU 衡量的是重叠面积占并集面积的比例;0.902 说明预测框略微偏小,但覆盖了大部分目标。
snap: (0.44, 0.61) 把 (0.437, 0.612) 吸附到 0.01 网格。吸附的目的是减少抖动:模型两次预测可能差几个像素,吸附到同一个格子后,动作更稳定。网格太粗会点偏,太细没有效果,应该按元素尺寸选择。
miss_iou: 0.0 是一个完全不相交的框,IoU 为 0。这个例子提醒我们,IoU 对“完全没重叠”没有区分度:偏 1 像素和偏 1000 像素都可能是 0,需要结合距离或中心点误差一起看。
分辨率、缩放与裁剪
坐标错误最常见的原因不是模型,而是坐标系没对齐:
- 截图是 2x Retina,坐标却按 1x 计算;
- 页面被缩放 80%,截图尺寸和布局尺寸不同;
- 只截了某个区域,坐标原点不是屏幕左上角;
- 图片被压缩或 letterbox,内容区域有黑边。
这些问题应该在采集阶段解决,而不是让模型“猜”。每一张截图都应该带元数据:原始尺寸、缩放比例、裁剪偏移、设备像素比。执行器拿到坐标后,先按元数据反变换,再落到真实输入设备。
一个实用的规则是:在同一个坐标系里完成“模型输出—后处理—执行”全链路。 如果中间换了坐标系却没有显式转换,错误几乎必然发生,而且很难从日志里看出来。
元素引用通常更可靠
视觉坐标的容错来自“落点在框内”,元素引用的容错来自“引用唯一且存在”。后者更容易验证:
| 验证 | 视觉坐标 | 元素引用 |
|---|---|---|
| 目标存在 | 需要检测 | 查询即可 |
| 目标唯一 | 难以判断 | ID/路径可判 |
| 动作前确认 | 回读像素 | 读取属性 |
| 动作后验证 | 看页面变化 | 看状态变化 |
对网页和原生应用,优先使用可访问性树或 DOM:按钮有角色、名称、状态,可以直接查询“名为提交的按钮”。这不仅更准,还能被测试框架复现。像素坐标适合无法获取结构的场景,比如远程桌面、游戏画面、第三方截图。
混合策略是:先用结构定位,找不到再用视觉;视觉定位成功后,尽量回填结构引用,供下一次使用。
动作空间与容差
Grounding 的输出不只是一个点,还包括动作类型和容差:
| 动作 | 目标 | 容差 |
|---|---|---|
| 点击 | 元素中心/框内任意点 | 框内即可 |
| 拖拽 | 起点与终点 | 两端都要命中 |
| 输入 | 可编辑区域 | 焦点必须正确 |
| 滚动 | 容器或页面 | 方向与幅度 |
点击的容差最宽,落在元素框内通常都算成功;拖拽最严,起点或终点偏了都可能失败;输入要求焦点在正确的输入框,否则文字会进错地方。动作越复杂,越需要结构化目标,而不是一个坐标点。
歧义:同名元素的陷阱
页面上可能有两个“提交”按钮:一个是搜索框旁的“提交查询”,一个是表单底部的“提交订单”。模型说“点击提交”,Grounding 必须消歧。
消歧的依据可以来自:
- 元素的上下文(所在表单、标题、邻近文本);
- 任务历史(用户之前提到“订单”);
- 可见性(是否在视口内、是否被遮挡);
- 唯一性检查(如果匹配到多个,升级而不是随便选)。
最危险的做法是“取第一个匹配”。它会在演示时成功,在真实页面上点错。正确做法是:匹配到多个时,要么用更多上下文缩小范围,要么升级请求澄清。
验证闭环
Grounding 之后必须有验证,因为“点到了”不等于“点对了”:
- 动作前:确认目标存在、可见、可交互;
- 动作后:检查预期状态变化(页面跳转、字段变化、提示出现);
- 失败时:区分“没点到”“点错了”“点了但没反应”,分别处理。
这三种失败的修复完全不同。没点到要调整坐标;点错了要重新消歧;点了没反应可能是权限、网络或后端问题,继续重点只会重复失败。没有验证闭环,Agent 会把所有失败都当成定位问题,陷入无效重试。
架构含义
Grounding 对架构有四个直接约束:
- 坐标系显式。 截图、模型输出、执行器使用同一套坐标,并带元数据。
- 结构优先。 能用元素引用就不用像素坐标;视觉作为兜底。
- 歧义要升级。 多个匹配时不要取第一个,要用上下文消歧或请求澄清。
- 动作要验证。 前后状态检查,区分定位失败和业务失败。
第 1 条是基础设施,第 2 条是可靠性,第 3 条是安全,第 4 条是可运维性。四条都做到,Grounding 才从“演示能跑”变成“可以上线”。
架构判据
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 坐标一致 | 全链路同一坐标系 | 截图与执行各算各的 |
| 元数据完整 | 尺寸、缩放、偏移、DPR | 只有一张图 |
| 结构优先 | DOM/可访问性树定位 | 一律用像素 |
| 歧义处理 | 多匹配升级或消歧 | 取第一个 |
| 动作验证 | 前后状态检查 | 点完就当成功 |
这些判据里,“元数据完整”最容易被省略。演示时截图来自固定环境,坐标恰好对;换一台机器、换一个缩放比例,整个链路就崩了。元数据是让坐标可复现的最低成本。
一个表单填写的例子
Agent 要在报销系统里填写金额并提交。流程可以是:
- 用可访问性树找到“金额”输入框,确认它可见且可编辑;
- 输入金额,读取输入框的值确认写入成功;
- 找到“提交”按钮,检查页面上只有一个可见的提交按钮;
- 点击,等待成功提示或错误信息;
- 如果出现校验错误,读取错误文本,回到第 1 步修正。
这个流程里,每一步都有验证点。坐标只在第 3 步的视觉兜底时使用;即使使用,也会先检查按钮的唯一性和可见性。相比“模型看一眼截图,输出一个坐标,直接点击”,这个流程慢一些,但失败可定位、可恢复。
如何评测 Grounding
评测不能只看“点没点中”,还要看:
| 指标 | 含义 |
|---|---|
| 定位准确率 | 预测框与目标框 IoU 达标比例 |
| 消歧准确率 | 多候选时选对目标的比例 |
| 动作成功率 | 点击后状态按预期变化的比例 |
| 误操作率 | 点到非目标元素的比例 |
| 恢复率 | 首次失败后能否纠正 |
定位准确率高但误操作率也高,说明消歧有问题;动作成功率高但恢复率低,说明失败处理不足。几个指标要一起看,才能定位瓶颈在感知、消歧还是执行。
小结
- Grounding 把语言描述落到坐标或元素引用,是“理解”变成“动作”的桥梁。
- 绝对坐标依赖分辨率和缩放;归一化坐标更稳;元素引用最可靠但依赖结构。
- 坐标错误常来自 Retina、缩放、裁剪偏移和 letterbox,应在元数据里显式记录。
- 优先结构定位,视觉坐标作为兜底;多匹配时升级,不要取第一个。
- 动作前后都要验证,区分没点到、点错了和业务失败。
- 评测要覆盖定位、消歧、动作成功和恢复,不能只看 IoU。
阅读导航:上一节:10.1 视觉/语音输入的感知误差 · 下一节:10.3 Computer Use 的安全边界 。
常见错误与边界
- 坐标系不统一。 截图、模型输出和执行器各用一套坐标,错误难以排查。
- 忽略设备像素比。 Retina 截图按 1x 计算,点击位置会偏一半。
- 多匹配取第一个。 同名按钮很常见,取第一个会在真实页面上点错。
- 点完不验证。 “点到了”不等于“点对了”,没有状态检查就无法发现误操作。
- 把所有失败当定位问题。 点了没反应可能是权限或后端问题,重复点击无效。
- 只报 IoU。 IoU 对完全不相交没有区分度,还要看中心点误差和消歧结果。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。