AB
AB
AiBoss

すべてのカテゴリ

チュートリアル

AGI-Eval

チュートリアル

用 AGI-Eval 搭建环境并跑通第一个模型评测任务

AGI-Eval 是一个开源的大模型评测框架，提供命令行工具 agieval，可对已适配的公开数据集或自定义数据集发起评测，并把过程与结果可视化。本文从 conda 环境搭建、源码安装、数据集准备、模型 API 配置讲到启动评测与查看结果，给出可直接照抄的命令与一个端到端的最小示例。

AGI-Eval 是一个面向大模型评测的开源框架，它把「准备数据集、调用待评测模型、调用打分模型、汇总结果、可视化查看」这几件事收进了一套命令行工具里。安装完成后，所有操作都通过 agieval 命令发起，不需要自己写评测脚本。它适合两类人：一类是手上有模型 API、想快速在公开数据集上拿到一份评测结果的工程师；另一类是需要把自有数据集接进统一评测流程、或者想通过插件体系定制指标与流程的开发者。如果你只是想先跑通一次评测，可以配合站内的 AGI-Eval 工具页对照着看本文的步骤。

下面按「环境 → 数据 → 模型 → 启动评测 → 看结果」的顺序展开，每一步都给出实际要执行的命令。文中涉及的具体数据集清单、插件依赖、模型服务地址等，请以项目当前的实际输出与官方说明为准。

准备工作

Python 与包管理环境

框架要求 Python 3.11 或更高版本。官方建议用 conda 管理 Python 环境，这样可以避免和系统里已有的 Python 包互相干扰。如果你的机器上已经有隔离好的 Python 3.11+ 环境，也可以跳过虚拟环境这一步，直接进入源码安装。

创建并激活环境：

# Python 版本要求 3.11 或更高
conda create --name agieval python=3.11 -y
conda activate agieval

环境名 agieval 只是示例，可以换成你自己的命名。激活之后，后续所有命令都在这个环境里执行。

获取源码并安装

框架以源码方式安装，先克隆仓库再以可编辑模式安装：

git clone https://github.com/AGI-Eval-Official/agi-eval.git
cd agi-eval
# 安装 Native backend
pip install -e .

pip install -e . 安装的是框架运行的必需依赖，同时会把 agieval 命令行工具装进当前环境。安装完成后可以用 agieval 命令调用框架能力，具体子命令的完整说明见命令行工具相关文档。

可选依赖与插件依赖

框架核心的插件体系允许用户自定义插件实现。插件需要的依赖不必写进主安装流程，而是作为可选依赖放在插件依赖文件 requirements.json 中。这个文件在对应插件第一次被加载使用时自动安装，因此你不需要手动 pip 安装插件依赖。

文件内容是 JSON 格式，key 是插件所在的 module，value 是依赖列表，列表里可以指定版本号和安装源。例如：

{
  "agieval.plugin.metrics.drop_f1_metrics": [
    "scipy>=1.16.0 -i https://mirrors.aliyun.com/pypi/simple/"
  ]
}

上面这个例子里，agieval.plugin.metrics.drop_f1_metrics 是插件模块路径，数组中是它需要的 scipy 及其版本约束，后面跟的 -i 参数指定了安装源。写这个文件时要注意：key 必须和插件实际所在的 module 一致，否则依赖不会被正确关联；版本约束和安装源都写在 value 的字符串里，和直接写 pip 命令时的写法一致。

模型 API 的前置条件

框架目前仅支持通过 litellm 调用 API 进行评测，因此待评测的模型必须能通过支持 OpenAI API 协议的服务访问。如果你的模型已经部署在兼容 OpenAI API 协议的服务上，可以直接使用；如果不是，需要先把它包装成兼容该协议的服务，再接入框架。

评测过程涉及两类模型，需要分别配置：

  • 待评测模型：被评测的对象，框架把数据集里的题目发给它并收集回答。
  • 打分模型：用于对回答进行评判的模型，部分评测方式需要它参与打分。

两类模型各自需要三项参数：服务地址、模型名称、API Key。这些参数通过环境变量传入，具体变量名在下一节给出。

操作步骤

第一步：确认环境可用

激活 conda 环境后，先确认 agieval 命令已经可用。如果提示找不到命令，通常是 pip install -e . 没有在正确的环境里执行，或者环境没有激活。回到源码目录、确认当前 Python 版本满足 3.11+ 后重新安装即可。

第二步：查看并准备数据集

框架已经适配了一部分公开数据集，可以直接使用。查看当前支持的数据集列表：

agieval benchmarks

这条命令会输出框架已适配的数据集清单。首次评测某个公开数据集时，框架会自动把数据文件下载到本地的 datasets 目录下，不需要手动下载和放置。因此第一次运行会比后续运行慢一些，需要保证机器能访问数据源。

如果你要评测的数据集不在列表里，有两条路可走：一是查看公开数据集相关文档，了解如何把新的公开数据集适配进来；二是直接适配自定义数据集，框架支持对任意格式的数据集进行评测。数据集适配属于开发工作，需要按照框架约定的格式组织数据，具体格式要求见适配数据集相关文档。

第三步：配置模型参数

通过环境变量配置待评测模型与打分模型。示例命令如下：

# 待评测模型
export API_BASE_URL=http://your-api-endpoint
export MODEL_NAME=your-model-name
export API_KEY=your-api-key

# 打分模型
export SCORE_API_BASE_URL=http://your-api-endpoint
export SCORE_MODEL_NAME=your-model-name
export SCORE_API_KEY=your-api-key

把 http://your-api-endpoint 换成你的模型服务地址，your-model-name 换成服务端实际可用的模型名称，your-api-key 换成对应的密钥。待评测模型和打分模型可以是同一个服务、同一个模型，也可以是不同的服务和模型，取决于你的评测设计。两组变量都要配置，缺少打分模型相关变量时，需要打分模型参与的评测环节会无法完成。

这些环境变量只在当前 shell 会话中有效。换一个终端窗口或重新登录后需要重新 export，或者把它们写进 shell 的启动配置文件里。

第四步：启动评测任务

参数配置完成后，执行启动命令：

agieval start test

这条命令会启动一个名为 test 的评测任务。任务启动后，框架会按调度中心的安排，把数据集中的样本分发给待评测模型，收集回答，再按评测方式调用打分模型或指标插件完成评判。评测过程与结果会写入结果目录，示例中的结果目录是 result/test。

启动评测的更详细参数说明见开始评测相关文档。如果你需要指定数据集、并发度、结果输出位置等，应查阅该文档确认可用的参数，不要凭猜测传参。

第五步：启动可视化服务查看结果

评测跑完后，用下面的命令启动结果可视化服务：

agieval appstart --result_dir=result/test

其中 --result_dir 指向评测任务的结果目录，需要和第四步实际使用的结果目录保持一致。服务启动后，可以在界面中查看评测过程与结果。可视化服务读取的是结果目录里的数据，所以如果换了任务名或结果目录，这条命令的参数也要跟着改。

一个完整示例

下面把上面的步骤串成一个从头到尾可执行的最小流程。假设你已经有一份兼容 OpenAI API 协议的模型服务，地址、模型名、密钥都已就绪。

1. 创建并激活环境

conda create --name agieval python=3.11 -y
conda activate agieval

2. 拉取源码并安装

git clone https://github.com/AGI-Eval-Official/agi-eval.git
cd agi-eval
pip install -e .

3. 查看可用数据集

agieval benchmarks

从输出中挑一个你想评测的数据集。首次评测该数据集时，框架会自动下载数据到本地 datasets 目录。

4. 配置待评测模型与打分模型

export API_BASE_URL=http://your-api-endpoint
export MODEL_NAME=your-model-name
export API_KEY=your-api-key

export SCORE_API_BASE_URL=http://your-api-endpoint
export SCORE_MODEL_NAME=your-model-name
export SCORE_API_KEY=your-api-key

5. 启动评测

agieval start test

等待任务执行完成。首次运行因为要下载数据集，耗时会比后续运行长。

6. 查看结果

agieval appstart --result_dir=result/test

在可视化界面中查看这次评测的过程与结果。至此，一个完整的评测闭环就跑通了。之后再评测其他数据集，只需要重复第 3 步到第 6 步，环境不需要重新搭建。

注意事项

  • Python 版本是硬性门槛。框架要求 Python 3.11 或更高版本，低于这个版本无法正常安装和运行。
  • 模型服务必须兼容 OpenAI API 协议。框架目前仅支持通过 litellm 调用 API 进行评测，不兼容该协议的服务无法直接接入。
  • 待评测模型和打分模型要分别配置。两组环境变量缺一不可，只配置待评测模型会导致需要打分模型的评测环节无法完成。
  • 环境变量只在当前会话有效。新开终端后需要重新 export，否则评测任务读不到模型配置。
  • 首次评测公开数据集会自动下载。数据文件落在本地 datasets 目录，需要保证网络可达；下载失败时后续步骤无法进行。
  • 插件依赖是延迟安装的。写在 requirements.json 里的依赖在插件第一次被加载使用时才自动安装，因此第一次使用某个插件时可能比之后慢，且需要能访问指定的安装源。
  • 结果目录要与可视化命令对应。agieval appstart --result_dir=... 的参数必须指向实际产生的结果目录，否则看不到对应任务的数据。
  • 数据集适配属于开发工作。公开数据集之外的任意格式数据集需要按框架约定适配后才能评测，适配前建议先确认数据格式要求。

框架支持很大程度的定制化开发能力，包括调度中心、插件系统与配置管理几个核心模块。跑通基础评测之后，如果需要自定义指标、调整调度策略或接入自有数据集，可以继续阅读插件开发指南与适配数据集相关文档。遇到问题或想提建议，可以通过项目仓库的 Issue 与讨论渠道反馈。文中涉及的功能范围、数据集清单与依赖版本，请以项目当前的实际信息为准。

戻る