LM Evaluation Harness：EleutherAI统一大模型评测框架安装与使用指南

一、项目背景

大模型圈有一句老话："不做评测，就是在裸奔。"当你自己微调了一个 7B 模型、或者从开源社区拉了一个新权重，怎么知道它到底比 Llama-3 强还是弱？靠人工抽样问几个问题显然不够，必须用标准化的 benchmark 套件——MMLU、GSM8K、HumanEval、HellaSwag、ARC、BoolQ、TruthfulQA……每个 benchmark 都有自己的数据格式、Prompt 模板、指标计算方式，自己一个个对接是噩梦。

EleutherAI 的 LM Evaluation Harness（pip 包名 lm-eval）就是为了消灭这种重复劳动而生。EleutherAI 是一家非营利研究机构，曾因发布 GPT-Neo、GPT-J 系列开源模型而闻名，而 lm-evaluation-harness 是它最有影响力的基础设施项目之一：一份配置文件即可在 60+ 个主流学术 benchmark 上评测任意 HuggingFace 模型、OpenAI 兼容 API 模型、vLLM、TensorRT-LLM、GGUF 本地模型。

如今它已成为业界事实标准：HuggingFace Open LLM Leaderboard 用它跑分，Togerther AI、Novita 等推理服务商用它做模型上线前回归，无数论文里的对比实验也是基于它跑出的数字。掌握这个工具，等于拿到了一张"大模型成绩单"的批量生成器。

二、核心特性

• 60+ 内置 Benchmark：MMLU、GSM8K、MATH、HumanEval、MBPP、HellaSwag、ARC-Challenge/Easy、BoolQ、Winogrande、TruthfulQA、PIQA、SQuAD、XSum、DROP 等开箱即用。
• 多后端支持：HuggingFace Transformers、vLLM、ExLlama、AutoGPTQ、GGUF/llama.cpp、OpenAI Completions/Chat API、Anthropic、Gemini、Text-Generation-Inference (TGI)。
• 统一指标：准确率、F1、Bleu、ROUGE、Exact Match、Pass@1 等自动计算，输出 JSON/CSV/表格。
• 自定义任务：用 YAML 配置即可新增一个评测任务，无需写代码。
• 多语言支持：包含 XWinograd、XCOPA、FLORES 等多语言基准。
• 分布式评测：基于 Accelerate，支持多卡多机张量并行，70B 模型也能跑。
• 结果可复现：固定版本、固定 few-shot 样本采样、固定 metric，论文级可复现。
• 命令行 & Python 双模式：一条命令跑分，也能嵌入自己的训练流水线。

三、环境要求

• Python：3.9 – 3.12（推荐 3.10 / 3.11）。
• GPU：评测 7B 模型建议单卡 24GB 显存（如 4090/A10）；70B 建议多卡 A100 80G。
• CPU 模式：可跑小模型（如 1B 以下）或 API 后端，但速度很慢。
• 磁盘：HuggingFace 模型权重 + 数据集缓存，建议预留 100GB+。
• 网络：需要能访问 huggingface.co 下载模型与数据集（国内可配置镜像 HF_ENDPOINT=https://hf-mirror.com）。
• 依赖：PyTorch 2.1+、Transformers、Accelerate、Datasets。

四、详细部署步骤

方式一：pip 安装（最简单）

# 建议先建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 基础安装（仅支持本地 Transformers 模型）
pip install -U lm-eval

# 如果要评测 HuggingFace 模型，安装 [hf] extra
pip install -U "lm_eval[hf]"

# 如果要用 vLLM 加速
pip install -U "lm_eval[vllm]" vllm

# 如果要评测 OpenAI / Anthropic 等 API 模型
pip install -U "lm_eval[api]"

验证安装：

lm_eval --version
# 应输出类似 0.4.7

方式二：从源码安装（获取最新特性）

git clone https://github.com/EleutherAI/lm-evaluation-harness
cd lm-evaluation-harness

# 可编辑模式安装
pip install -e .

# 如要开发或跑测试
pip install -e ".[dev,docs]"

方式三：国内网络加速配置

# 使用 HF 镜像站
export HF_ENDPOINT=https://hf-mirror.com
export HF_HOME=/data/hf_cache   # 把模型缓存放到大盘

# 如果用 wandb 记录日志，也可以关闭
export WANDB_MODE=disabled

第一次跑评测：30 秒上手

用一个小的 GPT-2 模型跑 ARC-Easy 任务，验证环境是否正常：

lm_eval \
  --model hf \
  --model_args pretrained=gpt2,device=cpu \
  --tasks arc_easy \
  --batch_size 8 \
  --limit 100

参数解释：

• --model hf：使用 HuggingFace Transformers 后端。
• --model_args pretrained=gpt2：模型权重名，也可以填本地路径。
• --tasks arc_easy：要跑的任务名；多个任务用逗号分隔。
• --limit 100：只取前 100 条样本，快速冒烟测试。
• --batch_size 8：批大小，显存够可开大。

跑完后会在终端打印一张成绩表，并把结果保存到 ./results/ 目录下的 JSON 文件里。

评测一个开源大模型（GPU）

lm_eval \
  --model hf \
  --model_args pretrained=Qwen/Qwen2.5-7B-Instruct,dtype=bfloat16,trust_remote_code=True \
  --tasks mmlu,gsm8k,hellaswag,arc_challenge \
  --num_fewshot 5 \
  --batch_size auto \
  --output_path ./results/qwen25-7b \
  --log_samples

关键参数：

• --num_fewshot 5：5-shot 评测，与论文对齐。
• --batch_size auto：自动找最大可行 batch。
• --log_samples：把每条样本的输入输出都存下来，便于 debug。
• trust_remote_code=True：Qwen 等需要执行仓库自定义代码。

用 vLLM 加速（速度提升 5-10 倍）

lm_eval \
  --model vllm \
  --model_args pretrained=Qwen/Qwen2.5-7B-Instruct,dtype=bfloat16,tensor_parallel_size=1 \
  --tasks mmlu \
  --batch_size 16 \
  --output_path ./results/qwen-vllm

评测 OpenAI 兼容 API 模型

export OPENAI_API_KEY=sk-xxxx
export OPENAI_API_BASE=https://api.openai.com/v1

lm_eval \
  --model openai-completions \
  --model_args model=gpt-4o-mini \
  --tasks mmlu \
  --limit 500

如果用国内兼容接口（如 DeepSeek、Moonshot），只需修改 OPENAI_API_BASE 即可。

列出所有可用任务

# 查看全部内置任务
lm_eval --tasks list

# 模糊搜索某个任务
lm_eval --tasks list | grep mmlu

五、进阶用法与生产建议

5.1 大规模评测最佳实践

• 先用 --limit 100 冒烟测试，确认无误再跑全量；
• 用 --batch_size auto 让框架自动找最大可行 batch；
• 多卡用 vLLM + tensor_parallel_size=N；
• 结果 JSON 留档，写论文时直接引用。

5.2 常用 Benchmark 速查

5.3 自定义任务 YAML 示例

# my_task.yaml
task:
  dataset_path: json
  dataset_kwargs:
    data_files: test.jsonl
  output_type: multiple_choice
  doc_to_text: "问题: {{question}}\nA. {{A}}\nB. {{B}}"
  doc_to_target: answer
  metric: acc

六、使用方法示例

Python API 调用（嵌入自己的流水线）：

from lm_eval import simple_evaluate
from lm_eval.models.huggingface import HFLM

model = HFLM(pretrained="Qwen/Qwen2.5-1.5B-Instruct", device="cuda")
results = simple_evaluate(
    model=model,
    tasks=["mmlu", "hellaswag"],
    num_fewshot=5,
    limit=100,
)
print(results["results"])

结果文件默认输出到 ./results/<model>/<timestamp>/results_*.json，包含每个任务的指标、样本数、运行时长。

典型评测场景：

• 微调前后对比：跑同一组 benchmark，看分数提升；
• 选模型：在 MMLU/GSM8K/HumanEval 上对比 5 个开源模型；
• 回归测试：每次发版前跑一遍核心任务，防止退化。

默认账号密码：本工具是纯命令行/库，没有 Web 界面、不需要登录。评测云端 API 模型时，需要通过环境变量传入对应服务商的 API Key。

七、常见问题（FAQ）

Q1：下载模型时报 Connection 错误 / 超时？

国内用户务必设置 export HF_ENDPOINT=https://hf-mirror.com，并提前用 huggingface-cli download 把模型拉到本地，再把 pretrained= 换成本地路径。

Q2：显存不足（OOM）怎么办？

(1) 加 --batch_size auto 或手动调小；(2) 模型 args 加 load_in_4bit=True 用 bitsandbytes 4bit 量化；(3) 切到 vLLM 后端，对显存利用更高效；(4) 多卡张量并行 tensor_parallel_size=N。

Q3：跑分和 Open LLM Leaderboard 上的数字对不上？

检查三点：lm-eval 版本是否一致（不同版本任务定义可能更新）、few-shot 数量是否一致、是否使用了 chat 模板（Instruct 模型在 base 任务上一般用 prompt 而非 chat 模板）。

Q4：如何评测自己的私有数据集？

在 lm_eval/tasks/ 下新建一个 YAML 文件，定义 dataset_path、output_type、doc_to_text、metric_list 即可，官方文档有完整教程。

Q5：能评测一个已经部署成 API 的本地模型吗？

可以。使用 --model local-completions 并指定 model_args model=你的模型名,base_url=http://localhost:8000/v1/completions，兼容任何 OpenAI Completions 接口。

七、跳转链接

• GitHub 仓库：https://github.com/EleutherAI/lm-evaluation-harness
• PyPI 包：https://pypi.org/project/lm-eval/
• 任务列表文档：Tasks 文档
• HuggingFace Open LLM Leaderboard：Open LLM Leaderboard
• 贡献指南：Contributing.md