UI-TARS 坐标定位实战指南：从参数校准到偏差排查的完整流程

UI-TARS 坐标定位实战指南从参数校准到偏差排查的完整流程【免费下载链接】UI-TARSPioneering Automated GUI Interaction with Native Agents项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS用 UI-TARS 跑 GUI 自动化任务时最典型的坑是点击落在目标旁边模型很笃地输出一个类似 (197, 525) 的坐标实际点下去却偏了一个字符位。原因不在模型“没看见”而在于 UI-TARS 输出的坐标属于缩放后截图的坐标系需要经过一次换算才能落回真实屏幕。本文按“理解概念 → 动手配置 → 验证结果 → 排查偏差”的顺序把坐标定位这条链路走一遍。️ 从一个点偏的点击说起坐标问题出在哪一步拿 GIMP 里的一个自动化任务举例。模型看到设置面板中的“系统资源”选项输出click(pointpoint197 525/point)。如果直接拿 197、525 当屏幕像素坐标去点击位置会偏屏幕分辨率越高偏得越厉害。根源只有一句模型拿到的是经smart_resize缩放后的截图输出的坐标也是以这张缩放图为准。所以“模型坐标 → 屏幕坐标”这一步不能省绝大多数点击错位都出在这里而不是模型识别环节。 原理速览绝对坐标、相对坐标与缩放因子动手前只需要弄清三个概念绝对坐标与相对坐标Qwen2.5VL 系列model_type 传qwen25vl输出的是缩放图上的绝对像素坐标Qwen2VL 系列qwen2vl输出 0~1000 区间的相对坐标要除以缩放因子才能得到 0~1 的归一化值。缩放因子 factor相对坐标分支里使用的换算参数项目测试用例中统一传 1000。qwen25vl 的绝对坐标分支不走 factor而是直接除以缩放图的宽和高。smart_resize截图送入模型前会被调整到“宽高均可被 28 整除、总像素落在 100×28×28 到 16384×28×28 之间、尽量保持原宽高比”的尺寸。这个尺寸就是坐标换算的基准必须和实际喂给模型的一致。️ 动手实践四个动作把坐标落到屏幕上按运行环境选对提示模板codes/ui_tars/prompt.py 里定义了三套模板桌面模板COMPUTER_USE 系列动作空间含 click、drag、hotkey、type、scroll、wait 等移动端模板MOBILE_USE 系列含 long_press、press_home、press_back、open_app 等Grounding 模板GROUNDING 系列只输出一个 click 动作适合纯定位任务。结论先说模板要跟运行环境一致。桌面任务用移动端模板模型可能输出桌面环境里不存在的动作坐标再准也点不到。坐标缩放因子怎么配解析函数里的 4 个参数“模型输出 → 结构化坐标”这一步由 codes/ui_tars/action_parser.py 中的parse_action_to_structure_output完成需要留意的有 4 个参数model_typeQwen2.5VL 系列传qwen25vl函数自动走绝对坐标换算其他模型走相对坐标分支factor相对坐标分支下传 1000把模型输出的 0~1000 区间归一到 0~1origin_resized_height/origin_resized_width传原始截图的宽高函数内部会用同样的 smart_resize 规则重新算出缩放尺寸再据此换算坐标。换算结果是归一化的start_box/end_box形如 [x1, y1, x2, y2]。随后交给parsing_response_to_pyautogui_code传入真实屏幕宽高即可得到像素级的 pyautogui 点击代码。不同分辨率下的自适应设置两步映射回原图不管屏幕是什么分辨率映射都只有两步以 GIMP 的 1920×1080 截图为例new_height, new_width smart_resize(height, width) new_coordinate (int(model_x / new_width * width), int(model_y / new_height * height))这个写法的效果是同一份模型输出在 1080p、2K 或其他分辨率上都能映射回各自的原图位置不需要为每种分辨率单独写规则。用坐标可视化工具确认红点落没落对README_coordinates.md 里给了完整的可视化示例把换算后的坐标以红点画在截图上再存成新图。判断标准很直接——红点落在目标元素中心说明换算链路正确红点偏出目标边缘先检查 factor 和截图尺寸参数不要急着怀疑模型。⚠️ 排坑清单先认现象再找原因现象点击存在固定方向的偏移屏幕分辨率越大偏得越远原因传入的原图宽高和实际送进模型的截图不一致比如截图被预先缩放过、或窗口尺寸变过但参数没跟着改。 处理保证传入的宽高就是实际截图的尺寸再用可视化红点核对一次位置。现象qwen2vl 下坐标全对换到 qwen25vl 后全偏原因两类模型坐标系不同——前者输出 0~1000 相对值后者输出缩放图上的绝对像素。 处理按实际使用的模型设置 model_typeqwen25vl 分支会自动切换绝对坐标换算不再依赖 factor 的含义。现象smart_resize 抛出“宽高比必须小于 200”的错误原因截图长宽比超过上限 MAX_RATIO200常见于极细长的截屏。 处理检查截图采集逻辑常规桌面的 16:9、4:3 比例不会触发该错误。现象解析时报 “Action cant parse” 错误原因Thought / Action 的输出格式与模板要求不符例如缺少 Action: 前缀或 type 的 content 里有未转义的引号。 处理核对提示模板是否完整套用小范围验证可以直接跑 codes/tests/action_parser_test.py 里的测试用例。✅ 验证与延伸如何确认定位准确验收建议桌面、移动端、grounding 三类场景各挑一两个任务确认可视化红点都落在目标元素内即可认为解析链路可用parse_action_to_structure_output的测试用例可作为本地回归的基准断言。从整体能力看UI-TARS 在 OSWorld 基准上取得 42.5% 的成功率、ScreenSpotPro 上取得 61.6% 的坐标定位准确率高于 OpenAI CUA36.4%和 Claude 3.728%说明坐标定位在真实任务中是可依赖的能力。延伸阅读坐标换算细节看 README_coordinates.md部署流程看 README_deploy.md完整解析实现见 codes/ui_tars/action_parser.py。下一步可以做的事很具体先照着 README_coordinates.md 跑一次可视化示例确认红点落在目标元素中心再去执行真实任务——这是投入最少、见效最快的排偏方式。【免费下载链接】UI-TARSPioneering Automated GUI Interaction with Native Agents项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考