MiniCPM5-1B 端侧大模型完全指南：双模式推理、部署与微调实践（MiniCPM 开源仓库详解）

MiniCPM5-1B 端侧大模型完全指南：双模式推理、部署与微调实践（MiniCPM 开源仓库详解）

【免费下载链接】MiniCPMMiniCPM5: SOTA on-device LLMs, small yet powerful.项目地址: https://gitcode.com/GitHub_Trending/mi/MiniCPM

导读

本文以 MiniCPM 开源仓库主文档（README-cn.md）为骨架，系统讲解 MiniCPM5 系列首个模型 MiniCPM5-1B 的能力定位、双模式（Think / No Think）推理机制、训练流程（Base training → mid-training → SFT → RL + OPD），并给出 vLLM、SGLang、Transformers、llama.cpp / Ollama / LM Studio / MLX 等 7 大推理后端与 TRL、LLaMA-Factory、ms-swift、unsloth、xtuner 等 5 大微调框架的完整实操方案。读完本文，你将掌握：如何用一条命令在本地或服务端跑起 MiniCPM5-1B、如何切换思考模式、如何启用 XML 工具调用，以及如何用 Agent Skills 一键复现官方部署与微调流程。

MiniCPM5-1B：面向端侧的 1B 稠密模型

MiniCPM5-1B 是 MiniCPM5 系列的首个模型，发布于 2026.05.19，面向本地助手、coding agent、工具调用流程以及需要紧凑模型的推理场景。它是一个标准的 1B 稠密 Transformer，在较小部署成本下提供原生长上下文能力（128K），并通过同一份权重支持 Think / No Think 两种对话模式。官方在同尺寸优秀开源模型（LFM2.5-1.2B-Thinking、Qwen3-0.6B/think、Qwen3.5-0.8B/think 等）对比中，于推理 / 知识 / 代码 / 指令跟随 / 数学 / 逻辑 / Agentic 评测取得平均分 42.57，优势主要体现在 Agentic 工具调用、代码和竞赛数学上。

模型下载

当前主推版本为 MiniCPM5-1B，提供 BF16 / GGUF / MLX 三种格式，可在 HuggingFace 与 ModelScope 双平台获取：

从部署 Agent Skill 的决策矩阵可以看到，不同格式对应不同的使用路径：HF fp16 用于transformers/vllm/sglang以及所有微调流程；GGUF 用于 llama.cpp 系运行时（llama.cpp / Ollama / LM Studio）；MLX 用于 Apple Silicon 原生推理。GGUF 各档位体积为：MiniCPM5-1B-F16.gguf约 2.1 GB、MiniCPM5-1B-Q8_0.gguf约 1.1 GB、MiniCPM5-1B-Q4_K_M.gguf约 657 MB，Q4_K_M 适合边缘 / 移动级硬件。

仓库同时归档了 MiniCPM-SALA（稀疏 + 线性注意力混合模型，百万 token 上下文）、MiniCPM4 / MiniCPM4.1（8B 级可训练稀疏注意力 + 混合思考）等历史版本，完整模型清单见 README-cn.md 的模型下载章节。

双模式推理：同一份权重，Think / No Think 自由切换

MiniCPM5-1B 内置<think>chat template，通过enable_thinking开关切换思考 / 非思考模式，无需加载两套权重。

推荐的 chat template 采样参数

• Think 模式适合数学、代码、多步推理等需要深度思考的任务；
• No Think 模式响应更快、输出更精简，适合延迟敏感场景（如 CPU 推理、桌宠对话）。

各后端均在chat_template_kwargs（OpenAI 兼容接口）或apply_chat_template(..., enable_thinking=...)（Transformers）中传递该开关。部署后的通用自检方式（来自 minicpm5-deploy）：

curl http://localhost:PORT/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM5-1B", "messages": [{"role":"user","content":"1+1=?"}], "temperature": 0.7, "top_p": 0.95, "max_tokens": 64, "chat_template_kwargs": {"enable_thinking": false} }'

预期返回 HTTP 200，且choices[0].message.content包含"2"。若返回<think>...前缀，说明请求命中了思考模式，需在chat_template_kwargs中显式关闭enable_thinking。

训练流程：UltraData 分级数据管理体系下的三段式训练

MiniCPM5-1B 的训练是 [UltraData 分级数据管理体系] 的一次完整实践，覆盖三个阶段：

1. Base training：采用逐级推进的训练配方，包含 stable training 与 decay training，建立基础语言能力与训练稳定性；
2. mid-training：进一步强化目标能力并适配数据分布，语料来自同步开源的 Ultra-FineWeb、Ultra-FineWeb-L3 与 UltraData-Math；
3. 后训练：分为SFT、RL与OPD三步——先用 200B tokens deep-thinking SFT 与 200B tokens hybrid-thinking SFT 建立深度思考、混合思考和通用对话能力（SFT 数据开源为 UltraData-SFT-2605），再针对数学、代码、闭卷问答和写作等方向训练专用 RL teacher，最后通过 On-Policy Distillation（OPD）将 teacher 能力蒸馏回同一个发布模型。

RL + OPD 带来了什么？

RL + OPD是后训练的关键环节：在数学、代码、指令跟随三类任务上，将平均分提升↑16 分，同时将回复触顶 max-tokens 预算的比例降低↓29 个百分点。

• RL 阶段组合了推理、闭卷问答、写作、指令跟随、长上下文理解和通用对话等多类互补信号。其中 Reasoning RL 基于 DAPO-Math-17k（借鉴 JustRL 极简配方），采用两阶段长度调度以减少过长回复并提升推理准确性；同时使用 TriviaQA、NQ-Open、LongWriter-Zero-RLData、合成可验证 RLVR 数据与 pair-wise RLHF 信号，提升可靠性、指令跟随与用户体验。
• OPD 阶段参考 Thinking Machines Lab 的 On-Policy Distillation 思路并结合 Rethinking On-Policy Distillation 做实现改进：在强化学习框架中使用反向 KL 散度作为优势估计值替代 verification-based advantage；在 response 序列每个位置分别对学生 / 教师模型 logits 做双边 top-k 采样，取并集后计算反向 KL 散度，平衡监督信号准确性与训练效率。OPD 直接复用各 RL teacher 训练时的同分布 prompt 作为蒸馏数据，无需额外构造语料。

快速上手：三种最常用的推理路径

MiniCPM5-1B 使用标准LlamaForCausalLM架构，主流推理引擎可直接加载，无需自定义算子，也无模型代码 fork，因此安装与启动都非常简单。

vLLM（OpenAI 兼容服务，NVIDIA GPU）

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

测试请求：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "openbmb/MiniCPM5-1B", "messages": [{"role": "user", "content": "你是谁？可以简单介绍一下自己吗？"}], "max_tokens": 128, "temperature": 0.7 }'

更完整的 vLLM 生产级配置（见 docs/deployment/vllm.md）建议显式指定模型名、dtype 与上下文长度：

vllm serve openbmb/MiniCPM5-1B \ --served-model-name MiniCPM5-1B \ --dtype bfloat16 \ --max-model-len 131072 \ --gpu-memory-utilization 0.85 \ --port 8000

vLLM 还支持离线批量推理（Engine API），llm.chat(..., chat_template_kwargs={"enable_thinking": True})可在代码中直接控制思考模式。

SGLang（OpenAI 兼容服务，NVIDIA GPU）

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

测试请求与 vLLM 相同（端口换为 30000）。生产配置可补充 RadixAttention 前缀缓存与并发参数，完整说明见 docs/deployment/sglang.md。官方建议在启动前导出以下环境变量以避免常见问题：

export VLLM_WORKER_MULTIPROC_METHOD=spawn export SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 export SGLANG_DISABLE_CUDNN_CHECK=1

Transformers（Python 本地推理，CPU 或 GPU）

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

from transformers import AutoModelForCausalLM, AutoTokenizer model_id = "openbmb/MiniCPM5-1B" 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=False, 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))

由于整个 1.08B 参数模型在 fp32 下不足 4.5 GB，CPU-only 推理也可行——将torch_dtype改为torch.float32、device_map="cpu"即可（无 GPU 的 CI 或笔记本也能做冒烟测试），详见 docs/deployment/transformers.md。

带工具调用（Tool Calling）：XML 格式与 SGLang 原生解析

工具调用 / function calling推荐使用 SGLang：MiniCPM5-1B 以XML 格式产出工具调用，SGLang 原生内置的minicpm5parser 会自动将其转成 OpenAI 兼容的tool_calls字段。

python -m sglang.launch_server --model-path openbmb/MiniCPM5-1B --port 30000 \ --tool-call-parser minicpm5 # 或：--tool-call-parser auto

启动后即可发送标准 OpenAI 风格的工具请求：

curl http://localhost:30000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM5-1B", "messages": [{"role": "user", "content": "What is the weather in Beijing?"}], "tools": [{ "type": "function", "function": { "name": "get_weather", "description": "Get current weather for a city", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"] } } }], "tool_choice": "auto", "temperature": 0.7, "max_tokens": 256 }'

vLLM 侧的工具调用解析器（Plugin 方式）

vLLM 侧同样计划内置minicpm5parser，但在仓库当前版本中尚未随 pip 发布。仓库为此同步了上游 PR 的同一份解析器源码 tool_parsers/minicpm5xml_tool_parser.py，可通过 vLLM 的--tool-parser-plugin加载：

vllm serve openbmb/MiniCPM5-1B \ --served-model-name MiniCPM5-1B \ --dtype bfloat16 --max-model-len 131072 --port 8000 \ --enable-auto-tool-choice \ --tool-parser-plugin /path/to/MiniCPM/tool_parsers/minicpm5xml_tool_parser.py \ --tool-call-parser minicpm5

从源码可以看到该解析器的工作机制（@ToolParserManager.register_module("minicpm5")注册的MiniCPM5XMLToolParser）：

• 以<function与</function>作为工具调用的起止 token，通过正则匹配<function name="...">块与<param name="...">...</param>参数块完成解析；
• 对模型输出做归一化处理（_normalize_model_output）：处理 SentencePiece/GPT 风格解码器可能输出的Ġ（U+0120）而非 ASCII 空格、以及<functionname="foo">这类标签与属性粘连的退化输出；
• 按工具的 schema 校验函数名、允许的参数列表（name_to_allowed_props）与必填参数（name_to_required），将合法调用序列化为 JSON arguments，非法块回退为普通文本；
• 同时实现了流式（streaming）版本extract_tool_calls_streaming，支持增量产出 OpenAI 兼容的tool_callsdelta（工具名先发、arguments 按片段累积）。

解析器在adjust_request中将skip_special_tokens置为 False，因为工具 XML 标签是 MiniCPM5 的特殊 token，不能被提前剥离。这一实现也说明 MiniCPM5-1B 的工具调用是一条「模型原生 XML 输出 → 引擎 parser 标准化」的完整链路。

部署与微调 Cookbook 与 Agent Skills

为方便开发者快速复现部署和微调流程，仓库提供单页 cookbook，并配套一一对应的 Agent Skill：cookbook 适合手动执行，Agent Skills 适合在 Cursor / Claude Code 中由 agent 根据目标后端、硬件和数据路径选择执行路线。

两个顶层 Skill 分别覆盖部署和微调入口：

在 Cursor / Claude Code 中可以这样调用——agent 会读取顶层 Skill，根据目标后端、硬件和数据路径选择对应的子 Skill 与 cookbook，再执行命令并回报结果：

@minicpm5-deploy 用 vLLM 在 8000 端口起 openbmb/MiniCPM5-1B @minicpm5-finetune 用 unsloth + LoRA 微调 /data/my_chat.jsonl，输出到 ./out

部署 Skill 的决策逻辑（skills/minicpm5-deploy/SKILL.md）非常明确：根据用户声明的硬件 / 格式 / 目标，从决策矩阵中选且仅选一个后端——"Quick Python script" 走 Transformers、"OpenAI server / production serving" 走 vLLM、"RadixAttention / prefix cache" 走 SGLang、"GGUF / CPU only" 走 llama.cpp、"Ollama run" 走 Ollama、"桌面 GUI" 走 LM Studio、"Apple Silicon native" 走 MLX。未指定时的兜底建议为：CUDA 最快服务选 vLLM、CUDA 最简 Python 选 Transformers、Mac 笔记本选 Ollama（最易）或 MLX（最快）、纯 CPU / Windows / 低显存选 llama.cpp + Q4_K_M。

Skill 还总结了三条跨后端通用陷阱：

• Think vs No-Think：默认是思考模式（temperature=0.9, top_p=0.95）；想要更快、更精简的非思考输出，需enable_thinking=false+temperature=0.7, top_p=0.95；
• 128K 上下文：max_position_embeddings=131072、rope_theta=5e6、无需 rope-scaling。使用完整窗口需显式传--max-model-len 131072（vLLM）/--context-length 131072（SGLang）/-c 131072（llama.cpp），显存紧张时可下调；
• Untied lm_head：tie_word_embeddings=false。假设 Llama 默认 tied 布局的工具（如mlx_lm.convert< 0.31）会静默丢掉lm_head，导致输出退化为随机 token——MLX 子 Skill 已内置修复。

推理部署（7 个后端）

其中 llama.cpp 是CPU / 边缘 / 消费级 GPU部署的推荐路径，无需任何 Python 环境。快速体验：

huggingface-cli download openbmb/MiniCPM5-1B-GGUF MiniCPM5-1B-Q4_K_M.gguf --local-dir ./minicpm5 # 交互式聊天（自动应用 chat template） llama-cli -m ./minicpm5/MiniCPM5-1B-Q4_K_M.gguf -n 2048 --temp 0.7 --top-p 0.95 -ngl 99

OpenAI 兼容服务（docs/deployment/llama_cpp.md）：

llama-server -m MiniCPM5-1B-Q4_K_M.gguf --port 8080 -ngl 99 -c 8192 --jinja

如需从自己训练的 checkpoint 构建 GGUF，流程为：convert_hf_to_gguf.py转出 F16 →llama-quantize量化 Q4_K_M / Q8_0。

Ollama 路线（docs/deployment/ollama.md）则是最简单的笔记本一键部署：下载 GGUF → 编写 Modelfile（内含 ChatML 模板与stop参数）→ollama create+ollama run，Modelfile 默认按 nothink 模式调参（temperature 0.7），Think 模式可单独建 tag 或通过--raw模式强制注入<think>\n前缀。

微调（5 个框架）

微调 Skill（skills/minicpm5-finetune/SKILL.md）同样给出决策矩阵与各框架的「坑」清单：

以 unsloth 为例（docs/finetune/unsloth.md），在 24 GB 消费级 GPU 上做长上下文微调时，其 2 倍显存节省依然实用。核心配方：FastLanguageModel.from_pretrained（load_in_4bit=True即 QLoRA）→get_peft_model挂 LoRA（r=16、lora_alpha=32、目标模块覆盖全部 attention 与 MLP 投影）→ 数据用tok.apply_chat_template(...)转成text列喂给 TRLSFTTrainer。官方示例中仅 1.03% 可训练参数即可在约 26.6 秒内将 loss 从 4.67 降到 3.52。训练完成后，适配器可直接被 vLLM / Transformers / SGLang 加载；若目标是 llama.cpp / Ollama / LM Studio / 桌宠（GGUF），则先用minicpm5-finetune-gguf-lora把 PEFT 适配器转为 GGUF LoRA，再以--lora adapter.gguf方式加载。

无论使用哪个框架，微调后的通用自检方式：确认OUTPUT_DIR下存在adapter_model.safetensors+adapter_config.json（LoRA）或完整 HF 目录，然后用PeftModel.from_pretrained快速推理1+1=?，若输出乱码或为空，最可能是 chat template 错位（对照上表各框架的坑排查）。

其他支持的框架：FlagOS 多芯片部署

除上述部署与微调框架外，MiniCPM5-1B 也支持通过 FlagOS 进行多芯片部署。FlagOS 是北京智源研究院联合众多科研机构、芯片企业、系统厂商共同发起的开源社区，致力于打造面向多种 AI 芯片的统一开源系统软件栈（大型算子库、统一 AI 编译器、并行训推框架、统一通信库），通过"一次开发跨芯迁移"降低开发者迁移成本。

基于 FlagOS，MiniCPM5-1B 已适配 9 种不同 AI 芯片，在 FlagRelease 平台发布了多芯片版本：Nvidia、Hygon（海光）、Metax（沐曦）、Iluvatar（天数智芯）、Zhenwu（镇武）、Mthreads（摩尔线程）、Kunlunxin（昆仑芯）、Ascend（昇腾）、ARM-v9。

在 Nvidia 上体验性能加速有两种方式：

• 从 FlagRelease 开始（推荐）：直接使用已内置软件包的 MiniCPM5-1B-nvidia-FlagOS 镜像版本；
• 从零开始：需 Python 3.12、GLIBC_2.39、GLIBCXX_3.4.33、CXXABI_1.3.15 环境，安装 FlagOS 算子库后开启加速：

pip install flag-gems==4.2.1rc0 pip install triton==3.5.1

import flag_gems flag_gems.enable(record=True, once=True, path="/root/gems.txt")

vllm serve ${model_path} \ --trust-remote-code \ --dtype bfloat16 \ --enforce-eager \ --port ${Port} \ --served-model-name ${model_name} \ --gpu-memory-utilization 0.85

此外，vllm-plugin-FL是基于 FlagOS 统一多芯片后端构建的 vLLM 插件，用于扩展 vLLM 在多种硬件环境下的功能与性能，其示例中直接包含 MiniCPM5-1B 的配置说明。

桌宠：以 MiniCPM5-1B 为本地大脑的桌面应用

仓库同步发布了OpenBMB/MiniCPM-Desk-Pet桌宠应用，由 MiniCPM5-1B 本地驱动：通过轻量llama.cpp的llama-serversidecar 加载 GGUF 模型，并向 Electron 桌宠 UI 提供 OpenAI 兼容的本地接口。

• 支持 Apple Silicon / NVIDIA GPU / CPU 三条运行路线；
• 可与 Cursor、Claude Code、Codex 等编码 agent 联动；
• 支持 LoRA 人格切换；
• 用户安装：从 Releases 下载Clawd-on-Desk-*-arm64.dmg，按引导完成环境检查、模型下载和 sidecar 启动；
• 开发者运行：git clone git@github.com:OpenBMB/MiniCPM-Desk-Pet.git && ./go.sh，详见 MiniCPM-Desk-Pet 仓库的「给开发者」章节。

桌宠 UI 层 fork 自 clawd-on-desk（AGPL-3.0），上游基础上加入了本地 MiniCPM5-1B sidecar、Onboarding 和 LoRA 人格切换。

系列其他版本：MiniCPM-SALA 与 MiniCPM4 / 4.1

仓库还完整归档了 MiniCPM 系列的演进路线，相关文档与推理代码均在本仓库内：

• MiniCPM-SALA（2026-02）：首个大规模「稀疏 + 线性注意力混合」模型，25% 层用 InfLLM-V2 稀疏注意力做长文本建模、75% 层用 Lightning Attention 线性注意力提升全局处理效率，配合 HyPE 位置编码支持百万 token 上下文；相比密集注意力基线实现 3.5 倍推理加速（在 A6000D 上、256K 序列下为 Qwen3-8B 的 3.5 倍），RTX 5090 单卡即可推理 1M token。推荐推理温度 0.9，推理方式包括 HuggingFace（trust_remote_code=True）与 SGLang（--attention-backend minicpm_flashinfer，需用官方 fork 分支安装）。完整内容见 README-cn.md 的 MiniCPM-SALA 章节；
• MiniCPM4 与 MiniCPM4.1（2025-06 / 2025-09）：8B 级可训练稀疏注意力（InfLLM-V2）+ 混合思考，支持enable_thinking=True/False及/think、/no_think后缀切换；支持稠密 / 稀疏两种推理模式（vLLM、SGLang 仅稠密；Transformers、CPM.cu 支持稀疏）；可通过 config.json 中sparse_config与rope_scaling（LongRoPE 扩展到 131072 tokens）调参；还支持 EAGLE3 投机采样（vLLM / SGLang / CPM.cu）。历史专题（BitCPM4 量化、MiniCPM4 的 Survey / MCP / Intel AIPC 应用）见 docs/README-legacy-cn.md。

开源协议与引用

• 本仓库代码与 MiniCPM 模型权重依照 Apache-2.0 协议开源（见 LICENSE）；
• MiniCPM 由面壁智能、清华大学自然语言处理实验室、人大高瓴人工智能学院联合开发；
• 引用论文：MiniCPM4: Ultra-efficient LLMs on end devices，BibTeX 见 README-cn.md 的工作引用章节；
• 需要注意：MiniCPM 作为语言模型无法理解或表达个人观点，使用其生成内容时应自行评估和验证；因使用开源模型导致的任何问题，模型开发者不承担责任。

小结

MiniCPM5-1B 以标准LlamaForCausalLM架构实现了「同尺寸 SOTA 能力 + 原生 128K 上下文 + 双模式推理 + XML 工具调用」的组合，配合仓库内一一对应的 7 个部署 Cookbook、5 个微调 Cookbook 与配套 Agent Skills，开发者可以在数分钟内完成从「模型下载 → 后端部署 → 工具调用 → 微调」的完整链路。无论是想快速在本地跑一个可对话、可调工具的 1B 助手，还是用 LoRA / QLoRA 在消费级 GPU 上定制专属人格，本文给出的命令、参数与源码路径都足以直接照做。

【免费下载链接】MiniCPMMiniCPM5: SOTA on-device LLMs, small yet powerful.项目地址: https://gitcode.com/GitHub_Trending/mi/MiniCPM