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

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

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

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：带有边界框叠加的标注截图

# 同步依赖
uv sync

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

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