小白必看！UI-TARS-desktop保姆级安装教程，轻松实现自然语言控制电脑
1. 章节名称
1.1 关于 UI-TARS-desktop
UI-TARS-desktop 是一个基于视觉语言模型（Vision-Language Model, VLM）的 GUI Agent 应用程序，旨在通过自然语言指令实现对计算机的智能控制。该应用内置了 Qwen3-4B-Instruct-2507 模型，并结合 vLLM 推理框架，提供轻量级、高性能的本地化 AI 代理服务。
其核心能力包括： -自然语言理解：用户可通过中文或英文输入指令，如“打开浏览器搜索天气”。 -视觉识别与交互：自动截屏分析当前界面元素，精准定位按钮、输入框等控件。 -自动化操作：支持模拟鼠标点击、键盘输入、窗口管理等系统级操作。 -多工具集成：内置 Search、Browser、File、Command 等常用工具模块，扩展性强。 -完全本地运行：所有数据处理均在本地完成，保障隐私安全。
项目开源地址：https://github.com/bytedance/UI-TARS-desktop
相关资源链接： - 📑 论文地址 - 🤗 Hugging Face 模型页 - 🤖 ModelScope 模型页
重要提示：本镜像已预装
Qwen3-4B-Instruct-2507模型并配置好 vLLM 服务，无需手动下载模型或安装依赖，开箱即用。
1.2 核心功能展示
| 使用场景 | 操作示例 | 视频演示 |
|---|---|---|
| 查询天气 | “请帮我查看旧金山现在的天气情况” | new_mac_action_weather.mp4 |
| 发送推文 | “发送一条内容为‘你好，世界’的推特” | new_send_twitter_windows.mp4 |
1.3 技术架构概览
UI-TARS-desktop 的整体架构分为三层：
前端层（UI）
提供图形化操作界面，接收用户自然语言输入，显示执行状态和反馈结果。推理服务层（vLLM + Qwen3-4B）
运行在本地的高性能 LLM 推理引擎，负责将自然语言解析为结构化动作指令。操作系统交互层（Agent Core）
调用系统 API 实现截图、OCR、鼠标控制、键盘模拟等功能，完成真实操作。
[用户输入] ↓ [UI-TARS-desktop 前端] ↓ [vLLM 推理服务 → Qwen3-4B-Instruct] ↓ [GUI Agent 执行器 → 截图 + 控件识别 + 操作模拟] ↓ [实际系统响应]2. 验证模型服务是否正常启动
由于本镜像已预配置好环境，您只需验证模型服务是否成功运行即可。
2.1 进入工作目录
cd /root/workspace此目录包含启动脚本、日志文件及模型服务配置。
2.2 查看模型服务日志
执行以下命令查看 vLLM 启动日志：
cat llm.log正常输出示例：
INFO: Started server process [12345] INFO: Uvicorn running on http://0.0.0.0:8000 INFO: OpenAPI schema available at http://0.0.0.0:8000/docs INFO: Model 'qwen3-4b-instruct-2507' loaded successfully using vLLM engine.若出现上述信息，说明模型服务已在http://0.0.0.0:8000成功启动，并对外提供 OpenAI 兼容接口。
注意：该服务默认监听 8000 端口，且允许跨域访问，可供前端直接调用。
3. 启动并使用 UI-TARS-desktop 前端界面
3.1 打开前端应用
在浏览器中访问以下地址：
http://localhost:3000或根据部署环境填写对应 IP 地址：
http://<your-server-ip>:3000页面加载后将显示如下主界面：
可视化效果如下：
3.2 配置模型服务地址
首次使用需设置后端 API 地址：
- 点击右上角齿轮图标进入「Settings」页面。
- 在Model Settings区域填写：
- VLM Base URL:
http://localhost:8000/v1 - Model Name:
ui-tars
注意：此处使用的
/v1是 vLLM 提供的 OpenAI 兼容接口路径。
保存设置后，前端会自动测试连接状态。若显示绿色勾选标志，则表示连接成功。
3.3 测试自然语言控制功能
现在可以尝试输入第一条指令：
打开终端并执行命令 ls -l观察以下行为： - 系统自动识别当前桌面环境 - 模拟快捷键打开终端（如 Ctrl+Alt+T 或 Command+Space） - 输入ls -l并回车执行 - 显示命令输出结果
如果整个流程顺利完成，恭喜您已成功部署并运行 UI-TARS-desktop！
4. 常见问题与解决方案
4.1 模型服务未启动
现象：访问http://localhost:8000失败，llm.log文件为空或报错。
解决方法： 检查服务是否被意外终止，尝试重新启动：
# 回到工作目录 cd /root/workspace # 查看是否有残留进程 ps aux | grep uvicorn # 若无进程，手动重启（假设启动脚本为 start_llm.sh） nohup python -m vllm.entrypoints.openai.api_server \ --host 0.0.0.0 \ --port 8000 \ --served-model-name ui-tars \ --model qwen3-4b-instruct-2507 > llm.log 2>&1 &确保 GPU 资源充足（至少 6GB 显存），否则可能加载失败。
4.2 前端无法连接后端
现象：前端提示 "Failed to connect to model server"。
排查步骤： 1. 确认后端服务正在运行：bash curl http://localhost:8000/health返回{"status":"ok"}表示健康。
检查防火墙或安全组规则是否放行 8000 端口。
若跨机器访问，请确认绑定地址为
0.0.0.0而非127.0.0.1。
4.3 权限不足导致操作失败（仅 macOS）
现象：无法截图或模拟鼠标键盘操作。
解决方法： 前往系统设置 → 隐私与安全性 → 添加以下权限： - ✅ 可访问性（Accessibility） - ✅ 屏幕录制（Screen Recording）
然后重启应用。
5. 总结
本文详细介绍了如何在预置镜像环境下快速部署和使用UI-TARS-desktop，并通过验证日志、启动前端、配置参数和功能测试四个步骤，帮助新手用户零门槛上手这一强大的 GUI Agent 工具。
我们重点强调了以下几个关键点： 1.开箱即用：镜像内置Qwen3-4B-Instruct-2507模型与 vLLM 推理服务，省去复杂安装流程。 2.本地化运行：所有数据不上传云端，保障用户隐私与安全。 3.自然语言驱动：只需简单描述任务，即可实现自动化操作。 4.跨平台兼容：支持 Windows 与 macOS 主流系统。
未来您可以进一步探索： - 自定义工具插件开发 - 集成企业内部系统作为 Action Provider - 构建专属工作流自动化助手
掌握 UI-TARS-desktop 不仅能提升个人效率，也为构建下一代人机交互范式提供了实践基础。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
