OpenCompass 快速上手:从配置、推理、评估到结果可视化的完整评测流程指南

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

OpenCompass 快速上手:从配置、推理、评估到结果可视化的完整评测流程指南

本指南以 OpenCompass 官方 Quick Start 文档为骨架,结合当前仓库的源码与配置实现,系统讲解一条完整的模型评测链路:配置(Configure)→ 推理(Inference)→ 评估(Evaluation)→ 可视化(Visualization)。读完本文,你将能够通过命令行或配置文件在本地完成一次真实的模型评测(以 OPT-125M / OPT-350M 在 SIQA 与 Winograd 上的评测为例),理解 run.py 的参数体系、评测任务的分区(partition)与并行机制,以及结果输出目录的结构与含义。

一、评测工作流总览

OpenCompass 将一个模型的评测过程抽象为四个阶段:

  1. Configure(配置):选定要评测的模型与数据集,同时可选配置评测策略、计算后端(本地 GPU / Slurm 集群 / 阿里云 DLC 等)以及结果展示方式。这是整个评测的起点,全部信息最终会汇总为一个包含 datasets 与 models 字段的配置对象。
  2. Inference(推理):让模型在评测数据集上逐个产生输出。OpenCompass 会把一个评测请求拆分成多个独立的"任务"(task),并行调度到不同的 GPU 分组或节点上执行,以最大化计算资源利用率。
  3. Evaluation(评估):将模型生成的输出与数据集的标准答案(gold standard)比对,计算准确率等指标。推理与评估阶段会被拆成多个并发任务;需要注意的是,在计算资源有限的环境下,任务切分过细反而会因为反复加载模型而拖慢整体速度(详见 FAQ: Efficiency)。
  4. Visualization(可视化):评测完成后,OpenCompass 将各数据集、各模型的指标汇总成易读的表格,同时输出 CSV 与 TXT 文件;如需实时状态推送,可开启 Lark(飞书)机器人上报。

本文将以两个 HuggingFace 预训练模型 OPT-125M 下的其他配置)。运行前请确保本地已正确安装 OpenCompass。

二、评测任务的三种配置方式

每个评测任务由"待评测模型 + 待评测数据集"两部分构成。统一入口是根目录下的 run.py,其内部仅一行核心逻辑——调用 opencompass/cli/main.py 中的 main() 解析参数并驱动整个流程。选择模型与数据集有三种方式:命令行指定 HuggingFace 模型、命令行引用预置配置名、或直接编写配置文件。

2.1 方式一:命令行直接构造 HuggingFace 模型

对于 HuggingFace 模型,可以不经配置文件,直接在命令行设置模型参数。例如评测 facebook/opt-125m:

python run.py --datasets siqa_gen winograd_ppl \
--hf-type base \
--hf-path facebook/opt-125m

这种方式的局限是一次只能评测一个模型,而另外两种方式支持一次评测多个模型。更完整的参数示例如下(各参数的解析入口见 parse_hf_args):

python run.py --datasets siqa_gen winograd_ppl \
--hf-type base \  # HuggingFace 模型类型,base 或 chat(默认 chat)
--hf-path facebook/opt-125m \  # HuggingFace 模型路径(必填)
--tokenizer-path facebook/opt-125m \  # 分词器路径,与模型路径相同时可省略
--tokenizer-kwargs padding_side='left' truncation='left' trust_remote_code=True \  # 构造 tokenizer 的参数
--model-kwargs device_map='auto' \  # 构造模型的参数
--max-seq-len 2048 \  # 模型可接受的最大序列长度
--max-out-len 100 \  # 生成的最大 token 数(默认 256)
--min-out-len 100 \  # 生成的最小 token 数(默认 1)
--batch-size 64  \  # 批大小(默认 8)
--hf-num-gpus 1  # 运行该模型所需 GPU 数量(默认 1)

⚠️ 注意:--hf-num-gpus 并不代表评测实际使用的 GPU 数量,而是运行该模型所需的最少 GPU 数量,它会被写入模型的 run_cfg,作为任务调度时资源分配的依据(详见 FAQ)。在源码层面,--num-gpus 参数已被弃用并会直接抛出错误提示改用 --hf-num-gpus(见 parse_args)。命令行构造 HuggingFace 模型的所有相关参数,可进一步参考 Launching an Evaluation Task。

2.2 方式二:命令行引用预置的模型与数据集配置

OpenCompass 将大量现成的模型与数据集配置分别存放在 opencompass/configs/models 与 opencompass/configs/datasets 下,命令行通过 --models 与 --datasets 组合即可:

python run.py --models hf_opt_125m hf_opt_350m --datasets siqa_gen winograd_ppl

使用前可用 tools/list_configs.py 查看/过滤当前可用的模型与数据集配置(该工具内部通过 match_files 对配置目录做模糊匹配,分别以 "Model / Config Path" 与 "Dataset / Config Path" 两张表格输出):

# 列出所有配置
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   | opencompass/configs/models/hf_llama2_13b.py   |
| hf_llama2_70b   | opencompass/configs/models/hf_llama2_70b.py   |
| ...             | ...                               |
+-----------------+-----------------------------------+
+-------------------+---------------------------------------------------+
| Dataset           | Config Path                                       |
|-------------------+---------------------------------------------------|
| cmmlu_gen         | opencompass/configs/datasets/cmmlu/cmmlu_gen.py   |
| cmmlu_gen_ffe7c0  | opencompass/configs/datasets/cmmlu/cmmlu_gen_ffe7c0.py   |
| ...               | ...                                               |
+-------------------+---------------------------------------------------+

表格第一列的配置名可直接作为 --models / --datasets 的输入参数。同一数据集名带不同后缀(如 siqa_gen、siqa_gen_e78df3),通常意味着提示词模板或评测方法不同。这一机制在 get_config_from_arg 中实现:run.py 会根据 args.models / args.datasets 到 opencompass/configs 下做模糊匹配并加载对应的 datasets / models 列表字段。如果想评测列表之外的模型,可参考"方式一"直接构造自定义 HuggingFace 模型,或参考"方式三"编写配置文件。

2.3 方式三:编写配置文件

除命令行外,也可以把实验的完整配置写进一个 Python 配置文件,交给 run.py 直接运行。配置文件必须包含 datasets 与 models 两个字段,并通过 mmengine 的继承机制(详见 Inheritance Mechanism)引入所需的模型与数据集配置。典型结构如下:

from mmengine.config import read_base

with read_base():
    from .datasets.siqa.siqa_gen import siqa_datasets
    from .datasets.winograd.winograd_ppl import winograd_datasets
    from .models.opt.hf_opt_125m import opt125m
    from .models.opt.hf_opt_350m import opt350m

datasets = [*siqa_datasets, *winograd_datasets]
models = [opt125m, opt350m]

随后把配置文件路径传给 run.py:

python run.py configs/eval_demo.py

关于 models 配置的深入说明

OpenCompass 在 opencompass/configs/models 下预置了一系列模型配置。以 opencompass/configs/models/opt/hf_opt_350m.py 为例,其完整内容如下:

from opencompass.models import HuggingFaceBaseModel

opt350m = dict(
    type=HuggingFaceBaseModel,
    abbr='opt-350m-hf',         # 模型简称,用于结果表格与输出目录命名
    path='facebook/opt-350m',   # 模型权重路径或 HuggingFace repo id
    max_out_len=1024,           # 最大生成 token 数
    batch_size=32,              # 批大小
    run_cfg=dict(num_gpus=1),   # 运行该模型所需的 GPU 数量
)

models = [opt350m]

同类配置 opencompass/configs/models/opt/hf_opt_125m.py 中 opt125m 的 batch_size=64,其余字段结构一致。type=HuggingFaceBaseModel 表示通过 HuggingFace 的 AutoModelForCausalLM 系列接口加载的基座模型(对话类模型则使用 HuggingFaceChatModel)。使用配置时,既可以像方式二那样通过命令行 --models 指定,也可以在配置文件中通过继承机制把模型配置导入 models 列表。更多模型配置说明见 Prepare Models。

关于 datasets 配置的深入说明

与模型类似,数据集配置文件位于 opencompass/configs/datasets 下。以 opencompass/configs/datasets/siqa/siqa_gen_e78df3.py 为例,一个生成式(gen)评测的数据集配置由四部分组成:

from opencompass.openicl.icl_prompt_template import PromptTemplate
from opencompass.openicl.icl_retriever import ZeroRetriever
from opencompass.openicl.icl_inferencer import GenInferencer
from opencompass.openicl.icl_evaluator import EDAccEvaluator
from opencompass.datasets import siqaDataset_V2

siqa_reader_cfg = dict(
    input_columns=['context', 'question', 'answerA', 'answerB', 'answerC'],
    output_column='all_labels',
    test_split='validation')

siqa_infer_cfg = dict(
    prompt_template=dict(
        type=PromptTemplate,
        template=dict(
            round=[
                dict(
                    role='HUMAN',
                    prompt=
                    '{context}\nQuestion: {question}\nA. {answerA}\nB. {answerB}\nC. {answerC}\nAnswer:'
                )
            ], ),
    ),
    retriever=dict(type=ZeroRetriever),
    inferencer=dict(type=GenInferencer),
)

siqa_eval_cfg = dict(
    evaluator=dict(type=EDAccEvaluator),
    pred_role='BOT',
)

siqa_datasets = [
    dict(
        abbr='siqa',
        type=siqaDataset_V2,
        path='opencompass/siqa',
        reader_cfg=siqa_reader_cfg,
        infer_cfg=siqa_infer_cfg,
        eval_cfg=siqa_eval_cfg)
]
  • reader_cfg:定义数据读取的输入列、输出列与测试集划分;
  • infer_cfg:定义提示词模板(PromptTemplate)、示例检索器(ZeroRetriever 表示零样本,不取示例)与推理器(GenInferencer 表示生成式推理,对应 gen;PPL 判别式评测则使用 PPLInferencer,对应 ppl);
  • eval_cfg:定义评测器与模型回答的角色字段。

数据集配置通常分为 ppl 与 gen 两种类型:ppl 表示判别式评测(用困惑度打分),gen 表示生成式评测。同时 opencompass/configs/datasets/collections 下存放了各种数据集集合,便于做全面评测。例如 base_medium.py 通过继承机制聚合了 MMLU、C-Eval、AGIEval、BBH、GSM8K、CLUE 系列、SuperGLUE 系列等数十个数据集的配置,是常见的全量测试集合,可直接按名引用:

python run.py --models hf_llama_7b --datasets base_medium

更完整的数据集说明见 Dataset Preparation。

⚠️ 网络提示:OpenCompass 默认假设网络可用(首次运行会从 HuggingFace 自动下载模型与数据集)。如果遇到网络问题或需要在离线环境运行,请参考 FAQ - Network 中的解决方案。

三、启动评测:先 Debug 后并行

OpenCompass 默认会并行启动评测进程,因此首次运行建议加上 --debug 参数,让任务串行执行并实时打印输出,以便排查问题:

python run.py configs/eval_demo.py -w outputs/demo --debug

首次运行时,facebook/opt-350m 与 facebook/opt-125m 的权重会从 HuggingFace 自动下载。一切正常时,屏幕会出现推理阶段的启动日志:

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

确认无异常后按 ctrl+c 中断,再以正常模式运行(此时任务在后台并行执行,输出被重定向到工作目录;前端进度条只反映任务完成数量,与成败无关,后台任务的失败仅会在终端打印警告):

python run.py configs/eval_demo.py -w outputs/demo

3.1 run.py 常用参数详解

源码层面,所有参数在 parse_args 中定义与校验。以下是评测相关的高频参数:

  • -w outputs/demo:工作目录,用于保存评测日志与结果。实验中所有产物会保存到 outputs/demo/{TIMESTAMP} 时间戳子目录;不指定时默认为 outputs/default。
  • -r:复用已有推理结果并跳过已完成任务。后面可跟一个时间戳(复用工作目录下该时间戳的结果),不跟参数则复用指定工作目录下的最新结果。需要留意:eval / viz 模式下必须指定 -r(或 --read-from-station),否则会直接报错(见 main)。
  • --mode all:指定运行阶段。
    • all(默认):完整执行推理与评估;
    • infer:只对每个数据集做推理;
    • eval:基于已有推理结果做评估;
    • viz:仅展示评估结果。
  • --max-partition-size 2000:数据集分区大小。某些数据集很大,该参数可将其拆分为多个子任务以更高效利用资源;但分区过细会导致模型反复加载,整体反而变慢(机制详见 FAQ: Efficiency)。
  • --max-num-workers 32:最大并行任务数。在 Slurm 等分布式环境中表示最大提交任务数,在本地环境表示最大并行执行任务数;实际并行数取决于可用 GPU 资源,可能小于该值。
  • --debug:单进程顺序执行任务,输出实时打印,适合首次运行排错。
  • --dry-run:只打印将要执行的命令而不真正运行(内部会强制开启 debug 模式)。
  • --accelerator vllm|lmdeploy:切换推理加速后端(配置中加载的模型会被替换为对应加速器实现的版本,见 get_config_from_arg)。
  • --dump-eval-details:默认开启,保存每个样本的对错等评估明细(会占用额外磁盘空间,可用 --dump-eval-details False 关闭)。
  • --analysis-repeat:在 viz 阶段分析模型回答中的重复现象。

如果不在本地而在 Slurm 集群上运行,还可指定以下参数(校验逻辑见 parse_args):

  • --slurm:通过集群的 srun 提交任务;
  • --partition(-p) my_part:Slurm 分区名(使用 --slurm 时必填);
  • --retry 2:失败任务的重试次数(默认 2)。

此外入口还支持将任务提交到阿里云 DLC(需配置 ~/.aliyun.cfg),更多自定义评测策略参见 Launching an Evaluation Task。

3.2 底层执行链路

从源码看,main() 的核心流程为:解析参数 → get_config_from_arg 构建配置 → 写入并重载 dump 出的配置文件(避免已初始化的类型无法序列化,见 main)→ 按 --mode 分别用 partitioner 切分任务、用 runner 执行任务(推理与评估各自有独立的 partitioner 与 runner 配置,fill_infer_cfg 与 fill_eval_cfg 负责在命令行模式下补齐默认配置)→ 最后调用 summarizer 汇总结果。推理产物写入 predictions/,评估产物写入 results/,汇总结果写入 summary/,这一目录划分与下文输出的目录结构一一对应。

四、结果可视化与输出目录

评测完成后,控制台会打印一张各模型在各数据集上的指标汇总表:

dataset    version    metric    mode      opt350m    opt125m
---------  ---------  --------  ------  ---------  ---------
siqa       e78df3     accuracy  gen         21.55      12.44
winograd   b6c7ed     accuracy  ppl         51.23      49.82

同时所有运行产物会被写入工作目录,结构如下:

outputs/default/
├── 20200220_120000
├── 20230220_183030     # 一次实验对应的文件夹
│   ├── configs         # 归档的配置文件(同一实验文件夹内重跑会保留多份)
│   ├── logs            # 推理与评估两个阶段的日志
│   │   ├── eval
│   │   └── infer
│   ├── predictions     # 每个任务的推理(预测)结果
│   ├── results         # 每个任务的评估结果
│   └── summary         # 单次实验的汇总结果
├── ...

其中 configs/ 目录在 main 中由运行时的配置 dump 而成,文件名以时间戳与进程号命名;汇总阶段(summarizer)可在配置中进一步定制,例如对 MMLU、C-Eval 等基准输出平均分。关于获取评估结果的更多细节,参见 Results Summary。另外,如需实时掌握任务状态,可在启动命令中加入 --lark 并配置 lark_bot_url,将运行状态实时推送到 Lark(飞书)客户端(见 parse_args 与 main)。

五、进阶学习路径

登录后查看全文
opencompass