README-cn.md

<div align="center">
<img src="https://huggingface.co/Caldalis/MiniCPM5-2B-Math/resolve/main/assets/banner.png" alt="MiniCPM5-2B-Math：面向数学与证明的 2.5B 模型，附带一个你自己就能跑起来的证明蜂群" width="100%" />
</div>

<p align="center">
<a href="https://github.com/Caldalis/MiniCPM-Math-harness" target="_blank">MiniCPM-Math harness</a> |
<a href="https://huggingface.co/Caldalis/MiniCPM5-2B-Math-GGUF" target="_blank">GGUF</a> |
<a href="https://huggingface.co/openbmb/MiniCPM5-2B" target="_blank">MiniCPM5-2B</a> |
<a href="https://github.com/OpenBMB/MiniCPM" target="_blank">MiniCPM GitHub</a>
</p>

<p align="center">
<a href="https://huggingface.co/Caldalis/MiniCPM5-2B-Math" target="_blank">English</a> |
中文
</p>


## 亮点

**MiniCPM5-2B-Math** 是一个基于 MiniCPM5 的数学与证明专项模型：基于
[MiniCPM5-2B](https://huggingface.co/openbmb/MiniCPM5-2B) 针对长链数学推理和证明写作做了后训练的
2.5B 稠密模型。单张消费级显卡或一台笔记本就能运行，保留原生 128k 上下文。

- **同尺寸下很强。** 作为最多思考 128K token 的普通单次调用，AIME 2025 92.3、AIME 2026 89.8、HMMT 2026 年 2 月赛 81.8
  （avg@16），16 样本投票为 100 / 93.3 / 90.9。整体 AIME，HMMT 测评上超越原版通用模型 MiniCPM5-2B。
- **能写出可核查的证明。** 在 IMO-ProofBench Basic 上，一次最多 128K token 的普通调用平均能为 30 题中的 21 题写出完整证明，
  证明蜂群为 23 题（AI 评审盲评）。
- **自带"证明蜂群"。** 开源的 [MiniCPM-Math harness](https://github.com/Caldalis/MiniCPM-Math-harness) 可以在任意兼容
  OpenAI 协议的服务上，围绕本模型运行并行证明、对抗式审稿、暴力验算和迭代修补。它针对实测到的失败模式设计。
- **小到可以自己拥有。** BF16 权重 5.0 GB，GGUF Q4_K_M 仅 1.6 GB。标准 `LlamaForCausalLM` 架构，无需自定义代码。

## 测评

### AIME 与 HMMT

| 测试 | 指标 | MiniCPM5-2B | MiniCPM5-2B-Math |
|---|---|---:|---:|
| AIME 2025 | avg@16 | 87.1 | **92.3** |
| | 投票（maj@16） | 93.3 | **100.0** |
| AIME 2026 | avg@16 | 89.8 | 89.8 |
| | 投票（maj@16） | 93.3 | 93.3 |
| HMMT Feb 2026 | avg@16 | 68.4 | **81.8** |
| | 投票（maj@16） | 75.8 | **90.9** |

*avg@16* 是单个样本的平均正确率，也就是一次普通 API 调用的正确率；*投票*是 16 个样本的多数答案（用
[harness](https://github.com/Caldalis/MiniCPM-Math-harness) 复现：`minicpm-math solve -n 16 --max-tokens 131072 --no-early-stop --no-force-finish`）。

### 证明题：IMO-ProofBench Basic

全部 30 题。*单次调用*：每题 16 次独立调用，每次最多 128K token。
*证明蜂群*：harness 的 `standard` 档位，prover 和 refiner 每次可用 128K token。
所有证明和评分均已
[公开](https://github.com/Caldalis/MiniCPM-Math-harness/tree/main/docs/results/proofbench-basic)。

| | 完整证明 | 平均分（0–7） |
|---|---:|---:|
| 单次调用（avg@16） | 21.0 / 30 | 5.48 |
| 证明蜂群 | **23 / 30** | **5.83** |

## 搭配证明蜂群使用

```bash
pip install "minicpm-math[math] @ git+https://github.com/Caldalis/MiniCPM-Math-harness"
vllm serve Caldalis/MiniCPM5-2B-Math --max-model-len 131072 --port 8000
minicpm-math prove "证明：对任意整数 n，n^5 - n 能被 30 整除。" --base-url http://127.0.0.1:8000/v1
```

上面的蜂群成绩使用了 `--max-tokens 131072`；默认档位每次调用 32K token，速度更快。

蜂群会返回最佳证明以及它的评审情况（只有全部 verifier 都打 ≥ 6/7 才标记为 `accepted`），并保留每一次调用的完整记录。
配置档位、答案投票模式和 benchmark 用法见 [harness README](https://github.com/Caldalis/MiniCPM-Math-harness)。

## 快速开始

> [!Tip]
> 推荐采样参数：`temperature=0.9, top_p=0.95, min_p=0.0`，开启思考模式。难题的证明可能需要 64K–120K 的输出
> token，请给服务足够的上下文（`--max-model-len 131072`），并为请求设置较大的 `max_tokens`。

### vLLM

```bash
pip install "vllm>=0.21"
vllm serve Caldalis/MiniCPM5-2B-Math --max-model-len 131072 --port 8000
```

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Caldalis/MiniCPM5-2B-Math",
    "messages": [{"role": "user", "content": "证明根号 2 是无理数。"}],
    "max_tokens": 16384, "temperature": 0.9, "top_p": 0.95,
    "chat_template_kwargs": {"enable_thinking": true}
  }'
```

vLLM 0.24.0 + RTX 4090 实测：单卡、短输入时单流解码约 155 tok/s。在五张 4090、最多 10 路并发的长证明任务中，单请求解码速度中位数约 118 tok/s，总吞吐约 900 tok/s。

### SGLang

```bash
pip install "sglang[srt]>=0.5.16"
python -m sglang.launch_server --model-path Caldalis/MiniCPM5-2B-Math --context-length 131072 --port 30000
```

### llama.cpp

```bash
llama-server -hf Caldalis/MiniCPM5-2B-Math-GGUF:Q8_0 --jinja -ngl 99 -c 98304 -np 4 -kvu --port 8000
```

8000 是 harness 默认连接的端口（不加 `--port` 时 llama-server 监听 8080）；配合这个服务运行 harness 时请用 `--profile quick`。Apple M5 笔记本（16 GB）+ Q8_0 实测：单流约 46 tok/s，4 个 slot 并发总计约 125 tok/s。llama.cpp 默认的
`min_p=0.05` 容易引发复读，请在请求中设置 `min_p=0.0`（harness 会自动设置）。

### Transformers

```bash
pip install -U "transformers>=5.6" accelerate torch
```

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "Caldalis/MiniCPM5-2B-Math"
tokenizer = AutoTokenizer.from_pretrained(model_id)
# 在 Apple Silicon（MPS）上请额外传入 attn_implementation="eager"：PyTorch 的 MPS SDPA 内核（torch 2.11 下验证）
# 处理本模型的分组查询注意力时会出错，导致输出质量下降。CUDA 和 CPU 不受影响。
model = AutoModelForCausalLM.from_pretrained(model_id, dtype="auto", device_map="auto")

messages = [{"role": "user", "content": "求所有使 n^2 - 19n + 99 为完全平方数的正整数 n。"}]
inputs = tokenizer.apply_chat_template(
    messages, tokenize=True, add_generation_prompt=True, enable_thinking=True,
    return_dict=True, return_tensors="pt",
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=8192, do_sample=True, temperature=0.9, top_p=0.95)
print(tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True))
```

### 提示词建议

- 有最终答案的题目，在末尾加上 *"Please reason step by step, and put your final answer within \boxed{}."*
- 证明题请明确要求"完整、严谨的证明"；遇到"求所有""确定"类问题，要求双向论证。
- 开启思考时，推理以 `</think>` 结束，后面是最终答案。带 reasoning parser 的服务会分开返回两部分，否则按 `</think>` 切分即可。

## 许可证

模型权重采用 [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可证发布（见 `LICENSE`），与基座模型
[MiniCPM5-2B](https://huggingface.co/openbmb/MiniCPM5-2B) 的许可证相同。