UI-TARS 本地部署与推理实战：从截图到脚本一次跑通-育师

UI-TARS 本地部署与推理实战：从截图到脚本一次跑通

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

云端推理服务排队时，一次 GUI 操作指令往往要等好几秒。UI-TARS 本地部署把视觉语言模型的截图理解与脚本生成搬回本机，UI-TARS 本地推理从此不依赖外网。本文基于仓库codes/目录，走通环境搭建、权重准备、坐标转换到 pyautogui 脚本生成的完整链路，全程以最小可运行示例为主。

上图给出 UI-TARS 的闭环：模型观察截图，输出 Thought 与 Action，再由执行端落回界面。下面按"先跑通、再讲清"的顺序拆成四步。

三分钟跑通环境：克隆与依赖安装

先确认硬件与软件基线。CPU 侧建议 8GB 内存起步，接了支持 CUDA 的 NVIDIA 显卡能明显缩短单轮推理时间；软件侧需要 Python 3.10+、Git，以及 pip 或 uv 任一。

git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS cd UI-TARS/codes pip install . uv run python -m unittest discover tests

最后一条是仓库自带的解析单元测试，专门验证 codes/ui_tars/action_parser.py 里坐标解析与代码生成这两条链路是否可用。

实践小贴士：先让这条测试绿了，再去接真实模型输出。环境有问题时，测试脚本能比主流程更快把原因暴露出来。

模型权重准备与首次本地推理验证

模型权重不在仓库里，需自行从模型平台下载，放到一个本地目录，例如codes/models/（该目录需手动创建）。这里仓库只读，权重与截图都放在工作区，不动仓库内文件。

验证"能不能跑"，不必等真实模型。仓库data/下有一张现成的桌面截图，配合一条写死的模型输出，就能走完一次本地推理的解析侧：

uv run python codes/tests/inference_test.py

该脚本会打印缩放前后的尺寸，并画出一张带红点的结果图。红点落在哪里，代表模型坐标还原后真正会点的位置。

坐标偏移的 3 个排查点与缩放原理

坐标偏移几乎都出在这三处，先记住再动手：一是原图尺寸拿错了，二是喂给模型的缩放后尺寸（origin_resized_height/width）与实际不一致，三是factor与模型训练时的取值对不上。

原理上，smart_resize会把图像缩到"两边都是 28 的整数倍、且总像素落在100*28*28到16384*28*28区间"的尺寸，返回(新高, 新宽)。模型是在这张缩放图上出坐标的，所以要还原，就必须知道这张图的尺寸。

from PIL import Image from ui_tars.action_parser import smart_resize, parse_action_to_structure_output shot = Image.open("data/coordinate_process_image.png") orig_w, orig_h = shot.size new_h, new_w = smart_resize(orig_h, orig_w) # 对齐 28 的倍数 resp = "Thought: 点击设置\nAction: click(start_box='(197,525)')" out = parse_action_to_structure_output( resp, factor=1000, origin_resized_height=new_h, origin_resized_width=new_w, model_type="qwen25vl") print(out[0]["action_inputs"]["start_box"]) # 得到 0~1 相对坐标

model_type="qwen25vl"时，模型给的是缩放图上的绝对像素，函数内部用它除以new_h/new_w归一到 0~1；换成qwen2vl这类相对坐标模型，则改用factor（常取 1000）去缩放。两条路径最终都收敛到同一份 0~1 的相对坐标，这是后面任意分辨率都能复用的关键。

把模型输出转成 pyautogui 可执行代码

拿到 0~1 坐标后，parsing_response_to_pyautogui_code负责乘回当前截图的image_width/image_height，并映射成click、type、drag、hotkey等具体调用：

from ui_tars.action_parser import parsing_response_to_pyautogui_code script = parsing_response_to_pyautogui_code( responses=out, image_height=orig_h, image_width=orig_w, ) print(script) # 输出形如： # pyautogui.click(x=..., y=..., button='left')

把打印结果另存为.py文件即可执行。点击、输入、拖拽、快捷键这些分支都已内置，想确认边界行为时，可对照 codes/tests/action_parser_test.py 里的三个用例，它分别覆盖parse_action、结构化解析与代码生成。