OpenCompass 代码能力评估实战:HumanEval 与 MBPP 的 pass@1 / pass@k 配置与底层原理
OpenCompass 代码能力评估实战:HumanEval 与 MBPP 的 pass@1 / pass@k 配置与底层原理
OpenCompass 提供了从配置到推理、评估、可视化的完整代码能力评测链路。本文以 humaneval 与 mbpp 两个经典 Python 代码生成数据集为例,系统讲解如何评估模型的 pass@1 与 pass@k 指标:包括直接用官方配置完成单次生成评测、借助 num_return_sequences 一次生成多条回答、以及针对不支持多回答生成的模型用数据集重复(num_repeats)方案兜底。读完本文,你将能够独立搭建并跑通两种 pass@k 评估实验,并理解其背后的数据集加载、代码执行与概率估计实现。
评测对象:HumanEval 与 MBPP
OpenCompass 的代码评估以“让模型根据自然语言任务描述补全 Python 函数,然后用真实测试用例执行验证”为核心。两个最常用的数据集是:
- HumanEval:OpenAI 发布的 164 道函数补全题,每道题给出 docstring 形式的函数签名与测试用例,评估器会调用
human-eval包的evaluate_functional_correctness执行真实代码并计算通过率; - MBPP:约 500 道“基础 Python 编程”任务,每道题包含任务描述(
text)、测试断言列表(test_list)与函数名,评估器将模型回答与断言拼接后实际执行,统计pass/timeout/failed/wrong_answer。
两者的评测方向略有差异:HumanEval 侧重“补全单个函数”,MBPP 侧重“按描述从零编写函数”,组合使用可以更全面地反映模型的代码生成能力。若需覆盖 Python 之外的多语言评测(C++、Java、Go、JS 等),可参考 Multilingual Code Evaluation Tutorial(对应 humaneval-x 与 DS1000 的 Docker 评测服务)。
快速开始:pass@1 单次生成评测
如果只评估模型“对每个题目生成一次回答”的 pass@1 表现,可以直接复用仓库中现成的数据集配置,无需任何改造:
- humaneval_gen_8e312c.py(
abbr='openai_humaneval') - deprecated_mbpp_gen_1e1056.py(
abbr='mbpp')
这两个文件遵循 OpenCompass 数据集配置的标准三段式结构(reader_cfg / infer_cfg / eval_cfg),以 humaneval 为例:
humaneval_reader_cfg = dict(
input_columns=['prompt'], output_column='task_id', train_split='test')
humaneval_infer_cfg = dict(
prompt_template=dict(
type=PromptTemplate,
template=dict(round=[
dict(
role='HUMAN',
prompt='Complete the following python code:\n{prompt}'),
])),
retriever=dict(type=ZeroRetriever),
inferencer=dict(type=GenInferencer, max_out_len=512))
humaneval_eval_cfg = dict(
evaluator=dict(type=HumanEvalEvaluator),
pred_role='BOT',
k=[1, 10, 100], # the parameter only for humaneval
pred_postprocessor=dict(type=humaneval_postprocess_v2),
)
其中几个字段的作用与源码对应关系如下:
reader_cfg.output_column='task_id':以任务 ID 作为回答与参考的配对键;inferencer=dict(type=GenInferencer, max_out_len=512):生成式推理,输出长度上限 512 token;pred_postprocessor=dict(type=humaneval_postprocess_v2):回答后处理。该函数定义在 humaneval.py,核心逻辑是用正则```\w*\n(.*?)```提取模型回答中第一个 Markdown 代码块,避免把模型闲聊内容带入执行;k=[1, 10, 100]:HumanEvalEvaluator默认支持的 pass@k 集合(仅 humaneval 使用),即使只生成一次回答,评估器也会按此集合输出指标。
MBPP 的配置与之类似,但提示模板使用了 Few-shot 风格:前几轮给出 [BEGIN] ... [DONE] 包裹的示例问答,最后一轮以 {text} Your code should pass these tests:\n\n {test_list} 提问、以 [BEGIN] 引导模型开始生成。其 mbpp_eval_cfg 使用 MBPPEvaluator,reader_cfg.output_column='test_list_2'。
运行方式
按照 快速开始教程 中的通用流程,在配置文件中组装 datasets 与 models 后执行:
python run.py configs/your_eval_config.py
也可以直接用命令行把数据集名与模型组合起来(详见 Launching an Evaluation Task):
python run.py --datasets humaneval_gen mbpp_gen --hf-type base --hf-path your/model
运行结束后,OpenCompass 会汇总结果并输出 CSV / TXT 报告;HumanEvalEvaluator 与 MBPPEvaluator 的 score 方法还会把每条样本的 details(原始回答、执行程序、是否正确)写回结果,便于逐题排查。
pass@k 评估:典型场景(模型支持多条生成)
pass@k 的定义是:对每个题目生成 n(n ≥ k)条候选回答,只要其中至少一条通过全部测试用例即视为“此题通过”,再对所有题目取平均。它本质上是概率估计,因此要求候选回答数量 必须大于等于 k,且回答之间要有随机性。
对于大多数支持 HF num_return_sequences 生成参数的模型,可以直接让一次前向生成多条回答。参考仓库示例 examples/eval_code_passk.py,配置要点如下:
from opencompass.datasets import MBPPDatasetV2, MBPPPassKEvaluator
with read_base():
from .datasets.humaneval.humaneval_gen_8e312c import humaneval_datasets
from .datasets.mbpp.deprecated_mbpp_gen_1e1056 import mbpp_datasets
mbpp_datasets[0]['type'] = MBPPDatasetV2
mbpp_datasets[0]['eval_cfg']['evaluator']['type'] = MBPPPassKEvaluator
mbpp_datasets[0]['reader_cfg']['output_column'] = 'test_column'
datasets = []
datasets += humaneval_datasets
datasets += mbpp_datasets
models = [
dict(
type=HuggingFaceCausalLM,
...,
generation_kwargs=dict(
num_return_sequences=10,
do_sample=True,
top_p=0.95,
temperature=0.8,
),
...,
)
]
为什么 MBPP 需要这三处修改
type→MBPPDatasetV2:pass@k 场景要求每个样本都能与“多条回答”一一对应。MBPPDatasetV2在加载时(mbpp.py)会额外构造一个test_column字段——一个包含test_list_2(拼好的断言)和task_id的字典,供评估器按任务聚合多条回答;reader_cfg.output_column→'test_column':让推理与评估阶段都能拿到这个聚合字段;eval_cfg.evaluator.type→MBPPPassKEvaluator:评估器从“逐条执行打分”切换为“按任务聚合后估计 pass@k”。
HumanEval 侧则无需改动:其配置 humaneval_passk_gen_8e312c.py 已内置 HumanEvalEvaluator(k=[1, 10, 100]),该评估器支持同时处理单条与多条回答(见下文的实现解析)。
generation_kwargs 的随机性要求
由于 pass@k 是对不同采样的估计,必须让模型回答产生多样性:
num_return_sequences=10:每个输入生成 10 条回答,必须 ≥ k;do_sample=True:开启采样;top_p=0.95与temperature=0.8:控制采样分布,避免回答过于集中。
示例配置中 eval_code_passk.py 使用了 CodeLlama-7b-Python 模型,并配套设置 max_out_len=1024、max_seq_len=2048、batch_size=8,以及 tokenizer_kwargs 中的 padding_side='left'(生成任务通常要求左侧填充)。
pass@k 评估:模型不支持多条生成的兜底方案
部分 HF 模型接口设计不完善或未实现 num_return_sequences。此时无法一次生成多条回答,OpenCompass 的替代思路是:把数据集按需重复 n 次,让每个样本被独立推理 n 遍,从而凑齐 n 条候选回答。参考示例 examples/eval_code_passk_repeat_dataset.py:
from opencompass.datasets import MBPPDatasetV2, MBPPPassKEvaluator
with read_base():
from .datasets.humaneval.humaneval_gen_8e312c import humaneval_datasets
from .datasets.mbpp.deprecated_mbpp_gen_1e1056 import mbpp_datasets
humaneval_datasets[0]['abbr'] = 'openai_humaneval_pass10'
humaneval_datasets[0]['num_repeats'] = 10
mbpp_datasets[0]['abbr'] = 'mbpp_pass10'
mbpp_datasets[0]['num_repeats'] = 10
mbpp_datasets[0]['type'] = MBPPDatasetV2
mbpp_datasets[0]['eval_cfg']['evaluator']['type'] = MBPPPassKEvaluator
mbpp_datasets[0]['reader_cfg']['output_column'] = 'test_column'
datasets = []
datasets += humaneval_datasets
datasets += mbpp_datasets
models = [
dict(
type=HuggingFaceCausalLM,
...,
generation_kwargs=dict(
do_sample=True,
top_p=0.95,
temperature=0.8,
),
...,
)
]
注意此方案不再需要 num_return_sequences,但仍必须保留 do_sample=True 等随机采样参数,否则重复生成的回答完全相同,pass@k 估计将失去意义。
需要修改的字段
由于数据集本身的 prompt 并未改变,只是被重复,需要通过替换字段达到目的:
num_repeats:数据集重复次数(示例中为 10,即每个样本推理 10 次得到 10 条回答);abbr:建议在调整重复次数时同步修改数据集缩写(如openai_humaneval_pass10/mbpp_pass10)。因为数据集条数发生了变化,若缩写与.cache/dataset_size.json中缓存的值不一致,可能引发潜在问题;- MBPP 的三处字段(
type、eval_cfg.evaluator.type、reader_cfg.output_column)与上一节相同,同样需要替换为MBPPDatasetV2/MBPPPassKEvaluator/'test_column'。
仓库已预置了对应的现成配置可直接继承:humaneval 侧为 humaneval_repeat10_gen_8e312c.py(abbr='openai_humaneval_repeat10'、num_repeats=10),MBPP 侧为 deprecated_mbpp_repeat10_gen_1e1056.py(位于 mbpp 目录),示例配置正是通过 read_base() 继承它们。eval_code_passk_repeat_dataset.py 中还展示了为 Chat 模型配置 _meta_template(<|User|>: ... <|Bot|>: ... <eoa>)的写法,以及对 SizePartitioner / LocalRunner / OpenICLInferTask 的推理环境设置。
底层原理:数据集加载与执行验证
理解配置背后的源码实现,有助于在遇到超时、误判或条数不一致等问题时快速定位。
数据集重复是怎么实现的
HumanevalDataset.load(humaneval.py)逐行读取path指向的 jsonl 文件,每个样本按num_repeats次展开成独立行,再Dataset.from_list组装;MBPPDatasetV2.load(mbpp.py)在processing_test中构造test_column = dict(test_list_2=..., task_id=...),随后用concatenate_datasets([test] * num_repeats)将测试集重复 n 倍。
两条代码路径都明确提示:重复次数变化时应同步修改 abbr,避免与 .cache/dataset_size.json 不一致。
回答提取与代码执行
- MBPP 回答提取:
MBPPEvaluator._process_answer(mbpp.py)用一组正则依次尝试匹配[BEGIN] ... [DONE]、Markdown 代码块等格式,抽取纯代码段; - 隔离执行:
execution/_execution(mbpp.py)把“待测代码 + 类型感知断言”送入multiprocessing.Process独立子进程执行,父进程join(timeout)控制超时(约 10 秒),超时则p.kill()并记为timeout。子进程内通过swallow_io吞掉 stdout/stderr,避免模型打印干扰结果; - HumanEval 执行:
HumanEvalEvaluator.score(humaneval.py)把预测写入临时 jsonl({'task_id', 'completion'}),再调用human_eval.evaluation.evaluate_functional_correctness(n_workers=4, timeout=3.0)执行,输出humaneval_{k}指标。若未安装human-eval包,会抛出带安装指引的ImportError。
pass@k 的数学估计
MBPPPassKEvaluator(mbpp.py)对每个 task_id 聚合 n 条回答的执行结果,统计正确数 c,再按标准无偏估计公式计算:
pass@k = 1 - comb(n - c, k) / comb(n, k)
源码中的实现为 1.0 - np.prod(1.0 - k / np.arange(n - c + 1, n + 1))(mbpp.py),逐任务求值后取平均并乘 100 输出 pass@{k}。这也解释了为什么 num_return_sequences / num_repeats 必须大于等于 k:若 n < k,该任务会被排除(源码中 if (task_total >= k).all() 的条件),无法得到有效的 pass@k 估计。HumanEvalEvaluator 同理,其 k 参数控制 evaluate_functional_correctness 输出的 pass@k 集合。
小结与排查提示
- 只测 pass@1:直接复用 humaneval_gen_8e312c.py 与 deprecated_mbpp_gen_1e1056.py,无需改造;
- 测 pass@k 且模型支持多回答:用 eval_code_passk.py 的思路,配置
num_return_sequences+ 采样参数,MBPP 侧替换三个字段; - 测 pass@k 且模型不支持多回答:用 eval_code_passk_repeat_dataset.py 的思路,配置
num_repeats并同步修改abbr; - 随机性缺失:忘记设置
do_sample=True时,多次生成结果相同,pass@k 会退化为 pass@1; - 条数不一致:修改
num_repeats后未更新abbr,可能触发.cache/dataset_size.json缓存不匹配; - 执行环境:代码在子进程中隔离执行并受超时保护,但若模型回答格式特殊导致正则提取失败,可在
eval_cfg中替换pred_postprocessor或检查details中的原始回答定位问题。
围绕代码评估,仓库还提供了 MBPP-Plus(MBPPEvaluator2、MBPPPlusDataset,依赖 evalplus)、sanitized MBPP(SanitizedMBPPDataset)以及 humaneval-plus(HumanEvalPlusEvaluator)等变体,相关配置与源码可分别在 mbpp 目录、humaneval 目录 与 mbpp.py、humaneval.py 中继续深入研读。