OmniTool 部署实战基于 OmniParser V2 的 Windows 11 虚拟机纯视觉 GUI Agent 全链路搭建指南【免费下载链接】OmniParserA simple screen parsing tool towards pure vision based GUI agent项目地址: https://gitcode.com/GitHub_Trending/omn/OmniParserOmniTool 是 OmniParser 仓库中开箱即用的计算机使用Computer UseAgent 套件它把 OmniParser V2 屏幕解析服务、一个运行在 Docker 容器内的 Windows 11 虚拟机OmniBox和一个可视化指挥界面Gradio串成一条完整链路你只需输入一句自然语言指令Vision-Language Model 就会通过 OmniParser 解析出的可交互元素编号逐步驱动 VM 中的鼠标键盘完成任务。本文将以omnitool/readme.md为骨架结合仓库源码逐组件讲解部署步骤、配置参数、底层调用链与常见故障排查帮助你在一台 CPU 机器 一台 GPU 机器上或单机上完整复现这套纯视觉 GUI Agent。OmniTool 是什么三组件架构总览OmniTool 的设计目标非常明确Control a Windows 11 VM with OmniParser your vision model of choice用 OmniParser 加任意你选定的视觉模型来控制一台 Windows 11 虚拟机。它不捆绑单一的模型或厂商而是提供标准化的屏幕解析 → 元素编号 → 模型决策 → 模拟操作流水线。整个系统由三个独立可部署的组件构成组件目录职责omniparserserveromnitool/omniparserserver一个 FastAPI 服务封装 OmniParser V2负责把 VM 屏幕截图解析为带编号的文本/图标元素列表SOM 标注图omniboxomnitool/omnibox运行在 Docker 容器中的 Windows 11 虚拟机作为 Agent 实际操作的桌面环境gradioomnitool/gradioGradio 界面接收你的指令、展示 Agent 的推理与每一步执行结果三者之间的数据流如下你在 Gradio 中输入任务 → Gradio 请求 omniparserserver 对 OmniBox 的屏幕截图做解析 → 得到带编号的交互元素parsed_content_list与screen_info文本后连同截图一起交给选定的 VLM → VLM 输出下一步动作 Box ID → Gradio 的 Executor 调用 computer 工具 通过 VM 内的控制服务移动鼠标、点击、输入文字 → 截图循环往复直到 VLM 判断任务完成。这套设计的关键点是纯视觉pure visionAgent 不读取任何 DOM、辅助功能树或 OCR 以外的结构化数据只依赖屏幕图像本身因此理论上可以操控任何在 VM 桌面上可见的应用。核心亮点omnitool/readme.md中明确了三个核心卖点均可在源码中找到对应支撑OmniParser V2 比 V1 快约 60%并能理解更多 OS、应用及应用内图标。V2 的检测与图标描述权重托管在 Hugging Facemicrosoft/OmniParser-v2.0本仓库根 README.md 亦说明 V2 在 Screen Spot Pro grounding benchmark 上取得 SOTA 结果docs/Evaluation.md中有详细评测说明。OmniBox 相比其他用于 Agent 测试的 Windows VM 节省约 50% 磁盘空间同时提供相同的 computer use API。它的实现基于 qemu/KVM 方案见 Dockerfile基础镜像为dockurr/windows-arm与qemux/qemu-docker通过 compose.yml 把 Windows 11 Enterprise Evaluation 版跑在容器里。OmniTool 开箱即支持多种视觉模型OpenAI4o/o1/o3-mini、DeepSeekR1、Qwen2.5VL、Anthropic Computer UseClaude Sonnet。模型分发逻辑在 omnitool/gradio/loop.py 中claude-3-5-sonnet-20241022走AnthropicActoromniparser gpt-4o/o1/o3-mini/R1/qwen2.5vl走VLMAgent带-orchestrated后缀的走VLMOrchestratedAgent多 Agent 编排模式。部署拓扑建议关于部署位置文档给出明确建议也是作者推荐的省钱方案omniparserserver虽然 OmniParser V2 可以在 CPU 上运行但为了速度建议放在GPU 机器上omnibox其 Windows 11 VM 依赖 KVM因此只能快速运行在 Windows 和 Linux 主机上macOS 不支持 KVMVM 本身纯 CPU 即可gradioCPU 机器即可。推荐拓扑omnibox gradio 放在同一台 CPU 机器omniparserserver 放在一台 GPU 服务器两者通过 HTTP 网络互通。组件一omniparserserverFastAPI 屏幕解析服务omniparserserver 是整个链路的第一步它把原始截图变成 Agent 可读的带编号元素清单。核心实现在 omnitool/omniparserserver/omniparserserver.pyPOST /parse/接收{base64_image: ...}调用Omniparser.parse()返回{som_image_base64: ..., parsed_content_list: ..., latency: ...}GET /probe/健康检查返回{message: Omniparser API ready}供 Gradio 与脚本探测服务可用性。安装步骤如果你已经有 OmniParser 的 conda 环境可以直接跳过前面几步# 1. 确认 conda 已安装 conda --version # 2. 进入仓库根目录 cd OmniParser # 3. 创建 Python 3.12 环境 conda create -n omni python3.12 # 4. 激活环境 conda activate omni # 5. 安装依赖 pip install -r requirements.txt下载模型权重在 Hugging Face PR #37 合并之前需要先从该 PR 手动下载最新的检测器权重然后下载图标描述caption权重# 下载 YOLOv9-E 检测器权重来自 PR 37 huggingface-cli download microsoft/OmniParser-v2.0 icon_detect_v3/model.pt \ --revision refs/pr/37 --local-dir weights # 清理默认的 caption 目录避免冲突 rm -rf weights/icon_caption weights/icon_caption_florence # 下载 caption 权重florence2 huggingface-cli download microsoft/OmniParser-v2.0 --local-dir weights \ --repo-type model --include icon_caption/* # 目录重命名与默认配置对齐 mv weights/icon_caption weights/icon_caption_florence仓库根 README.md 给出了等价的另一种下载写法逐个文件下载icon_caption/{config.json,generation_config.json,model.safetensors}再mv重命名两者效果相同。PR 合并后OmniParser 会在首次使用时自动下载相同权重。启动服务cd OmniParser/omnitool/omniparserserver python -m omniparserserver从源码可以看到服务启动时解析的命令行参数及其默认值如下参数默认值说明--som_model_pathNone可选的本机检测器路径不传时 V3 检测器默认从 Hugging Face 下载--caption_model_nameflorence2图标描述模型名称--caption_model_path../../weights/icon_caption_florence图标描述模型权重路径--devicecpu模型运行设备GPU 机器请设为cuda--BOX_TRESHOLD0.05框检测置信度阈值--host127.0.0.1API 监听地址--port8000API 监听端口例如 GPU 机器上可以这样启动并启用 uvicorn 热重载python -m omniparserserver --device cuda --host 0.0.0.0 --port 8000注意omniparserserver.py顶部注释给出了一种更完整的调用方式python -m omniparserserver --caption_model_name florence2 --caption_model_path ../../weights/icon_caption_florence --device cuda --BOX_TRESHOLD 0.05可作为显式传参的参考模板。组件二omniboxDocker 中的 Windows 11 虚拟机omnibox 是 Agent 实际动手的桌面环境。它的底层思路是用 Docker 容器内跑的 QEMU 虚拟机安装 Windows 11 Enterprise Evaluation90 天试用版再在 VM 首次启动时通过 setup.ps1 等脚本自动预装 Python、Git 及一批常用工具与一套computer control server监听 5000 端口提供截图与鼠标键盘操作 API即localhost:5000/probe与localhost:5000/screenshot的来源。前置条件至少 30GB 磁盘空间其中 5GB 用于 ISO、400MB 用于 Docker 容器镜像、20GB 用于存储文件夹Docker Desktop或支持 compose 的 Docker 环境KVM 支持VM 加速依赖/dev/kvm因此仅 Windows / Linux 主机可流畅运行下载 Windows 11 Enterprise Evaluation ISO从微软评估中心下载Windows 11 Enterprise90 天试用英语美国ISO约 6GB将其重命名为custom.iso并放到OmniParser/omnitool/omnibox/vm/win11iso目录下该目录下另有 README.md 可参考。创建虚拟机cd OmniParser/omnitool/omnibox/scripts ./manage_vm.sh create该脚本manage_vm.sh会依次执行若本地不存在windows-local镜像则docker build -t windows-local ..构建容器镜像约 400MBdocker compose -f ../compose.yml up -d启动容器与 VM轮询探测 VM 内localhost:5000/probe直到返回 200 后打印VM server is up and running!。整个创建过程下载 安装 Windows 预装应用通常需要20~90 分钟常见约 60 分钟取决于下载速度。安装期间可以通过NoVNC 查看器实时观察桌面上的应用安装进度http://localhost:8006/vnc.html?view_only1autoconnect1resizescale注意NoVNC 窗口中显示的终端在 setup 完成后不会继续停留在桌面。如果安装时看到终端窗口请耐心等待不要点击窗口里的内容以免干扰自动安装。日常管理命令首次创建完成后VM 状态会保存到OmniParser/omnitool/omnibox/vm/win11storage。之后用同一个脚本进行生命周期管理命令行为./manage_vm.sh start启动已有 VM并等待 computer control server 就绪打印VM started./manage_vm.sh stop停止 VMdocker compose stop./manage_vm.sh delete删除容器docker compose down不删除存储文件夹如需彻底删除 VM执行./manage_vm.sh delete后手动删除OmniParser/omnitool/omnibox/vm/win11storage目录。容器配置速览compose.yml 中可调整的关键参数RAM_SIZE: 8G、CPU_CORES: 4、DISK_SIZE: 20GVM 资源规格按主机能力调整privileged: true 设备映射/dev/kvm、/dev/net/tuncap_add: NET_ADMINQEMU/KVM 虚拟化所需的特权配置端口8006:8006NoVNC Web 查看器入口卷挂载custom.iso注入安装镜像vm/win11setup/firstboot作为 OEM 首启脚本setupscripts映射为共享数据目录win11storage持久化 VM 磁盘。组件三gradio指挥与控制界面gradio 是你与 Agent 交互的入口提供聊天式输入、模型选择、API Key 管理、实时 NoVNC 画面与执行过程展示。启动cd OmniParser/omnitool/gradio conda activate omni python app.py --windows_host_url localhost:8006 --omniparser_server_url localhost:8000两个命令行参数对应 app.py参数默认值说明--windows_host_urllocalhost:8006OmniBox 的 NoVNC 地址用于页面内嵌屏幕画面--omniparser_server_urllocalhost:8000omniparserserver 服务地址用于发送截图做解析启动后在浏览器打开终端输出的 URL默认127.0.0.1:7888填入对应模型的 API Key即可开始向 Agent 下达任务。支持的模型与厂商在 Gradio 设置面板的 Model 下拉框中可选择的模型与 app.py 中choices一一对应包括omniparser gpt-4o/o1/o3-miniOpenAI提供者openaiomniparser R1DeepSeek-R1-Distill提供者groq经 Groq 服务推理对应 groqclient.pyomniparser qwen2.5vlQwen2.5-VL-72B提供者dashscope走阿里云 DashScope 兼容接口见 vlm_agent.pyclaude-3-5-sonnet-20241022Anthropic Computer Use上述各模型对应的-orchestrated版本多 Agent 编排模式见 vlm_agent_with_orchestrator.py界面还提供N most recent screenshots 滑块0~10默认 2控制只保留最近 N 张截图喂给模型用于控制上下文长度与 token 成本。Agent 循环的底层工作原理从 loop.py 可以看到每次 Agent 循环的核心步骤如下OmniParserClient()请求http://{omniparser_server_url}/parse/内部先通过 screen_capture.py 的get_screenshot()从http://localhost:5000/screenshot抓取 VM 当前屏幕编码为 base64 后 POST 给 omniparserserveromniparserclient.py 的reformat_messages()把parsed_content_list转成ID: n, Text/Icon: ...格式的screen_info文本连同原始截图、SOM 标注图、分辨率一起返回VLMAgent或AnthropicActor把截图 screen_info注入 system prompt让 VLM 输出结构化 JSON{Reasoning, Next Action, Box ID, value}。VLM 可用的动作集定义在 vlm_agent.py 的 prompt 中type、left_click、right_click、double_click、hover、scroll_up、scroll_down、wait任务完成或需要人工介入如验证码/登录时输出Next Action: NoneAnthropicExecutoranthropic_executor.py解析模型输出的tool_use块通过 computer.py 中的ComputerTool在 VM 上执行鼠标键盘动作支持key、type、mouse_move、left_click、right_click、double_click、screenshot、wait等并把工具结果回填进消息上下文循环回到步骤 1直到模型输出 None 结束任务。常见安装与运行错误排查OmniBox 安装耗时过长如果你的网速较慢、希望得到一个预装应用更少的精简 VM可以编辑 setup.ps1注释掉定义所有待安装应用的段落文档给出的行号区间约为 57 到 350 行。修改后重新创建 VM 时请务必先按下一节的恢复出厂设置步骤清除此前的 omnibox 状态。Validation errors: Windows Host is not responding在 Gradio 中点击 Submit 后报这个错表示VM 内接收 Gradio 命令并移动鼠标/键盘的服务不可用。排查方法docker exec -it omni-windows bash -c curl http://localhost:5000/probe确保 omnibox 已经完全完成初始化NoVNC 窗口中不应再有终端窗口首次创建约需 20~90 分钟。如果已就绪可能只是服务尚未就绪稍等片刻即可。按文档建议的排查顺序递进处理等待 10 分钟后重试用./manage_vm.sh stop停止、./manage_vm.sh start重启 VM若仍不行执行./manage_vm.sh delete保留win11storage存储文件夹后再次./manage_vm.sh create——由于复用已有存储重建会很快最后手段是完全恢复出厂设置./manage_vm.sh delete # 手动删除 vm/win11storage 目录 ./manage_vm.sh createlibpaddle: The specified module could not be foundOmniParser 使用的 OCR 库 Paddle 在 Windows 上依赖C Redistributable。如果你在 Windows 主机上运行且报此错误请先安装 C 运行库然后重新执行pip install -r requirements.txt。风险与责任实践为与 Microsoft AI 原则和负责任 AI 实践保持一致项目做了如下风险缓解措施见omnitool/readme.md的 Risks and Mitigations 一节图标描述模型训练中使用了负责任 AI 数据使模型尽可能避免从图标图像中推断人物个体的敏感属性如种族、宗教等同时鼓励用户仅对不包含有害/暴力内容的截图使用 OmniParserOmniTool 部分使用Microsoft Threat Modeling Tool进行了威胁模型分析项目建议人类保持在环human in the loop以最大限度降低风险。此外OmniTool 的开发借鉴了 Claude Computer Use、OSWorld、Windows Agent Arena、computer_use_ootb 等开源项目相关致谢均列在omnitool/readme.md的 Acknowledgment 一节。总结三组件一键串联至此你已经掌握了 OmniTool 的完整部署链路GPU 机器上启动 omniparserserver解析屏幕元素CPU 机器上运行 omniboxDocker 内的 Windows 11 VM与 gradio交互界面最后在 Gradio 中填入 API Key 即可用自然语言指挥你的视觉模型在真实 Windows 桌面上完成搜索、办公、多页面操作等任务。这套方案的价值在于组件解耦 模型中立解析服务、虚拟环境、决策模型各司其职你可以在不改变其他组件的前提下随时替换你偏好的 VLM为纯视觉 GUI Agent 的研究与落地提供了一条可复现、可扩展的实践路径。【免费下载链接】OmniParserA simple screen parsing tool towards pure vision based GUI agent项目地址: https://gitcode.com/GitHub_Trending/omn/OmniParser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
