UI-TARS: 如何让点击精准落地——坐标定位调试完整指南

UI-TARS: 如何让点击精准落地——坐标定位调试完整指南【免费下载链接】UI-TARSPioneering Automated GUI Interaction with Native Agents项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARSUI-TARS 是一个靠看截图就能完成点击、输入、拖拽的多模态 GUI 智能体。真实部署中最让人头疼的失败往往是坐标定位差之毫厘、点击尽失。本文带你弄清模型输出的坐标是怎么映射回真实屏幕的原理、验证方法、常见坑位全部可照做。原理篇模型输出的坐标为什么不能直接用模型看屏幕时看到的其实是一张被压缩过的图。原始截图比如 1920x1080 的桌面画面会先经过 codes/ui_tars/action_parser.py 里的smart_resize再送入模型。这个函数做三件事让宽高都能被IMAGE_FACTOR值为 28整除、把总像素数压进MIN_PIXELS100×28×28到MAX_PIXELS16384×28×28之间、并尽量保持宽高比不变。所以模型给出的 (x, y) 活在缩放后图像的坐标系里不是屏幕真实像素。想拿到最终点击位置必须把缩放反推回去。codes/tests/inference_test.py 里的核心两行就是这件事new_coordinate ( int(model_output_width / new_width * width), int(model_output_height / new_height * height), )其中new_width/new_height是缩放后尺寸width/height是原始截图尺寸。还有一层细节model_typeqwen25vl的模型输出绝对像素坐标parse_action_to_structure_output会除以smart_resize的结果归一化qwen2vl 系模型输出的是以factor常取 1000为基准的相对坐标。两条分支最终都得到 0~1 的相对坐标之后再乘以截图尺寸才是鼠标真正落下的位置。方法篇三个环节把点击拉回目标参数配置环节三个坐标相关参数怎么传factor相对坐标的除数。qwen2vl 系模型传 1000qwen25vl 不参与该除法但函数签名要求必须给值。origin_resized_height/origin_resized_width截图的真实像素尺寸。用 PIL 的img.size读取并程序化传入别手填。model_type决定走绝对坐标分支还是相对坐标分支必须与你实际部署的模型一致。完整的调用示例见 codes/README.md。调试验证环节如何验证坐标解析是否正确最快的验证方式是打点看。仓库自带的 codes/tests/inference_test.py 做了完整闭环smart_resize求缩放后尺寸 → 反推原始像素坐标 → 用plt.scatter在截图上画一个红点。判断标准只有一条红点落在目标控件的中央。跑真实业务前建议先执行 codes/tests/action_parser_test.py确认解析逻辑的单元测试通过。跨分辨率环节换机器时如何自适应smart_resize会自动处理任意分辨率前提是宽高比不超过MAX_RATIO200因此你不需要为每台设备单独写配置文件。真正需要盯住的是系统显示缩放一块 4K 屏开了 200% 缩放截图抓到的就是缩放后的像素只要截图像素 → 缩放 → 换回截图像素这条链全程自洽直接传截图尺寸即可。建议在每次运行时打印原始尺寸、缩放后尺寸、最终点击坐标三元组出偏差时一眼能定位是哪一环错位。实操篇用仓库自带截图复现坐标定位红点验证场景GIMP 偏好设置界面模拟模型输出click(start_box(197,525))验证红点是否落在左侧菜单的System Resources一项上。准备输入截图用仓库里的data/coordinate_process_image.png1920x1080模型输出文本参考 README_coordinates.md 中的示例格式。运行示例脚本在仓库根目录执行python codes/tests/inference_test.py它会打印原始分辨率与smart_resize得到的缩放后尺寸。读取映射结果输出的new_coordinate就是换算到原始像素系的最终点击坐标。保存可视化脚本用plt.savefig导出带红点的图请把保存路径改成临时文件不要写进仓库目录。目检判定红点落在System Resources条目上即链路正确。此后真实模型的每一步输出都过同一流程回归点击错位率会立刻可见。避坑篇三种典型偏移现象现象点击严重偏移甚至落到窗口外原因origin_resized_height/origin_resized_width与实际截图尺寸不符最常见的是高宽传反或误传了屏幕物理分辨率。 解决一律从截图文件用img.size读取后程序化传入不要手抄。现象单元测试通过真机执行却偏原因系统显示缩放使截图像素与鼠标物理坐标不在同一坐标系。 解决整条链路只认截图像素计算中不要混入操作系统的物理像素。现象更换模型系列后点击位置跳变原因绝对坐标与相对坐标两套坐标系混用——model_typeqwen25vl分支除以smart_resize结果其他分支除以factor。 解决model_type参数与实际部署的模型保持严格一致别从旧项目里照抄参数。模型看的是缩小版截图你的工作是把坐标换回真实屏幕参数、坐标系、验证三件事缺一不可红点验证一通坐标定位就不再是玄学。坐标处理官方教程README_coordinates.md核心实现smart_resize与parse_action_to_structure_outputcodes/ui_tars/action_parser.py红点可视化示例脚本codes/tests/inference_test.pyui-tars Python 包快速上手codes/README.md【免费下载链接】UI-TARSPioneering Automated GUI Interaction with Native Agents项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考