OpenCompass 数学能力评测实战:基于 MATHVerifyEvaluator 的数学推理与 LaTeX 答案自动校验

原创2026-09-27 20:51:522,138 阅读
文章标签:人工智能大模型模型评测AI 评测排行榜机器学习深度学习开发者工具

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 方法对每条样本执行如下流程:

  1. 解析参考答案(gold):将参考答案用 $...$ 包裹后,依次用 LatexExtractionConfig() 与 ExprExtractionConfig() 两种提取配置、以 first_match 模式解析(math_evaluator.py);
  2. 解析模型预测(pred):用 LatexExtractionConfig 提取,并配置 NormalizationConfig 对 LaTeX 做归一化,包括 nits=False、malformed_operators=False、basic_latex=True、equations=True、boxed='all'、units=True 等(math_evaluator.py);
  3. 等价性验证:调用 verify(answer_parsed, gold_parsed) 判定二者在数学意义上是否等价(math_evaluator.py);
  4. 超时保护:每条样本在子进程中执行,默认 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。

仓库中还提供了多种可直接复用的组合配置,例如:

模型配置与预测后处理

评测数学推理类模型时,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 等官方配置,这套方案都能直接落地,帮助你得到更准确、更可信的模型数学能力评估结果。

登录后查看全文
opencompass