OpenCompass 快速上手:从配置、推理、评估到结果可视化的完整评测流程指南
OpenCompass 快速上手:从配置、推理、评估到结果可视化的完整评测流程指南
本指南以 OpenCompass 官方 Quick Start 文档为骨架,结合当前仓库的源码与配置实现,系统讲解一条完整的模型评测链路:配置(Configure)→ 推理(Inference)→ 评估(Evaluation)→ 可视化(Visualization)。读完本文,你将能够通过命令行或配置文件在本地完成一次真实的模型评测(以 OPT-125M / OPT-350M 在 SIQA 与 Winograd 上的评测为例),理解
run.py的参数体系、评测任务的分区(partition)与并行机制,以及结果输出目录的结构与含义。
一、评测工作流总览
OpenCompass 将一个模型的评测过程抽象为四个阶段:
- Configure(配置):选定要评测的模型与数据集,同时可选配置评测策略、计算后端(本地 GPU / Slurm 集群 / 阿里云 DLC 等)以及结果展示方式。这是整个评测的起点,全部信息最终会汇总为一个包含
datasets与models字段的配置对象。 - Inference(推理):让模型在评测数据集上逐个产生输出。OpenCompass 会把一个评测请求拆分成多个独立的"任务"(task),并行调度到不同的 GPU 分组或节点上执行,以最大化计算资源利用率。
- Evaluation(评估):将模型生成的输出与数据集的标准答案(gold standard)比对,计算准确率等指标。推理与评估阶段会被拆成多个并发任务;需要注意的是,在计算资源有限的环境下,任务切分过细反而会因为反复加载模型而拖慢整体速度(详见 FAQ: Efficiency)。
- 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)。