OpenCompass 快速开始:模型评测的配置、推理、评估与可视化全流程指南

原创2026-09-28 09:54:361,852 阅读
文章标签:人工智能大模型模型评测AI 评测排行榜机器学习深度学习开发者工具

OpenCompass 快速开始:模型评测的配置、推理、评估与可视化全流程指南

本文以 OpenCompass 官方中文快速开始文档(docs/zh_cn/get_started/quick_start.md)为骨架,结合仓库源码与真实配置文件,系统讲解如何在 OpenCompass 中完成一次完整的模型评测:从理解"配置 -> 推理 -> 评估 -> 可视化"四阶段工作流,到用命令行或配置文件组织评测任务,再到启动并行评估、查看结果表格与输出目录结构。读完本文,你将能够独立用 OpenCompass 评测 HuggingFace 基座模型与对话模型,并掌握调试、复用、任务调度等进阶操作。

评估工作流概览:配置、推理、评估、可视化

在 OpenCompass 中评估一个模型通常包括四个阶段:

  • 配置(Configure):整个工作流的起点。你需要配置整个评估过程,选择要评估的模型和数据集,还可以选择评估策略、计算后端,并定义结果展示方式。
  • 推理与评估(Inference & Evaluation):OpenCompass 会对模型和数据集进行并行推理与评估。推理阶段让模型基于数据集产生输出,评估阶段衡量这些输出与标准答案的匹配程度。为提升效率,这两个过程会被拆分为多个同时运行的"任务",但要注意:如果计算资源有限,这种并行拆分策略反而可能让评测更慢。关于该问题的成因与解决方案,可参考 FAQ: 效率。
  • 可视化(Visualization):评估完成后,OpenCompass 将结果整理成易读的表格,并保存为 CSV 和 TXT 文件。你也可以激活飞书(Lark)状态上报功能,在飞书客户端中实时获得评测状态报告。

从源码看,这一工作流由 run.py 统一驱动,它只做一件事:调用 opencompass/cli/main.py 中的 main() 入口,由入口解析命令行参数、组装配置、调度任务。因此,run.py 是理解整个评测入口的关键文件。

环境准备与本次实验目标

运行本文示例前,请确保已在本地安装 OpenCompass,完整安装步骤见 安装指南。本次实验将在 一张 GTX-1660-6G GPU 上评估三个小规模模型:

模型类型 模型 评估数据集
基座模型 internlm/internlm2-1_8b GSM8K、MATH(下采样)
对话模型 internlm/internlm2-chat-1_8b、Qwen/Qwen2-1.5B-Instruct GSM8K、MATH(下采样)

它们的配置文件分别位于 examples/eval_base_demo.py 与 examples/eval_chat_demo.py。对于参数量更大的模型(如 Llama3-8B),可参考 opencompass/configs/models 目录下的其他示例配置。

这里提到的数据集实际上是 demo 采样版本。以 demo_gsm8k_chat_gen.py 为例,其内部通过继承机制引入完整 GSM8K 配置后,做了两处修改:

gsm8k_datasets[0]['abbr'] = 'demo_' + gsm8k_datasets[0]['abbr']
gsm8k_datasets[0]['reader_cfg']['test_range'] = '[0:64]'

即把数据集缩写加上 demo_ 前缀,并通过 test_range='[0:64]' 只读取前 64 条样本,从而在低算力环境下快速跑通全流程。这正是 demo 数据集与完整数据集(如 gsm8k_gen_1d7fe4)之间的本质区别。

配置评估任务:三种方式

在 OpenCompass 中,每个评估任务由"待评估的模型 + 数据集"组成,入口为 run.py。用户可以通过命令行或配置文件选择要测试的模型和数据集。下文分别给出三种配置方式,并给出对话模型与基座模型各自对应的命令。

方式一:命令行直接指定自定义 HF 模型

对于 HuggingFace 模型,用户可以不写任何配置文件,直接在命令行设置模型参数。例如评估对话模型 internlm/internlm2-chat-1_8b:

python run.py \
    --datasets demo_gsm8k_chat_gen demo_math_chat_gen \
    --hf-type chat \
    --hf-path internlm/internlm2-chat-1_8b \
    --debug

评估基座模型 internlm/internlm2-1_8b:

python run.py \
    --datasets demo_gsm8k_base_gen demo_math_base_gen \
    --hf-type base \
    --hf-path internlm/internlm2-1_8b \
    --debug

注意:通过这种方式,OpenCompass 一次只评估一个模型,而另外两种方式可以一次评估多个模型。

run.py 支持的 HF 模型相关完整参数如下表(可在 opencompass/cli/main.py 的 hf_parser 中逐一找到对应实现):

命令行参数 描述 样例数值
--hf-type HuggingFace 模型类型,可选 chat 或 base chat
--hf-path HuggingFace 模型路径 internlm/internlm2-chat-1_8b
--model-kwargs 构建模型的参数 device_map='auto'
--tokenizer-path HuggingFace tokenizer 路径(与模型路径相同时可省略) internlm/internlm2-chat-1_8b
--tokenizer-kwargs 构建 tokenizer 的参数 padding_side='left' truncation='left' trust_remote_code=True
--generation-kwargs 生成参数 do_sample=True top_k=50 top_p=0.95
--max-seq-len 模型可接受的最大序列长度 2048
--max-out-len 生成的最大 token 数(源码默认值 256) 100
--min-out-len 生成的最小 token 数 1
--batch-size 批量大小 64
--hf-num-gpus 运行一个模型实例所需的 GPU 数量(源码默认值 1) 1
--stop-words 停用词列表 '<|im_end|>' '<|im_start|>'
--pad-token-id 填充 token 的 ID 0
--peft-path (例如)LoRA 模型的路径 internlm/internlm2-chat-1_8b
--peft-kwargs (例如)构建 LoRA 模型的参数 trust_remote_code=True

一个更复杂的命令样例:占用 2 卡测试 Qwen1.5-14B-Chat,开启数据采样(do_sample=True)并设置温度:

python run.py --datasets demo_gsm8k_chat_gen demo_math_chat_gen \
    --hf-type chat \
    --hf-path Qwen/Qwen1.5-14B-Chat \
    --max-out-len 1024 \
    --min-out-len 1 \
    --hf-num-gpus 2 \
    --generation-kwargs do_sample=True temperature=0.6 \
    --stop-words '<|im_end|>' '<|im_start|>' \
    --debug

需要说明的是,原文档中"基座模型更复杂命令样例"一节把 --hf-type 误写为 chat,实际评测基座模型时应使用 --hf-type base,其余参数含义一致。

方式二:命令行组合预置配置(--models / --datasets)

OpenCompass 将模型与数据集的配置以 Python 文件形式预存在 opencompass/configs/models 与 opencompass/configs/datasets 中。用户可以用 --models 和 --datasets 组合想要测试的模型与数据集:

python run.py \
    --models hf_internlm2_chat_1_8b hf_qwen2_1_5b_instruct \
    --datasets demo_gsm8k_chat_gen demo_math_chat_gen \
    --debug

基座模型对应:

python run.py \
    --models hf_internlm2_1_8b hf_qwen2_1_5b \
    --datasets demo_gsm8k_base_gen demo_math_base_gen \
    --debug

如何知道有哪些可用配置?使用 tools/list_configs.py 查看或过滤:

# 列出所有配置
python tools/list_configs.py
# 列出与 llama 和 mmlu 相关的所有配置
python tools/list_configs.py llama mmlu

运行 python tools/list_configs.py llama mmlu 将产生如下输出:

+-----------------+-----------------------------------+
| Model           | Config Path                       |
|-----------------+-----------------------------------|
| hf_llama2_13b   | configs/models/hf_llama2_13b.py   |
| hf_llama2_70b   | configs/models/hf_llama2_70b.py   |
| ...             | ...                               |
+-----------------+-----------------------------------+
+-------------------+---------------------------------------------------+
| Dataset           | Config Path                                       |
|-------------------+---------------------------------------------------|
| cmmlu_gen         | configs/datasets/cmmlu/cmmlu_gen.py               |
| cmmlu_gen_ffe7c0  | configs/datasets/cmmlu/cmmlu_gen_ffe7c0.py        |
| ...               | ...                                               |
+-------------------+---------------------------------------------------+

从源码看,list_configs.py 内部用 match_files('opencompass/configs/models/', pattern, fuzzy=True) 与 match_files('opencompass/configs/datasets/', pattern, fuzzy=True) 做模糊匹配,并以 tabulate 输出两张表格。用户可以使用第一列的名称作为 run.py 中 --models 与 --datasets 的输入参数。对数据集而言,同名不同后缀通常表示其 Prompt 或评估方法不同(例如 cmmlu_gen_ffe7c0 是带哈希后缀的固定版本配置)。

如果你要评估的模型不在列表中,有两种出路:一是参考"方式一"用命令行自定义 HF 模型;二是参考下文"方式三"用配置文件准备模型配置。

方式三:配置文件 + 继承机制

除了命令行,OpenCompass 允许在配置文件中编写实验的完整配置,并通过 run.py 直接运行。配置文件以 Python 格式组织,必须包含 datasets 和 models 字段。

本次对话模型测试的配置在 examples/eval_chat_demo.py 中,通过继承机制引入所需的数据集与模型配置,并按要求组合字段:

from mmengine.config import read_base

with read_base():
    from .datasets.demo.demo_gsm8k_chat_gen import gsm8k_datasets
    from .datasets.demo.demo_math_chat_gen import math_datasets
    from .models.qwen.hf_qwen2_1_5b_instruct import models as hf_qwen2_1_5b_instruct_models
    from .models.hf_internlm.hf_internlm2_chat_1_8b import models as hf_internlm2_chat_1_8b_models

datasets = gsm8k_datasets + math_datasets
models = hf_qwen2_1_5b_instruct_models + hf_internlm2_chat_1_8b_models

基座模型配置在 examples/eval_base_demo.py:

from mmengine.config import read_base

with read_base():
    from .datasets.demo.demo_gsm8k_base_gen import gsm8k_datasets
    from .datasets.demo.demo_math_base_gen import math_datasets
    from .models.qwen.hf_qwen2_1_5b import models as hf_qwen2_1_5b_models
    from .models.hf_internlm.hf_internlm2_1_8b import models as hf_internlm2_1_8b_models

datasets = gsm8k_datasets + math_datasets
models = hf_qwen2_1_5b_models + hf_internlm2_1_8b_models

运行任务时,只需把配置文件路径传给 run.py:

python run.py examples/eval_chat_demo.py --debug
python run.py examples/eval_base_demo.py --debug

配置文件之所以能写成相对导入,得益于 OpenCompass 基于 mmengine 的 read_base() 继承机制:被导入的模块本质上是"基础配置",导入后其中的 models / datasets 列表会被展开合并。注意,仓库中 examples/ 下的实际实现为 from opencompass.configs.datasets... 的绝对导入写法,二者等价,均可运行。

深入理解模型与数据集配置

模型配置:对话模板与基座模型

OpenCompass 在 opencompass/configs/models 下提供了一系列预定义模型配置。与 InternLM2-Chat-1.8B 对应的配置片段(hf_internlm2_chat_1_8b.py)如下:

# 使用 HuggingFacewithChatTemplate 评估由 HuggingFace AutoModelForCausalLM 支持的对话模型
from opencompass.models import HuggingFacewithChatTemplate

models = [
    dict(
        type=HuggingFacewithChatTemplate,
        abbr='internlm2-chat-1.8b-hf',         # 模型的缩写
        path='internlm/internlm2-chat-1_8b',   # 模型的 HuggingFace 路径
        max_out_len=1024,                      # 生成的最大 token 数
        batch_size=8,                          # 批量大小
        run_cfg=dict(num_gpus=1),              # 该模型所需的 GPU 数量
    )
]

与 InternLM2-1.8B 基座模型对应的配置片段(hf_internlm2_1_8b.py):

# 使用 HuggingFaceBaseModel 评估由 HuggingFace AutoModelForCausalLM 支持的基座模型
from opencompass.models import HuggingFaceBaseModel

models = [
    dict(
        type=HuggingFaceBaseModel,
        abbr='internlm2-1.8b-hf',              # 模型的缩写
        path='internlm/internlm2-1_8b',        # 模型的 HuggingFace 路径
        max_out_len=1024,                      # 生成的最大 token 数
        batch_size=8,                          # 批量大小
        run_cfg=dict(num_gpus=1),              # 该模型所需的 GPU 数量
    )
]

两处配置的关键差异在 type 字段:对话模型使用 HuggingFacewithChatTemplate(自动套用对话模板与停止词),基座模型使用 HuggingFaceBaseModel。其余字段通用:abbr 是展示缩写(会出现在最终结果表中),path 是 HuggingFace 模型标识,max_out_len 限制生成长度,batch_size 控制推理批量,run_cfg.num_gpus 声明所需 GPU 数。

使用配置时,可通过 --models 命令行参数指定相关文件,或用继承机制将模型配置导入到配置文件 models 列表中。更多模型配置细节见 准备模型。

数据集配置:ppl 判别式与 gen 生成式

与模型类似,数据集配置文件位于 opencompass/configs/datasets。以 examples/eval_chat_demo.py 中的数据集片段为例:

from mmengine.config import read_base  # 使用 mmengine.read_base() 读取基本配置

with read_base():
    # 直接从预设的数据集配置中读取所需的数据集配置
    from .datasets.demo.demo_gsm8k_chat_gen import gsm8k_datasets  # 读取 GSM8K 配置,使用 4-shot,基于生成式进行评估
    from .datasets.demo.demo_math_chat_gen import math_datasets    # 读取 MATH 配置,使用 0-shot,基于生成式进行评估

datasets = gsm8k_datasets + math_datasets       # 最终的配置需要包含所需的评估数据集列表 'datasets'

数据集配置通常有两种类型:ppl 与 gen,分别指示评估方法:

  • ppl:判别性(discriminative)评估,基于困惑度打分,适用于基座模型的选择题类任务;
  • gen:生成性(generative)评估,让模型自由生成答案后再比对,对话模型一律使用 gen。

具体来说,对话模型仅使用 gen 生成式评估;基座模型对"选择题"类型的数据集使用 ppl 判别式评估,其余使用 gen 生成式评估。

此外,opencompass/configs/dataset_collections/chat_OC15.py 收录了多种数据集集合,便于综合评测。OpenCompass 通常使用 chat_OC15 对对话模型做全面测试,该文件通过 read_base() 一次性引入 MMLU、CMMLU、C-Eval、GaokaoBench、TriviaQA、NQ、RACE、Winogrande、HellaSwag、BBH、GSM8K、MATH、TheoremQA、HumanEval、MBPP、GPQA、IFEval 等 20 个数据集(涵盖知识、推理、代码、指令遵循等维度),并以 datasets = sum((v for k, v in locals().items() if k.endswith('_datasets')), []) 汇总。要复现该集合的评测,只需:

python run.py --models hf_internlm2_chat_1_8b --datasets chat_OC15 --debug

更多数据集配置方法见 配置数据集。

启动评估:从调试模式到并行执行

由于 OpenCompass 默认并行启动评估过程,首次运行时建议以 --debug 模式启动并检查是否存在问题。在 --debug 模式下,任务按顺序执行,输出实时打印(opencompass/cli/main.py 中该参数被描述为 "Debug mode, in which scheduler will run tasks in the single process, and output will not be redirected to files")。

python run.py examples/eval_chat_demo.py -w outputs/demo --debug

对话模型 internlm/internlm2-chat-1_8b 和 Qwen/Qwen2-1.5B-Instruct 将在首次运行期间从 HuggingFace 自动下载。如果一切正常,屏幕上会出现 "Starting inference process" 且进度条开始前进:

[2023-07-12 18:23:55,076] [opencompass.openicl.icl_inferencer.icl_gen_inferencer] [INFO] Starting inference process...

随后可按 Ctrl+C 中断程序,并以正常模式运行:

python run.py examples/eval_chat_demo.py -w outputs/demo

在正常模式下,评估任务在后台并行执行,其输出被重定向到输出目录 outputs/demo/{TIMESTAMP}。前端的进度条只指示已完成任务的数量,不区分成功或失败;任何后端任务失败都只会在终端触发警告消息。 因此在并行模式下,务必在结束后检查输出目录中的日志与结果文件。

run.py 更多参数详解

以下参数与评估相关,可帮助你按环境配置更高效的推理任务:

  • -w outputs/demo:保存评估日志和结果的工作目录。实验结果将保存到 outputs/demo/{TIMESTAMP};未指定时默认 outputs/default(见 main.py 中 --work-dir 的注释说明)。
  • -r {TIMESTAMP/latest}:复用已有的推理结果并跳过已完成任务。后跟时间戳则复用工作空间路径下该时间戳的结果;若给定 latest 或干脆不指定,则复用指定工作空间路径下的最新结果。
  • --mode all:指定任务阶段。
    • all(默认):执行完整评估,包括推理和评估;
    • infer:仅在每个数据集上执行推理;
    • eval:仅根据推理结果进行评估;
    • viz:仅显示评估结果。
  • --max-num-workers 8:并行任务的最大数量。在 Slurm 等分布式环境中,此参数指定提交任务的最大数量;在本地环境中,它指定同时执行任务的最大数量。注意:实际并行数量取决于可用 GPU 资源,可能不等于该数值。

如果你不是在本地执行,而是使用 Slurm 集群,可指定以下参数:

  • --slurm:在集群上使用 Slurm 提交任务;
  • --partition(-p) my_part:Slurm 集群分区;
  • --retry 2:失败任务的重试次数。

从 main.py 的源码可以看到,--slurm 与 --dlc 是互斥参数组(add_mutually_exclusive_group),默认使用本地 runner;入口还支持将任务提交到阿里云深度学习中心(DLC),以及更多自定义评估策略,详见 评测任务发起。

可视化评估结果

评估完成后,结果表格将打印如下(demo 数据集、accuracy 指标、生成式评估):

dataset     version    metric    mode      qwen2-1.5b-instruct-hf    internlm2-chat-1.8b-hf
----------  ---------  --------  ------  ------------------------  ------------------------
demo_gsm8k  1d7fe4     accuracy  gen                        56.25                     32.81
demo_math   393424     accuracy  gen                        18.75                     14.06

所有运行输出定向到 outputs/demo/ 目录,结构如下:

outputs/default/
├── 20200220_120000
├── 20230220_183030     # 每个实验一个文件夹
│   ├── configs         # 用于记录的已转储配置文件。若在同一实验文件夹中重跑不同实验,可能保留多个配置
│   ├── logs            # 推理和评估阶段的日志文件
│   │   ├── eval
│   │   └── infer
│   ├── predictions     # 每个任务的推理结果
│   ├── results         # 每个任务的评估结果
│   └── summary         # 单个实验的汇总评估结果
├── ...

其中 configs 目录用于复现记录,logs/infer 与 logs/eval 分别存放两个阶段的日志,predictions 保存各任务的推理输出,results 保存各任务的评估分数,summary 汇总单个实验的最终结果。打印评测结果的过程可进一步定制,例如输出 MMLU、C-Eval 等数据集的平均分,具体见 结果展示。

网络与离线环境注意事项

OpenCompass 通常假定运行环境网络可用(模型权重需从 HuggingFace 下载、部分数据集需在线拉取)。如果你遇到网络问题或希望在离线环境中运行 OpenCompass,请参考 FAQ - 网络 寻求解决方案,其中介绍了预下载模型与数据、配置镜像源等做法。

继续深入:更多教程

想进一步掌握 OpenCompass,可继续学习以下文档:

登录后查看全文
opencompass