企业官网建设流程全解析

UI-TARS 点击总是偏一点：坐标定位链路排查与验证方法

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

UI-TARS 是字节跳动开源的多模态 GUI 智能体，适合桌面与移动端界面自动化。模型说"点击哪里"通常不难，难的是把模型给的坐标准确落到真实屏幕上。本文以一次点击任务为主线，讲清 UI-TARS 坐标从模型输出到屏幕像素的转换链路，并给出可逐项核对的检查项和验证办法。

一次没点中的操作说明了什么

先设想一个常见场景：让 UI-TARS 在 GIMP 里打开"系统资源"面板，模型输出了click(start_box='(197,525)')，指令也执行了，但鼠标落在了旁边。问题往往不在"模型看错了"，而在坐标的参照系：模型看到的截图在送入前被smart_resize按 28 的因子调整过尺寸，它输出的数字对应的是调整后的图，而执行点击时用的是原始屏幕尺寸。两套坐标之间隔了一次缩放，再叠加系统显示缩放、宽高参数传错，点位自然偏移。

所以排查顺序应该是：先确认坐标在哪一层被转换，再逐层核对参数，最后画点验证，而不是反复调模型。

从截图到鼠标动作的完整链路

UI-TARS 的交互闭环：用户指令经模型产生 Thought 与 Action，由 PyAutoGUI 执行后回到 Observation，形成循环

一次点击要经过四步，每步都发生在 codes/ui_tars/action_parser.py 中：

1. 截图缩放：smart_resize把原始截图（如 1920×1080）缩放到宽高都能被 28 整除、总像素落在 [min_pixels, max_pixels] 区间内的尺寸，且尽量保持宽高比。
2. 模型输出坐标：Qwen2.5VL 系列输出的是"调整后图像上的绝对坐标"；Qwen2VL 系列输出的是按 factor=1000 归一化的相对坐标。两者走不同的换算分支。
3. 解析为归一化框：parse_action_to_structure_output把模型文本里的point/start_box统一解析成 0~1 之间的 [x1, y1, x2, y2]。
4. 还原为像素：parsing_response_to_pyautogui_code用归一化值乘以截图的image_width/image_height，生成最终的 pyautogui 调用。

理解这四点后，"点偏了"就能定位到具体环节：偏移方向固定多半出在第 1、2 步的尺寸或模型类型上，偏移忽大忽小多半出在第 3 步的解析上。

5 个可直接执行的检查项

检查 1：model_type 与真实模型是否一致

parse_action_to_structure_output的model_type决定走哪条换算分支：qwen25vl走绝对坐标除以 smart_resize 尺寸，其他走除以 factor。用 7B 的 2.5VL 模型却传了别的类型，换算分母会差一个量级。确认方式：打印解析结果里的start_box，若数值明显小于 1 且远小于真实位置比例，基本就是分支用错了。

检查 2：origin_resized 宽高是否等于真实截图尺寸

调用解析函数时：

parsed = parse_action_to_structure_output( response, factor=1000, origin_resized_height=1080, origin_resized_width=1920, model_type="qwen25vl")

其中两个 origin 参数必须来自实际截屏文件的img.size，而不是显示器的"显示分辨率"。确认方式：在截屏后打印一次尺寸，与传参逐项比对。

检查 3：系统显示缩放是否吃掉了坐标

Windows 125%/150% 或 macOS 缩放下，截图的像素尺寸与"逻辑分辨率"不一致，点击 API 又按逻辑坐标计算，会造成整体偏移。处理办法：以截图文件的像素尺寸为准参与换算，并让执行端使用同一坐标系。

检查 4：提示模板是否与运行平台匹配

codes/ui_tars/prompt.py 提供三套模板：COMPUTER_USE面向桌面，MOBILE_USE面向手机与安卓模拟器（多了长按、返回、打开应用等动作），GROUNDING只输出动作、不带思考。桌面任务用了移动端模板，动作空间不一致会导致输出格式漂移。确认方式：检查模板名与目标环境一一对应。

检查 5：用仓库自带测试锁住解析行为

codes/tests/action_parser_test.py 里有对click(point='<point>200 300</point>')这类输出的解析断言。本地改动过解析相关代码后，跑一遍python -m unittest，确认action_type与start_box的断言仍然通过，可以把"解析逻辑被意外改坏"这类问题提前拦住。

如何验证：把预测点画回截图上

最直接的验证是可视化。README_coordinates.md 里给出了完整示例：对data/coordinate_process_image.png（1920×1080 的 GIMP 界面），模型输出坐标 (197, 525)，先算出模型实际看到的尺寸，再按比例映射回原图：

new_h, new_w = smart_resize(1080, 1920) # 模型"看到"的尺寸 x = 197 / new_w * 1920 # 映射回原始宽度 y = 525 / new_h * 1080 # 映射回原始高度

映射结果标回截图：

原始截图：模型需要将"系统资源"选项定位到红点附近

换算后画回截图的点击点，红点即最终落点

若红点落在目标元素上，链路正确；落在附近但系统性偏一点，重点复查检查 2、3；落点完全跑偏，重点复查检查 1。

常见偏差速查

• 整体平移一个固定比例：多为显示缩放（检查 3），换算与执行不在同一坐标系。
• 偏移量与坐标位置成正比，越靠边缘偏越多：smart_resize触发了 max_pixels 上限，模型看到的图比预期更小，核对 min/max pixels 参数是否与推理端一致。
• 横竖方向只偏其一：宽高参数互换，origin_resized_height传成了宽度，这类错误测试用例很难覆盖，打印一次实际值最快。
• 动作类型解析成功但坐标为空：模型输出的动作写法（point=与start_box=）与预期模板不符，先对照提示模板再定位解析逻辑。

🔧 建议下一步：先按检查 2 打印一次"截图真实尺寸 vs 传参尺寸"，再跑一遍可视化画点。这两步花不了十分钟，却能覆盖绝大多数点击偏移问题；确认链路无误后，再考虑模型层面的优化。

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