GUI-HalluBench

GUI 页面解析能力评测基准（GUI Hallucination Benchmark），用于评估大语言模型（LLM）对 GUI 页面截图的 UI 元素解析能力。通过将模型预测的 UI 元素（坐标 + 描述）与人工标注的 Ground Truth 进行对比，计算精确率、召回率及描述相似度。

项目背景

随着多模态大模型在 GUI 理解任务中的广泛应用，模型对页面元素的解析能力（即准确识别页面中各 UI 元素的位置和语义描述）成为关键指标。本项目构建了一套标准化的评测流程，支持中英文双语场景，能够自动化地完成：

• 从原始训练数据中提取 UI 元素标注
• 过滤含个人隐私信息的图片
• 通过大模型进行批量推理
• 基于坐标 IoU 和描述相似度计算评测指标

目录结构

GUI-HalluBench/
├── src/                          # 评测核心代码
│   ├── evaluate.py               # 主评测代码（推理 + 评测流程）
│   └── metrics.py                # 指标计算模块（IoU、Precision、Recall、描述相似度）
├── data/
│   ├── annotation/
│   │   ├── en/                   # 英文标注
│   │   │   └── ui_elements_en.json
│   │   └── zh/                   # 中文标注
            └── ui_elements_zh.json
│   └── images/
│       ├── en/                   # 英文场景图片
│       └── zh/                   # 中文场景图片
└── LEGAL.md                      # 法律免责声明

安装方法

环境要求

• Python >= 3.10
• 依赖包：openai、loguru、tqdm（批量推理）；评测核心代码仅依赖 Python 标准库

安装依赖

pip install openai loguru tqdm

如使用 DashScope 适配器（阿里云通义千问 VL 系列），还需安装：

pip install dashscope

数据格式

标注格式（Annotation）

标注文件位于 data/annotation/{en,zh}/ 目录下，为 JSON 数组格式，每个条目对应一张页面截图：

[
  {
    "image_path": "data/images/en/A*6rjpRanVPtAAAAAASxAAAAgAevV3AQ.jpg",
    "elements": [
      {
        "type": "icon",
        "index": 0,
        "description": "wifi",
        "coordinates": [831, 9, 877, 48]
      },
      {
        "type": "text",
        "index": 0,
        "description": "支付宝",
        "coordinates": [8, 5, 59, 25]
      }
    ]
  }
]

字段	说明
image_path	图片路径（相对于项目根目录）
elements	UI 元素列表
elements[].type	元素类型（icon、text、button、image、input 等）
elements[].index	元素在该页面中的序号
elements[].description	元素的文字描述
elements[].coordinates	边界框坐标 [x1, y1, x2, y2]（左上角和右下角）

数据集规模

语言	标注条目数
英文（en）	1000
中文（zh）	1000

评测指标

评测代码位于 src/ 目录，主评测流程（evaluate.py）与指标计算（metrics.py）分离。

指标定义

1. 坐标匹配：预测框与真实框的 IoU > 0.5 时视为匹配成功（TP）
2. 精确率（Precision） = TP / (TP + FP)
3. 召回率（Recall） = TP / (TP + FN)
4. F1 = 2 × Precision × Recall / (Precision + Recall)
5. 描述相似度：对坐标匹配成功的元素对，使用 Python difflib.SequenceMatcher 计算 description 的文本相似度（0~1）

匹配算法采用贪心策略：计算所有预测-真实对的 IoU，按 IoU 降序逐一匹配，每个预测框和真实框最多匹配一次。

指标模块 API

src/metrics.py 提供以下核心函数：

from metrics import compute_iou, evaluate_sample, evaluate_dataset

# 计算两个边界框的 IoU
iou = compute_iou([0, 0, 10, 10], [5, 5, 15, 15])

# 评测单条样本
result = evaluate_sample(pred_elements, gt_elements, iou_threshold=0.5)
# 返回: {"precision", "recall", "tp", "fp", "fn", "avg_description_similarity", ...}

# 评测整个数据集（通过 image_path 对齐预测与标注）
results = evaluate_dataset(predictions, ground_truths, iou_threshold=0.5)
# 返回: {"overall_precision", "overall_recall", "overall_f1", "avg_description_similarity", "per_sample", ...}

使用方法

1. 运行评测

评测代码支持通过 OpenAI 兼容 API 或 DashScope 进行推理，可自定义模型、prompt 和 IoU 阈值。

使用 OpenAI 兼容 API（适用于 Qwen-VL、GPT-4o、GLM-4V 等）

python src/evaluate.py \
    --annotation data/annotation/en/ui_elements_en.json \
    --model qwen-vl-max \
    --adapter openai \
    --api-base http://localhost:8000/v1 \
    --api-key YOUR_API_KEY \
    --output result/eval_result.json

使用 DashScope（阿里云通义千问）

python src/evaluate.py \
    --annotation data/annotation/zh/ui_elements_zh.json \
    --model qwen-vl-max \
    --adapter dashscope \
    --api-key YOUR_DASHSCOPE_API_KEY \
    --output result/eval_result_zh.json

自定义 prompt

将 prompt 写入文件后通过 --prompt 参数指定：

python src/evaluate.py \
    --annotation data/annotation/en/ui_elements_en.json \
    --model qwen-vl-max \
    --adapter openai \
    --api-base http://localhost:8000/v1 \
    --api-key YOUR_API_KEY \
    --prompt my_prompt.txt \
    --output result/eval_result.json

限制评测样本数

python src/evaluate.py \
    --annotation data/annotation/en/ui_elements_en.json \
    --model qwen-vl-max \
    --adapter openai \
    --api-base http://localhost:8000/v1 \
    --api-key YOUR_API_KEY \
    --max-samples 100 \
    --output result/eval_result.json

2. 命令行参数说明

参数	说明	默认值
--annotation	标注文件路径（必填）	-
--model	模型名称（必填）	-
--adapter	LLM 适配器类型：openai / dashscope	openai
--api-base	API base URL（openai 适配器）	-
--api-key	API key	-
--image-dir	图片根目录（image_path 为相对路径时拼接）	-
--prompt	自定义 prompt 文件路径	使用内置默认 prompt
--iou-threshold	IoU 匹配阈值	0.5
--max-samples	最多评测样本数	全部
--temperature	生成温度	0.0
--max-tokens	最大生成 token 数	4096
--output	结果输出路径	不保存

3. 评测结果格式

评测结果以 JSON 格式输出，包含汇总指标和逐样本详情：

{
  "num_samples": 4796,
  "total_tp": 150000,
  "total_fp": 30000,
  "total_fn": 25000,
  "overall_precision": 0.8333,
  "overall_recall": 0.8571,
  "overall_f1": 0.8451,
  "avg_description_similarity": 0.7823,
  "per_sample": [
    {
      "image_path": "data/images/en/A*xxx.jpg",
      "precision": 0.9,
      "recall": 0.85,
      "tp": 45,
      "fp": 5,
      "fn": 8,
      "avg_description_similarity": 0.82
    }
  ]
}

扩展自定义模型适配器

src/evaluate.py 中的 BaseLLMAdapter 是抽象基类，继承并实现 infer 方法即可适配新的模型：

from evaluate import BaseLLMAdapter

class MyCustomAdapter(BaseLLMAdapter):
    def infer(self, image_path: str, prompt: str) -> str:
        # 实现自定义推理逻辑，返回模型文本输出
        ...
        return model_output_text

然后在 build_adapter 函数中注册即可通过命令行 --adapter 使用。