MiniCPM：面壁智能端侧小模型部署指南

OpenBMB/MiniCPM 是面壁智能（OpenBMB）推出的端侧小模型系列，当前 Star 数约 11.7k，采用 Apache-2.0 协议。本仓库最新发布的是 MiniCPM5-2B，是 MiniCPM5 系列继 MiniCPM5-1B 之后的第二个权重，一个稠密 2B Transformer，专为端侧、本地部署与资源受限场景设计，在 2B 级开源模型中取得 SOTA。它的参数仅 25 亿，却在编码、数学、长上下文理解、工具调用与 Agent 任务上对同级模型形成优势，整体平均分 53.9，甚至超过了仓库中列出的更大尺寸模型（最高 51.1）。模型结构是标准 LlamaForCausalLM，42 层、GQA 16 个 Q 头 / 2 个 KV 头、上下文长度 131072（128K），因此主流推理引擎可以直接加载，不需要自定义内核或模型代码分支——这对二次开发非常友好，意味着 vLLM、SGLang、llama.cpp、Transformers 这些成熟工具开箱即用，不用等社区适配，开发者拿到权重就能跑，也方便后续微调替换，迁移成本极低，是少有的端侧全能选手。除权重外，团队还把背后的高质量训练数据以 UltraData 系列开放，包括 UltraX 预训练语料、UltraData-Code 分层代码数据、50 万条 Agent SFT 样本与 8 万多条 RL 样本。对普通用户来说，MiniCPM5-2B 的意义在于：它把"能干活的小模型"塞进了一块 8GB 显存甚至纯 CPU 能跑的体量里——不需要云端 API，不需要等排队，下载完 GGUF 文件就能在自己笔记本上跑一个带深度思考、会用工具、写代码不丢人 的助手。在隐私敏感的写作、代码、笔记场景里，这种本地小模型比云端大模型更让人安心，不必担心把工作内容上传到第三方服务器，也不用担心断网就用不了，是真正属于自己的 AI，随用随开。本系列文章基于官方 README 完整翻译整理，覆盖模型规格、训练思路、四种部署方式、工具调用与常见问题，帮助端侧开发者快速把这个 2B 小模型用起来，不必在多个文档间来回跳转，一篇就够，看完即可上手，是入门 MiniCPM5 的最佳读物。

一、项目官方信息

二、官方图片

README 附有能力雷达图（按领域对比同级模型）、公开排行榜对比图、训练流程图（base / mid / post 三阶段）以及 RL+OPD 收益柱状图，直观展示这个 2B 小模型在各维度的优势，也能让读者一眼看清它和 LFM2.5、Qwen3.5、Gemma 等同级模型的差距，避免凭感觉选型，照着图对比就能决定是否试用，节省评估时间。本系列封面使用仓库官方图，保持风格统一。

三、环境要求

MiniCPM5-2B 是标准 Llama 架构，推理门槛很低：GPU 路线用 vLLM 或 SGLang，要求对应框架支持的 CUDA 版本；纯 CPU / 笔记本可用 llama.cpp 加载 GGUF 量化版；Apple Silicon 用 MLX 版。官方推荐的采样参数是 temperature=1.0, top_p=0.95, min_p=0.0；遇到重复输出再加 repetition_penalty=1.05。注意 llama.cpp 默认 min_p=0.05 会过滤掉概率低于最高 token 5% 的候选，反而容易困在重复循环里，官方建议显式设 min_p=0.0。硬件上，2B 模型 BF16 大约 5GB 显存，GGUF Q4 量化后 1.5GB 左右即可，普通办公本也能跑。对企业用户来说，这套低门槛意味着可以把模型直接部署在边缘设备、内网服务器上，不用把数据发到云端，隐私和合规都更容易过。128K 的上下文长度也让它能吃下整本长文档、整份代码库做分析，适合做本地 RAG 或代码问答，不必为长文档单独买大模型服务。官方把模型做成标准 Llama 架构，也是为了让用户现有推理框架不用改代码就能接入，降低迁移成本，团队里的现有技术栈可以直接复用，不用重新培训，上手极快，是企业内网部署的理想选择。

四、完整部署步骤

1. vLLM（OpenAI 兼容服务）

pip install "vllm>=0.21"
vllm serve openbmb/MiniCPM5-2B --port 8000

之后用标准 /v1/chat/completions 接口调用即可。vLLM 是生产环境最常用的选择，吞吐高、支持并发，适合把小模型挂成内部服务给多个前端用。启动后用标准 OpenAI SDK 即可接入，不需要改业务代码；如果只是本地调试，也可以直接在浏览器访问自带的 playground 快速试效果，无需写一行代码，非常适合快速验证想法，新手也能五分钟跑通，门槛极低。

2. SGLang（推荐用于工具调用）

pip install "sglang[srt]>=0.5.16"
python -m sglang.launch_server --model-path openbmb/MiniCPM5-2B --port 30000

SGLang 在工具调用和投机采样上支持更完整，官方把它列为工具调用场景的首选后端。它还配合发布了 MiniCPM5-2B-DSpark 投机采样草稿模型，启用后在不改变输出质量的前提下加速解码：--speculative-algorithm DSPARK --speculative-draft-model-path openbmb/MiniCPM5-2B-DSpark --speculative-dspark-block-size 7，对在线服务体验提升明显，生成速度能翻一倍以上，用户等待时间大幅缩短。

3. llama.cpp（本地 / 无独显）

llama-server -m MiniCPM5-2B-F16.gguf -a MiniCPM5-2B --port 8080 -ngl 99 -c 8192 --jinja

-c 8192 设上下文长度，可按需调大；-ngl 99 表示尽量把层卸载到 GPU。GGUF 权重在 MiniCPM5-2B-GGUF 下载。这是笔记本用户最省事的路径，不需要 Python 环境，下载一个 gguf 文件配一个 exe 就能跑，适合完全不懂 Python 的普通用户，双击即用，门槛极低，零基础也能上手，是本地体验的首选。

4. Transformers 原生推理

适合想直接写 Python 脚本、不想起服务的场景。要求 transformers>=5.6，注意版本太低会加载失败。代码里用 apply_chat_template 并开启 enable_thinking=True，就能触发模型的深度思考能力，让它在回答前先在内部推理，适合做研究或批量脚本调用，也方便和其他 PyTorch 流程串起来，做自定义实验，灵活度最高。

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

from transformers import AutoModelForCausalLM, AutoTokenizer
model_id = "openbmb/MiniCPM5-2B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype="auto", device_map="auto")
messages = [{"role": "user", "content": "你好，请介绍一下自己。"}]
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=128)
print(tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True))

5. 工具调用

工具调用推荐用 SGLang 后端，MiniCPM5-2B 输出 XML 风格的工具调用，SGLang 内置的 minicpm5 解析器会自动转成 OpenAI 兼容的 tool_calls：python -m sglang.launch_server --model-path openbmb/MiniCPM5-2B --port 30000 --tool-call-parser minicpm5（或 auto）。这意味着你可以把它接进任何支持 OpenAI function calling 的应用框架，比如把它当成一个本地小 Agent 来查数据库、调内部 API、自动化重复操作，所有数据不出本机，安全可控，适合内网环境，是企业内网的首选方案。

五、核心特性与使用方法

训练配方。 MiniCPM5-2B 走的是 UltraData 分层数据管理 的完整流程：base 训练（稳定训练 + 衰减训练打基础）→ mid 训练（对齐目标数据分布）→ post 训练三步走 SFT、RL、OPD。其中 SFT 用了 4000 亿 token 的深度思考数据；RL 阶段为数学、代码、Agent、写作等领域分别训练专门的"教师模型"；最后用 On-Policy Distillation（OPD）把 16 个 RL 专家教师蒸馏回一个发布模型。RL+OPD 让推理与通用能力平均提升 10.96 分、Agent 能力提升 6.96 分。这套"先训专家、再蒸馏合一"的路线，是小模型能打出大模型水平的关键工程手段：与其让一个模型同时学数学、代码、写作、Agent 所有技能，不如先给每个领域单独训一个 RL 教师，再把它们的能力蒸到一个学生模型里，这样学生既能博采众长，又不会互相打架。公开数据显示这套流程让推理与通用能力平均涨了近 11 分，Agent 能力涨了近 7 分，是小模型能跨越同级模型的关键，也是 MiniCPM5 系列能以 2B 体量打 4B 级对手的核心原因，值得学习。

权重格式齐全。 当前发布覆盖 BF16 完整版、GGUF（llama.cpp / 本地）、MLX（Apple Silicon）、GPTQ 量化、DSpark 投机草稿等多种格式，HuggingFace 与 ModelScope 双站同步，国内用户直接走 ModelScope 下载更快。这种"一次训练、全格式分发"的做法，让同一个 2B 权重既能上云 GPU 做高吞吐服务，也能塞进 Mac、手机、树莓派做端侧推理，对个人开发者和小团队特别友好，不必为不同设备分别维护模型版本，也不用担心兼容性问题，一份权重到处跑，省心得多。

面向 Agent 场景。 官方同时提供部署与微调的 cookbook（transformers、vllm、sglang、llama_cpp），并配了一套 Cursor / Claude Code 风格的 Agent Skills，适合把小模型接进编码助手工作流。对开发者而言，这意味着不必为了用工具调用而在本地跑 7B 模型，2B 就够用。官方还把每个部署路径写成了 cookbook 和 Agent Skill，相当于手把手教你把它接进 Cursor 这类编码代理，减少了大量踩坑时间，小团队也能快速搭起本地编码助手，不必依赖云端大模型 API，成本更低，体验更好。

六、常见问题 FAQ

1. 2B 小模型能干什么？ 官方定位是本地助手、编码 Agent、工具调用与推理场景；在编码、数学、长上下文、工具使用与 Agent 任务上对同级模型有优势，整体可与 4B 级模型掰手腕。别指望它替代云端大模型，但在隐私敏感、离线可用、成本敏感的场景里非常够用，比如个人知识库问答、离线代码助手、内网客服机器人、写作陪练、会议纪要整理、本地翻译、文档摘要、知识管理。

2. 普通笔记本能跑吗？ 可以，用 GGUF 量化版在 llama.cpp 里跑，CPU 也能推理；有 N 卡就走 vLLM / SGLang，Apple Silicon 用 MLX 版。2B 量化后显存占用不到 2GB，核显轻薄本都能起步，是真正意义上的"随身 AI"，出差没网也能写代码、查笔记、整理资料，不依赖网络，也不担心数据泄露，随处可用，是出门在外的好帮手。

3. 为什么推荐 min_p=0.0？ llama.cpp 默认 min_p=0.05 会把概率低于最高 token 5% 的候选直接过滤掉，容易把"跳出重复循环"所需的那个 token 也滤掉，官方建议显式设 0.0。这是从无数用户反馈里总结出来的经验，遇到复读机问题先调它，比换模型管用，也比反复调温度更快见效，是本地小模型出问题的第一排查点，值得记在备忘里，少走弯路。

4. 怎么做工具调用？ 用 SGLang 启动并加 --tool-call-parser minicpm5，模型输出的 XML 工具调用会被自动转成 OpenAI 格式 tool_calls，可以直接接 LangChain、Dify 等主流框架，不必自己写解析器，几行配置就能跑通，省去了手动写正则提取参数的麻烦，适合快速搭本地 Agent，几分钟就能跑通，效率极高。

5. 想要更快的解码？ 用 SGLang 加载 DSpark 草稿模型做投机采样，块大小设 7，不改变目标模型输出，能在同样显存下明显提升生成速度，适合对延迟敏感的交互场景，比如实时聊天、代码补全、客服机器人，用户感知会明显变快，等待时间大幅缩短，体验更好，是线上服务的首选优化。

6. 训练数据开放吗？ 开放，包括 UltraX、UltraData-Code、UltraData-SFT-Agent-2609、UltraData-RL-2609 等，适合研究者复现或做自己的微调，不必从零攒数据，站在官方数据上继续训练即可，节省大量清洗和标注成本，学术和企业都能直接用，省去了自己找语料的麻烦，是研究者的福音。

7. 和 MiniCPM5-1B 怎么选？ 1B 更轻量、对内存要求更低；2B 能力更强，适合能接受稍大占用的用户，两者训练配方一致，只是规模不同。按自己的设备内存选即可，不必硬上大的；1B 能在手机上跑，2B 更适合笔记本和桌面端，按用途挑就行，写代码选 2B，做纯对话选 1B，按需选不浪费资源，适合自己的设备最重要。

8. 支持商用吗？ 代码与权重均为 Apache-2.0，商用友好，是少有的可以直接商用的端侧小模型系列，适合嵌入到自己的产品里做本地化部署，不必担心许可纠纷，也不用额外申请授权，团队可以放心做产品，不用担心法律风险，商用门槛极低。

七、跳转链接

• GitHub 仓库：OpenBMB/MiniCPM
• 模型权重：HuggingFace / ModelScope
• 在线 Demo：HF Space
• 技术报告：arXiv:2506.07900
• 多模态姊妹篇：MiniCPM-V
• 开放数据：UltraData