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(point='<point>197 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_type：Qwen2.5VL 系列传qwen25vl，函数自动走绝对坐标换算；其他模型走相对坐标分支；factor：相对坐标分支下传 1000，把模型输出的 0~1000 区间归一到 0~1；origin_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_type，qwen25vl 分支会自动切换绝对坐标换算，不再依赖 factor 的含义。
现象：smart_resize 抛出“宽高比必须小于 200”的错误原因：截图长宽比超过上限 MAX_RATIO=200，常见于极细长的截屏。 处理：检查截图采集逻辑；常规桌面的 16:9、4:3 比例不会触发该错误。
现象：解析时报 “Action can't 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 CUA（36.4%）和 Claude 3.7（28%），说明坐标定位在真实任务中是可依赖的能力。
延伸阅读：坐标换算细节看 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），仅供参考
