OpenCompass 数学能力评测实战:基于 MATHVerifyEvaluator 的数学推理与 LaTeX 答案自动校验
OpenCompass 数学能力评测实战:基于 MATHVerifyEvaluator 的数学推理与 LaTeX 答案自动校验
数学推理是大语言模型(LLM)的核心能力之一,而如何对模型逐步求解数学问题后给出的最终答案进行精确、公平、可复现的判定,是评测工程中的关键难点。本文以 OpenCompass 官方指南 General Math Evaluation Guidance 为骨架,结合仓库源码与真实配置,完整讲解如何用 CustomDataset + MATHVerifyEvaluator 搭建数学评测任务:从数据集格式、三大配置组件、评测器内部实现原理,到与 CascadeEvaluator(规则评测 + LLM 评判器级联)的进阶组合。读完后你将能够为任意数学数据集(Math-500、AIME、GSM8K 或自建 JSONL/CSV)一键配置并运行高可信度的数学能力评测。
为什么需要专门的数学答案校验器
数学评测与传统文本评测的最大区别在于:"答案正确"不等于"字符串相同"。模型可能给出 \boxed{\frac{1}{2}}、0.5 或 1/2,参考答案也可能是 (x+1)^2 而非 x^2 + 2x + 1。如果仅做文本比对,大量等价答案会被误判为错误,导致评测分数失真。
为此,OpenCompass 在 README.md 中宣布(2025.02.15 更新)新增了 MATHVerifyEvaluator 作为数学推理评测工具。它基于开源的 math_verify 库,对模型输出与参考答案进行 LaTeX 解析与数学等价性验证——即把表达式解析成符号数学对象后再判断是否等价,而不是比对字符串。这是官方推荐的数学评测方案,与其配套的 LLM 评判器指南 共同构成了 OpenCompass 的答案校验体系。
数据集格式:JSONL 或 CSV,问题 + 解答两列即可
数学评测数据集应为 JSON Lines(.jsonl)或 CSV 格式。每条样本至少包含两个字段:
- 问题陈述(problem statement)
- 解答/答案(solution/answer),通常为 LaTeX 格式,最终答案用
\boxed{}包裹
JSONL 格式示例(每条记录一行,字段间用逗号分隔):
{"problem": "Find the value of x if 2x + 3 = 7", "solution": "Let's solve step by step:\n2x + 3 = 7\n2x = 7 - 3\n2x = 4\nx = 2\nTherefore, \\boxed{2}"}
CSV 格式示例:
problem,solution
"Find the value of x if 2x + 3 = 7","Let's solve step by step:\n2x + 3 = 7\n2x = 7 - 3\n2x = 4\nx = 2\nTherefore, \\boxed{2}"
实操提示:
solution列建议保留完整解题过程并在末尾用\boxed{...}给出最终答案,这样既方便人类复核,也便于MATHVerifyEvaluator从长文本中提取答案。
仓库中真实的 Math-500 配置 math_500_gen.py 即使用 JSONL 数据集:path='opencompass/math'、file_name='test_prm800k_500.jsonl',可直接作为你自建数据集的参照。
三大配置组件:reader_cfg / infer_cfg / eval_cfg
在 OpenCompass 中,一个数学评测任务由三个核心配置组装而成,官方指南分别给出了定义:
1. 数据集读取配置(reader_cfg)
指定问题列与答案列的名称:
math_reader_cfg = dict(
input_columns=['problem'], # Column name for the question
output_column='solution' # Column name for the answer
)
2. 推理配置(infer_cfg)
定义提示词模板(要求模型逐步推理并输出 \boxed{} 最终答案)、检索器与推理器。对于数学评测,通常使用 ZeroRetriever(零样本,不检索示例)与 GenInferencer(生成式推理):
math_infer_cfg = dict(
prompt_template=dict(
type=PromptTemplate,
template=dict(
round=[
dict(
role='HUMAN',
prompt='{problem}\nPlease reason step by step, and put your final answer within \\boxed{}.',
),
]
),
),
retriever=dict(type=ZeroRetriever),
inferencer=dict(type=GenInferencer),
)
注意 {problem} 占位符对应 reader_cfg 中的 input_columns,提示词中的 \boxed{} 要求是让后续规则评测器能够准确定位最终答案的关键约定。
3. 评测配置(eval_cfg)
将评测器指定为 MATHVerifyEvaluator:
math_eval_cfg = dict(
evaluator=dict(type=MATHVerifyEvaluator),
)
使用 CustomDataset 组装完整任务
将上述三个配置挂载到 CustomDataset 上,即可构成一个完整的数据集评测配置(官方指南原文示例):
from mmengine.config import read_base
from opencompass.models import TurboMindModelwithChatTemplate
from opencompass.datasets import CustomDataset
math_datasets = [
dict(
type=CustomDataset,
abbr='my-math-dataset', # Dataset abbreviation
path='path/to/your/dataset', # Path to your dataset file
reader_cfg=math_reader_cfg,
infer_cfg=math_infer_cfg,
eval_cfg=math_eval_cfg,
)
]
字段说明:
abbr:数据集简称,将显示在评测结果汇总表中;path:数据集文件路径,支持本地.jsonl/.csv文件或opencompass/xxx这类数据仓库路径(如math_500_gen.py中path='opencompass/math');- 若文件名为非默认值,可额外指定
file_name,见 math_500_gen.py; - 三件套
reader_cfg/infer_cfg/eval_cfg必须齐全,评测器才会在评测阶段被调用。
MATHVerifyEvaluator 源码级剖析
MATHVerifyEvaluator 是专门用于数学答案判定的评测器,其完整实现位于 opencompass/evaluator/math_evaluator.py,通过 @ICL_EVALUATORS.register_module() 注册,因此既可以从 opencompass.evaluator 导入(如 math_500_gen.py 的 from opencompass.evaluator import MATHVerifyEvaluator),也可按官方文档写法从 opencompass.openicl.icl_evaluator.math_evaluator 导入。
基于 math_verify 库的解析与验证流程
评测器依赖 math_verify 与 latex2sympy2_extended 两个库(安装缺失时会抛出明确的 ImportError 提示,见 math_evaluator.py)。其 score 方法对每条样本执行如下流程:
- 解析参考答案(gold):将参考答案用
$...$包裹后,依次用LatexExtractionConfig()与ExprExtractionConfig()两种提取配置、以first_match模式解析(math_evaluator.py); - 解析模型预测(pred):用
LatexExtractionConfig提取,并配置NormalizationConfig对 LaTeX 做归一化,包括nits=False、malformed_operators=False、basic_latex=True、equations=True、boxed='all'、units=True等(math_evaluator.py); - 等价性验证:调用
verify(answer_parsed, gold_parsed)判定二者在数学意义上是否等价(math_evaluator.py); - 超时保护:每条样本在子进程中执行,默认 10 秒超时,超时或解析出错会被记为错误/跳过,避免个别病态表达式拖垮整个评测(math_evaluator.py)。
从源码结构可以推断,将解析放入 multiprocessing 子进程(_verify_worker)的设计,是为了隔离 sympy 等符号计算库可能出现的资源占用或卡死问题,保证评测流程稳健。
支持的数学表达式类型
官方文档与源码测试用例(math_evaluator.py)共同确认了评测器覆盖的数学类型:
- 基本算术运算:如
\boxed{\frac{1}{2}}、\boxed{2 + 3}、\boxed{2 \times 3} - 分数与小数:如
0.5与\frac{1}{2}等价 - 代数表达式:如
\boxed{x^2 + 2x + 1}与(x+1)^2等价 - 三角函数:如
\boxed{\sin(x) + \cos(x)}、\tan^2(x) + \sec^2(x) - 根式与指数:如
\boxed{\sqrt{16}}、\sqrt[3]{x^2 + 1} - 对数:如
\ln(e^2)、\log_2(8) - 极限与求和:如
\lim_{x \to 0} \frac{\sin(x)}{x}、\sum_{i=1}^{n} i - 积分:如
\int_{0}^{1} x^2 dx,甚至双重积分 - 矩阵:如
\begin{pmatrix} 1 & 2 \\ 3 & 4 \end{pmatrix} - 组合表达式:如
\frac{\sqrt{x^2 + 1}}{\ln(x)} + \int_{0}^{x} t^2 dt
源码还专门覆盖了空 \boxed{}、缺分母的非法 \boxed{\frac{1}}、嵌套 \boxed{\boxed{1}} 等边界情况,体现其健壮性。
评测输出格式
score 方法返回 {'accuracy': ..., 'details': <a href="https://link.gitcode.com/i/1dda4c1f915f3fba519c6200950d7f41" target="_blank">...]} 结构([math_evaluator.py),官方文档给出的输出示例如下:
{
'accuracy': 85.0, # Percentage of correct answers
'details': [
{
'predictions': 'x = 2', # Parsed prediction
'references': 'x = 2', # Parsed reference
'correct': True # Whether they match
},
# ... more results
]
}
其中 accuracy 为正确率百分比,details 中每条记录包含解析后的预测答案(pred)、解析后的参考答案(answer)与 correct 布尔标记;超时或解析异常时,pred 字段会保留原始预测或错误信息,correct 为 False(math_evaluator.py)。
进阶组合:MATHVerifyEvaluator + CascadeEvaluator 级联评测
纯规则校验对高度格式化的数值答案非常高效,但对叙述型或含歧义的答案可能误判。OpenCompass 的 CascadeEvaluator(实现见 cascade_evaluator.py)给出了更稳健的方案:先用规则评测器(如 MATHVerifyEvaluator)判定,仅对规则判定为错误的样本再交给 LLM 评判器复核;若设置 parallel=True,则规则与 LLM 同时评测全部样本,最终"任一判定正确即为正确"。
其真实应用可见 aime2025_cascade_eval_gen_5e9f4f.py:
cascade_evaluator = dict(
type=CascadeEvaluator,
rule_evaluator=dict(
type=MATHVerifyEvaluator,
),
llm_evaluator=dict(
type=GenericLLMEvaluator,
prompt_template=dict(
type=PromptTemplate,
template=dict(
begin=[
dict(
role='SYSTEM',
fallback_role='HUMAN',
prompt="You are a helpful assistant who evaluates the correctness and quality of models' outputs.",
)
],
round=[
dict(role='HUMAN', prompt=GRADER_TEMPLATE),
],
),
),
dataset_cfg=dict(
type=CustomDataset,
path='opencompass/aime2025',
reader_cfg=aime2025_reader_cfg,
),
judge_cfg=dict(),
dict_postprocessor=dict(type=generic_llmjudge_postprocess),
),
parallel=False,
)
aime2025_eval_cfg = dict(
evaluator=cascade_evaluator,
)
级联评测的返回结构比单独使用 MATHVerifyEvaluator 更丰富,包含 cascade_stats 统计(rule_correct、rule_accuracy、llm_evaluated、llm_correct、llm_accuracy、final_correct、final_accuracy、parallel_mode)以及每条样本的 rule_evaluation / llm_evaluation / cascade_correct 明细,相关结果结构的校验可参考测试文件 test_aime2025_eval.py。
仓库中还提供了多种可直接复用的组合配置,例如:
- math_500_cascade_eval_gen_6ff468.py:Math-500 的规则 + LLM 级联评测
- math_prm800k_500_llmverify_gen_6ff468.py:纯 LLM 评判(
GenericLLMEvaluator)方案,可对比验证 - examples/eval_cascade_evaluator.py:完整可运行示例,同一份
eval_cfg中注释保留了"仅规则评测 / 仅 LLM 评测 / 级联评测"三种切换方式
模型配置与预测后处理
评测数学推理类模型时,OpenCompass 的 BaseEvaluator 支持通过 pred_postprocessor 对模型输出做统一预处理(见 icl_base_evaluator.py)。对于输出长思维链(reasoning)的推理模型,官方示例 examples/eval_math_verify.py 演示了关键技巧——在模型配置中使用 extract_non_reasoning_content 剔除思维链内容,只保留最终答案部分再交给评测器:
models = [
dict(
type=TurboMindModelwithChatTemplate,
abbr='deepseek-r1-distill-llama-8b-turbomind',
path='deepseek-ai/DeepSeek-R1-Distill-Llama-8B',
engine_config=dict(session_len=32768, max_batch_size=8, tp=1),
gen_config=dict(
top_k=1, temperature=1e-6, top_p=0.9, max_new_tokens=4096
),
max_seq_len=32768,
max_out_len=32768,
batch_size=32,
run_cfg=dict(num_gpus=1),
pred_postprocessor=dict(type=extract_non_reasoning_content),
),
# ... 更多模型
]
该示例同时展示了两种采样策略:确定性采样(top_k=1, temperature=1e-6)适合追求稳定分数的场景,带 do_sample=True 的随机采样(如 temperature=0.6, top_p=0.95)则适合需要多样性的实验。
环境依赖与运行方式
安装依赖
MATHVerifyEvaluator 需要 math_verify 与 latex2sympy2_extended 两个 Python 包。仓库在 requirements/extra.txt 中将其声明为 math-verify[antlr4_11_0](标注 # Math),可安装:
pip install math-verify latex2sympy2_extended
# 或安装完整 extra 依赖
pip install -r requirements/extra.txt
运行评测
将数据集与模型配置写入配置文件后,通过 OpenCompass 的统一入口 run.py 启动(参见 快速开始):
python run.py configs/your_math_eval_config.py
完整可运行示例
以下为官方文档提供的完整配置模板,按仓库源码补齐了导入路径(MATHVerifyEvaluator 从 opencompass.evaluator 导入,与 math_500_gen.py 保持一致),可直接复制改造:
from mmengine.config import read_base
from opencompass.models import TurboMindModelwithChatTemplate
from opencompass.datasets import CustomDataset
from opencompass.evaluator import MATHVerifyEvaluator
from opencompass.openicl.icl_prompt_template import PromptTemplate
from opencompass.openicl.icl_retriever import ZeroRetriever
from opencompass.openicl.icl_inferencer import GenInferencer
# Dataset reader configuration
math_reader_cfg = dict(input_columns=['problem'], output_column='solution')
# Inference configuration
math_infer_cfg = dict(
prompt_template=dict(
type=PromptTemplate,
template=dict(
round=[
dict(
role='HUMAN',
prompt='{problem}\nPlease reason step by step, and put your final answer within \\boxed{}.',
),
]
),
),
retriever=dict(type=ZeroRetriever),
inferencer=dict(type=GenInferencer),
)
# Evaluation configuration
math_eval_cfg = dict(
evaluator=dict(type=MATHVerifyEvaluator),
)
# Dataset configuration
math_datasets = [
dict(
type=CustomDataset,
abbr='my-math-dataset',
path='path/to/your/dataset.jsonl', # or .csv
reader_cfg=math_reader_cfg,
infer_cfg=math_infer_cfg,
eval_cfg=math_eval_cfg,
)
]
# Model configuration
models = [
dict(
type=TurboMindModelwithChatTemplate,
abbr='your-model-name',
path='your/model/path',
# ... other model configurations
)
]
# Output directory
work_dir = './outputs/math_eval'
若需对齐官方预置数据集,可将 math_datasets 直接替换为仓库内置配置,例如 math_500_gen.py 导出的 math_datasets(其 path='opencompass/math'、file_name='test_prm800k_500.jsonl'),并用 examples/eval_math_verify.py 的运行方式指定模型即可快速验证。
小结
本文完整还原了 OpenCompass 数学能力评测的官方指南,并深入源码补充了实现细节:数据集仅需 problem + solution 两列(JSONL/CSV);评测链路由 reader_cfg、infer_cfg、eval_cfg 三件套组装;MATHVerifyEvaluator 通过 math_verify 库实现 LaTeX 提取、符号化解析与数学等价性验证,并内置子进程超时保护;当需要更高容错时,可升级为 CascadeEvaluator(规则评测 + LLM 评判器)组合。从自建数据集到 Math-500/AIME 等官方配置,这套方案都能直接落地,帮助你得到更准确、更可信的模型数学能力评估结果。