# bbox-tester：多模态GUI视觉定位基准测试工具

> bbox-tester 是一款用于评估多模态大模型在GUI视觉定位任务上表现的Python CLI工具。它支持多种模型提供商，能够自动发送截图和指令、解析预测边界框、与标准答案对比评分，并生成包含可视化叠加层和排行榜的交互式报告。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-13T00:33:01.000Z
- 最近活动: 2026-05-13T00:51:11.570Z
- 热度: 159.7
- 关键词: GUI Agent, 视觉定位, 多模态模型, 基准测试, 边界框, MLLM, Ollama, Gemini
- 页面链接: https://www.zingnex.cn/forum/thread/bbox-tester-gui
- Canonical: https://www.zingnex.cn/forum/thread/bbox-tester-gui
- Markdown 来源: ingested_event

---

## 背景与问题

随着多模态大语言模型（MLLM）的快速发展，GUI智能体（GUI Agent）逐渐成为自动化操作计算机界面的热门方向。这类智能体需要理解屏幕截图内容，并准确定位界面元素的位置，以执行点击、输入等操作。然而，不同模型在视觉 grounding 任务上的表现差异显著，缺乏统一的评估工具让开发者和研究者难以客观比较各模型的能力。

## bbox-tester 简介

bbox-tester 是一个专为GUI视觉定位设计的Python命令行基准测试工具。它通过标准化的测试流程，帮助用户评估多模态模型在理解截图并预测目标元素边界框方面的准确性。

### 核心功能

1. **多提供商支持**：兼容 Azure OpenAI、Gemini、OpenRouter 和本地 Ollama 等多种模型提供商
2. **标准化测试流程**：发送截图和目标描述到模型，提取预测的边界框坐标
3. **自动评分机制**：将预测框与标准答案（gold box）对比，计算准确性指标
4. **可视化报告**：生成包含边界框叠加层、模型对比、排行榜的交互式HTML报告
5. **点击准确性评估**：支持评估模型预测的点击位置是否落在目标区域内

## 技术实现细节

### 坐标系统与评分

bbox-tester 使用归一化的0-1000坐标系统表示边界框 `[y1, x1, y2, x2]`。评分时计算预测框与标准答案的重叠程度，支持以下评估模式：

- **边界框模式**：评估预测矩形与目标矩形的匹配度
- **点击模式**：评估预测点击点是否落在目标区域内

### 测试套件格式

测试用例采用JSONL格式定义，包含以下字段：

- `id`：任务唯一标识
- `image`：截图文件路径
- `target` 或 `instruction`：定位目标的自然语言描述
- `gold_box`：标准答案边界框 `[y1, x1, y2, x2]`
- `expected_click`（可选）：预期的点击坐标 `[x, y]`
- `source`, `license`, `notes`（可选）：元数据信息

### 输出报告结构

每次运行会在 `runs/` 目录下生成时间戳文件夹，包含：

- `summary.json`：结构化运行摘要
- `results.jsonl`：每次模型调用的详细结果
- `results.csv`：便于表格处理的指标数据
- `leaderboard.csv` / `leaderboard.md`：按提供商/模型/推理设置的聚合指标
- `report.html`：可视化交互报告
- `annotated/*.jpg`：带有边界框叠加的标注截图

## 使用方式

### 快速开始

```bash
# 同步依赖
uv sync

# 复制环境变量模板
cp .env.example .env

# 运行样本测试（Ollama提供商）
uv run bbox-tester \
  --suite benchmarks/sample-yahoo/tasks.jsonl \
  --providers ollama \
  --model gemma4:latest \
  --runs 3
```

### 单图测试模式

对于单个截图的快速测试：

```bash
uv run bbox-tester \
  --image benchmarks/sample-yahoo/yahoo.png \
  --target "Output the position of yahoo!finance" \
  --gold-box 17 203 34 259 \
  --providers gemini
```

### 独立评分工具

`bbox-check` 命令可用于不调用模型的情况下直接评分：

```bash
# 评估边界框预测
uv run bbox-check --gold-box 17 203 34 259 --pred-box 19 205 33 257

# 评估点击预测
uv run bbox-check --gold-box 17 203 34 259 --pred-click 230 25
```

## 支持的模型提供商

| 提供商 | 说明 |
|--------|------|
| `azure` | Azure OpenAI Responses API 部署 |
| `gemini` | Gemini Developer API 或 Vertex AI |
| `openrouter` | 通过 LiteLLM 使用 OpenRouter |
| `ollama` | 本地 Ollama 视觉模型 |

## 配置与扩展

用户可通过 `config.json` 自定义模型矩阵，覆盖默认模型名称或推理设置：

```json
{
  "models": [
    {
      "provider": "ollama",
      "model": "gemma4:latest",
      "reasoning": ["auto"]
    }
  ]
}
```

## 实际意义与应用场景

bbox-tester 填补了GUI智能体开发中的关键空白：

1. **模型选型参考**：帮助团队客观比较不同多模态模型在特定应用场景的表现
2. **回归测试**：在模型迭代过程中持续监控定位准确性变化
3. **Prompt工程优化**：测试不同指令描述对模型定位能力的影响
4. **数据集构建**：为收集和标注GUI定位数据集提供标准化流程

## 总结

bbox-tester 为GUI视觉定位任务提供了一个轻量但完整的评估解决方案。其多提供商支持、标准化评分机制和丰富的可视化输出，使其成为多模态模型开发者和研究者的实用工具。随着GUI智能体技术的成熟，这类专用评估工具将在确保模型可靠性和推动技术进步方面发挥越来越重要的作用。