UI-TARS 1.5 vLLM 部署指南：从零跑通到稳定生产的三个台阶

UI-TARS 1.5 vLLM 部署指南：从零跑通到稳定生产的三个台阶

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

第一次部署 GUI 智能体模型，最常碰上的两个坑：服务起不来，以及模型点出来的坐标对不上界面。UI-TARS 1.5 是一个接收屏幕截图、输出可执行 UI 操作（点击、输入等）的 GUI 自动化智能体模型。如果你有一块 CUDA 显卡和 24GB 以上显存，本文将以 vLLM 为推理引擎，带你用三个阶段完成 UI-TARS vLLM 部署：跑起来、跑得快、跑得稳。

🔧 跑起来：UI-TARS 1.5 推理服务启动的最短路径

环境确认只要四条，先过一遍再动手：

• Python ≥ 3.10（项目声明的最低版本）
• CUDA 11.8+；vLLM 需选择官方支持 Qwen2.5-VL 架构（UI-TARS 1.5 底座）的版本，安装前核对对应版本的支持列表
• 单卡 24GB+ 显存更稳妥（如 RTX 4090、A10）；云上 L40S、A100 均可
• 安装 git-lfs 与 huggingface-cli，用于拉取模型权重

下面一条命令链完成克隆、装包与权重下载：

git clone https://gitcode.com/GitHub_Trending/ui/UI-TARS cd UI-TARS && pip install ui-tars huggingface-cli download ByteDance-Seed/UI-TARS-1.5-7B \ --local-dir ./models/UI-TARS-1.5-7B

权重就位后，用 vllm serve 启动 OpenAI 兼容推理服务：

vllm serve ./models/UI-TARS-1.5-7B \ --served-model-name uitars \ --gpu-memory-utilization 0.9 \ --max-num-batched-tokens 8192 \ --limit-mm-per-prompt image=1 \ --port 8000

核心启动参数说明：

最后验证服务已就绪：

curl -s http://localhost:8000/v1/models

返回包含 uitars 的 JSON 即成功。请求体格式可参考仓库示例 data/test_messages.json。

⚙️ 核心机制：UI-TARS vLLM 坐标解析是怎么工作的

这一节不是操作步骤，但理解这条链路，你才能解释"为什么坐标会偏"。

模型输出是固定两段式：Thought（思考）加 Action（操作），例如Action: click(start_box='(197,525)')。关键点：这个坐标定义在缩放后的图像坐标系上，不是你的原图。

缩放发生在图像入模前，由 smart_resize 完成，它同时满足三条约束：宽高均能被 28（视觉 patch 因子）整除、总像素落在 [100×28², 16384×28²] 区间、保持长宽比；长宽比超过 200:1 直接报错。实现在 action_parser.py。

模型输出的 (197,525) 为什么落在原图上会是另一个位置？因为图像被缩放过，需要按"原始尺寸 / 缩放后尺寸"对每个坐标轴分别反乘，才能映射回原图。inference_test.py 就是这条校准链路的完整示例。

下图展示了坐标解析的直观效果：红点是坐标缩回原图后落在原始截图上的位置。

最后一环是后处理：parse_action_to_structure_output把不同 VLM 的输出格式（Qwen 的<point>标签、Seed 的 bbox 等）统一为结构化动作，parsing_response_to_pyautogui_code再生成可执行的 pyautogui 脚本：

from ui_tars.action_parser import parse_action_to_structure_output parsed = parse_action_to_structure_output( response, factor=1000, origin_resized_height=1080, origin_resized_width=1920, model_type="qwen25vl")

任务指令同样影响输出稳定性，prompt.py 为桌面与移动环境提供了不同模板，切换环境时记得对应更换。

⚡ 跑得快：UI-TARS vLLM 显存优化的三个主旋钮

AWQ 4bit 量化：先砍显存

量化的作用是用少量精度换大量显存，把 7B 权重的占用从约 15GB 压到 5GB 量级，给 KV 缓存让出空间。设置上在启动参数加--quantization awq（需对应 AWQ 权重量化版本），GPTQ 同理。注意：量化权重上线前，先用若干真实 GUI 任务回归一次，确认坐标解析偏差可接受再切换。

KV 缓存：定好 gpu-memory-utilization 与 swap-space

剩余显存基本都交给 KV 缓存，--gpu-memory-utilization 0.9表示允许 vLLM 用满 90% 的卡。并发峰值高时追加--swap-space 16（GB），调度器会把被抢占的请求换出到 CPU，用少量延迟换请求不被拒。注意：这个值别超过 0.9，再高容易在峰值时触发 CUDA OOM。

批处理：调 max-num-batched-tokens 与并发

该参数决定单轮调度能合并多少 prefill 令牌。截图加指令越长，越需要调大：从 8192 起步，出现排队再加到 16384。注意观察 P99 延迟，调大后若明显抬升就该回退——批处理吞吐是以单请求延迟为代价换来的。

三者叠加后的量级参考（单卡 L40S，以 FP16 为基线，实测值随机器不同）：

以上为量级参考，请以本机压测为准。

🛡️ 跑得稳：常见 vLLM 报错排查与生产监控

排查按"现象 → 原因 → 处理"对号入座：

• 启动即 CUDA out of memory → 显存比例过高或权重未完全载入 → 降到 0.85，仍失败则调小 --max-num-batched-tokens
• 点击坐标偏移超过 10px → 请求端与后处理端缩放参数不一致 → 统一 factor 与像素上下限，跑一次 calibration 脚本核对
• 大图请求 413 或超时 → base64 payload 过大 → 先压缩截图，或调低 max_pixels
• 输出缺 Action 行、解析失败 → 采样未固定 → temperature 设 0，按环境选对 prompt 模板
• 首个请求异常慢 → 权重冷加载与 CUDA graph 捕获 → 服务启动后先发一次预热请求

生产环境至少加一层负载均衡与监控：

监控看三个数：P99 推理延迟、请求队列长度、坐标解析成功率（响应中能被正常 parse 的比例）。第三个数一旦下滑，多半是 prompt 或输入格式被动过，先于用户投诉把它揪出来。

下一步

到这里三个阶段闭环：服务起来了，坐标链路清楚了，性能与稳定性都在可控区间。

• 修改任何缩放参数前，先读 action_parser.py 的完整实现，并用 inference_test.py 验证坐标链路
• 需要自定义任务指令时，从 prompt.py 的模板出发改写
• 云端部署（如 Hugging Face Endpoint）的参考配置见 README_deploy.md

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