OpenCompass 快速开始:模型评测的配置、推理、评估与可视化全流程指南
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,可继续学习以下文档: