open-compass/VLMEvalKit · 上手攻略

• 仓库：open-compass/VLMEvalKit
• 链接：https://github.com/open-compass/VLMEvalKit
• 分类：多模态评估 / 评测工具
• 作者：spark
• 更新：2026-07-16

是什么

VLMEvalKit（Python 包名 vlmeval）由上海人工智能实验室 OpenCompass 团队开源，是大型视觉-语言模型（LVLM / VLM）的事实标准评估工具包。它的口号是 "一命令评测 220+ LVLM、80+ benchmark" —— 用户只写一个 generate_inner()，剩下的数据下载、预处理、推理、metric 全部由框架接管。

它同时是 HuggingFace 上 OpenVLM Leaderboard（https://huggingface.co/spaces/opencompass/open_vlm_leaderboard） 的官方评测底座，因此结果与排行榜数字严格对齐，可信度在中文 VLM 圈几乎"无人质疑"。论文 VLMEvalKit: An Open-Source Toolkit for Evaluating Large Multi-Modality Models（arXiv:2407.11691）2024 年发表在 ACM Multimedia，截至 2026-07 仍持续更新。

License：Apache-2.0；stars ≈ 4.3k（截至 2026-07-16）；最近 commit 2026-07-14，活跃度极高。

解决什么问题

当你有了一个新 VLM（自研 / 微调 / 蒸馏），想立刻知道它在主流榜单上什么水平，会发现：

1. 数据下载零碎：MMMU、MMBench、MathVista、OCRBench、HallusionBench …… 每个都在不同 HF / GitHub 仓库，部分还要走 ModelScope。
2. Prompt template 各家不同：InternVL、Qwen-VL、GPT-4o 各自一套 zero-shot prompt，要对齐 baseline 才能比。
3. 评测范式混乱：有的用 PPL（perplexity-based），有的用 generation-based（采样后判断），可重复性天差地别。
4. 答案抽取：MCQ 的 A/B/C/D 容易被模型说成 "The answer is (A)."，需要 LLM-as-judge 或正则回提。
5. 多模型批量对比：组里 5 个模型都想跑同一套榜单，每次手动换 model_name 太累。

VLMEvalKit 把这些事一次性打包：

• 220+ 模型 / 80+ benchmark 一键评测；
• 统一 generation-based + LLM answer extraction；
• HuggingFace / ModelScope 双数据源（环境变量切）；
• 支持 LMDeploy / vLLM 分布式推理（2025-05 起，多节点多卡）。

快速安装

git clone https://github.com/open-compass/VLMEvalKit.git
cd VLMEvalKit
pip install -e .
# 评闭源模型时还要装:
pip install lmdeploy vllm            # 二选一，加速用

环境变量：

export OPENAI_API_KEY=sk-xxx        # 评 GPT-4o / o1 等
export DASHSCOPE_API_KEY=...        # QwenVL DashScope
export HF_HOME=/path/to/cache
export HF_TOKEN=hf_xxx
# 可选：从 ModelScope 下载视频 benchmark
export VLMEVALKIT_USE_MODELSCOPE=True

注意 transformers 版本要按模型固定（README 列了一长串版本推荐，下面"坑"里展开）。

核心用法

1) 命令行跑一个单模型单 benchmark

python run.py \
  --model Qwen2.5-VL-3B-Instruct \
  --data MMBench_DEV_EN MMStar MathVista_MINI \
  --use-vllm

--data 可以空格分隔多个 benchmark；--use-vllm / --use-lmdeploy 启用加速。

2) Python API 调单个模型推理

from vlmeval.config import supported_VLM

model = supported_VLM['idefics_9b_instruct']()
ret = model.generate(['assets/apple.jpg', 'What is in this image?'])
print(ret)
# "The image features a red apple with a leaf on it."

3) 评自家模型（只要实现 generate_inner）

# vlmeval/config.py 里加自己的模型类
class MyVLM:
    def generate_inner(self, message, dataset=None):
        # message 是 OpenAI ChatML 格式 [{"type":"image","url":...},{"type":"text","text":...}]
        return my_backend.infer(message)

generate_inner() 是唯一需要用户实现的接口，其余所有 benchmark / 数据加载 / metric / leaderboard 汇总全部白送。

4) 跑带 thinking mode 的模型（2025-09 新功能）

export SPLIT_THINK=True        # 让框架正确解析 <think>...</think> 标签
export PRED_FORMAT=tsv         # 长回答超过 16k/32k token 时避免 xlsx 截断
python run.py --model InternVL3-78B --data MMMU_Pro ...

5) 多节点分布式（2025-05 起 LMDeploy/VLLM 后端）

在 vlmeval/config.py 的模型 config 里加 use_lmdeploy=True 或 use_vllm=True，即可在多机多卡上跑 InternVL / QwenVL / LLaMA4 等大模型评测。

6) 上传结果到 OpenVLM Leaderboard

from vlmeval.tools import upload_results
upload_results('./outputs/Qwen2.5-VL-3B-Instruct/results.xlsx')
# 生成 PR / 报告所需的 JSON

典型适用场景

• VLM 研究者发表论文需要跑 MMMU / MathVista / OCRBench / Video-MME 等权威榜单。
• 中文 VLM 团队（InternVL、QwenVL、MiniCPM-V、Ovis 等）已经把 OpenVLM Leaderboard 作为"过审门槛"，VLMEvalKit 是唯一被认的底座。
• 闭源 API 用户：评测 GPT-4o / Claude / Gemini / Doubao-VL，统一在一个框架里横向对比。
• 工业 PoC：选型阶段用 VLMEvalKit 在自有 30 张图上对比 GPT-4o vs Qwen2.5-VL-72B vs InternVL3-78B 的 hallucination rate。
• 课程作业：大学多模态课程直接拿 VLMEvalKit 做实验。

坑与注意

• transformers 版本钉死：README 列出 12+ 个版本映射：Qwen 系列要 4.33.0、LLaVA 系列 4.37.0、Molmo 4.50.3+、Qwen3.5 ≥ 5.2.0。切换模型基本要重装依赖，建议每个模型独立 venv。
• Torchvision 版本：Moondream / Aria 要求 ≥ 0.16。
• Flash-attn 编译：pip install flash-attn --no-build-isolation，Aria 等必须；编译 10-30 分钟。
• 评测范式固定为 generation-based：对 SEEDBench 等用 PPL 的基准，数字会与原论文不一致 —— 框架明确"不试图复现所有 3rd party benchmark 的精确数字"。
• Long-response 截断：xlsx 单 cell 32k 字符上限是历史包袱；thinking model 容易触发；务必 PRED_FORMAT=tsv。
• CAN_INFER 路由变化：2025-08 的 PR 1175 把 can_infer_option / can_infer_text 重构，MCQ 评测会更激进地走 LLM choice extractor，数字会有 0.5-1pp 微漂移，复现老版本时留意。
• 闭源 API 费用：跑全 80+ benchmark + GPT-4o 当裁判，单次评估可能上千美元；先用 --limit 50 小样本验证。
• 2026 年新 benchmark 集成：Video-MME-v2、SeePhys、PhyX、OvisU1 等是 2025-2026 才加的；早期 commit 不含，确认要加的基准已被 README "Supported Benchmarks" 收录。
• 结果可复现性：LM decoding 受 batching 影响，对比时用同 seed / 同 batch / 同 vLLM 配置。
• 许可证：Apache-2.0，商用友好；但每个被评测 VLM 自身可能有不同 license，发布结果时注意分别署名。

与同类对比

• vs lmms-eval：VLMEvalKit 模型广度（220+）完胜，lmms-eval 在协议一致性、视频/音频覆盖、统计显著性上更强；学术圈更认 lmms-eval，工业圈（尤其中文）更认 VLMEvalKit。
• vs HuggingFace OpenVLM Leaderboard 网页：Leaderboard 是 VLMEvalKit 的官方结果展示，反过来 VLMEvalKit 是其评测底座 —— 想"上榜"必须用 VLMEvalKit 跑。
• vs 闭源 API 评测平台（如 Promptfoo、Arize Phoenix）：VLMEvalKit 专注 VLM benchmark，那些平台专注 LLM eval + 监控，不可比但可互补。

一句话推荐结论

如果你是 VLM 研究者或中文 VLM 团队，VLMEvalKit 几乎是 2026 年必须装的基础工具——既能为你的模型"挂名 OpenVLM Leaderboard"，又能 1 行命令跑 80+ 榜单；如果你的工作偏多模态 RAG / 长视频 / 音频评测，可以同时引入 lmms-eval 做补充。

来源：仓库 README + arXiv:2407.11691 论文页 + 飞书 VLMEvalKit Features Wiki（2026-07-16 抓取）+ 1 次 web_search 旁证 2025-2026 最新功能（PR 1229 thinking mode / PR 1175 can_infer）+ OpenVLM Leaderboard 公开数据。

不确定处：(1) "220+ LMMs、80+ benchmarks" 为 README 自述，准确数字以 vlmeval/config.py 中 supported_VLM 字典长度为准；(2) "1 行命令跑全 80+ benchmark" 是修辞性描述，实际 OpenAI / Anthropic API 仍会因调用成本受限；(3) 2025-08 PR 1175 的"MCQ 性能轻微提升"为作者报告，未独立 benchmark 复现。