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

UI-TARS-desktop 1.0 模型部署指南vLLM 本地推理与云端 API 两种方案归档文档技术解析【免费下载链接】UI-TARS-desktopThe Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop本文基于仓库中已归档的 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 Facebytedance-research 组织上提供了五个规格模型规格定位2B-SFT轻量级显存需求最低7B-SFT中等规模监督微调版7B-DPO中等规模DPO 对齐版官方推荐72B-SFT旗舰规模监督微调版72B-DPO旗舰规模DPO 对齐版官方推荐官方建议在硬件允许的前提下优先选择 7B-DPO 或 72B-DPO 以获得最佳性能。DPODirect 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_VERSION0.6.6 CUDA_VERSIONcu124 pip install vllm${VLLM_VERSION} --extra-index-url https://download.pytorch.org/whl/${CUDA_VERSION}参数说明transformers负责模型配置加载与 tokenizervllm${VLLM_VERSION}固定到 0.6.6满足文档0.6.1的下限要求锁定版本可避免不同小版本间的行为漂移--extra-index-url从 PyTorch 官方 wheel 索引额外拉取与cu124CUDA 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_servervLLM 内置的 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 UrlOpenAI 兼容 API 端点地址。云端部署填 Inference Endpoint 的地址本地部署填http://localhost:8000/v1这类地址VLM API Key端点的鉴权密钥本地 vLLM 服务可任意填写占位值VLM Model Name与--served-model-name一致的模型名例如ui-tars。文档同时给出了一条重要NoteVLM 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 定义了VlmModeEnumChat 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_01.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 模型部署与理解其端点协议的历史参考其中的安装命令、模型清单与设置字段均忠实继承自归档原文。参考文件原文档docs/archive-1.0/deployment.md设置截图docs/archive-1.0/images/settings_model.png当前部署指引docs/deployment.mdProvider 枚举apps/ui-tars/src/main/store/types.tsVLM 常量与像素上限packages/ui-tars/shared/src/constants/vlm.ts动作解析器packages/ui-tars/action-parser/src/actionParser.ts【免费下载链接】UI-TARS-desktopThe Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS-desktop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考