LM-Eval-Harness：统一的大语言模型评估工具

什么是 LM-Eval-Harness？

LM-Eval-Harness 是由 EleutherAI 开发的一个开源框架，旨在为各类大语言模型（LLM）提供统一、可复现、标准化的评估流水线。它将数百个公开基准任务整合到一套简洁的命令行接口和 Python API 中，让你能够像执行单元测试一样快速评测模型。

无论是 Hugging Face 模型、OpenAI 的商业 API，还是自研的私有模型，只需要少量配置就能接入同一套评估体系，彻底告别“每个任务写一份评估脚本”的繁琐工作。

为什么需要统一的评估框架？

模型能力评测在 LLM 生命周期中占据核心地位，但长久以来研究者面临三大痛点：

• 任务实现碎片化：MMLU 用 A 代码，HellaSwag 用 B 代码，格式、指标、预处理各不相同，对比论文结果时极易出错。
• 复现困难：数据切片方式、few-shot 示例、提示词模板若存微小差异，最终分数就会漂移。
• 新模型集成成本高：每接入一个新模型，都要为所有基准重写推理逻辑。

LM-Eval-Harness 的解决方案是：任务实现一次，模型适配一次，之后任意组合即可得到可靠分数。 它已经被用于 Hugging Face Open LLM Leaderboard、NeurIPS 论文以及多个工业级模型的技术报告中，成为事实上的标准评测工具。

环境准备与安装

系统要求

• Python 3.9 及以上
• 推荐使用 Linux（部分任务依赖 Unix 工具，Windows 下可能需通过 WSL 使用）
• 至少 16 GB 内存（具体取决于模型尺寸和任务数量）

安装步骤

# 创建虚拟环境（强烈建议）
python -m venv lm-eval-env
source lm-eval-env/bin/activate  # Windows: lm-eval-env\Scripts\activate

# 从 GitHub 安装最新稳定版
git clone https://github.com/EleutherAI/lm-evaluation-harness
cd lm-evaluation-harness
pip install -e .

# 如需支持 vLLM 加速推理，附加安装
pip install -e ".[vllm]"

验证安装：

lm-eval --help

若输出帮助信息，说明安装成功。

快速入门：一条命令评测模型

LM-Eval-Harness 将整个流程抽象为 lm-eval 命令。下面演示如何用 Hugging Face 上的 HuggingFaceTB/SmolLM-135M 运行两个经典任务：

lm-eval \
  --model hf \
  --model_args pretrained=HuggingFaceTB/SmolLM-135M \
  --tasks mmlu_abstract_algebra,hellaswag \
  --device cuda:0 \
  --batch_size auto

参数解析：

• --model hf：告诉框架使用 Hugging Face 模型后端。
• --model_args：指定模型标识符和加载参数。
• --tasks：逗号分隔的任务名称（任务列表可通过 lm-eval --tasks list 查看）。
• --device：推理设备。
• --batch_size auto：自动检测最大批处理大小以加速评估。

执行完毕后，终端会显示每个任务的得分，同时也生成一个 JSON 结果文件（默认在 ./results/ 目录），便于后续分析。

核心概念：任务、模型与流水线

理解三个核心组件的分工是深入使用框架的关键。

任务（Task）

任务是框架的“度量标准”。每个任务定义了三要素：

1. 数据集：从数据源（Hugging Face Datasets、本地文件等）加载样本。
2. 提示模板：如何将样本组织成模型可接受的输入格式。
3. 指标计算：如何将模型输出解析为最终得分（准确率、F1、困惑度等）。

所有内置任务位于 lm_eval/tasks/ 目录，每个 YAML 文件都遵循统一配置语法。你可以通过以下命令查看某个任务的详细信息：

lm-eval --tasks mmlu_anatomy --describe

模型（Model）

框架通过模型抽象层解耦具体实现。当你指定 --model hf 时，它会实例化一个 HuggingFaceModel 类，该类负责将任务生成的请求转化为模型推理调用，并返回文本结果。目前支持的后端包括：

• hf：Hugging Face Transformers（支持 Accelerate、Bitsandbytes 量化）
• vllm：vLLM 引擎，适用于高吞吐场景
• neuron：AWS Neuron SDK 加速
• openai-completions、openai-chat：OpenAI 及兼容接口
• anthropic-chat、google-gemini 等商业模型
• 自定义 Python API 接口

流水线（TaskManager）

任务管理器负责串联整个评估流程：下载数据、生成请求、分配模型执行、收集结果并计算指标。它还会自动处理 few-shot 示例抽取、随机种子固定等细节，确保可复现性。

使用 Python API 实现脚本化评估

命令行适合快速实验，但在自动化流程、定制预处理或集成到训练循环时，更推荐使用 Python API。

from lm_eval import simple_evaluate
import torch

results = simple_evaluate(
    model="hf",
    model_args="pretrained=HuggingFaceTB/SmolLM-135M",
    tasks=["mmlu_abstract_algebra", "hellaswag"],
    device="cuda" if torch.cuda.is_available() else "cpu",
    batch_size="auto",
    num_fewshot=0,         # 0-shot 评估
    output_path="./results"
)

# 查看摘要
print(results["results"])
# 某个任务的详细指标
print(results["results"]["mmlu_abstract_algebra"])

simple_evaluate 会自动返回与命令行相同结构的字典，其中 results 字段包含各任务指标，samples 字段保存每个样本的模型预测（若需要进一步错误分析）。

常用内置任务速查

完整任务列表超过 200 个，查阅命令：

lm-eval --tasks list

自定义评估任务：YAML 配置速成

假设你需要评估模型对“中文成语填空”的能力，而社区暂无此任务，可通过 YAML 快速自定义。

步骤 1：按任务类型创建数据集（以多选题为例）。 准备一个 JSON 文件，每条数据包含 question、choices 和 answer 字段。

步骤 2：编写任务配置文件 chengyu_fill.yaml：

task: chengyu_fill
dataset_path: json
dataset_kwargs:
  data_files: ./my_data/chengyu.jsonl
output_type: multiple_choice
training_split: train
validation_split: train   # 若数据量小，直接用同一份
test_split: train
doc_to_text: "{{question}}\nA. {{choices[0]}}\nB. {{choices[1]}}\nC. {{choices[2]}}\nD. {{choices[3]}}\n答案："
doc_to_target: "{{answer}}"
doc_to_choice: ["A", "B", "C", "D"]
metric_list:
  - metric: acc
    aggregation: mean
    higher_is_better: true

步骤 3：指定任务路径并运行。

lm-eval \
  --model hf \
  --model_args pretrained=Qwen/Qwen2-0.5B \
  --tasks chengyu_fill \
  --include_path ./my_tasks

--include_path 指向存放 YAML 文件的目录，框架会自动加载其中的任务。

高级技巧与最佳实践

1. Few-shot 配置与上下文管理

通过 --num_fewshot 5 启用 5-shot 评估。框架会从训练集中自动抽取示例，并按照模板拼接在输入前面，无需手动编写。如果任务提示模板不支持少数样本，可在 YAML 中定义 fewshot_config 覆盖示例数量或抽取方式。

2. 大规模模型的分片与量化

对于无法载入单卡的模型，使用 --model_args 传入加速参数：

lm-eval \
  --model hf \
  --model_args pretrained=meta-llama/Llama-2-7b,load_in_8bit=True,device_map=auto \
  ...

3. 连接数据管道：从 Hugging Face Hub 直接加载

大多数任务依赖的原始数据直接从 Hub 下载，无需手动管理。若需要私有数据集，可将 dataset_path 设为本地路径或带认证参数的 Hugging Face 仓库。

4. 复现与日志记录

• 通过 --output_path 指定结果目录，每次运行都会保存包含时间戳的子文件夹。
• 在命令行加 --wandb_args 可将结果直接上传至 Weights & Biases 项目。
• 在所有实验中固定随机种子：--seed 42。

5. 评估封闭 API 模型

以 OpenAI GPT-4 为例：

export OPENAI_API_KEY="your-key"
lm-eval \
  --model openai-chat \
  --model_args model=gpt-4 \
  --tasks mmlu_physics,gsm8k \
  --num_fewshot 0

同样的范式适用于 Anthropic Claude、Google Gemini，确保所有模型在同一尺度下被衡量。

典型工作流总结

1. 确定评估目标：根据模型用途选择能力维度对应的任务组合。
2. 快速试跑：用小模型验证任务是否正常运行（如 SmolLM-135M）。
3. 全面评测：部署真实模型，批量运行 20-50 个核心任务，生成结果矩阵。
4. 结果分析：利用输出的 JSON 或 Weights & Biases 仪表盘对比基线、定位薄弱项。
5. 迭代优化：调整训练数据或提示策略后重新评估，量化改善程度。

常见问题排查

• 内存不足：降低 --batch_size，使用量化加载（load_in_8bit=True）或切换到 vllm 模型后端。
• 任务下载失败：检查网络连接，可手动将 Hugging Face 数据集下载到本地并修改 dataset_path 为本地路径。
• 输出乱码 / 分数异常：确认任务 output_type 与指标类型匹配（如生成任务用 generate_until，选择题用 multiple_choice）。
• 自定义模型不识别：检查模型包名是否满足规范，或者通过 Python API 传入一个实现了 lm_eval.api.model.LM 接口的类实例。

扩展阅读与资源

• 官方 GitHub 仓库：https://github.com/EleutherAI/lm-evaluation-harness
• 内置任务完整说明：https://github.com/EleutherAI/lm-evaluation-harness/tree/main/lm_eval/tasks
• Hugging Face Open LLM Leaderboard 任务组合定义（v2、v3）可作为你的初始任务列表参考。
• 论文：Gao et al., “A Framework for Few-shot Language Model Evaluation” (2021)

LM-Eval-Harness 将模型评估从“手工作坊”带入“工业流水线”，让你把精力集中在分析和提升模型质量上，而非维护评估脚本。立即安装并运行你的第一条评测命令，迈出量化模型能力的第一步。