《AI Agent 技术原理与架构·模型、推理与能力边界》10.2 坐标 Grounding 与动作空间

Grounding 是把“点击提交按钮”变成一组可执行坐标或元素引用的过程。它看起来只是坐标换算,实际包含分辨率缩放、裁剪偏移、元素歧义和落点容差。本节用归一化、IoU 和网格吸附实验,演示如何度量定位误差,并讨论为什么元素引用通常比像素坐标更可靠。

以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。

模型说“点击提交按钮”,这句话对人很清楚,对执行器却不够。执行器需要知道点哪里:是屏幕坐标、页面元素 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 之后必须有验证,因为“点到了”不等于“点对了”:

  1. 动作前:确认目标存在、可见、可交互;
  2. 动作后:检查预期状态变化(页面跳转、字段变化、提示出现);
  3. 失败时:区分“没点到”“点错了”“点了但没反应”,分别处理。

这三种失败的修复完全不同。没点到要调整坐标;点错了要重新消歧;点了没反应可能是权限、网络或后端问题,继续重点只会重复失败。没有验证闭环,Agent 会把所有失败都当成定位问题,陷入无效重试。

架构含义

Grounding 对架构有四个直接约束:

  1. 坐标系显式。 截图、模型输出、执行器使用同一套坐标,并带元数据。
  2. 结构优先。 能用元素引用就不用像素坐标;视觉作为兜底。
  3. 歧义要升级。 多个匹配时不要取第一个,要用上下文消歧或请求澄清。
  4. 动作要验证。 前后状态检查,区分定位失败和业务失败。

第 1 条是基础设施,第 2 条是可靠性,第 3 条是安全,第 4 条是可运维性。四条都做到,Grounding 才从“演示能跑”变成“可以上线”。

架构判据

判据合格的样子不合格的样子
坐标一致全链路同一坐标系截图与执行各算各的
元数据完整尺寸、缩放、偏移、DPR只有一张图
结构优先DOM/可访问性树定位一律用像素
歧义处理多匹配升级或消歧取第一个
动作验证前后状态检查点完就当成功

这些判据里,“元数据完整”最容易被省略。演示时截图来自固定环境,坐标恰好对;换一台机器、换一个缩放比例,整个链路就崩了。元数据是让坐标可复现的最低成本。

一个表单填写的例子

Agent 要在报销系统里填写金额并提交。流程可以是:

  1. 用可访问性树找到“金额”输入框,确认它可见且可编辑;
  2. 输入金额,读取输入框的值确认写入成功;
  3. 找到“提交”按钮,检查页面上只有一个可见的提交按钮;
  4. 点击,等待成功提示或错误信息;
  5. 如果出现校验错误,读取错误文本,回到第 1 步修正。

这个流程里,每一步都有验证点。坐标只在第 3 步的视觉兜底时使用;即使使用,也会先检查按钮的唯一性和可见性。相比“模型看一眼截图,输出一个坐标,直接点击”,这个流程慢一些,但失败可定位、可恢复。

如何评测 Grounding

评测不能只看“点没点中”,还要看:

指标含义
定位准确率预测框与目标框 IoU 达标比例
消歧准确率多候选时选对目标的比例
动作成功率点击后状态按预期变化的比例
误操作率点到非目标元素的比例
恢复率首次失败后能否纠正

定位准确率高但误操作率也高,说明消歧有问题;动作成功率高但恢复率低,说明失败处理不足。几个指标要一起看,才能定位瓶颈在感知、消歧还是执行。

小结

  • Grounding 把语言描述落到坐标或元素引用,是“理解”变成“动作”的桥梁。
  • 绝对坐标依赖分辨率和缩放;归一化坐标更稳;元素引用最可靠但依赖结构。
  • 坐标错误常来自 Retina、缩放、裁剪偏移和 letterbox,应在元数据里显式记录。
  • 优先结构定位,视觉坐标作为兜底;多匹配时升级,不要取第一个。
  • 动作前后都要验证,区分没点到、点错了和业务失败。
  • 评测要覆盖定位、消歧、动作成功和恢复,不能只看 IoU。

阅读导航:上一节:10.1 视觉/语音输入的感知误差 · 下一节:10.3 Computer Use 的安全边界 。

常见错误与边界

  1. 坐标系不统一。 截图、模型输出和执行器各用一套坐标,错误难以排查。
  2. 忽略设备像素比。 Retina 截图按 1x 计算,点击位置会偏一半。
  3. 多匹配取第一个。 同名按钮很常见,取第一个会在真实页面上点错。
  4. 点完不验证。 “点到了”不等于“点对了”,没有状态检查就无法发现误操作。
  5. 把所有失败当定位问题。 点了没反应可能是权限或后端问题,重复点击无效。
  6. 只报 IoU。 IoU 对完全不相交没有区分度,还要看中心点误差和消歧结果。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图