# 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 标准库

### 安装依赖

```bash
pip install openai loguru tqdm
```

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

```bash
pip install dashscope
```

## 数据格式

### 标注格式（Annotation）

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

```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` 提供以下核心函数：

```python
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 等）

```bash
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（阿里云通义千问）

```bash
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` 参数指定：

```bash
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
```

#### 限制评测样本数

```bash
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 格式输出，包含汇总指标和逐样本详情：

```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` 方法即可适配新的模型：

```python
from evaluate import BaseLLMAdapter

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

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