LM Eval Harness：标准LLM评估测试套件

为什么需要 LM Eval Harness：评估黑箱 → 可复现的标准化评测

在评测框架出现之前，团队评估一个模型通常靠临时脚本：自己写 prompt 模板、自己接模型输出、自己算准确率。这种做法的代价是巨大的——不同人写的评测逻辑口径不一，同一个模型在不同脚本下分数可以相差好几个点；few-shot 示例取几条、答案匹配是精确匹配还是包含匹配、生成长度设多少，都会显著影响结果。更严重的是，这些脚本往往没有保存完整的请求与参数，评测完就散落在各处，无法回溯，导致「分数对不上」成为团队内耗的常见来源。

LM Eval Harness 把这条链路标准化了。它用同一套代码加载模型、组合 prompt、执行推理、计算指标，任务定义、few-shot 配置、后处理逻辑全部固化在仓库中。你只需指定模型和任务名，就能得到与社区公开结果可对照的分数；每次运行还会自动写出 JSON artifact，记录模型参数、任务配置与逐条样本输出，让任何一次评测都可复现、可审计。

与 OpenCompass、HELM 等相比，它的气质是「轻而标准」：不追求大而全的平台化功能，而是把「跑一个可信的基准分」这件事做到极简。对中小团队和模型单体评测，这是性价比最高的切入点。

安装与环境配置：2 步就绪

步骤一：安装。 推荐在 Python 3.9+ 的独立虚拟环境中安装。基础版只需 lm-eval 一个包；若要使用 vLLM 后端加速评测，需安装带 vllm 扩展的版本，并与你本地 CUDA 版本匹配。

步骤二：验证。 安装后执行 lm_eval --help，能正常打印参数说明即就绪。若需从 GitHub 安装最新开发版，可先克隆仓库再执行可编辑安装。

补充说明：包名是 lm-eval（PyPI），导入与命令名是 lm_eval（下划线），两者不要混淆。0.4.x 与 0.3.x 的命令行不兼容，安装后请以本项目官方文档为准，勿照搬旧教程。

# 创建并激活虚拟环境（示例用 conda）conda create -n lm-eval python=3.10 -y && conda activate lm-eval # 基础安装pip install lm-eval # 带 vLLM 后端（可选，按需安装）pip install lm-eval[vllm] # 验证安装lm_eval --help

快速上手：5 分钟跑通第一个基准评测

思路。 最小可用流程只需要三个要素：一个模型（本例用 gpt2）、一个任务（arc_easy）、一条命令。为了快速验证链路，用 --limit 20 只取前 20 个样本，不必跑全量。

操作步骤：

1. 打开终端，进入已安装 lm-eval 的虚拟环境。

2. 运行下方命令，将模型替换为你可访问的任意 HF 模型名。

3. 等待运行结束，Readout 区将打印任务名、样本数与各项指标（acc、acc_norm 及各指标的 stderr）。

4. 追加 --output_path results/ 可把完整 JSON 结果落盘，供后续对比。

结果说明。 输出末尾会给出类似 arc_easy | 20 | 0.3500 | 0.4286 的表格行，含义依次是任务名、样本数、acc、acc_norm；每个指标后带 stderr（标准差）。进阶技巧：小规模冒烟没问题后，去掉 --limit 跑全量；换用更强模型时建议加 --batch_size auto，让框架自动挑选安全且高效的 batch，避免 OOM。

# 有 GPU 时加上 --device cuda:0；CPU 可省略lm_eval --model hf \    --model_args pretrained=gpt2 \    --tasks arc_easy \    --device cuda:0 \    --limit 20

核心能力详解：4 大支柱

支柱一·标准化任务库（60+ 基准）。 项目内置了 MMLU、ARC、HellaSwag、TruthfulQA、WinoGrande、GSM8K、HumanEval 等主流基准的任务定义，每个任务在 YAML 中声明数据集路径、prompt 模板、doc_to_text（把原始样本拼成输入文本的规则）、doc_to_target（标准答案提取规则）与指标。任务自带合理的 few-shot 默认值，符合对应 benchmark 的社区惯例。这意味着你不需要关心「这个任务要用什么 prompt」，开箱即用。

支柱二·多模型后端。 0.4.x 支持 hf（HuggingFace Transformers）、vllm（高吞吐推理）、tgi（HuggingFace TGI 服务）、local-completions（OpenAI 兼容接口的本地服务）、gguf（llama.cpp 量化模型）等后端的适配器。同一份命令只需改 --model 与 --model_args，即可评测不同部署形态的同一个模型，非常适合「先量化、后回归」的流程。其中 vLLM 后端是 0.4.0 引入的核心加速能力，适合长任务、大批量评测。

支柱三·可扩展 Task API。 当项目内置任务无法覆盖你的场景时，可以写一个 YAML 文件注册自定义任务。例如从 JSON 数据集构造「问题→答案」评测，只需声明 dataset_path、doc_to_text 与指标字段，再通过 --include_path 指向该目录即可。相比 0.3.x 时代需要继承 Python Task 类写代码，YAML 方式让非深度开发者也能贡献任务，这也让社区任务库得以快速增长。

支柱四·可复现与可观测。 每次运行默认在 --output_path 目录下生成 JSON artifact，包含完整请求数据（input、arguments、resps）、metric 汇总、模型配置与运行配置。配合 --log_samples 可保留每条样本的实际输出，方便排查 badcase；配合 --wandb_args 可把指标同步到 Weights & Biases，在训练过程中持续监控指标曲线。这一支柱是「评测结果能作为发布依据」的关键保障。

生产部署与监控：从上线到运维

CI 回归测试。 在 GitHub Actions 或自建 CI 中对模型仓配置「评测门禁」：merge 前跑 --limit 200 的冒烟集（如 arc_easy、hellaswag），发版前再跑全量重要基准（如 mmlu + gsm8k 的 few-shot 复现）。将 JSON artifact 上传为 CI artifact，并设置指标阈值，如 GSM8K 分数下降超过 2 分则阻断合并。这是让评测从「临时动作」变成「持续动作」的最低成本方案。

大规模评测调度。 多卡环境可以用 vLLM 后端配合 tensor_parallel_size 参数做张量并行，把大模型分布到多张 GPU；也可以先在 TGI 中部署模型服务，再用 --model tgi 指向服务地址，评测端与推理端解耦，便于在 Slurm 集群上统一调度。CPU 推理建议只用于极小型模型或链路冒烟，生产级全量评测务必用 GPU 后端。

可观测性。 三种手段配合使用：--output_path 保证每次运行有完整落盘记录；--wandb_args 提供指标趋势图，用于训练过程中实时对比 checkpoint；--log_samples 保留样本级输出，作为 badcase 分析与标注迭代的依据。注意不同后端（hf 与 vllm）在部分任务上因 logprob 处理细节可能存在零点几分的差异，记录后端类型后再做跨实验比较。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>0.3.x 教程大规模失效：0.4.0 是破坏性重写，旧版 python -m lm_eval 命令与 Python API 均不兼容，网上大量教程已过期，务必以官方文档和 lm_eval --help 为准。</li><li>复现分数不等于「跑通就有分」：论文分数往往绑定特定 few-shot 数与 prompt 模板，直接跑默认配置得到的结果不能与论文对照；复现前先核对任务在官方仓库中的默认配置，再显式传 --num_fewshot。</li><li>vLLM 后端与 hf 后端数值不是严格相等：不同后端对 logprob 与生成的细节处理略有差异，跨后端比较时要在 artifact 中记录 model 后端字段，避免把实现差异误判为模型退化。</li><li>显存不足时优先加 --limit 做冒烟，全量评测统一用 --batch_size auto 或 vLLM 后端，不要在 0.4.x 上使用旧文档推荐的 --batch_size 1 硬跑大模型。</li></ul>

版本迭代

LM Eval Harness 由 EleutherAI 维护。2024 年 4 月 0.4.0 完成一次破坏性重写：任务从 Python 子类改为 YAML 声明、新增 vLLM/TGI 等高吞吐后端、CLI 与日志体系重建；此后 0.4.x 以任务库扩充与稳定性修复为主。截至训练数据（2025 年初）最新正式版为 0.4.5，可能已有更新版本，请以 GitHub Releases 为准。

AI 应用场景

常见误区

面试题