OmniParser 纯视觉 GUI Agent 屏幕解析指南环境安装、核心流水线与 Set-of-Mark 输出全解析【免费下载链接】OmniParserA simple screen parsing tool towards pure vision based GUI agent项目地址: https://gitcode.com/GitHub_Trending/omn/OmniParserOmniParser 是面向纯视觉 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 python3.12 conda activate omni pip install -r requirements.txtrequirements.txt 中的关键依赖如下深度学习框架torch、torchvision图标检测ultralytics8.3.70用于加载基于 Ultralytics 的早期检测器图标语义描述captiontransformers、timm、accelerate、einops0.8.0OCReasyocr、paddlepaddle、paddleocrPaddleOCR 精度更高推理时通过use_paddleocr参数切换标注与可视化supervision0.18.0、opencv-python、opencv-python-headlessGradio 界面gradioHugging Face 权重下载huggingface_hub2. 下载模型权重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 weightsREADME.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()驱动完整调用链为OCR 文本识别调用 util/utils.py 的check_ocr_box()默认使用 EasyOCR英文也可通过use_paddleocrTrue切换为 PaddleOCR。内部把文本坐标统一为xyxy格式同时返回识别文本列表text与坐标ocr_bbox。PaddleOCR 分支还会按text_threshold如 0.8过滤低置信度文本。图标区域检测调用get_yolo_model()加载检测器再经predict_yolo()对整图做目标检测。检测结果xyxy像素坐标会除以图像宽高归一化到 0~1 比例坐标。重叠框过滤调用 util/utils.py 的remove_overlap_new()输入被组织为两类元素——OCR 文本元素interactivity: False与 YOLO 图标元素interactivity: True按 IoU 阈值去重若 OCR 文本在图标内部则把文本标签合并进图标source: box_yolo_content_ocr若图标完全在文本内部则丢弃该图标。图标语义描述调用 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()。合并结构化列表OCR 文本被格式化为Text Box ID {i}: {txt}图标描述被格式化为Icon Box ID {i}: {desc}二者拼接为parsed_content_merged。Set-of-Mark 可视化调用 util/box_annotator.py 的BoxAnnotator在原图上绘制编号包围框与文字标签文字背景自动避让其他检测框最后返回 base64 编码的标注图。parse()的返回值包含三部分dino_labled_imgbase64 标注图、parsed_content_list元素列表含type/bbox/interactivity/content/source、以及归一化的label_coordinates当output_coord_in_ratioTrue时坐标被除以图像宽高便于 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(devicedevice) caption_model_processor get_caption_model_processor( model_nameflorence2, model_name_or_pathweights/icon_caption_florence, devicedevice, ) 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_imgFalse, output_bb_formatxyxy, easyocr_args{paragraph: False, text_threshold: 0.9}, use_paddleocrTrue) text, ocr_bbox ocr_bbox_rslt dino_labled_img, label_coordinates, parsed_content_list get_som_labeled_img( image_path, som_model, BOX_TRESHOLD0.05, output_coord_in_ratioTrue, ocr_bboxocr_bbox, draw_bbox_configdraw_bbox_config, caption_model_processorcaption_model_processor, ocr_texttext, use_local_semanticsTrue, iou_threshold0.7, scale_imgFalse, batch_size128)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.pygradio_demo.py 暴露了四个影响解析质量的参数对应process()函数的入参参数默认值取值范围作用box_threshold0.050.01 ~ 1.0移除置信度低于该值的检测框默认 0.05iou_threshold0.10.01 ~ 1.0移除重叠度过高的检测框默认 0.1use_paddleocrTrue布尔使用 PaddleOCR 替代 EasyOCR 提升文本识别精度imgsz640640 ~ 1920步长 32图标检测的输入图像尺寸服务默认监听127.0.0.1:7861并开启shareTrue生成公网分享链接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可选本地检测器路径默认 NoneV3 权重从 Hugging Face 自动下载--caption_model_namecaption 模型名默认florence2--caption_model_pathcaption 权重路径默认../../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 机器上供omniboxWindows 11 Docker 虚拟机与gradio前端调用详见 omnitool/readme.md。输出格式与 Agent 对接要点结构化解析结果的三大价值点可交互性标记interactivity字段区分文本False与图标True帮助 Agent 过滤掉不可点击区域坐标可直接使用bbox为归一化比例坐标Agent 拿到label_coordinates后乘以屏幕宽高即可得到像素级点击/悬停坐标语义与编号对齐Text Box ID/Icon Box ID编号与标注图中的编号一一对应模型可以点击 ID 12 的图标这种形式生成动作天然适合多轮交互例如 OmniTool 的 agent 循环。版本演进与评测表现根据 README.md 的 News 时间线V1.52024/11更精细的小图标检测并新增元素是否可交互的预测能力V22025/2发布 V2 checkpoints项目方在 Screen Spot Pro 新基准上取得 39.5% 的 grounding 结果具体评测脚本与推理日志见 docs/Evaluation.md 与 eval/且据 omnitool/readme.md 所述 V2 推理速度较 V1 提升约 60%OmniTool2025/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.00203OmniParser 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考