一、入门
安装
1.环境准备
面向开源模型的gpu环境
conda create --name opencompass python=3.10 pytorch torchvision pytorch-cuda -c nvidia -c pytorch -y
conda activate opencompass
面向api模型测试的cpu环境
conda create -n opencompass python=3.10 pytorch torchvision torchaudio cpuonly -c pytorch -y
conda activate opencompass
# 如果需要使用各个API模型,请 `pip install -r requirements/api.txt` 安装API模型的相关依赖
2.安装opencompass
git clone https://github.com/open-compass/opencompass.git
cd opencompass
pip install -e .
3.安装 humaneval(可选)
如果你需要在 humaneval 数据集上评估模型代码能力,请执行此步骤,否则忽略这一步。
git clone https://github.com/openai/human-eval.git
cd human-eval
pip install -r requirements.txt
pip install -e .
cd ..
请仔细阅读 human_eval/execution.py 第48-57行的注释,了解执行模型生成的代码可能存在的风险,如果接受这些风险,请取消第58行的注释,启用代码执行评测。
4.安装 Llama(可选)
git clone https://github.com/facebookresearch/llama.git
cd llama
pip install -r requirements.txt
pip install -e .
cd ..
可以在 configs/models 下找到所有 Llama / Llama-2 / Llama-2-chat 模型的配置文件示例。(示例)
5.安装 alpaca-eval(可选)
如果你需要使用官方alpaca-eval实现评测 alpaca-eval 数据集,请执行此步骤,否则忽略这一步。
pip install alpaca-eval
数据集准备
OpenCompass 支持的数据集主要包括两个部分:
1.Huggingface 数据集: Huggingface Dataset 提供了大量的数据集,这部分数据集运行时会自动下载。
2. 自建以及第三方数据集:OpenCompass 还提供了一些第三方数据集及自建中文数据集。运行以下命令手动下载解压。
在 OpenCompass 项目根目录下运行下面命令,将数据集准备至 ${OpenCompass}/data 目录下:
wget https://github.com/open-compass/opencompass/releases/download/0.2.2.rc1/OpenCompassData-core-20240207.zip
unzip OpenCompassData-core-20240207.zip
如果需要使用 OpenCompass 提供的更加完整的数据集 (~500M),可以使用下述命令进行下载和解压:
wget https://github.com/open-compass/opencompass/releases/download/0.2.2.rc1/OpenCompassData-complete-20240207.zip
unzip OpenCompassData-complete-20240207.zip
cd ./data
find . -name "*.zip" -exec unzip "{}" \;
两个 .zip 中所含数据集列表如此处所示。
https://github.com/open-compass/opencompass/releases/tag/0.2.2.rc1
快速开始
在 OpenCompass 中评估一个模型通常包括以下几个阶段:配置 -> 推理 -> 评估 -> 可视化。
配置评估任务
在 OpenCompass 中,每个评估任务由待评估的模型和数据集组成。评估的入口点是 run.py。通过命令行或配置文件选择要测试的模型和数据集。
命令行
使用 --models 和 --datasets 结合想测试的模型和数据集。
python run.py --models hf_opt_125m hf_opt_350m --datasets siqa_gen winograd_ppl
模型和数据集的配置文件预存于 configs/models 和 configs/datasets 中。用户可以使用 tools/list_configs.py 查看或过滤当前可用的模型和数据集配置。
# 列出所有配置
python tools/list_configs.py
# 列出与llama和mmlu相关的所有配置
python tools/list_configs.py llama mmlu
命令行自定义HF模型
对于 HuggingFace 模型,用户可以通过命令行直接设置模型参数,无需额外的配置文件。例如,对于 facebook/opt-125m 模型,您可以使用以下命令进行评估:
python run.py --datasets siqa_gen winograd_ppl \
--hf-type base \
--hf-path facebook/opt-125m
通过这种方式,OpenCompass 一次只评估一个模型,而其他方式可以一次评估多个模型。
–hf-num-gpus 不代表实际用于评估的 GPU 数量,而是该模型所需的最少 GPU 数量。
详细示例:
python run.py --datasets siqa_gen winograd_ppl \
--hf-type base \ # HuggingFace 模型类型, base 或 chat
--hf-path facebook/opt-125m \ # HuggingFace 模型路径
--tokenizer-path facebook/opt-125m \ # HuggingFace tokenizer 路径(如果与模型路径相同,可以省略)
--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 数
--min-out-len 100 \ # 生成的最小 token 数
--batch-size 64 \ # 批量大小
--hf-num-gpus 1 # 运行模型所需的 GPU 数量
有关 run.py 支持的所有与 HuggingFace 相关的参数,请阅读:
https://opencompass.readthedocs.io/zh-cn/latest/user_guides/experimentation.html#id2
配置文件
除了通过命令行配置实验外,OpenCompass 还允许用户在配置文件中编写实验的完整配置,并通过 run.py 直接运行它。配置文件是以 Python 格式组织的,并且必须包括 datasets 和 models 字段。
本次测试配置在 configs/eval_demo.py 中。此配置通过 继承机制 引入所需的数据集和模型配置,并以所需格式组合 datasets 和 models 字段。
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
启动评估
由于 OpenCompass 默认并行启动评估过程,我们可以在第一次运行时以 --debug 模式启动评估,并检查是否存在问题。在 --debug 模式下,任务将按顺序执行,并实时打印输出。
python run.py configs/eval_demo.py -w outputs/demo --debug
预训练模型 ‘facebook/opt-350m’ 和 ‘facebook/opt-125m’ 将在首次运行期间从 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 configs/eval_demo.py -w outputs/demo
在正常模式下,评估任务将在后台并行执行,其输出将被重定向到输出目录 outputs/demo/{TIMESTAMP}。前端的进度条只指示已完成任务的数量,而不考虑其成功或失败。任何后端任务失败都只会在终端触发警告消息。
run.py中更多参数
以下是与评估相关的一些参数,可以帮助您根据环境配置更有效的推理任务:
-w outputs/demo:保存评估日志和结果的工作目录。在这种情况下,实验结果将保存到 outputs/demo/{TIMESTAMP}。
-r:重用现有的推理结果,并跳过已完成的任务。如果后面跟随时间戳,将重用工作空间路径下该时间戳的结果;否则,将重用指定工作空间路径下的最新结果。
–mode all:指定任务的特定阶段。
all:(默认)执行完整评估,包括推理和评估。
infer:在每个数据集上执行推理。
eval:根据推理结果进行评估。
viz:仅显示评估结果。
–max-partition-size 40000:数据集分片大小。一些数据集可能很大,使用此参数可以将它们分成多个子任务以有效利用资源。但是,如果分片过细,由于模型加载时间较长,整体速度可能会变慢。
–max-num-workers 32:并行任务的最大数量。在如 Slurm 之类的分布式环境中,此参数指定提交任务的最大数量。在本地环境中,它指定同时执行的任务的最大数量。请注意,实际的并行任务数量取决于可用的 GPU 资源,可能不等于这个数字。
如果您不是在本地机器上执行评估,而是使用 Slurm 集群,您可以指定以下参数:
–slurm:在集群上使用 Slurm 提交任务。
–partition(-p) my_part:Slurm 集群分区。
–retry 2:失败任务的重试次数。
可视化评估结果
评估完成后,评估结果表格将打印如下:
dataset version metric mode opt350m opt125m
siqa e78df3 accuracy gen 21.55 12.44
winograd b6c7ed accuracy ppl 51.23 49.82
所有运行输出将定向到 outputs/demo/ 目录,结构如下:
outputs/default/
├── 20200220_120000
├── 20230220_183030 # 每个实验一个文件夹
│ ├── configs # 用于记录的已转储的配置文件。如果在同一个实验文件夹中重新运行了不同的实验,可能会保留多个配置
│ ├── logs # 推理和评估阶段的日志文件
│ │ ├── eval
│ │ └── infer
│ ├── predictions # 每个任务的推理结果
│ ├── results # 每个任务的评估结果
│ └── summary # 单个实验的汇总评估结果
├── …
教程
学习配置文件
配置数据集
准备模型
要在 OpenCompass 中支持新模型的评测,有以下几种方式:
1.基于 HuggingFace 的模型
2.基于 API 的模型
3.自定义模型
1.基于HuggingFace 的模型
支持直接从 Huggingface 的 AutoModel.from_pretrained 和 AutoModelForCausalLM.from_pretrained 接口构建评测模型。如果需要评测的模型符合 HuggingFace 模型通常的生成接口, 则不需要编写代码,直接在配置文件中指定相关配置即可。
如下,为一个示例的 HuggingFace 模型配置文件:
# 使用 `HuggingFace` 评测 HuggingFace 中 AutoModel 支持的模型
# 使用 `HuggingFaceCausalLM` 评测 HuggingFace 中 AutoModelForCausalLM 支持的模型
from opencompass.models import HuggingFaceCausalLM
models = [
dict(
type=HuggingFaceCausalLM,
# 以下参数为 `HuggingFaceCausalLM` 的初始化参数
path='huggyllama/llama-7b',
tokenizer_path='huggyllama/llama-7b',
tokenizer_kwargs=dict(padding_side='left', truncation_side='left'),
max_seq_len=2048,
batch_padding=False,
# 以下参数为各类模型都有的参数,非 `HuggingFaceCausalLM` 的初始化参数
abbr='llama-7b', # 模型简称,用于结果展示
max_out_len=100, # 最长生成 token 数
batch_size=16, # 批次大小
run_cfg=dict(num_gpus=1), # 运行配置,用于指定资源需求
)
]
参数说明:
(1)batch_padding=False:如为 False,会对一个批次的样本进行逐一推理;如为 True,则会对一个批次的样本进行填充, 组成一个 batch 进行推理。对于部分模型,这样的填充可能导致意料之外的结果;如果评测的模型支持样本填充, 则可以将该参数设为 True,以加速推理。
(2)padding_side=‘left’:在左侧进行填充,因为不是所有模型都支持填充,在右侧进行填充可能会干扰模型的输出。
(3)truncation_side=‘left’:在左侧进行截断,评测输入的 prompt 通常包括上下文样本 prompt 和输入 prompt 两部分, 如果截断右侧的输入 prompt,可能导致生成模型的输入和预期格式不符,因此如有必要,应对左侧进行截断。
在评测时,OpenCompass 会使用配置文件中的 type 与各个初始化参数实例化用于评测的模型, 其他参数则用于推理及总结等过程中,与模型相关的配置。例如上述配置文件,我们会在评测时进行如下实例化过程:
model = HuggingFaceCausalLM(
path='huggyllama/llama-7b',
tokenizer_path='huggyllama/llama-7b',
tokenizer_kwargs=dict(padding_side='left', truncation_side='left'),
max_seq_len=2048,
)
2.基于API的模型
OpenCompass 目前支持以下基于 API 的模型推理:
-
OpenAI(opencompass.models.OpenAI)
-
ChatGLM@智谱清言 (opencompass.models.ZhiPuAI)
-
ABAB-Chat@MiniMax (opencompass.models.MiniMax)
-
XunFei@科大讯飞 (opencompass.models.XunFei)
以 OpenAI 的配置文件为例,模型如何在配置文件中使用基于 API 的模型。
from opencompass.models import OpenAI
models = [
dict(
type=OpenAI, # 使用 OpenAI 模型
# 以下为 `OpenAI` 初始化参数
path='gpt-4', # 指定模型类型
key='YOUR_OPENAI_KEY', # OpenAI API Key
max_seq_len=2048, # 最大输入长度
# 以下参数为各类模型都有的参数,非 `OpenAI` 的初始化参数
abbr='GPT-4', # 模型简称
run_cfg=dict(num_gpus=0), # 资源需求(不需要 GPU)
max_out_len=512, # 最长生成长度
batch_size=1, # 批次大小
),
]
3.自定义模型
(1)新增API模型
新增基于API的模型,需要在 opencompass/models 下新建 mymodel_api.py 文件,继承 BaseAPIModel,并实现 generate 方法来进行推理,以及 get_token_len 方法来计算 token 的长度。在定义好之后修改对应配置文件名称即可。
from ..base_api import BaseAPIModel
class MyModelAPI(BaseAPIModel):
is_api: bool = True
def __init__(self,
path: str,
max_seq_len: int = 2048,
query_per_second: int = 1,
retry: int = 2,
**kwargs):
super().__init__(path=path,
max_seq_len=max_seq_len,
meta_template=meta_template,
query_per_second=query_per_second,
retry=retry)
...
def generate(
self,
inputs,
max_out_len: int = 512,
temperature: float = 0.7,
) -> List[str]:
"""Generate results given a list of inputs."""
pass
def get_token_len(self, prompt: str) -> int:
"""Get lengths of the tokenized string."""
pass
(2)新增第三方模型
新增基于第三方的模型,需要在 opencompass/models 下新建 mymodel.py 文件,继承 BaseModel,并实现 generate 方法来进行生成式推理, get_ppl 方法来进行判别式推理,以及 get_token_len 方法来计算 token 的长度。在定义好之后修改对应配置文件名称即可。
from ..base import BaseModel
class MyModel(BaseModel):
def __init__(self,
pkg_root: str,
ckpt_path: str,
tokenizer_only: bool = False,
meta_template: Optional[Dict] = None,
**kwargs):
...
def get_token_len(self, prompt: str) -> int:
"""Get lengths of the tokenized strings."""
pass
def generate(self, inputs: List[str], max_out_len: int) -> List[str]:
"""Generate results given a list of inputs. """
pass
def get_ppl(self,
inputs: List[str],
mask_length: Optional[List[int]] = None) -> List[float]:
"""Get perplexity scores given a list of inputs."""
pass
高效评测
任务运行和监控
评估指标
在评测阶段,我们一般以数据集本身的特性来选取对应的评估策略,最主要的依据为标准答案的类型,一般以下几种类型:
-
选项:常见于分类任务,判断题以及选择题,目前这类问题的数据集占比最大,有MMLU、CEval数据集等,评估指标一般使用准确率——ACCEvaluator
-
短语:常见于问答以及阅读理解任务,这类数据集主要包括,CLUE_CMRC, CLUE_DRCD, DROP 等,评估标准一般使用匹配率——EMvaluator
-
句子:常见于翻译以及生成伪代码、命令行任务中,主要包括Flores, Summscreen, Govrepcrs, Iwdlt2017 数据集等等,评估标准一般使用——BLEU(Bilingual Evaluation Understudy)–BleuEvaluator。
-
段落:常见于文本摘要生成的任务,常用的数据集包括Lcsts, TruthfulQA, Xsum 数据集等等,评估标准一般使用——ROUGE(Recall-Oriented Understudy for Gisting Evaluation)–RougeEvaluator。
-
代码:常见于代码生成的任务,常用的数据集主要包括Humaneval,MBPP 数据集等等,评估标准一般使用执行通过率以及pass@k,,目前 Opencompass 支持的有MBPPEvaluator、HumanEvaluator。
还有一类打分类型评测任务没有标准答案,比如评判一个模型的输出是否存在有毒,可以直接使用相关的API服务进行打分,目前支持的有ToxicEvaluator,目前有 realtoxicityprompts 数据集使用此评测方式。
已支持评估指标
目前 OpenCompass 中,常用的 Evaluator 主要放在 opencompass/openicl/icl_evaluator文件夹下, 还有部分数据集特有指标的放在 opencompass/datasets 的部分文件中。以下是汇总:
评估指标 | 评估策略 | 常用后处理方式 | 数据集 |
---|---|---|---|
ACCEvaluator | 正确率 | first_capital_postprocess | agieval, ARC, bbh, mmlu, ceval, commonsenseqa, crowspairs, hellaswag |
EMEvaluator | 匹配率 | None, dataset_specification | drop, CLUE_CMRC, CLUE_DRCD |