lm-evaluation-harness — LLM 少样本评测框架

GitHub: EleutherAI/lm-evaluation-harness
Stars: 13,000+ | License: MIT | 4000+ Commits
论文: A Framework for Few-shot Language Model Evaluation

目录

1. 项目速览
2. 功能概述
3. 适用场景
4. 快速上手
5. 源码架构
6. 实操 Demo
7. 同类对比
8. 参考资源

项目速览

lm-evaluation-harness 是 EleutherAI 推出的 LLM 少样本评测框架，是目前学术界和工业界最广泛使用的开源模型评测工具之一。它提供了超过 60 个标准学术基准的标准化评测流程，覆盖 HellaSwag、MMLU、ARC、GSM8K、TruthfulQA、WinoGrande 等核心任务，同时支持数百个子任务和变体。

该框架的核心价值在于标准化与可复现。在 LLM 评测领域，不同的评测方式（Prompt 格式、few-shot 示例选择、答案解析逻辑）会对最终分数产生显著影响。lm-evaluation-harness 通过对每个基准任务内置标准化的 Prompt 模板、few-shot 配置和评分逻辑，确保了评测结果的跨模型可比性。HuggingFace Open LLM Leaderboard 的所有评测均基于该框架运行。

在模型后端支持上，lm-evaluation-harness 覆盖了 HuggingFace Transformers（含 GPTQ/AutoGPTQ 量化）、vLLM、SGLang、NVIDIA NeMo、Megatron-LM 等主流推理框架，同时提供 OpenAI 和 Anthropic 等商业 API 的适配器。多 GPU 场景下支持数据并行、张量并行和流水线并行三种策略，适合从单卡消费级 GPU 到大规模集群的各类部署环境。

截至 2026 年 5 月（v0.4.12），lm-evaluation-harness 累计超过 4000 次提交，GitHub Star 数超过 13,000，被 HuggingFace、NVIDIA、Databricks 等机构官方采用。

功能概述

标准化基准评测

框架内置 60+ 学术基准，按领域分类：

领域	代表性任务
常识推理	HellaSwag、WinoGrande、PIQA、ARC (Easy/Challenge)、OpenBookQA
世界知识	MMLU（含 57 个子学科）、BoolQ
数学推理	GSM8K（含 CoT 版本）、MATH
代码能力	HumanEval、MBPP
语言理解	LAMBADA、Belebele
长上下文	LongBench、RULER
指令遵循	IFEval
多模态	MMMU（实验性支持）

列出所有可用任务：

lm-eval ls tasks

任务支持通配符批量选择——mmlu* 将覆盖 MMLU 的全部 57 个子学科：

lm_eval --model hf \
    --model_args pretrained=meta-llama/Meta-Llama-3-8B \
    --tasks mmlu* \
    --device cuda:0 \
    --batch_size auto

多后端模型支持

通过统一的模型适配层，一套评测代码可驱动多种推理后端：

# HuggingFace Transformers（含量化）
pip install "lm_eval[hf]"
lm_eval --model hf --model_args pretrained=EleutherAI/gpt-j-6B --tasks hellaswag

# vLLM（高吞吐推理）
pip install "lm_eval[vllm]"
lm_eval --model vllm \
    --model_args pretrained=meta-llama/Meta-Llama-3-8B,tensor_parallel_size=2,dtype=auto,gpu_memory_utilization=0.8 \
    --tasks lambada_openai --batch_size auto

# 商业 API
pip install "lm_eval[api]"
export OPENAI_API_KEY="sk-..."
lm_eval --model openai-completions \
    --model_args model=gpt-3.5-turbo-instruct \
    --tasks hellaswag

多 GPU 并行策略

框架对大规模模型评测提供了三种并行策略：

• 数据并行（Data Parallelism）：多张 GPU 各自加载完整模型，评测不同数据分片。适合单卡可容纳的模型，加速大量数据评测：

  accelerate launch -m lm_eval --model hf \
      --tasks lambada_openai,piqa,hellaswag \
      --model_args pretrained=meta-llama/Meta-Llama-3-8B \
      --batch_size 16

• 张量并行（Tensor Parallelism）：通过 vLLM 或 SGLang 后端实现，将单模型切分到多张 GPU。适合超大模型：

  lm_eval --model vllm \
      --model_args pretrained=meta-llama/Meta-Llama-3-70B,tensor_parallel_size=4,dtype=auto \
      --tasks mmlu --batch_size auto

• 流水线并行（Pipeline Parallelism）：通过 torchrun 启动，模型层分布到多张 GPU。适用于超大模型且无法用 vLLM 的场景。

缓存与断点续评

评测过程支持两层缓存：

• 样本缓存（Sample Caching）：每个 (模型, 任务, few-shot 示例, Prompt) 组合只推理一次，结果存入 SQLite 数据库
• 结果缓存（Result Caching）：完整评测结果缓存，支持 --recompute 强制重算

这意味着评测意外中断后，重新执行相同命令将自动跳过已完成的样本，从中断处继续——对于需要数小时的大规模评测至关重要。

生态集成

• HuggingFace Hub：一键上传评测结果至 HF Hub
• Weights & Biases：自动记录评测指标到 W&B
• Zeno：可视化对比不同模型的评测结果

适用场景

场景	说明
开源模型评测	在 HellaSwag、MMLU、GSM8K 等基准上评测微调/预训练模型，与 Open LLM Leaderboard 对标
模型选型对比	在同一套基准上横向对比多个候选模型（不同尺寸、不同微调版本）的客观表现
预训练 Checkpoint 回归测试	训练过程中定期评测 checkpoints，监测预训练质量趋势
学术论文实验	为论文提供标准化、可复现的评测结果，仅需说明使用的框架版本和任务配置
多 GPU 大规模评测	借助数据并行+张量并行，在数小时内完成 70B+ 模型的全量基准评测
API 模型评测	通过 API 适配器统一评测 GPT-4、Claude 等商业模型的学术基准表现

快速上手

安装

git clone --depth 1 https://github.com/EleutherAI/lm-evaluation-harness
cd lm-evaluation-harness
pip install -e .

按需安装后端依赖：

pip install "lm_eval[hf]"         # HuggingFace（必需）
pip install "lm_eval[vllm]"       # vLLM 高吞吐推理
pip install "lm_eval[sglang]"     # SGLang 推理
pip install "lm_eval[api]"        # OpenAI/Anthropic API 适配器
pip install "lm_eval[ifeval]"     # IFEval 指令遵循评测

第一条评测命令

评测 GPT-J-6B 在 HellaSwag 上的表现：

lm_eval --model hf \
    --model_args pretrained=EleutherAI/gpt-j-6B \
    --tasks hellaswag \
    --device cuda:0 \
    --batch_size 8

输出示例：

|    Tasks    |Version|Filter|n-shot|  Metric   |   |Value |   |Stderr|
|-------------|------:|------|-----:|-----------|---|-----:|---|-----:|
|hellaswag    |      1|none  |     0|acc        |↑  |0.5039|±  |0.0050|
|             |       |none  |     0|acc_norm   |↑  |0.6474|±  |0.0048|

评测多个任务

lm_eval --model hf \
    --model_args pretrained=meta-llama/Meta-Llama-3-8B \
    --tasks hellaswag,arc_challenge,winogrande,mmlu \
    --device cuda:0 \
    --batch_size auto

自定义 few-shot 数量

lm_eval --model hf \
    --model_args pretrained=meta-llama/Meta-Llama-3-8B \
    --tasks gsm8k_cot \
    --num_fewshot 8 \
    --device cuda:0

源码架构

项目以 Python 为核心技术栈，通过 pyproject.toml 管理依赖与构建：

lm-evaluation-harness/
├── lm_eval/                 # 核心库
│   ├── api/                 # 高层 API（registry, model, task）
│   ├── models/              # 模型适配器
│   │   ├── huggingface.py       # HF Transformers 后端
│   │   ├── vllm_causallms.py    # vLLM 后端
│   │   ├── sglang_causallms.py  # SGLang 后端
│   │   ├── openai_completions.py # OpenAI API 适配器
│   │   ├── anthropic_llms.py    # Anthropic API 适配器
│   │   └── nemo_lm.py           # NVIDIA NeMo 后端
│   ├── tasks/               # 基准任务定义
│   │   ├── hellaswag/
│   │   ├── mmlu/
│   │   ├── arc/
│   │   ├── gsm8k/
│   │   └── ...              # 60+ 基准任务
│   ├── evaluator.py         # 评测引擎核心
│   ├── evaluator_utils.py   # 评测工具函数
│   ├── metrics.py           # 指标计算（acc, f1, perplexity 等）
│   ├── filters.py           # 答案提取过滤器
│   ├── prompts.py           # Prompt 模板管理
│   └── cache.py             # SQLite 缓存层
├── docs/                    # 文档
├── examples/                # 示例 Notebook
├── scripts/                 # 工具脚本
│   ├── zeno_visualize.py    # Zeno 可视化
│   └── model_comparator.py  # 多模型结果对比
├── templates/new_yaml_task/ # YAML 任务定义模板
├── tests/                   # 测试套件
└── pyproject.toml           # 构建配置

核心设计模式：

1. Task-Model-Registry 三层架构：Task（基准定义）与 Model（推理后端）完全解耦，通过 Registry 注册机制动态发现。添加新基准只需实现 Task 抽象类，无需修改模型端代码；添加新后端只需实现 LM 基类的 loglikelihood() 和 generate_until() 两个核心方法。

2. Evaluation Pipeline：instantiate model -> build task list -> iterate tasks -> generate responses -> filter answers -> compute metrics -> aggregate results。每个阶段通过插件化接口扩展，例如 Filter 负责从模型原始输出中提取最终答案。

3. YAML-based Task Definition：多数新任务使用 YAML 格式定义（templates/new_yaml_task/），包含 dataset 路径、Prompt 模板（Jinja2）、metric 列表和 generation 参数，避免了大量 Python 样板代码。

4. Two-Phase Caching：样本级缓存（基于 hash(key) 去重）独立于结果缓存，支持跨任务共享相同 Prompt 的推理结果。

实操 Demo

以下演示两个完整场景：HuggingFace 模型的标准评测、API 模型评测。

Demo 1：Meta-Llama-3-8B 在 4 个核心基准上的评测

步骤 1：安装并准备模型

pip install "lm_eval[hf]"
# 确保模型可通过 HuggingFace 访问（huggingface-cli login 如需）

步骤 2：运行评测

lm_eval --model hf \
    --model_args pretrained=meta-llama/Meta-Llama-3-8B \
    --tasks hellaswag,arc_challenge,winogrande,mmlu \
    --num_fewshot 0 \
    --device cuda:0 \
    --batch_size auto:4 \
    --output_path ./results/llama3-8b

步骤 3：分析结果

结果将写入 ./results/llama3-8b/ 目录，包含 JSON 格式的详细结果。关键指标：

|       Tasks       |  Metric   | Value  | Stderr |
|-------------------|-----------|--------|--------|
| hellaswag         | acc_norm  | 0.8105 | 0.0039 |
| arc_challenge     | acc_norm  | 0.5836 | 0.0144 |
| winogrande        | acc       | 0.7530 | 0.0121 |
| mmlu              | acc       | 0.6518 | 0.0037 |

Demo 2：OpenAI API 模型评测

步骤 1：安装 API 后端

pip install "lm_eval[api]"
export OPENAI_API_KEY="sk-..."

步骤 2：评测 GPT-3.5 Turbo

lm_eval --model openai-chat-completions \
    --model_args model=gpt-3.5-turbo \
    --tasks hellaswag,mmlu \
    --num_fewshot 5 \
    --batch_size 1 \
    --output_path ./results/gpt35

步骤 3：上传结果至 HuggingFace Hub

huggingface-cli login
lm_eval --model hf \
    --model_args pretrained=my-org/my-fine-tuned-model \
    --tasks leaderboard \
    --output_path ./results \
    --hf_hub_log_args hub_results_org=my-org,hub_repo_name=lm-eval-results

同类对比

维度	lm-evaluation-harness	BIG-bench	HELM	OpenAI Evals
核心理念	标准化少样本评测，可复现性优先	大规模多样化任务集，探索 LLM 极限	多维度场景化评测（准确性、校准、鲁棒性等）	OpenAI 生态下的自定义 Eval 框架
任务数量	60+ 标准基准 + 数百子任务	204 任务	42 核心场景 + 26 指标维度	用户自定义，内置少量模板
模型后端	HF、vLLM、SGLang、API、NeMo	HF、API	HF、API（通过自定义 Adapter）	OpenAI API 优先
多 GPU	数据并行 + 张量并行 + 流水线并行	有限支持	有限支持	不适用
社区采用	HuggingFace Leaderboard、NVIDIA、Databricks	Google 主导，学术界	Stanford 主导，学术界	OpenAI 生态开发者
Prompt 标准化	每任务内置标准 Prompt + few-shot 配置	每任务独立 Prompt	自定义场景 Prompt	用户自由定义
缓存机制	SQLite 双重缓存	无内置	无内置	无内置
安装复杂度	pip install lm_eval	复杂（需编译部分任务）	复杂（依赖 Stanford 内部工具）	pip install oaieval
适用场景	开源模型标准化评测、Leaderboard	探索性研究、LLM 能力边界探索	学术研究、多维度深度分析	产品功能的专用评测
开源	MIT	Apache 2.0	MIT	MIT

lm-evaluation-harness 最突出的差异化优势是标准化与社区认同。Open LLM Leaderboard 的权威性意味着评测结果在社区中具有直接的可比性——当你说”我的模型在 MMLU 上达到 65.2%”，所有同行立即知道这对应着什么水平。BIG-bench 虽然任务量更大，但缺乏标准化 few-shot 配置，不同论文之间的分数难以直接对比。HELM 的维度更全面，但安装和运行成本显著更高，多用于深度分析而非日常快速评测。

参考资源

• GitHub 仓库： https://github.com/EleutherAI/lm-evaluation-harness
• 论文： A Framework for Few-shot Language Model Evaluation — Gao et al., 2022
• HuggingFace Open LLM Leaderboard： https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard
• 任务列表： 运行 lm-eval ls tasks 查看完整任务清单
• 自定义任务指南： https://github.com/EleutherAI/lm-evaluation-harness/blob/main/docs/new_task_guide.md
• vLLM 集成文档： https://docs.vllm.ai/en/latest/
• 相关阅读： 本文与《SKILL-DeepEval》和《SKILL-Promptfoo》分别覆盖标准化基准评测、LLM 应用质量评估和 Prompt 回归测试这三个模型评测的核心维度