VLM Testing Toolkit：构建多模态大模型快速诊断工具
你的 VLM 在 MMMU 上表现如何？在 MathVista 上能解出几何题吗？DocVQA 的 OCR 准确率达标了吗？如果这些问题让你夜不能寐，那么这套工具链或许能帮你找回一些睡眠。
项目地址
开源代码：http://bitbucket.iluvatar.ai:7990/users/jiacheng.wan/repos/filehost/browse
定位说明：快速诊断，而非完整评测
重要：这套工具的设计目标是快速诊断模型能力，而非替代专业的完整评测。
为什么不做完整评测？
- 时间成本过高：完整评测需要测试数千个样本，如果每个样本都通过模型 API 请求 + 答案匹配，耗时可能长达数小时甚至数天
- 专业性不足：专业的评测框架（如 OpenCompass、VLMEvalKit）经过精心优化，测试代码更加鲁棒，评分逻辑更加严谨
- 场景不同：完整评测用于论文发布、基准测试；快速诊断用于开发调试、模型选型、问题定位
适用场景
✅ 推荐使用：
- 模型部署后快速验证基本功能
- 对比多个模型的特定能力（如 OCR、Grounding）
- 开发过程中快速迭代测试
建议：先用本工具快速诊断，发现问题后再使用专业评测框架进行完整测试。
引言：为什么我们需要这套工具
Vision-Language Models (VLMs) 正在以惊人的速度进化。从 GPT-4V 到 Qwen-VL，从 LLaVA 到 InternVL，每个模型都声称在各项基准测试中取得了 SOTA 成绩。然而，当你真正部署一个 VLM 并尝试评估其性能时，会发现一个尴尬的现实：
评测数据的获取、标准化和测试流程，比想象中复杂得多。
- HuggingFace 上有数百个 VLM 评测数据集，字段命名各不相同
- 有些数据集需要授权访问，有些图片链接会过期
- 不同任务类型需要不同的评估指标（IoU、NED、字符串匹配…）
- 测试结果需要完整的记录和可追溯性
VLM Testing Toolkit 正是为了解决这些工程化痛点而设计。它由三个核心模块组成：
┌──────────────────────────────────────────────────────────────────┐
│ VLM Testing Toolkit │
├──────────────────────────────────────────────────────────────────┤
│ hf-case-collector │ vlm-case-tester │ vlm-test-orchestrator │
│ (数据收集) │ (模型测试) │ (流程编排) │
└──────────────────────────────────────────────────────────────────┘
设计初衷
痛点一：数据集字段混乱
HuggingFace 上的 VLM 评测数据集百花齐放，但字段命名却是一团糟。同一个"问题"字段，有的叫 question，有的叫 prompt，有的叫 input，还有的叫 text。答案字段更是五花八门：answer、output、target、label、response…
解决思路：建立一套标准化的字段映射机制。通过优先级列表自动匹配，用户无需关心原始字段名，统一使用 prompt、answer、options 等标准字段。
痛点二：图片资源获取困难
图片 URL 可能藏在各种数据结构中：有的直接是字符串，有的嵌套在字典的 src 字段，有的在 decoded_image.src，还有的是数组形式。更糟糕的是，很多数据集的图片链接会过期。
解决思路：实现递归提取逻辑，自动识别各种图片存储格式。同时支持三种存储方式：原始 URL、本地下载路径、Base64 编码，适应不同的使用场景。
痛点三：评估指标不统一
不同任务类型需要完全不同的评估方式：
- VQA 多选题：选项匹配
- OCR 任务：归一化编辑距离 (NED)
- Grounding 任务：IoU 计算
- 开放式问答：字符串匹配
解决思路：设计任务类型感知的评估引擎，根据数据集自动选择合适的评估指标，对外提供统一接口。
痛点四：流程碎片化
收集数据、构建请求、调用模型、评估结果、生成报告——这些步骤散落在不同的脚本中，手动串联容易出错。
解决思路：引入编排层 (Orchestrator)，用自然语言指令驱动整个流程，自动协调数据收集和模型测试。
整体架构设计
三层架构
┌────────────────────────────────────────────────────────────────┐
│ vlm-test-orchestrator │
│ (元技能编排层) │
│ 解析自然语言指令 → 协调数据收集 → 调度模型测试 → 生成报告 │
└───────────────────────────┬────────────────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ hf-case-collector │ │ vlm-case-tester │
│ (数据收集层) │ │ (测试执行层) │
│ │ │ │
│ • HuggingFace API │ │ • OpenAI API 兼容 │
│ • 字段标准化 │ │ • 多模态请求构建 │
│ • 媒体下载 │ │ • 评估引擎 │
│ • SQLite 持久化 │ │ • JSON 结果记录 │
└───────────────────────┘ └───────────────────────┘
数据流向
用户指令 → Orchestrator 流程指南 → 检查缓存
↓
[缓存未命中] → hf-case-collector → HuggingFace API → 标准化 → SQLite
↓
vlm-case-tester → 构建 OpenAI 请求 → VLM 推理 → 评估引擎 → JSON 结果
模块一：hf-case-collector —— 数据收集的艺术
核心思路
从 HuggingFace 数据集收集测试用例，听起来简单，实则暗藏玄机。不同数据集的字段命名、数据结构、访问权限千差万别。
设计要点
1. 利用 Dataset Viewer API
HuggingFace 提供了 Dataset Viewer API，可以分页获取数据，无需下载完整数据集。这大大降低了存储压力和网络开销。
2. 字段映射优先级
建立字段映射优先级列表，自动匹配最可能的字段名：
| 标准字段 | 可能的原始字段名 |
|---|---|
| prompt | question, problem, query, input, text, instruction, context |
| answer | answer, answers, output, target, label, response, ground_truth |
| options | choices, options, candidates, alternatives |
| image | image, img, images, screenshot, figure, photo, diagram |
3. 媒体资源递归提取
图片 URL 可能藏在各种数据结构中，需要递归提取。支持 HuggingFace Dataset Viewer 的 decoded_image.src 格式，也支持常见的 url、src、link 字段。
4. SQLite 存储设计
持久化存储采用精心设计的 Schema，同时存储 URL、本地路径和 Base64 编码，适应不同使用场景。保留 raw_data 字段，便于调试和扩展。
模块二：vlm-case-tester —— 模型测试的工程化
核心思路
测试 VLM 模型，关键在于：构建正确的请求 和 选择合适的评估指标。
支持的任务类型
| 任务类型 | 代表数据集 | 评估指标 | 通过阈值 |
|---|---|---|---|
| VQA & STEM | MMMU, MathVista | 字符串匹配/选项匹配 | 精确匹配 |
| OCR & Document | DocVQA, OCRBench | 归一化编辑距离 (NED) | NED >= 0.8 |
| Grounding | RefCOCO | Intersection over Union (IoU) | IoU >= 0.5 |
| Video | VideoMME | 序列帧评估 | 字符串匹配 |
| Multi-Image | BLINK | 并行图片处理 | 字符串匹配 |
评估引擎设计
不同任务类型使用不同的评估逻辑：
- Grounding 任务：计算预测框和真实框的 IoU
- OCR 任务：计算归一化编辑距离，容忍 OCR 的微小误差
- VQA 多选题：智能匹配，模型回答 “答案是 A” 或 “选择苹果” 都应该被接受
设计哲学：模型输出格式多样，评估应该宽松但公平。
多模态请求构建
构建 OpenAI API 兼容的请求，支持单图、多图、视频帧序列等不同输入形式。Grounding 任务会自动添加 bounding box 格式提示。
输出结构
每次测试生成完整的记录，包含时间戳、模型信息、数据集、问题、选项、真实答案、模型回答、评估结果等。所有记录保存为 JSON，便于后续分析。
模块三：vlm-test-orchestrator —— 元技能编排
核心思路
这是整个工具链的"大脑"，负责解析自然语言指令并协调其他两个模块。用户只需用自然语言描述需求，系统自动完成数据收集和模型测试。
工作流程
┌─────────────────────────────────────────────────────────────┐
│ 用户指令: "测试 http://127.0.0.1:8000 上的 qwen-vl-max， │
│ 使用 MMstar 的第 10 个 case" │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 1: 解析指令 │
│ • 模型 URL: http://127.0.0.1:8000 │
│ • 模型名称: qwen-vl-max │
│ • 数据集: MMstar │
│ • Case 范围: 第 10 个 │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 2: 检查数据缓存 │
└─────────────────────────┬───────────────────────────────────┘
│
┌───────────┴───────────┐
│ │
[缓存命中] [缓存未命中]
│ │
│ ▼
│ ┌───────────────────────────────────┐
│ │ Step 3: 下载数据 │
│ └───────────────┬───────────────────┘
│ │
└────────────┬────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 4: 执行测试 │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Step 5: 生成报告 │
└─────────────────────────────────────────────────────────────┘
指令解析规则
| 信息类型 | 识别模式 | 示例 |
|---|---|---|
| 模型 URL | http://ip:port | http://127.0.0.1:8000 |
| 模型名称 | 显式指定或从 URL 推断 | qwen-vl-max |
| 数据集 | 名称匹配 + 模糊搜索 | MMstar → Lin-Chen/MMStar |
| Case 范围 | “第 N 个”、“N 到 M” | 10 或 5-15 |
数据集智能映射
用户说"测试 OCR 能力"，系统自动推断使用 DocVQA 和 OCRBench。这种语义映射让用户无需记忆具体数据集名称。
参数推荐
为了保证测试结果的确定性和可复现性，推荐使用低温度采样 (temperature=0.1)。评测需要确定性输出，高温度会导致同一问题得到不同答案，影响结果可比性。
实际使用演示
以下是一个完整的使用流程示例，展示从自然语言指令到测试报告的全过程。
用户输入
帮我测试一下部署在 http://127.0.0.1:8000 上的 qwen-vl-max 模型，使用 MMMU 数据集的前 5 个 case，看看它的多模态理解能力如何。
系统执行过程
Step 1: 解析用户指令
✓ 检测到模型服务地址: http://127.0.0.1:8000
✓ 识别模型名称: qwen-vl-max
✓ 识别数据集: MMMU (自动解析为 MMMU/MMMU_Pro)
✓ 识别测试范围: 前 5 个 case
✓ 推断任务类型: VQA (多选题)
Step 2: 检查数据缓存
正在检查本地缓存...
数据库: dataset.sqlite
查询: SELECT COUNT(*) FROM cases WHERE dataset_name = 'MMMU'
结果: 缓存未命中
→ 需要从 HuggingFace 下载数据
Step 3: 收集测试数据
正在连接 HuggingFace Dataset Viewer API...
✓ 数据集验证通过
✓ 获取到 5 个测试用例
字段映射结果:
question → prompt ✓
answer → answer ✓
image → image ✓
下载图片资源...
✓ 5 张图片已下载并转换为 Base64
数据已保存到 dataset.sqlite
Step 4: 执行模型测试
正在测试模型 qwen-vl-max...
[Case 1/5] MMMU - Computer Science
问题: Which of the following best describes the time complexity of binary search?
选项: A. O(n) B. O(log n) C. O(n²) D. O(1)
模型回答: B. O(log n)
正确答案: B
结果: ✓ PASS (选项匹配)
[Case 2/5] MMMU - Mathematics
问题: Given the function f(x) = x² + 2x - 3, find the vertex...
模型回答: The vertex is at (-1, -4)
正确答案: (-1, -4)
结果: ✓ PASS (字符串匹配)
[Case 3/5] MMMU - Physics
问题: [包含电路图] What is the total resistance?
模型回答: A. 15Ω
正确答案: A
结果: ✓ PASS (选项匹配)
[Case 4/5] MMMU - Chemistry
问题: Which element has the highest electronegativity?
模型回答: Fluorine (F)
正确答案: A. Fluorine
结果: ✓ PASS (选项文本匹配)
[Case 5/5] MMMU - Biology
问题: [包含细胞结构图] What organelle is labeled A?
模型回答: C. Mitochondria
正确答案: B. Nucleus
结果: ✗ FAIL (选项不匹配)
测试完成！
Step 5: 输出测试结果
================================================================================
Dataset | Type | Status | Score | Reason
--------------------------------------------------------------------------------
MMMU_Computer_Science| vqa | PASS | 1.00 | String Match (option 'B. O(log n)')
MMMU_Mathematics | vqa | PASS | 1.00 | String Match
MMMU_Physics | vqa | PASS | 1.00 | Option Letter Match (A)
MMMU_Chemistry | vqa | PASS | 1.00 | String Match (option 'Fluorine')
MMMU_Biology | vqa | FAIL | 0.00 | String Match
================================================================================
All test records saved to: qwen-vl-max/
├── MMMU_Computer_Science_response.json
├── MMMU_Mathematics_response.json
├── MMMU_Physics_response.json
├── MMMU_Chemistry_response.json
└── MMMU_Biology_response.json
总结
通过一条自然语言指令，系统自动完成了：
- 解析用户意图
- 检查/收集测试数据
- 构建多模态请求
- 调用 VLM 模型
- 评估结果
- 生成可读报告
异常处理机制
认证问题
Gated datasets（如 MMMU、MathVista）需要用户同意条款并获取 Token。系统检测到 403 错误时，会给出清晰的指引。
网络问题
采用指数退避重试机制，自动处理临时网络故障。
字段缺失
当标准字段映射失败时，保留原始数据供调试，不会丢失任何信息。
技术亮点总结
1. 字段映射的通用性
通过优先级列表和递归提取，支持了数十种数据集的字段差异。一个映射规则，适配多种数据集。
2. 评估引擎的灵活性
不同任务类型使用不同指标，但接口统一。用户无需关心底层实现细节。
3. 存储设计的实用性
SQLite Schema 同时支持在线测试（URL）、离线测试（本地路径）、API 调用（Base64 编码）。
4. 流程指南的清晰性
工作流程指南明确定义了从数据收集到测试输出的完整步骤，降低使用门槛，便于 AI Agent 或用户理解和执行。
总结与展望
VLM Testing Toolkit 解决了多模态大模型评测中的三个核心问题：
- 数据获取：通过 HuggingFace API 和字段映射，统一了不同数据集的访问方式
- 测试执行：通过 OpenAI 兼容接口和多模态请求构建，支持了主流 VLM 部署方案
- 结果评估：通过任务类型感知的评估引擎，实现了多种评测指标的统一接口
未来改进方向
- 更多评估指标：支持 LLM-as-a-Judge、人工评估等主观指标
- 分布式测试：支持多机并行测试大规模数据集
- 可视化面板：Web UI 展示测试结果和趋势分析
- 更多数据源：除了 HuggingFace，支持 Google Dataset Search、Papers With Code 等
评测不是终点，而是起点。当你知道模型在哪里跌倒，才能帮它学会站起来。这套工具链，就是那个帮你找到"跌倒点"的放大镜。