🧪 Evalchemy

一个统一且易于使用的工具包，用于评估后训练的语言模型

Evalchemy 由 DataComp 社区 和 Bespoke Labs 开发，并基于 LM-Eval-Harness 构建。

🎉 最新动态

[2025.02.24] 新的推理基准测试

• AIME25 和《爱丽丝梦游仙境》已被添加到可用的基准测试中。

[2025.01.30] API 模型支持

• 通过 Curator 的 API 模型：使用 --model curator 参数，现在可以通过 Curator 评估更多基于 API 的模型，包括所有由 LiteLLM 支持的模型。

  python -m eval.eval \
        --model curator  \
        --tasks AIME24,MATH500,GPQADiamond \
        --model_name "gemini/gemini-2.0-flash-thinking-exp-01-21" \
        --apply_chat_template False \
        --model_args 'tokenized_requests=False' \
        --output_path logs

[2025.01.29] 新的推理基准测试

• AIME24、AMC23、MATH500、LiveCodeBench、GPQADiamond、HumanEvalPlus、MBPPPlus、BigCodeBench、MultiPL-E 和 CRUXEval 已被添加到我们不断增长的可用基准测试列表中。这是 Open Thoughts 项目的一部分。请参阅我们的博客文章，了解如何使用 Evalchemy 来评估推理模型。

[2025.01.28] 新的模型支持

• vLLM 模型：采用 PagedAttention 技术的高性能推理和推理服务引擎

python -m eval.eval \
    --model vllm \
    --tasks alpaca_eval \
    --model_args "pretrained=meta-llama/Meta-Llama-3-8B-Instruct" \
    --batch_size 16 \
    --output_path logs

• OpenAI 模型：全面支持 OpenAI 的模型系列

python -m eval.eval \
    --model openai-chat-completions \
    --tasks alpaca_eval \
    --model_args "model=gpt-4o-mini-2024-07-18,num_concurrent=32" \
    --batch_size 16 \
    --output_path logs 

核心功能

• 统一安装：所有基准测试一步到位，消除依赖冲突
• 并行评估：
  • 数据并行：在多张 GPU 上分散评估任务，加快结果生成速度
  • 模型并行：处理单个 GPU 无法容纳的大型模型
• 简化使用：通过一致的命令行界面运行任何基准测试
• 结果管理：
  • 本地结果跟踪，输出格式标准化
  • 可选数据库集成，实现系统化跟踪
  • 排行榜提交功能（需设置数据库）

⚡ 快速入门

安装

建议使用 conda（安装说明）。

# 创建并激活 conda 环境
conda create --name evalchemy python=3.10
conda activate evalchemy

# 克隆仓库
git clone git@github.com:mlfoundations/evalchemy.git   
cd evalchemy

# 安装依赖
pip install -e .
pip install -e eval/chat_benchmarks/alpaca_eval

# 注意：在某些 HPC 系统上，您可能需要修改 pyproject.toml，
# 将 fschat 依赖项的路径改为绝对路径：
# 将："fschat @ file:eval/chat_benchmarks/MTBench"
# 替换为："fschat @ file:///absolute/path/to/evalchemy/eval/chat_benchmarks/MTBench"
# 或者直接移除，并单独运行
# pip install -e eval/chat_benchmarks/MTBench 

# 登录 HuggingFace 以获取数据集和模型。
huggingface-cli login

📚 可用任务

内置基准测试

• 来自 LM Evaluation Harness 的所有任务
• 自定义基于指令的任务（位于 eval/chat_benchmarks/）：

  • MTBench: 多轮对话评估基准

  • WildBench: 真实世界任务评估

  • RepoBench: 代码理解和仓库级任务

  • MixEval: 跨领域的综合评估

  • IFEval: 指令遵循能力评估

  • AlpacaEval: 指令遵循评估

  • HumanEval: 代码生成与问题求解

  • HumanEvalPlus: 包含更多测试用例的 HumanEval

  • ZeroEval: 逻辑推理与问题求解

  • MBPP: Python 编程基准

  • MBPPPlus: 包含更多测试用例的 MBPP

  • BigCodeBench: 针对多样化函数调用和复杂指令的代码生成基准测试

    🚨 警告： 对于 BigCodeBench 的评估，我们强烈建议使用 Docker 容器，因为在主机上执行 LLM 生成的代码可能会导致破坏性后果。更多信息请参见 这里。

  • MultiPL-E: 大型语言模型在多编程语言代码方面的评估

  • CRUXEval: 代码推理、理解和执行评估

  • AIME24: 数学推理数据集

  • AIME25: 数学推理数据集

  • AMC23: 数学推理数据集

  • MATH500: 数学推理数据集，源自 Let's Verify Step by Step

  • LiveCodeBench: LLMs 的代码基准测试

  • LiveBench: 一个专为避免测试集污染并实现客观评估而设计的 LLM 基准

  • GPQA Diamond: 研究生级别的防谷歌问答基准

  • 爱丽丝梦游仙境: 展示 LLM 完全推理失效的简单任务

  • Arena-Hard-Auto（即将推出）：面向指令微调 LLM 的自动评估工具

  • SWE-Bench（即将推出）：评估大型语言模型处理现实软件问题的能力

  • SafetyBench（即将推出）：评估 LLM 的安全性

  • SciCode Bench（即将推出）：评估语言模型生成用于解决实际科学研究问题的代码的能力

  • 伯克利函数调用排行榜（即将推出）：评估 LLM 使用 API 的能力

我们已在 reproduced_benchmarks.md 中记录了这些基准测试的复现结果，并与已发表的数据进行了对比。

基本用法

如果需要使用 LLM 作为评判者，请确保在运行评估之前已在环境中设置好 OPENAI_API_KEY。

python -m eval.eval \
    --model hf \
    --tasks HumanEval,mmlu \
    --model_args "pretrained=mistralai/Mistral-7B-Instruct-v0.3" \
    --batch_size 2 \
    --output_path logs

结果将被写入 output_path 目录中。如果您已安装 jq 下载地址，可以在评估完成后轻松查看结果。例如：jq '.results' logs/Qwen__Qwen2.5-7B-Instruct/results_2024-11-17T17-12-28.668908.json

参数说明：

• --model: 指定要评估的模型类型或提供商（例如：hf）
• --tasks: 以逗号分隔的任务列表，表示要评估的基准测试
• --model_args: 模型路径及参数。以逗号分隔的参数列表，传递给模型构造函数。格式为 "arg1=val1,arg2=val2,..."。支持的参数列表可在 此处 查看。
• --batch_size: 推理时的批处理大小
• --output_path: 保存评估结果的目录

示例：运行多个基准测试：

python -m eval.eval \
    --model hf \
    --tasks MTBench,WildBench,alpaca_eval \
    --model_args "pretrained=mistralai/Mistral-7B-Instruct-v0.3" \
    --batch_size 2 \
    --output_path logs

配置快捷方式：

为了能够重复使用常用设置，而无需每次都手动提供完整参数，我们支持从 YAML 文件中读取评估配置。这些配置文件可以替代 --batch_size、--tasks 和 --annotator_model 参数。一些示例配置文件位于 ./configs 目录中。要使用这些配置文件，可以使用 --config 标志，如下所示：

python -m eval.eval \
    --model hf \
    --model_args "pretrained=mistralai/Mistral-7B-Instruct-v0.3" \
    --output_path logs \
    --config configs/light_gpt4omini0718.yaml

我们在 eval/examples 中添加了更多命令示例，帮助您快速上手 Evalchemy。

🔧 高级用法

对不同模型的支持

通过 LM-Eval-Harness，我们支持所有 HuggingFace 模型，并且目前正在增加对 OpenAI 和 VLLM 等其他 LM-Eval-Harness 支持的模型的支持。有关这些模型的更多信息，请访问 模型页面。

要选择模型，只需设置 pretrained=<HuggingFace 模型名称>，其中模型名称可以是 HuggingFace 官方模型名，也可以是本地模型的路径。

HPC 分布式评估

为了获得更快的评估速度，可以使用完全的数据并行，并为每块 GPU 启动一个 vLLM 进程。

我们还使这一过程在 HPC（高性能计算）集群上的多节点环境中大规模执行变得非常简单：

python eval/distributed/launch.py --model_name <model_id> --tasks <task_list> --num_shards <n> --watchdog

关键特性：

• 在多个计算节点上并行运行评估
• 极大地缩短大型基准测试的墙钟时间
• 支持离线模式，适用于 GPU 节点上无互联网连接的环境
• 自动集群检测与配置
• 高效的结果收集与评分

更多详细信息请参阅 分布式 README。

注意：此配置针对特定的 HPC 集群，但可以轻松调整。此外，也可以通过使用 CUDA_VISIBLE_DEVICES 代替 SLURM 作业数组来适应非 HPC 环境。

多 GPU 评估

注意：这比完全数据并行评估（见上一节）要慢。

accelerate launch --num-processes <num-gpus> --num-machines <num-nodes> \
    --multi-gpu -m eval.eval \
    --model hf \
    --tasks MTBench,alpaca_eval \
    --model_args 'pretrained=mistralai/Mistral-7B-Instruct-v0.3' \
    --batch_size 2 \
    --output_path logs

大模型评估

对于无法容纳在单个 GPU 上的模型，请使用模型并行：

python -m eval.eval \
    --model hf \
    --tasks MTBench,alpaca_eval \
    --model_args 'pretrained=mistralai/Mistral-7B-Instruct-v0.3,parallelize=True' \
    --batch_size 2 \
    --output_path logs

💡 注意：虽然支持“自动”批大小，但我们建议手动调整批大小以获得最佳性能。最优批大小取决于模型大小、GPU 内存以及具体基准测试。我们在 8 块 H100 GPU 上评估 Llama-3-8B-Instruct 时，最大批大小设为 32，最小批大小设为 4（用于 RepoBench）。

输出日志结构

我们生成的日志包含了每次评估的关键信息，有助于指导您的实验。以下是我们日志中突出显示的重要内容：

• 模型配置
  • model: 使用的模型框架
  • model_args: 模型框架的参数
  • batch_size: 处理批次大小
  • device: 计算设备规格
  • annotator_model: 用于标注的模型（例如 “gpt-4o-mini-2024-07-18”）
• 随机种子配置
  • random_seed: 通用随机种子
  • numpy_seed: NumPy 特定的种子
  • torch_seed: PyTorch 特定的种子
  • fewshot_seed: 少样本示例的种子
• 模型详情
  • model_num_parameters: 模型参数数量
  • model_dtype: 模型数据类型
  • model_revision: 模型版本
  • model_sha: 模型提交哈希值
• 版本控制
  • git_hash: 仓库提交哈希值
  • date: 评估的 Unix 时间戳
  • transformers_version: Hugging Face Transformers 版本
• 分词器配置
  • tokenizer_pad_token: 填充标记详情
  • tokenizer_eos_token: 句子结束标记
  • tokenizer_bos_token: 句子开始标记
  • eot_token_id: 文本结束标记 ID
  • max_length: 最大序列长度
• 模型设置
  • model_source: 模型来源平台
  • model_name: 完整的模型标识符
  • model_name_sanitized: 用于文件系统的清理后模型名称
  • chat_template: 对话模板
  • chat_template_sha: 模板哈希值
• 计时信息
  • start_time: 评估开始时间戳
  • end_time: 评估结束时间戳
  • total_evaluation_time_seconds: 总耗时
• 硬件环境
  • PyTorch 版本及构建配置
  • 操作系统详情
  • GPU 配置
  • CPU 规格
  • CUDA 和驱动程序版本
  • 相关库版本

自定义评估

🤖 更改标注模型

作为 Evalchemy 的一部分，我们希望在标准基准测试中轻松更换不同的语言模型评判者。目前，我们支持两种评判者设置。第一种是默认设置，即使用基准测试的默认评判者。要激活此设置，您可以什么都不做，或者传递以下参数：

--annotator_model auto

除了默认设置外，我们还支持使用 gpt-4o-mini-2024-07-18 作为评判者：

--annotator_model gpt-4o-mini-2024-07-18

我们计划在未来添加对不同评判者的支持！

⏱️ 运行时间和成本分析

Evalchemy 使得运行常见基准测试变得简单、快速且灵活！我们列出了使用 Evalchemy 在 8 块 H100 GPU 上对 Meta-Llama-3-8B-Instruct 进行评估时，各项基准测试的速度和成本。

基准测试	运行时间（8xH100）	批次大小	总令牌数	默认评判者成本 ($)	gpt-4o-mini 评判者成本 ($)	备注
MTBench	14:00	32	~196K	6.40	0.05
WildBench	38:00	32	~2.2M	30.00	0.43
RepoBench	46:00	4	~23K	-	-	由于内存限制，批次较小
MixEval	13:00	32	~4-6M	3.36	0.76	根据评判者模型而异
AlpacaEval	16:00	32	~936K	9.40	0.14
HumanEval	4:00	32	~300	-	-	无 API 费用
IFEval	1:30	32	~550	-	-	无 API 费用
ZeroEval	1:44:00	32	~8K	-	-	运行时间最长
MBPP	6:00	32	500	-	-	无 API 费用
MMLU	7:00	32	500	-	-	无 API 费用
ARC	4:00	32	-	-	-	无 API 费用
DROP	20:00	32	-	-	-	无 API 费用

备注：

• 运行时间是在 8 块 H100 GPU 上使用 Meta-Llama-3-8B-Instruct 模型测得的。
• 批次大小已针对内存和速度进行了优化。
• API 费用因选择的评判者模型而异。

省费提示：

• 尽可能使用 gpt-4o-mini-2024-07-18 评判者以显著节省成本。
• 根据可用内存调整批次大小。
• 考虑使用数据并行评估以获得更快的结果。

🔐 特殊访问要求

ZeroEval 访问

要运行 ZeroEval 基准测试，您需要：

1. 在 Hugging Face 上申请访问 ZebraLogicBench-private 数据集
2. 接受条款和条件
3. 在运行评估时登录您的 Hugging Face 账户

🛠️ 实现自定义评估

要添加新的评估系统：

1. 在 eval/chat_benchmarks/ 下创建一个新的目录。
2. 实现 eval_instruct.py，其中包含两个必需的函数：
   • eval_instruct(model): 接受 LM 评估模型，返回结果字典。
   • evaluate(results): 接受结果字典，返回评估指标。

添加外部评估代码库

使用 git subtree 来管理外部评估代码：

# 添加外部代码库
git subtree add --prefix=eval/chat_benchmarks/new_eval https://github.com/original/repo.git main --squash

# 拉取更新
git subtree pull --prefix=eval/chat_benchmarks/new_eval https://github.com/original/repo.git main --squash

# 将贡献推回
git subtree push --prefix=eval/chat_benchmarks/new_eval https://github.com/original/repo.git contribution-branch

🔍 调试模式

要在调试模式下运行评估，请添加 --debug 标志：

python -m eval.eval \
    --model hf \
    --tasks MTBench \
    --model_args "pretrained=mistralai/Mistral-7B-Instruct-v0.3" \
    --batch_size 2 \
    --output_path logs \
    --debug

这在测试新的评估实现、调试模型配置、验证数据集访问权限以及测试数据库连接时特别有用。

🚀 性能提示

1. 利用批处理以加快评估速度：

all_instances.append(
    Instance(
        "generate_until",
        example,
        (
            inputs,
            {
                "max_new_tokens": 1024,
                "do_sample": False,
            },
        ),
        idx,
    )
)

outputs = self.compute(model, all_instances)

2. 使用 LM-eval 日志记录器，以确保跨评估的日志一致性。

🔧 故障排除

Evalchemy 已在 CUDA 12.4 上进行了测试。如果您遇到类似以下问题：undefined symbol: __nvJitLinkComplete_12_4, version libnvJitLink.so.12，请尝试更新您的 CUDA 版本：

wget https://developer.download.nvidia.com/compute/cuda/repos/debian11/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo add-apt-repository contrib
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-4

🏆 排行榜集成

为了跟踪实验和评估结果，我们支持将结果记录到 PostgreSQL 数据库中。有关条目模式和数据库设置的详细信息，请参阅 database/。

贡献

感谢所有为使该项目成为可能而做出贡献的开发者！ 请按照 这些说明 来了解如何参与贡献。

引用

如果您觉得 Evalchemy 有用，请考虑引用我们！

@software{Evalchemy: 自动化的大语言模型评估工具，
  author = {Raoof, Negin 和 Guha, Etash Kumar 和 Marten, Ryan 和 Mercat, Jean 和 Frankel, Eric 和 Keh, Sedrick 和 Bansal, Hritik 和 Smyrnis, Georgios 和 Nezhurina, Marianna 和 Vu, Trung 和 Sprague, Zayne Rea 和 Merrill, Mike A 和 Chen, Liangyu 和 Choi, Caroline 和 Khan, Zaid 和 Grover, Sachin 和 Feuer, Benjamin 和 Suvarna, Ashima 和 Su, Shiye 和 Zhao, Wanjia 和 Sharma, Kartik 和 Ji, Charlie Cheng-Jie 和 Arora, Kushal 和 Li, Jeffrey 和 Gokaslan, Aaron 和 Pratt, Sarah M 和 Muennighoff, Niklas 和 Saad-Falcon, Jon 和 Yang, John 和 Aali, Asad 和 Pimpalgaonkar, Shreyas 和 Albalak, Alon 和 Dave, Achal 和 Pouransari, Hadi 和 Durrett, Greg 和 Oh, Sewoong 和 Hashimoto, Tatsunori 和 Shankar, Vaishaal 和 Choi, Yejin 和 Bansal, Mohit 和 Hegde, Chinmay 和 Heckel, Reinhard 和 Jitsev, Jenia 和 Sathiamoorthy, Maheswaran 和 Dimakis, Alex 和 Schmidt, Ludwig}
  month = 六月,
  title = {{Evalchemy}},
  year = {2025}
}

Evalchemy 快速上手指南

Evalchemy 是一个统一且易用的工具包，专为评估后训练语言模型（Post-trained LLMs）而设计。它由 DataComp 社区和 Bespoke Labs 开发，基于 LM-Eval-Harness 构建，支持多种基准测试、并行评估及结果管理。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐) 或 macOS。
• Python 版本: 3.10 (强烈建议使用 Conda 管理环境)。
• 依赖工具:
  • Conda (用于环境隔离)
  • Git (用于克隆代码库)
  • Hugging Face CLI (用于下载模型和数据集)
• 硬件: 至少一张 NVIDIA GPU (用于本地模型推理)。若评估需要 LLM 作为裁判（如 AlpacaEval），需配置 OPENAI_API_KEY。

国内开发者提示：若访问 Hugging Face 或 GitHub 较慢，建议配置镜像源或使用代理加速。

• pip 镜像：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...
• Hugging Face 镜像：设置环境变量 export HF_ENDPOINT=https://hf-mirror.com

安装步骤

推荐使用 Conda 创建独立环境以避免依赖冲突。

1. 创建并激活 Conda 环境

   conda create --name evalchemy python=3.10
   conda activate evalchemy
   

2. 克隆仓库

   git clone git@github.com:mlfoundations/evalchemy.git   
   cd evalchemy
   

3. 安装核心依赖

   # 安装主包
   pip install -e .
   
   # 安装聊天基准测试依赖 (如 AlpacaEval)
   pip install -e eval/chat_benchmarks/alpaca_eval
   

   注意：在某些高性能计算 (HPC) 系统中，若遇到 fschat 路径问题，可能需要手动修改 pyproject.toml 使用绝对路径，或单独运行 pip install -e eval/chat_benchmarks/MTBench。

4. 登录 Hugging Face 您需要登录以下载受保护的模型和数据集：

   huggingface-cli login
   

   (按提示输入您的 Access Token)

5. (可选) 配置 API Key 如果运行的基准测试需要调用外部 API 进行评判（例如使用 GPT-4 作为裁判）：

   export OPENAI_API_KEY="your-api-key-here"
   

基本使用

安装完成后，您可以使用统一的命令行接口运行评估。以下是最基础的用法示例。

运行单个基准测试

以下命令使用 Hugging Face 模型 (mistralai/Mistral-7B-Instruct-v0.3) 在 HumanEval (代码生成) 和 mmlu (知识问答) 基准上进行评估：

python -m eval.eval \
    --model hf \
    --tasks HumanEval,mmlu \
    --model_args "pretrained=mistralai/Mistral-7B-Instruct-v0.3" \
    --batch_size 2 \
    --output_path logs

参数说明：

• --model: 模型类型，hf 代表 Hugging Face 模型。
• --tasks: 要评估的任务列表，用逗号分隔。
• --model_args: 模型路径及参数。pretrained 可以是 Hugging Face 模型 ID 或本地路径。
• --batch_size: 推理批大小，根据显存大小调整。
• --output_path: 结果保存目录。

查看结果

评估完成后，结果将以 JSON 格式保存在 output_path 指定的目录中。如果您安装了 jq 工具，可以快速查看结果摘要：

# 示例：查看最新生成的结果文件中的 results 字段
jq '.results' logs/Qwen__Qwen2.5-7B-Instruct/results_*.json

使用预设配置文件 (简化操作)

为了避免每次输入冗长的参数，Evalchemy 支持通过 YAML 文件加载常用配置（位于 ./configs 目录）：

python -m eval.eval \
    --model hf \
    --model_args "pretrained=mistralai/Mistral-7B-Instruct-v0.3" \
    --output_path logs \
    --config configs/light_gpt4omini0718.yaml

支持的其他模型类型

除了本地 Hugging Face 模型，Evalchemy 还支持通过参数切换其他后端：

• vLLM (高性能推理):

  python -m eval.eval \
      --model vllm \
      --tasks alpaca_eval \
      --model_args "pretrained=meta-llama/Meta-Llama-3-8B-Instruct" \
      --batch_size 16 \
      --output_path logs
  

• OpenAI API 模型:

  python -m eval.eval \
      --model openai-chat-completions \
      --tasks alpaca_eval \
      --model_args "model=gpt-4o-mini-2024-07-18,num_concurrent=32" \
      --batch_size 16 \
      --output_path logs 
  

• Curator (支持更多 API 模型，如 Gemini):

  python -m eval.eval \
        --model curator  \
        --tasks AIME24,MATH500,GPQADiamond \
        --model_name "gemini/gemini-2.0-flash-thinking-exp-01-21" \
        --apply_chat_template False \
        --model_args 'tokenized_requests=False' \
        --output_path logs
  

更多高级用法（如多卡并行、分布式集群评估）请参考项目官方文档。