EvolvingLMMs-Lab/lmms-eval · 上手攻略

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

是什么

lmms-eval（Python 包名 lmms-eval，前身为 LMMs-Eval）是 EvolvingLMMs-Lab 维护的"统一多模态大模型评估工具包"。目标只有一个：让"同一个模型 + 同一个 benchmark + 同一套参数"在两台机器上跑出来数字一致，并且能覆盖文本、图像、视频、音频四大模态的 100+ 任务、30+ 模型后端。

它脱胎于 EleutherAI 的 lm-evaluation-harness（LLM 时代的事实标准），针对多模态做了三件事：

1. 统一的 Chat 协议：所有模型按 apply_chat_template + 结构化 ChatMessages 输入，告别"图是 base64 还是 PIL.Image"的混乱。
2. 可复现：同一份 commit 同一份 yaml 同一份权重，应该跑出同样的 confidence interval。
3. 工程效率：异步 serving + adaptive batching + TorchCodec 视频 I/O（v0.7 起提速最高 3.58×），不让评估成为 GPU 利用率的瓶颈。

截至 2026-07-16，README 显示 stars ≈ 4.3k + 460+ forks，157+ contributors，版本线 v0.1（2024-03）→ v0.7（2026-02），活跃且仍在 30+ 模型/100+ 任务持续扩张。

解决什么问题

多模态评估一直是"三不管地带"：数据散落在 30+ GitHub 仓库、prompt template 各家自己定、post-processing 没标准、最后贴出来的 accuracy 数字常常对不上。两条研究组用同一模型跑同一基准，结果差 5pp 的事并不少见 —— 不是模型差，是 pipeline 差。

lmms-eval 想把这件事标准化成"装一个包、跑一行命令、出一份带 CI 和 paired t-test 的报告"。它解决的具体痛点：

• 视频评测 I/O 太慢：老一代用 OpenCV 抽帧，瓶颈不在模型在解码；v0.7 切到 TorchCodec 后报 3.58× 提升。
• 不同模型 chat 协议不统一：LLaVA、Qwen2.5-VL、Gemini-Audio、InternVL 各自一套；lmms-eval 用 doc_to_messages + ChatMessages 把差异收敛。
• "单数字 accuracy"无法做显著性判断：v0.6 引入 paired t-test + confidence interval，方便 AB 评测。
• 音频任务被忽视：v0.5 把 Qwen2-Audio、Gemini-Audio、音频 captioning 等纳入。
• 可服务化：v0.6 起提供 standalone HTTP eval server，可以把 GPU 节点变成评估 API，跨进程复用。

快速安装

# 官方强烈推荐 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/EvolvingLMMs-Lab/lmms-eval.git
cd lmms-eval
uv pip install -e ".[all]"

# 跑一个 5 分钟的 sanity check
python -m lmms_eval \
  --model qwen2_5_vl \
  --model_args pretrained=Qwen/Qwen2.5-VL-3B-Instruct \
  --tasks mme \
  --batch_size 1 \
  --limit 8

只读访问 Git 装也行：

uv venv eval && source eval/bin/activate
uv pip install git+https://github.com/EvolvingLMMs-Lab/lmms-eval.git

环境变量建议：

export HF_HOME="/path/to/hf-cache"
export HF_TOKEN="hf_xxx"
export HF_HUB_ENABLE_HF_TRANSFER=1
export OPENAI_API_KEY="sk-xxx"      # 如果要评 GPT 系列
export ANTHROPIC_API_KEY="..."      # Claude 系列
export DASHSCOPE_API_KEY="..."      # Qwen DashScope

核心用法

1) 评一个图像 + 视频模型

python -m lmms_eval \
  --model qwen2_5_vl \
  --model_args pretrained=Qwen/Qwen2.5-VL-3B-Instruct \
  --tasks mme,mmmu,mathvista,video_mme \
  --batch_size 4 \
  --output_path ./results/qwen25vl

2) 通过 vLLM / SGLang 后端跑（高吞吐）

仓库自带 examples/models/：

bash examples/models/vllm_qwen2vl.sh
bash examples/models/vllm_qwen3vl.sh
bash examples/models/sglang.sh
bash examples/models/openai_compatible.sh

vLLM / SGLang 后端可以多卡并发加速，70B 级别的视觉模型也能跑得起。

3) HTTP eval server（v0.6+）

把 GPU 节点作为评估服务，对外暴露 REST；适合多团队共用一套 GPU。

python -m lmms_eval.server --model qwen2_5_vl --port 8000
# 客户端
curl -X POST http://eval-node:8000/evaluate \
     -d '{"task":"mme","limit":50}'

4) 加一个新任务（写一个 yaml）

# my_task.yaml
task: my_custom_vqa
dataset_path: HuggingFaceM4/my-vqa
test_split: test
output_type: generate_until
doc_to_messages: !function utils.my_doc_to_messages
metric_list:
  - metric: exact_match
    aggregation: mean

5) 注册一个新模型

# lmms_eval/models/chat/my_model.py
from lmms_eval.api.registry import register_model
from lmms_eval.api.model import lmms

@register_model("my_chat_model")
class MyChatModel(lmms):
    is_simple = False
    def generate_until(self, requests):
        ...

v0.7 起所有新模型都推荐用 Chat 协议写（models/chat/），Simple（models/simple/）作为 legacy 保留。

典型适用场景

• 多模态研究者：发论文时复现别人 baseline / 跑自家模型，对数字可复现性要求高。
• 模型团队：上线前内部 benchmark 套件，覆盖 MMMU / MathVista / Video-MME / EgoSchema 等主流榜单。
• 大模型平台方：把 lmms-eval 当作评估 API 服务，给内部所有 SFT/RLHF 流程做 AB。
• 教学场景：大学课程"多模态模型评估"章节直接拿 100+ 任务 yaml 做实验。
• CI/CD 集成：v0.6 引入 paired t-test 后，可以在 model registry 里每次微调后跑一组子任务，用 CI 决定是否 promote。

坑与注意

• CUDA / Torch 版本敏感：仓库 miscs/repr_torch_envs.txt 列了不同 torch/cuda 下能复现 LLaVA-1.5 的精确环境；版本不一致会有 1-2pp 漂移。
• Java 1.8.0 for pycocoeval：评测 COCO / RefCOCO / NoCaps caption 任务时必须装 openjdk=8，新 Java 版本会失败。
• 依赖地狱：部分环境会触发 httpx / protobuf / numpy 版本冲突，README 给出应急命令： bash pip install httpx==0.23.3 protobuf==3.20 numpy==1.26 sentencepiece
• transformers 版本约束：不同 VLM 对 transformers 版本要求不一样（例如 Molmo 要 4.50.3+，LLaVA-NeXT 要 4.48.0，InternVL 要 4.37.0），切换模型时基本要重装依赖；README "Transformers Version Recommendation" 章节有详表。
• FlashAttention 编译：Aria 等模型需要 pip install flash-attn --no-build-isolation，编译时间 10-30 分钟。
• 多卡 / 分布式：v0.7 还未原生支持 multi-node，要多卡请走 vLLM / SGLang 后端。
• 结果稳定性：seed 默认是确定的，但 LM decoding 部分仍受 batching 影响，跑两次完全相同的命令得到的数字偶尔差 0.1-0.3pp，做 AB 时务必用 paired t-test，不要直接比 mean。
• 许可证：仓库标注 NOASSERTION（多模态生态里不少混合协议），商业二次分发前建议核对 LICENSE 与 lmms_eval/ 子目录。

与同类对比

• vs VLMEvalKit：后者模型多（220+）、对中文 VLM 友好（OpenVLM Leaderboard）、社区更密；lmms-eval 在协议一致性、统计显著性、视频/音频覆盖上更强。如果你的模型已经在 OpenCompass 评测榜单，VLMEvalKit 是更省事的"挂名"工具；如果要做严肃的研究型 AB，lmms-eval 更好。
• vs lm-evaluation-harness：纯文本版本之父，多模态这边 lmms-eval 是它的延伸，API 风格一致，老用户零学习成本。
• vs MMBench / MMVet：是单一 benchmark，不是 harness；lmms-eval 内部就包含这些 benchmark 的 yaml。

一句话推荐结论

做多模态研究或严肃模型对比，lmms-eval 是 2026 H1 最值得装的统一评估底座；纯刷 OpenVLM 排名的场景用 VLMEvalKit 更省事，两者并非互斥，常被同一个团队并存使用。

来源：仓库 README + docs/releases/v0.5-v0.7 release notes（2026-07-16 抓取）+ lmms-lab.com 官方介绍页 + 1 次 web_search 旁证 v0.7 提速数据 + PyPI lmms-eval 下载量。

不确定处：(1) "3.58× faster" 是 v0.7 release notes 自报数据，未在第三方独立复现；(2) 30+ 模型 / 100+ 任务为 README 自述，建议动手前查 docs/advanced/current_tasks.md 拿当前准确数；(3) NOASSERTION 许可证的具体组合（很可能混合 MIT + Apache-2.0 + 各模型子目录自有协议）未逐文件核验，二次分发前请自行 SPDX 扫描。