企业官网建设流程全解析

OmniParser 纯视觉 GUI Agent 屏幕解析指南：环境安装、核心流水线与 Set-of-Mark 输出全解析

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

OmniParser 是面向"纯视觉 GUI Agent"的屏幕解析工具，它将任意 GUI 截图解析为结构化的文本元素与图标元素，从而显著提升 GPT-4V 等大模型生成可精确定位（grounding）到界面区域的执行动作的能力。本文以仓库根目录 README.md 为主线，结合 util/、gradio_demo.py、demo.ipynb 与 omnitool/omniparserserver/omniparserserver.py 等源码，完整讲解 OmniParser 的安装、模型权重获取、推理流水线与输出格式，读完即可独立运行解析并接入自己的视觉 Agent。

OmniParser 解决什么问题

在基于纯视觉的 GUI Agent 方案中，模型看到的只是一张截图，往往难以把自然语言动作（如"点击保存按钮"）准确对应到截图的具体像素位置。OmniParser 的核心思路是把截图先"翻译"成结构化的中间表示：

• 检测出界面中的所有图标（icon）区域，并给出每个图标的包围框坐标；
• 用 OCR 识别出界面中的全部文本，并给出文本包围框；
• 用视觉语言模型（caption model）为每个图标生成功能描述；
• 将所有元素按坐标输出为带编号的结构化列表，并在原图上叠加标注（Set-of-Mark），供 Agent 在后续动作生成时精确引用。

项目定位在 README.md 中有明确表述："OmniParser is a comprehensive method for parsing user interface screenshots into structured and easy-to-understand elements, which significantly enhances the ability of GPT-4V to generate actions that can be accurately grounded in the corresponding regions of the interface."

快速开始：环境安装

1. 克隆仓库并创建 Python 环境

按 README.md 的 Install 章节操作：

cd OmniParser conda create -n "omni" python==3.12 conda activate omni pip install -r requirements.txt

requirements.txt 中的关键依赖如下：

• 深度学习框架：torch、torchvision
• 图标检测：ultralytics==8.3.70（用于加载基于 Ultralytics 的早期检测器）
• 图标语义描述（caption）：transformers、timm、accelerate、einops==0.8.0
• OCR：easyocr、paddlepaddle、paddleocr（PaddleOCR 精度更高，推理时通过use_paddleocr参数切换）
• 标注与可视化：supervision==0.18.0、opencv-python、opencv-python-headless
• Gradio 界面：gradio
• Hugging Face 权重下载：huggingface_hub

2. 下载模型权重

OmniParser 需要两类权重：图标区域检测器（YOLOv9-E / icon_detect）和图标功能描述模型（icon_caption）。

图标检测器权重：在 Hugging Face PR #37 被合并之前，需要显式下载最新 YOLOv9-E 检测器到本地weights目录：

huggingface-cli download microsoft/OmniParser-v2.0 icon_detect_v3/model.pt \ --revision refs/pr/37 --local-dir weights

README.md 说明：OmniParser 优先使用该本地权重，PR 合并后会在首次使用时自动下载相同权重。

图标描述模型权重：下载 caption 权重到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

最终目录结构为weights/icon_detect_v3/model.pt与weights/icon_caption_florence/。这与 util/utils.py 中get_yolo_model的逻辑一致：它优先查找仓库根目录下weights/icon_detect_v3/model.pt，存在则直接使用本地路径加载；若路径为空或指向 icon_detect_v3，则走 util/yolov9.py 中基于torch.jit.load的YOLOv9Detector（默认从microsoft/OmniParser-v2.0仓库的icon_detect_v3/model.pt下载，可通过repo_id、revision参数指定来源）。

注意：仓库 README 中以注释形式保留的 V1 流程（weights/icon_detect、weights/icon_caption_blip2以及convert_safetensor_to_pt.py转换脚本）已标记为 deprecated，仅作历史参考，当前版本不推荐使用。

核心解析流水线：源码级剖析

一次屏幕解析由 util/omniparser.py 中的Omniparser.parse()驱动，完整调用链为：

1. OCR 文本识别：调用 util/utils.py 的check_ocr_box()，默认使用 EasyOCR（英文），也可通过use_paddleocr=True切换为 PaddleOCR。内部把文本坐标统一为xyxy格式，同时返回识别文本列表text与坐标ocr_bbox。PaddleOCR 分支还会按text_threshold（如 0.8）过滤低置信度文本。
2. 图标区域检测：调用get_yolo_model()加载检测器，再经predict_yolo()对整图做目标检测。检测结果（xyxy像素坐标）会除以图像宽高归一化到 0~1 比例坐标。
3. 重叠框过滤：调用 util/utils.py 的remove_overlap_new()，输入被组织为两类元素——OCR 文本元素（interactivity: False）与 YOLO 图标元素（interactivity: True），按 IoU 阈值去重：若 OCR 文本在图标内部，则把文本标签合并进图标（source: box_yolo_content_ocr）；若图标完全在文本内部则丢弃该图标。
4. 图标语义描述：调用 util/utils.py 的get_parsed_content_icon()，把每个图标裁剪并缩放为 64×64，按batch_size（默认 128，约为 4GB 显存占用）分批送入 caption 模型生成<CAPTION>描述（Florence-2）或 "The image shows" 引导句（BLIP-2）。也支持 phi3_v 变体get_parsed_content_icon_phi3v()。
5. 合并结构化列表：OCR 文本被格式化为Text Box ID {i}: {txt}，图标描述被格式化为Icon Box ID {i}: {desc}，二者拼接为parsed_content_merged。
6. Set-of-Mark 可视化：调用 util/box_annotator.py 的BoxAnnotator在原图上绘制编号包围框与文字标签（文字背景自动避让其他检测框），最后返回 base64 编码的标注图。

parse()的返回值包含三部分：dino_labled_img（base64 标注图）、parsed_content_list（元素列表，含type/bbox/interactivity/content/source）、以及归一化的label_coordinates（当output_coord_in_ratio=True时坐标被除以图像宽高，便于 Agent 直接换算回像素坐标）。

三种使用方式

方式一：Notebook 交互式示例

仓库提供了开箱即用的 demo.ipynb，演示完整调用流程：

from util.utils import get_som_labeled_img, check_ocr_box, get_caption_model_processor, get_yolo_model import torch from PIL import Image device = 'cuda' som_model = get_yolo_model(device=device) caption_model_processor = get_caption_model_processor( model_name="florence2", model_name_or_path="weights/icon_caption_florence", device=device, ) image_path = 'imgs/word.png' image = Image.open(image_path).convert('RGB') # 按图像尺寸自适应计算标注框与文字大小 box_overlay_ratio = max(image.size) / 3200 draw_bbox_config = { 'text_scale': 0.8 * box_overlay_ratio, 'text_thickness': max(int(2 * box_overlay_ratio), 1), 'text_padding': max(int(3 * box_overlay_ratio), 1), 'thickness': max(int(3 * box_overlay_ratio), 1), } ocr_bbox_rslt, _ = check_ocr_box(image_path, display_img=False, output_bb_format='xyxy', easyocr_args={'paragraph': False, 'text_threshold': 0.9}, use_paddleocr=True) text, ocr_bbox = ocr_bbox_rslt dino_labled_img, label_coordinates, parsed_content_list = get_som_labeled_img( image_path, som_model, BOX_TRESHOLD=0.05, output_coord_in_ratio=True, ocr_bbox=ocr_bbox, draw_bbox_config=draw_bbox_config, caption_model_processor=caption_model_processor, ocr_text=text, use_local_semantics=True, iou_threshold=0.7, scale_img=False, batch_size=128)

Notebook 中输出示例显示：对 Word 界面截图（imgs/word.png）共检出 128 个元素，其中约 41 个需要图标语义描述，caption 阶段耗时约 0.25 秒。parsed_content_list中的元素示例如下：

{'type': 'text', 'bbox': [0.034, 0.047, 0.055, 0.072], 'interactivity': False, 'content': 'Home', 'source': 'box_ocr_content_ocr'} {'type': 'icon', 'bbox': [0.100, 0.115, 0.111, 0.134], 'interactivity': True, 'content': 'Bold', 'source': 'box_yolo_content_yolo'}

其中bbox为归一化xyxy比例坐标，interactivity标记元素是否可交互——这是 V1.5 起新增的能力（见下方版本演进章节）。

方式二：Gradio 交互式 Demo

直接运行即可启动本地 Web 界面：

python gradio_demo.py

gradio_demo.py 暴露了四个影响解析质量的参数，对应process()函数的入参：

服务默认监听127.0.0.1:7861，并开启share=True生成公网分享链接（gradio_demo.py）。界面分为输入区（上传图片 + 参数滑块）与输出区（标注图 +Parsed screen elements文本列表），文本输出将每个元素格式化为icon {i}: {content}的一行一元素形式。

方式三：Python API 封装与 FastAPI 服务

util/omniparser.py 提供了面向程序调用的Omniparser类，输入为 base64 编码的图片字符串，输出为标注图 base64 与结构化元素列表，适合作为 Agent 的解析后端。

仓库进一步提供了现成的 FastAPI 服务 omnitool/omniparserserver/omniparserserver.py，命令行启动方式：

python -m omniparserserver --caption_model_name florence2 --caption_model_path ../../weights/icon_caption_florence --device cuda --BOX_TRESHOLD 0.05

支持的启动参数（见 omniparserserver.py）：

• --som_model_path：可选本地检测器路径，默认 None（V3 权重从 Hugging Face 自动下载）
• --caption_model_name：caption 模型名，默认florence2
• --caption_model_path：caption 权重路径，默认../../weights/icon_caption_florence
• --device：运行设备，默认cpu
• --BOX_TRESHOLD：框检测阈值，默认 0.05
• --host/--port：服务地址，默认127.0.0.1:8000

服务提供两个端点：POST /parse/（接收{"base64_image": "..."}，返回som_image_base64、parsed_content_list与latency）和GET /probe/（健康检查）。该服务是 OmniTool 中omniparserserver组件的核心，常被部署在 GPU 机器上供omnibox（Windows 11 Docker 虚拟机）与gradio前端调用，详见 omnitool/readme.md。

输出格式与 Agent 对接要点

结构化解析结果的三大价值点：

1. 可交互性标记：interactivity字段区分文本（False）与图标（True），帮助 Agent 过滤掉不可点击区域；
2. 坐标可直接使用：bbox为归一化比例坐标，Agent 拿到label_coordinates后乘以屏幕宽高即可得到像素级点击/悬停坐标；
3. 语义与编号对齐：Text Box ID/Icon Box ID编号与标注图中的编号一一对应，模型可以"点击 ID 12 的图标"这种形式生成动作，天然适合多轮交互（例如 OmniTool 的 agent 循环）。

版本演进与评测表现

根据 README.md 的 News 时间线：

• V1.5（2024/11）：更精细的小图标检测，并新增"元素是否可交互"的预测能力；
• V2（2025/2）：发布 V2 checkpoints；项目方在 Screen Spot Pro 新基准上取得 39.5% 的 grounding 结果（具体评测脚本与推理日志见 docs/Evaluation.md 与 eval/），且据 omnitool/readme.md 所述 V2 推理速度较 V1 提升约 60%；
• OmniTool（2025/2）：用 OmniParser + 自选视觉模型控制 Windows 11 虚拟机，开箱支持 OpenAI、DeepSeek、Qwen 2.5VL 或 Anthropic Computer Use，并支持本地轨迹日志以构建领域训练数据流水线（文档标注为 WIP）。

以上均为项目方在文档中自行声明的成果与基准表现，如需复现请以 docs/Evaluation.md 与 eval/ss_pro_gpt4o_omniv2.py 中的实际脚本为准。

模型权重许可说明

README.md 明确说明：icon_detect_v3基于 MIT 许可的 YOLOv9 实现；早期基于 Ultralytics 的图标检测器保留其原始 AGPL 许可；caption 模型为 MIT 许可。在使用与再分发时需注意区分各组件对应的许可证。

引用

技术报告为 arXiv 2408.00203（OmniParser for Pure Vision Based GUI Agent，作者 Yadong Lu、Jianwei Yang、Yelong Shen、Ahmed Awadallah）。如需引用可参考 README.md 中的 BibTeX 条目。

总结

OmniParser 通过"OCR + 图标检测 + 图标语义描述 + Set-of-Mark 标注"四步流水线，把任意 GUI 截图转化为带编号、带坐标、带语义的结构化元素列表，是连接纯视觉大模型与界面操作之间的桥梁。按照本文流程安装环境、下载权重后，即可通过demo.ipynb、Gradio 或 FastAPI 三种方式快速跑通解析，并在此基础上进一步接入 omnitool/gradio/ 中的 Agent 循环，构建属于自己的计算机使用 Agent。

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