UI-TARS-desktop 1.0 模型部署指南：vLLM 本地推理与云端 API 两种方案（归档文档技术解析）

2026-09-05 19:27:49作者：庞眉杨Will

本文基于仓库中已归档的 UI-TARS 1.0 部署文档，系统讲解 UI-TARS-desktop 在 1.0 时代的模型部署两条路径：基于 HuggingFace Inference Endpoints 的云端部署，以及基于 vLLM 的本地部署。读完本文，你将掌握 vLLM 推理环境搭建、OpenAI 兼容 API 服务的启动方式、UI-TARS 模型（2B/7B/72B 各规格）的选择策略，以及模型服务与桌面应用（Settings 中的 VLM 配置项）之间的对接方式，并了解从源码层面看桌面端如何消费这些模型服务。

一、文档定位：1.0 归档部署指南的适用前提

该文档位于 docs/archive-1.0/ 目录下，文档开头即标注"This document has been archived"（已归档）。当前仓库主文档 docs/deployment.md 明确说明：UI-TARS-1.0 的部署指南已不再维护，1.0 用户应参考本归档文档，而 UI-TARS-1.5 拥有独立的最新部署指南。

因此，本文所有结论的适用前提是：你部署的是 UI-TARS 1.0 系列模型（2B/7B/72B 的 SFT 或 DPO 版本），并为旧版桌面应用（或兼容 1.0 协议的客户端）提供推理服务。

从源码结构可以印证 1.0 模型在项目中的地位：packages/ui-tars/shared/src/constants/vlm.ts 中定义了 UITarsModelVersion 枚举，V1_0 = '1.0' 与 V1_5 = '1.5' 并存，同时为不同版本模型保留了独立的图像像素上限（MAX_PIXELS_V1_0 与 MAX_PIXELS_V1_5）。这说明 1.0 模型的输入处理参数在代码中至今单独维护，理解这些参数对部署 1.0 模型至关重要（后文详述）。

桌面端对模型提供方（Provider）的抽象也保留在 apps/ui-tars/src/main/store/types.ts 中：

VlmProvider 枚举提供了 Huggingface = 'Hugging Face' 与 vLLM = 'vLLM' 两个取值——正好对应本文的两条部署路径（云部署走 Hugging Face、本地部署走 vLLM）。值得注意的是，该枚举中 Ollama = 'ollama' 一项被注释掉了，表明 Ollama 仅作为文档层面的备选提及，并非桌面端一等公民；
VLMProviderV2 枚举则进一步细分了云端提供方，包括 ui_tars_1_0 = 'Hugging Face for UI-TARS-1.0'、ui_tars_1_5 = 'Hugging Face for UI-TARS-1.5' 以及火山引擎方舟上的豆包视觉模型。这可以推断出：1.0 时代官方推荐的云端模型托管在 Hugging Face，桌面应用按"提供方 + 模型版本"组合来识别服务来源。

二、模型选型：GGUF 降级公告与 SFT/DPO 规格选择

原部署文档开篇即有一条重要公告：GGUF 量化版模型经过量化后性能无法保证，官方决定对其降级。推荐的替代方案只有两条路：

云端部署（HuggingFace Inference Endpoints）——适合没有 GPU 的用户；
本地 vLLM 部署——适合拥有足够 GPU 显存资源的用户。

本地模型方面，官方在 Hugging Face（bytedance-research 组织）上提供了五个规格：

模型	规格定位
2B-SFT	轻量级，显存需求最低
7B-SFT	中等规模，监督微调版
7B-DPO	中等规模，DPO 对齐版（官方推荐）
72B-SFT	旗舰规模，监督微调版
72B-DPO	旗舰规模，DPO 对齐版（官方推荐）

官方建议：在硬件允许的前提下，优先选择 7B-DPO 或 72B-DPO 以获得最佳性能。DPO（Direct Preference Optimization）版本相比 SFT 版本经过偏好对齐，在 GUI Agent 场景中的动作决策质量通常更好——这也是文档将其列为推荐选项的原因。

从源码结构看，1.0 模型对输入图像有明确的像素上限约束：packages/ui-tars/shared/src/constants/vlm.ts 中定义 IMAGE_FACTOR = 28（视觉编码器的 patch 粒度），MAX_PIXELS_V1_0 = 2700 * IMAGE_FACTOR * IMAGE_FACTOR，即 1.0 模型单图像素上限约为 2700 × 28 × 28（约 211 万像素），而 1.5 模型（MAX_PIXELS_V1_5 = 16384 * IMAGE_FACTOR * IMAGE_FACTOR）上限高得多。这意味着：部署 1.0 模型时，桌面端会按 1.0 的像素上限裁剪/缩放截图后再送推理，部署者无需（也无法）自行放大输入分辨率，模型服务只需如实按 OpenAI 兼容协议处理传入图像即可。

三、云端部署：HuggingFace Inference Endpoints

原文档的云端部署部分非常简洁：官方推荐使用 HuggingFace Inference Endpoints 进行快速部署，并分别提供了英文版与中文版的《GUI 模型部署教程》（文档中以外部链接形式给出）。核心流程可以概括为：

在 Hugging Face 控制台创建 Inference Endpoint，选择 UI-TARS 1.0 对应模型；
指定推理实例的 GPU 规格并完成部署；
部署完成后获得一个 OpenAI 兼容的 API 端点（Base URL + API Key）；
将该端点填入 UI-TARS 桌面应用的模型设置（见第五节）。

云端部署的关键优势在于：无需本地 GPU，部署时间短，且端点天然兼容 OpenAI API 协议——这正是桌面端"VLM Base Url 必须是 OpenAI 兼容端点"这一要求（见第五节说明）的来源。

四、本地部署：基于 vLLM 的完整操作流程

这是本文档最核心的实操部分。官方要求 vllm >= 0.6.1，并以 0.6.6 版本为例给出安装命令。

4.1 准备推理环境

原档给出的安装脚本（依赖 PyTorch 的 CUDA wheel 索引指定 cu124 版本）：

pip install -U transformers
VLLM_VERSION=0.6.6
CUDA_VERSION=cu124
pip install vllm==${VLLM_VERSION} --extra-index-url https://download.pytorch.org/whl/${CUDA_VERSION}

参数说明：

transformers：负责模型配置加载与 tokenizer；
vllm==${VLLM_VERSION}：固定到 0.6.6，满足文档">=0.6.1"的下限要求，锁定版本可避免不同小版本间的行为漂移；
--extra-index-url：从 PyTorch 官方 wheel 索引额外拉取与 cu124（CUDA 12.4）匹配的构建，确保 GPU 运行时与驱动版本匹配。若你的环境是其他 CUDA 大版本，需要相应调整 CUDA_VERSION 取值。

4.2 下载模型

从 Hugging Face 上下载第二节所列五个规格之一的模型权重（2B-SFT / 7B-SFT / 7B-DPO / 72B-SFT / 72B-DPO）到本地，得到模型目录路径 <path to your model>。显存参考：7B 模型需单卡中等显存即可，72B 模型则需要多卡或大显存配置——这也解释了为什么文档要求你"based on your hardware configuration"（基于自身硬件配置）在 7B 与 72B 之间取舍。

4.3 启动 OpenAI 兼容 API 服务

模型下载完成后，执行以下命令启动服务：

python -m vllm.entrypoints.openai.api_server --served-model-name ui-tars --model <path to your model>

关键参数：

vllm.entrypoints.openai.api_server：vLLM 内置的 OpenAI 兼容服务入口，暴露与 OpenAI Chat Completions 一致的接口（默认监听 http://localhost:8000）；
--served-model-name ui-tars：服务对外暴露的模型名。桌面端在调用该服务时以这个名字作为 model 字段值，因此必须与后续在应用设置中填写的 "VLM Model Name" 保持一致（都填 ui-tars）；
--model：指向本地模型权重目录。

启动后，该服务即成为桌面应用 VLM 设置中的一个"本地 OpenAI 兼容端点"，Base URL 通常形如 http://localhost:8000/v1。

五、将模型服务接入 UI-TARS 桌面应用

服务就绪后，在桌面应用的 Settings（模型配置页）中填入 API 信息。原文档此处配有一张设置截图（即文首图片，见 docs/archive-1.0/images/settings_model.png），需要填写的核心字段为：

VLM Provider：模型提供方。按 apps/ui-tars/src/main/store/types.ts 中 VlmProvider 枚举的定义，可选 Hugging Face（云端部署）或 vLLM（本地部署）；
VLM Base Url：OpenAI 兼容 API 端点地址。云端部署填 Inference Endpoint 的地址，本地部署填 http://localhost:8000/v1 这类地址；
VLM API Key：端点的鉴权密钥（本地 vLLM 服务可任意填写占位值）；
VLM Model Name：与 --served-model-name 一致的模型名，例如 ui-tars。

文档同时给出了一条重要 Note：VLM Base Url 必须是 OpenAI 兼容的 API 端点（协议细节参考 OpenAI 官方 vision 指南中 base-64 图像编码的部分）。这从两个方向约束了部署者：

自建的推理服务必须实现 Chat Completions 协议，vLLM 的 openai.api_server 正是为此而设计；
图像以 base-64 编码内嵌于请求体传输，因此高帧率 Agent 循环下的网络吞吐会成为实际瓶颈——云端部署时 Endpoint 的就近部署、本地部署时的局域网/回环地址都优于公网链路。

此外，文档源码中还保留了一段被注释掉的 Ollama 备选配置：

VLM Provider: ollama
VLM Base Url: http://localhost:11434/v1
VLM API Key: api_key
VLM Model Name: ui-tars

这提示：任何能暴露 OpenAI 兼容 /v1 端点的推理框架（包括 Ollama）理论上都可接入。但结合 VlmProvider 枚举中 Ollama 被注释这一事实可以推断，Ollama 路径在当时的桌面版本中并未作为正式选项提供，仅作原理性参考。

六、源码纵深：桌面端如何消费 1.0 模型服务

结合仓库源码，可以补充说明部署完成后应用侧的行为细节，帮助你判断"部署是否真的生效"：

Agent/Chat 双模式：packages/ui-tars/shared/src/constants/vlm.ts 定义了 VlmModeEnum（Chat = 'chat' 与 Agent = 'agent'）。同一个部署好的端点既可作为通用视觉模型被 Chat 模式调用，也可被 Agent 循环以"截图 → 推理 → 动作"的方式高频调用；
动作解析：Agent 模式下单次推理产出的动作由 packages/ui-tars/action-parser/src/actionParser.ts 解析，其 UITarsModelVersion 参数决定了按哪个版本的输出格式解析动作。1.0 模型部署后，客户端需以 1.0 版本标识与之配对，格式才能正确匹配；
循环与图像预算：同文件中的 MAX_LOOP_COUNT = 100（单任务最大 Agent 步数）、MAX_IMAGE_LENGTH = 5（会话中保留的历史截图数量上限）、MAX_PIXELS_V1_0（1.0 图像像素上限）共同定义了客户端发送给模型服务的请求形态。部署者据此可以评估端点的吞吐需求：一次 Agent 循环会稳定产生包含 1~5 张（已被裁剪至 1.0 像素上限的）base-64 图像的请求；
调用链路：桌面端主进程经由 IPC 与 SDK 组织请求，模型配置（Base URL、Key、Model Name）存储在主进程状态中，apps/ui-tars/src/main/store/types.ts 的 VlmProvider / VLMProviderV2 即该状态的一部分。若 API Key 或端点填写错误，任务会在首次模型调用时失败，排查时应先确认 curl 该端点（以 Chat Completions 请求）是否正常返回。

七、注意事项与现状

GGUF 版本不推荐使用：量化导致性能不可控，官方已对其降级；
vLLM 版本下限：文档要求 vllm >= 0.6.1，示例锁定 0.6.6 / CUDA 12.4；
端点协议约束：必须是 OpenAI 兼容端点，--served-model-name 与应用中的 Model Name 必须一致；
文档已归档：UI-TARS 1.5 已发布并带来显著改进，新的部署方式请以 docs/deployment.md 中指引的 1.5 官方部署指南为准。本文内容仅作为 1.0 模型部署与理解其端点协议的历史参考，其中的安装命令、模型清单与设置字段均忠实继承自归档原文。

参考文件：