如何用MiniCPM-2B-history跑通第一次对话?新手最简Python示例与踩坑清单
如何用MiniCPM-2B-history跑通第一次对话?新手最简Python示例与踩坑清单
MiniCPM-2B-history 是面壁智能与清华大学 NLP 实验室开源的 MiniCPM-2B 训练过程 Checkpoint 历史仓库,完整保留了从第 1 步到第 350000 步的模型权重快照。本文用最简 Python 示例带你加载其中某个训练步的权重、跑通第一次对话,并附上一份新手必看的踩坑清单。
⚠️ 重要提醒(引自 README.md):本仓库是训练过程中的 checkpoint,服务于研究目的,不是最终可用的模型文件!如果你只是想用 MiniCPM-2B 做应用,应使用官方发布的
openbmb/MiniCPM-2B-sft-bf16等正式版;本教程的目标是让你亲手"打开训练黑盒",观察不同训练阶段的模型表现。
一、先搞懂:MiniCPM-2B-history 是什么?
MiniCPM 是面壁智能与清华大学自然语言处理实验室共同开源的端侧语言大模型系列,主体语言模型 MiniCPM-2B 仅有 24 亿(2.4B)非词嵌入参数,一张 1080/2080 可高效微调、Int4 量化后甚至能跑在手机上。
这个仓库每隔 500 步保存一次检查点,公开发放的是步数为 10000 整数倍的 35 个检查点(每个约 5.4GB,bf16 精度)。按照训练阶段可以这样理解:
| 检查点步数 | 训练阶段 | 建议用途 |
|---|---|---|
10000 ~ 260000 |
稳定训练阶段 | 研究训练过程,输出质量波动大,早期步数可能"不知所云" |
260000 ~ 280000(准确为 261000~279500) |
退火(decay)阶段 | 公开检查点中效果最好,想跑通对话推荐从这里选 |
> 280000 |
未被利用的剩余退火阶段 | 学习率已极小且无收益,不建议使用 |
💡 新手建议:想看到最接近"成品"的对话效果,优先加载 pytorch_model.260000 之后的检查点。
二、环境准备:安装依赖 + 正确下载权重文件
1. 安装 Python 依赖
pip install "transformers>=4.36.0" accelerate
2. 用 Git LFS 克隆仓库(关键!)
仓库里的权重文件托管在 Git LFS 上。如果没装 git-lfs,你下载到的 pytorch_model.260000 会只是一个 135 字节的指针文件,而不是真正的 5.4GB 权重:
git lfs install
git clone https://gitcode.com/OpenBMB/MiniCPM-2B-history
克隆完成后,检查文件大小确认 LFS 生效:
ls -lh MiniCPM-2B-history/pytorch_model.260000
# 正常应显示约 5.4G,而不是 135 字节
三、最简 Python 示例:三步跑通第一次对话
第 1 步:整理一个"标准加载目录"
from_pretrained 只能自动识别 pytorch_model.bin 这类标准文件名,而本仓库的权重叫 pytorch_model.<步数>,需要手动复制重命名(仓库是只读的,不要直接改名):
mkdir -p minicpm-2b-load && cd minicpm-2b-load
cp ../MiniCPM-2B-history/config.json .
cp ../MiniCPM-2B-history/generation_config.json .
cp ../MiniCPM-2B-history/configuration_minicpm.py .
cp ../MiniCPM-2B-history/modeling_minicpm.py .
cp ../MiniCPM-2B-history/tokenizer.json .
cp ../MiniCPM-2B-history/tokenizer.model .
cp ../MiniCPM-2B-history/tokenizer_config.json .
cp ../MiniCPM-2B-history/special_tokens_map.json .
cp ../MiniCPM-2B-history/pytorch_model.260000 pytorch_model.bin # 选定训练步 260000
第 2 步:加载模型并发起第一次对话
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch
torch.manual_seed(0)
path = "./minicpm-2b-load"
tokenizer = AutoTokenizer.from_pretrained(path, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
path,
torch_dtype=torch.bfloat16, # 必须显式指定数据类型,否则会引起较大计算误差!
device_map="cuda",
trust_remote_code=True, # 必须开启,才能加载自定义的建模代码
)
response, history = model.chat(
tokenizer,
"山东省最高的山是哪座山,它比黄山高还是矮?",
temperature=0.8,
top_p=0.8,
)
print(response)
chat 是仓库在 modeling_minicpm.py 中封装的对话入口,它会按 tokenizer_config.json 里的 chat 模板(<用户> / <AI> 标签)拼接提示词、调用 generate 生成回复,并自动把问答追加进 history,返回 (response, history) 两个值。
第 3 步:查看输出
参考 README.md 给出的期望输出风格,正式版模型的典型回复类似:
山东省最高的山是泰山,海拔1545米。
相对于黄山(海拔1864米),泰山海拔较低,相差约319米。
📌 注意:加载的是训练中期 checkpoint,回复的流畅度和准确性会与正式版有差异,这是正常的——观察这种差异正是研究训练过程的价值所在。
四、进阶:用 history 参数实现多轮对话
chat 方法把上一轮的问答存入了 history,下一轮直接传入即可,模型会自动带上上下文:
response, history = model.chat(tokenizer, "它比黄山高还是矮?差距多少?",
history=history, temperature=0.8)
print(response)
其他常用生成参数(见 modeling_minicpm.py 的 chat 签名):
max_length:最大生成长度,默认 4096(与 config.json 的max_position_embeddings: 4096一致,输入+输出总长不要超过这个值)temperature/top_p:控制随机性,数值越低回复越稳定num_beams:束搜索宽度,设为 1 即普通采样
若不经过 chat 而直接调用 generate,采样参数默认读取 generation_config.json(do_sample: true、top_p: 0.8、temperature: 0.8)。
五、新手踩坑清单(逐条对照检查)
| # | 现象 | 原因 | 解决办法 |
|---|---|---|---|
| 1 | 模型加载报 File ... not found |
权重文件名不是标准的 pytorch_model.bin |
按"第 1 步"复制并重命名后再加载 |
| 2 | 下载下来的权重只有 135 字节 | 未安装 Git LFS,只下载了指针文件 | git lfs install 后重新拉取 |
| 3 | 回复全是乱码/无意义字符 | 加载了训练早期 checkpoint(如 step 10000) | 改选 260000~280000 退火阶段的检查点 |
| 4 | 数值异常、输出质量明显劣化 | from_pretrained 未显式指定 torch_dtype |
加上 torch_dtype=torch.bfloat16(README 重点警告) |
| 5 | 报错找不到 MiniCPMForCausalLM 架构 |
漏了 trust_remote_code=True |
tokenizer 和 model 加载时都开启 |
| 6 | device_map 报错 |
未安装 accelerate |
pip install accelerate |
| 7 | 显存不足(OOM) | bf16 权重约 5.5GB,加上下文后 8GB 显卡才宽裕 | 用 torch_dtype=torch.bfloat16 且控制 max_length,不要尝试 fp32 加载 |
| 8 | 同样问题多次回答不一致 | 小模型受 prompt 影响大,属已知局限性 | 降低 temperature、更换 top_p 或固定随机种子复现 |
另外官方在 README.md 中提示:Huggingface 生成质量略差于 vLLM,因此正式评测推荐使用 vLLM;如果你只是跑通 demo,用本文的 transformers 方式即可。
六、仓库常用文件速查表
| 文件 | 作用 |
|---|---|
| README.md | 项目说明、训练阶段划分、使用示例与协议 |
| config.json | 模型结构配置(40 层、hidden_size 2304、vocab 122753 等) |
| modeling_minicpm.py | 自定义建模代码,chat 方法位于 L1308-L1331 |
| configuration_minicpm.py | 自定义配置类 MiniCPMConfig |
| tokenizer.json / tokenizer.model | SentencePiece 分词器文件 |
| tokenizer_config.json | 分词器配置与 <用户>/<AI> 对话模板 |
| generation_config.json | generate 默认采样参数 |
| pytorch_model.260000 等 35 个文件 | 各训练步的完整权重(每文件约 5.4GB,LFS 存储) |
小结:跑通 MiniCPM-2B-history 的核心路径只有三步——装依赖、整理标准加载目录(复制+改名权重)、from_pretrained + chat。牢记"显式指定 torch_dtype、开启 trust_remote_code、用 LFS 拉取、优先选退火阶段 checkpoint"这四条,你的第一次对话基本就能顺利跑通。祝研究愉快,也欢迎对比不同训练步的输出来直观感受大模型的"成长曲线"!