3步跑通OmniParser：纯视觉屏幕解析工具完整教程

3步跑通OmniParser：纯视觉屏幕解析工具完整教程

【免费下载链接】OmniParserA simple screen parsing tool towards pure vision based GUI agent项目地址: https://gitcode.com/GitHub_Trending/omn/OmniParser

OmniParser是一个屏幕解析（Screen Parsing）工具，能把一张 GUI 截图转成带编号、带描述的结构化界面元素。读完本文，你可以装好环境、解析出自己的第一张截图，并把解析结果接入视觉大模型生成界面操作。

它解决什么问题

• 不依赖系统辅助功能树，只靠截图**识别（Grounding）**界面元素
• 定位按钮、输入框等可交互区域，并给每个图标生成文字描述
• 支持桌面、网页、移动端截图（见 demo.ipynb）
• 通过OmniTool（omnitool/）驱动 Windows 11 虚拟机执行操作
• 适合做 GUI Agent、界面自动化或训练数据采集

从零到跑起来

先建环境：

git clone https://gitcode.com/GitHub_Trending/omn/OmniParser cd OmniParser conda create -n omni python==3.12 conda activate omni pip install -r requirements.txt

这条命令创建 Python 3.12 环境并安装依赖，依赖来自 requirements.txt，含 torch、transformers、gradio、paddleocr 等，全部装完才算就绪。

再下载 V2 模型权重：

huggingface-cli download microsoft/OmniParser-v2.0 icon_detect_v3/model.pt --revision refs/pr/37 --local-dir weights for f in icon_caption/{config.json,generation_config.json,model.safetensors}; do huggingface-cli download microsoft/OmniParser-v2.0 "$f" --local-dir weights; done mv weights/icon_caption weights/icon_caption_florence

第一段下载 YOLOv9-E 检测器权重（在 HF PR #37 合并前需用该方式），第二段下载 Florence2 描述模型并改目录名，weights/下最终应有icon_detect_v3和icon_caption_florence两个子目录。

启动网页演示：

python gradio_demo.py

浏览器会打开演示页（默认 7861 端口），左侧上传截图，右侧出解析结果。

第一次真实使用：解析一张 Word 界面截图

以 demo.ipynb 使用的 Word 截图为例，走一遍流程：

1. 输入：启动 gradio 演示后，上传一张 Word 文档截图。
2. 调参：确认 Box Threshold 为 0.05、IOU Threshold 为 0.1（默认值），打开 Use PaddleOCR。
3. 执行：点击 Submit，检测与描述两个模型依次跑完，终端打印finish processing。
4. 查看：右侧出现带编号边框的标注图，文字框输出icon 0: ...形式的元素列表。
5. 衔接：把这份编号元素清单交给视觉大模型，它即可输出"点哪个框、做什么动作"的决策。

进阶用法

如何调整元素识别精度

• 网页演示里有两个滑杆：Box Threshold过滤低置信度边框（0.01–1.0），IOU Threshold去除重叠框（0.01–1.0），代码在 gradio_demo.py。
• 服务化部署时，在 omniparserserver/omniparserserver.py 的启动参数里用--BOX_TRESHOLD设置检测阈值，--device cuda可切到 GPU 加速。
• 经验做法：小图标漏检就调低 Box Threshold，边框杂乱就调高它。

模型组合与密钥怎么配

• 在 omnitool/gradio/app.py 的界面模型选择器中切换方案，除默认omniparser + gpt-4o外，还有omniparser + o1、omniparser + R1、omniparser + qwen2.5vl和claude-3-5-sonnet-20241022（走 Anthropic Computer Use，不经 OmniParser）。
• 界面上填入对应 OpenAI 或 Anthropic 的 API Key 后即可开始。

OmniTool 虚拟机链路怎么搭

• 三个组件：omniparserserver（FastAPI 解析服务）、omnibox（Docker 容器里的 Windows 11 虚拟机）、gradio（下指令的界面），说明见 omnitool/readme.md。
• omnibox 依赖 KVM，适合在 Linux 或 Windows 上跑，需准备 Windows 11 Enterprise 评估版 ISO 并放入omnitool/omnibox/vm/win11iso。
• 依次启动：python -m omniparserserver，再用omnitool/omnibox/scripts下的./manage_vm.sh create建虚拟机，最后python app.py --windows_host_url localhost:8006 --omniparser_server_url localhost:8000。

它是怎么工作的

解析分两阶段：先用YOLOv9-E检测器找出屏幕上的可交互区域，再用微调的Florence2模型为每个图标生成文字描述，同时用 OCR（PaddleOCR/EasyOCR）提取文本；三类信息合并成带编号的结构化元素列表，交给视觉语言模型做动作决策。它只做"看懂截图"这一步，本身不执行鼠标键盘操作；OmniTool 场景里，执行由虚拟机内的 pyautogui 完成。边界提醒：解析质量受截图分辨率和界面样式影响，omnibox 目前只支持 Windows 11。

避坑指南

现象：gradio 界面点提交后报 "Windows Host is not responding"。原因：虚拟机里接收命令的服务还没起来，通常是 omnibox 首次安装没跑完。解决办法：在 NoVNC 里确认桌面没有残留终端窗口；等待 10 分钟无效就用./manage_vm.sh stop+start重启，仍不行则delete后重新create（已有存储会很快）。

现象：Windows 上启动报libpaddle: The specified module could not be found。原因：PaddleOCR 依赖 C++ Redistributable 运行时。解决办法：先安装 C++ Redistributable，再重新执行pip install -r requirements.txt。

现象：manage_vm.sh create长时间不结束。原因：首次创建要下载组件并安装一批预装应用，通常耗时 20–90 分钟。解决办法：耐心等终端出现 "VM + server is up and running!"；如果只需最小环境，可按 omnitool/readme.md 的说明注释掉部分预装应用。

OmniParser 用纯视觉链路把截图变成可被大模型消费的元素清单，配合 OmniTool 即可构成完整的 GUI 操作闭环。下一步建议阅读 README.md 和 docs/Evaluation.md 了解基准评测细节。

【免费下载链接】OmniParserA simple screen parsing tool towards pure vision based GUI agent项目地址: https://gitcode.com/GitHub_Trending/omn/OmniParser