LLM Math Evaluation Harness：让数学推理基准测试回归标准化

背景：为什么需要一个"数学基准"工具包？

如果你是一名 AI 研究者，正在训练一个大语言模型（LLM），你最想回答的一个问题是：我的模型数学能力到底怎么样？

这个看似简单的问题，在实际中却困难重重。当前主流的数学评测基准包括 GSM8K、MATH、SVAMP 等十余个数据集，每个数据集的格式、答案提取方式、评分逻辑都各不相同。更让人头疼的是，研究者们发现：不同评测框架对同一模型的评分差异可达 5% 以上——这意味着"GPT-4 在 MATH 上得 42%"可能在另一个框架下是 47%，根本无法公平比较。

ZubinGou（GitHub ID）的 math-evaluation-harness 正是为解决这一痛点而生。它将多个数学评测基准的评估逻辑统一封装，提供标准化的打分管道，让研究者可以在同一套框架下，对比任何 Hugging Face 或 vLLM 支持的 LLM 在数学任务上的表现。

这个项目并非闭门造车——微软的 ToRA（ICLR'24）和 DeepSeek-Coder 均已将其作为官方评测工具。

核心功能：一条命令，评测所有主流数学基准

该项目最核心的价值在于评测覆盖度和模型兼容性的统一。

支持的评测数据集（14个）：

从初等数学（GSM8K）到高等数学（MATH、minerva_math），从文字应用题（SVAMP、ASDiv、MAWPS）到多步推理（TabMWP、TheoremQA），从金融计算（FinQA）到SAT数学题，覆盖了目前 LLM 数学评测的主流数据集。数据来源包括 Hugging Face 公开数据集（competition_math、gsm8k 等）和本地 JSONL 文件两种方式。

支持的模型接入方式：

项目同时支持 Hugging Face Transformers 和 vLLM 两种推理后端。vLLM 提供了高吞吐量的 PagedAttention 推理，适合大批量评测；Transformers 则适合需要精细控制生成过程的场景。模型加载只需配置 MODEL_NAME_OR_PATH，极大降低了接入成本。

支持的提示策略（Prompting Paradigms）：

代码实现层面，prompts/ 目录下存放了 cot、pal、tora 三种提示模板，通过 utils.py 中的 construct_prompt() 函数组装。研究者可以在这里扩展自己的提示策略。

技术架构：从模型推理到符号评分的完整管道

evaluate.py 是整个评测管道的入口，其执行流程如下：

1. 数据加载（data_loader.py）：从本地 JSONL 或 Hugging Face Dataset 加载评测数据，按 idx 去重并排序。

2. 答案解析（parser.py）：将原始数据中的 ground truth 解析为标准格式（gt_cot 推理链 + gt 最终答案）。

3. 模型推理：调用 vLLM 或 HF 生成预测结果。

4. 代码执行（python_executor.py）：对 PAL/PoT 类提示，提取代码块并通过 Python executor 执行，捕获 stdout 作为预测答案。

5. 评分（grader.py）：这是最核心、最复杂的模块。它实现了 4 层答案匹配逻辑：

   • 精确数值匹配：浮点数比较，支持百分比（37% → 0.37/37/37.0 三种等价形式）
   • 符号表达式匹配：通过 SymPy 进行符号化简和等价判断（如 x^2-1 = (x-1)(x+1)）
   • LaTeX 解析匹配：LaTeX 格式答案转 SymPy 后匹配，处理 rac{}{}、矩阵等复杂格式
   • 数值近似匹配：isclose() 处理浮点精度问题

grader.py 中还引入了一个自定义依赖：latex2sympy2（来自 git+https://github.com/ZubinGou/latex2sympy.git），这是作者 fork 维护的版本，用于处理评测数据集中的 LaTeX 数学表达式。

并发评测方面，evaluate.py 使用 pebble.ProcessPool 实现多进程并行评分，单次评测最多可利用全部 CPU 核心，timeout 为 3 秒/题。

部署体验：GPU 是硬性要求

从部署角度看，这是一个纯 CLI 工具，没有 Web 界面，交互全靠命令行参数。

安装方式很简单：

git clone https://github.com/ZubinGou/math-evaluation-harness.git
cd math-evaluation-harness
pip install -r requirements.txt

核心依赖包括：vLLM（推理加速）、transformers + torch（Hugging Face 模型加载）、sympy（符号计算）、latex2sympy2（LaTeX 解析）、Pebble（并发）。值得注意的是 sympy==1.12 和 antlr4-python3-runtime==4.11.1 之间存在版本兼容约束，这是安装时容易踩的坑。

GPU 是硬性要求：模型推理需要 NVIDIA GPU，最低 6GB 显存（适合 6-7B 参数模型），推荐 16GB+。README 中提供了通过 Docker 启动 vLLM 的示例，但这只是一个 vLLM 服务的启动命令，并非项目自带的 Dockerfile。整体部署难度评分为中等，没有容器化打包，需要手动配置 CUDA 环境。

评测运行示例：

bash scripts/run_eval.sh cot Qwen/Qwen1.5-1.8B
bash scripts/run_eval.sh pal Qwen/Qwen1.5-1.8B
bash scripts/run_eval.sh tool-integrated ToRA/ToRA-7B

局限与争议

这个工具包并非完美，以下几点值得注意：

1. 符号计算依赖的脆弱性：LaTeX 解析和符号计算高度依赖 sympy 和 latex2sympy2 两个库，版本不匹配会导致评分失败。requirements.txt 中明确限制了 sympy==1.12 和 antlr4==4.11.1 的组合，安装其他版本可能引发连锁问题。

2. 数据集版本管理缺失：部分数据集（如 theorem_qa、finqa）直接从 Hugging Face 在线加载，没有锁定版本。数据集更新后，评测结果可能出现无法复现的问题。

3. 并发执行的稳定性：pebble.ProcessPool 在部分系统上可能因资源竞争导致超时，建议在多核机器上运行并留意日志中的 timeout_cnt。

4. 不适合终端用户：项目面向的是 AI 研究者和工程师，普通开发者无法直接使用。对于只是想测试某个模型数学能力的用户，门槛较高。

行业意义：推动数学评测标准化

math-evaluation-harness 的出现，反映了 LLM 评测领域的一个深层矛盾：各研究团队自行实现评测代码，导致结果无法横向对比。ToRA 和 DeepSeek-Coder 的认可（将其作为官方评测工具）说明该项目已在一定程度上起到了行业基准的作用。

从基准测试数据的增长曲线来看，该仓库获得了 277 颗 GitHub Stars、23 次 Fork，活跃的 issue 讨论表明社区仍在持续使用。2026 年 6 月 25 日还有更新，说明项目仍处于维护状态。

对于 AI 研究团队而言，这个工具包是快速建立评测管线的实用选择；对于 AI 爱好者，它也是理解大模型数学能力边界的一面镜子——通过它，你可以清晰地看到：GPT-4 级别的模型在复杂数学推导上仍有明显短板，而结合外部工具（如 ToRA）的模型则能显著缩小这一差距。