MiniCPM3-4B 全栈实战指南：函数调用、代码解释器、长上下文与多引擎推理

本篇技术指南以开源仓库 MiniCPM 中的 MiniCPM3 英文文档 为核心，系统讲解 MiniCPM3-4B 这一 4B 参数语言模型的综合能力评测、长上下文处理方案，以及从 Hugging Face、SGLang、vLLM、llama.cpp 四种推理引擎到函数调用（Function Calling）与代码解释器（Code Interpreter）两大 Agent 能力的完整实战用法。读完本文，你将掌握 MiniCPM3-4B 的部署、调用与二次开发全流程，并能直接运行仓库自带的 函数调用示例 与 代码解释器示例。

模型概览：4B 参数、全面能力

MiniCPM3 是一个参数量为 4B 的语言模型。相比 MiniCPM 1.0/2.0，它功能更加全面、综合能力大幅提升，在多数评测集上的效果比肩甚至超越众多 7B-9B 参数量的模型。其核心能力可以概括为以下五点：

• 支持函数调用与代码解释器：在 Berkeley Function Calling Leaderboard（BFCL）上取得 9B 规模以下模型的 SOTA 成绩，超越 GLM-4-9B-Chat、Qwen2-7B-Instruct。
• 突出的推理能力：数学能力方面，在 MathBench 上的效果超越 GPT-3.5-Turbo 以及多个 7B-9B 模型；在极具挑战性的 LiveCodeBench 上，效果超越 Llama3.1-8B-Instruct。
• 出色的中英文指令遵循能力：英文指令遵循（IFEval）、中文指令遵循（FollowBench-zh）效果均超越 GLM-4-9B-Chat、Qwen2-7B-Instruct。
• 长文本能力：原生支持 32k 上下文长度，32k 长度内的大海捞针（Needle in a Haystack）测试表现全绿；配合分治式长序列处理框架 LLMxMapReduce，理论上可处理任意长度的上下文，在综合性长文本评测基准 InfiniteBench 上达到与 GPT-4、KimiChat 相当甚至更优的水平。
• RAG 能力：随 MiniCPM 系列发布 RAG 套件，包括在中文、中英跨语言检索测试中表现优异的 MiniCPM-Embedding、MiniCPM-Reranker，以及针对 RAG 场景的 MiniCPM3-RAG-LoRA。

综合评测结果

官方在英文、中文、数学、编码、工具使用五个维度上与多款主流开源模型进行了对比，MiniCPM3-4B 的总体平均分达到 66.3，位列对比模型首位：

评测集	Qwen2-7B-Instruct	GLM-4-9B-Chat	Gemma2-9B-it	Llama3.1-8B-Instruct	GPT-3.5-Turbo-0125	Phi-3.5-mini-Instruct(3.8B)	MiniCPM3-4B
英文能力
MMLU	70.5	72.4	72.6	69.4	69.2	68.4	67.2
BBH	64.9	76.3	65.2	67.8	70.3	68.6	70.2
MT-Bench	8.41	8.35	7.88	8.28	8.17	8.60	8.41
IFEVAL (Prompt Strict-Acc.)	51.0	64.5	71.9	71.5	58.8	49.4	68.4
中文能力
CMMLU	80.9	71.5	59.5	55.8	54.5	46.9	73.3
CEVAL	77.2	75.6	56.7	55.2	52.8	46.1	73.6
AlignBench v1.1	7.10	6.61	7.10	5.68	5.82	5.73	6.74
FollowBench-zh (SSR)	63.0	56.4	57.0	50.6	64.6	58.1	66.8
数学能力
MATH	49.6	50.6	46.0	51.9	41.8	46.4	46.6
GSM8K	82.3	79.6	79.7	84.5	76.4	82.7	81.1
MathBench	63.4	59.4	45.8	54.3	48.9	54.9	65.6
编码能力
HumanEval+	70.1	67.1	61.6	62.8	66.5	68.9	68.3
MBPP+	57.1	62.2	64.3	55.3	71.4	55.8	63.2
LiveCodeBench v3	22.2	20.2	19.2	20.4	24.0	19.6	22.6
工具使用
BFCL v2	71.6	70.1	19.2	73.3	75.4	48.4	76.0
总体
Average	65.3	65.0	57.9	60.8	61.0	57.2	66.3

从表中可以看到：数学维度上 MathBench 得分 65.6 为对比模型最高，超越 GPT-3.5-Turbo 及多款 7B-9B 模型；工具使用维度上 BFCL v2 得分 76.0 同样领先，且超越 GPT-3.5-Turbo-0125。

函数调用专项评测（BFCL）

官方在 Berkeley Function Calling Leaderboard（BFCL）上对函数调用能力做了专项评测，MiniCPM3-4B 在总体准确率（Overall Accuracy）上超越多款 7B-9B 参数模型以及 GPT-3.5-Turbo-0125：

模型	Overall Accuracy	AST Summary	Exec Summary	Irrelevance Detection	Relevance Detection
MiniCPM3-4B	76.03%	68.55%	85.54%	53.71%	90.24%
Llama3.1-8B-Instruct	73.28%	64.61%	86.48%	43.12%	85.37%
Qwen2-7B-Instruct	71.61%	65.71%	79.57%	44.70%	90.24%
GLM-4-9B-Chat	70.08%	60.69%	80.02%	55.02%	82.93%
Phi-3.5-mini-instruct	48.44%	38.89%	54.04%	46.78%	65.85%
Gemma2-9B-it	19.18%	5.41%	18.50%	88.88%	7.32%

值得关注的是，MiniCPM3-4B 在执行摘要（Exec Summary）维度达到 85.54%，相关性检测（Relevance Detection）达到 90.24%，说明它不仅"会声明调用"，而且调用的参数解析与执行结果也高度可靠。

长上下文能力：原生 32k 与 LLMxMapReduce

MiniCPM3 原生支持 32k 上下文长度。在 32k 上下文的 Needle in a Haystack 测试中结果全绿（flawless），即无论检索目标（"needle"）被放置在长文本的哪个位置，模型都能准确定位：

在 32k 之外，官方进一步提出了分治式（divide-and-conquer）长序列处理框架 LLMxMapReduce：将超长文本切分为多个分片分别处理，再把各分片的结果做归并汇总，从而在理论上支持任意长度的上下文。基于该框架的 MiniCPM3xMapReduce 在综合性长文本基准 InfiniteBench 上与 GPT-4、KimiChat 等标杆模型达到可比水平：

任务	上下文长度	Qwen2-70b	Kimi-Chat(2024.06)	GPT-4 (InfiniteBench)	MiniCPM 3.0 x MR	Qwen2-70b x MR	Llama3-70b x MR
Math.Find	87.9k	59.71%	18.57%	60.00%	83.43%	54.29%	91.43%
Retrieve.KV	89.9k	29.00%	69.20%	89.00%	93.80%	98.80%	98.89%
En.Dia	103.6K	23.00%	23.00%	7.50%	12.50%	46.50%	17.50%
Code.Debug	114.7k	45.43%	38.32%	54.31%	25.63%	54.82%	62.94%
Retrieve.Number	122.4k	100.00%	97.45%	100.00%	99.32%	100.00%	99.79%
Retrieve.PassKey	122.4k	100.00%	99.32%	100.00%	98.81%	100.00%	100.00%
En.Sum	171.5K	31.85%	29.94%	14.73%	25.89%	32.39%	30.63%
En.MC	184.4k	81.66%	79.91%	68.12%	66.38%	83.84%	82.10%
En.QA	192.6k	21.97%	18.80%	22.44%	28.39%	23.13%	34.70%
Zh.QA	2068.6k	21.40%	19.84%	25.96%	23.66%	19.10%	N/A
avg w/o Zh.QA	/	51.92%	52.96%	55.33%	59.29%	64.98%	68.64%
avg	/	48.86%	49.65%	52.39%	55.55%	60.39%	N/A

需要说明的是，上表数据均为官方文档在对应评测设置下公布的数值，其中部分任务（如 En.Dia、Code.Debug）并非 MiniCPM3xMapReduce 的强项，实际选型时应结合具体任务判断。

推理部署指南：四种引擎

Hugging Face

使用 Hugging Face transformers 加载模型进行对话生成，示例代码：

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch
torch.manual_seed(0)

path = 'openbmb/MiniCPM3-4B'
tokenizer = AutoTokenizer.from_pretrained(path)
model = AutoModelForCausalLM.from_pretrained(path, torch_dtype=torch.bfloat16, device_map='cuda', trust_remote_code=True)

responds, history = model.chat(tokenizer, "Write an article about Artificial Intelligence.", temperature=0.7, top_p=0.7)
print(responds)

关键点：trust_remote_code=True 是必须的，因为 MiniCPM3 依赖仓库内随模型发布的自定义建模代码；显式设置 torch_dtype=torch.bfloat16 可在保持精度的同时降低显存占用。

SGLang（推荐）

SGLang 是官方推荐的推理引擎，安装最新版本建议从源码编译（具体步骤参考 SGLang 官方仓库）。启动服务：

python -m sglang.launch_server --model openbmb/MiniCPM3-4B --trust-remote-code --port 30000 --chat-template chatml

调用示例（声明式多轮对话）：

from sglang import function, system, user, assistant, gen, set_default_backend, RuntimeEndpoint

@function
def multi_turn_question(s, question_1, question_2):
    s += user(question_1)
    s += assistant(gen("answer_1", max_tokens=1024))
    s += user(question_2)
    s += assistant(gen("answer_2", max_tokens=1024))

set_default_backend(RuntimeEndpoint("http://localhost:30000"))

state = multi_turn_question.run(
    question_1="Introduce artificial intelligence",
    question_2="Write an article about it",
)

for m in state.messages():
    print(m["role"], ":", m["content"])

注意 --chat-template chatml 与 MiniCPM3 使用的 ChatML 模板（<|im_start|>/<|im_end|> 结构）保持一致，这一点在后面的函数调用与代码解释器场景中同样重要。

vLLM

安装 vLLM（要求版本不低于 0.6.2）：

pip install "vllm>=0.6.2"

推理示例：

from transformers import AutoTokenizer
from vllm import LLM, SamplingParams

model_name = "openbmb/MiniCPM3-4B"
prompt = [{"role": "user", "content": "Write an article about Artificial Intelligence."}]

tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
input_text = tokenizer.apply_chat_template(prompt, tokenize=False, add_generation_prompt=True)

llm = LLM(model=model_name,
    trust_remote_code=True,
    tensor_parallel_size=1
)
sampling_params = SamplingParams(top_p=0.7, temperature=0.7, max_tokens=1024)

outputs = llm.generate(prompts=input_text, sampling_params=sampling_params)

print(outputs[0].outputs[0].text)

这里先用 apply_chat_template 把消息列表渲染成带 ChatML 标记的提示词，再交给 vLLM 生成，是 vLLM 下使用对话模型的标准姿势。

llama.cpp

官方提供了 MiniCPM3 的 GGUF 量化格式，可在 llama.cpp 中直接使用。安装与推理：

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make

./llama-cli -c 1024 -m minicpm3-4b-fp16.gguf -n 1024 --top-p 0.7 --temp 0.7 --prompt "<|im_start|>user\nWrite an article about Artificial Intelligence.<|im_end|>\n<|im_start|>assistant\n"

注意 --prompt 中手写了 ChatML 标记，这与上述其他引擎通过 chat template 生成的内容完全等价，体现了 MiniCPM3 对话协议的一贯性。

微调：LLaMA-Factory

官方已支持通过 LLaMA-Factory 对 MiniCPM3 进行微调，具体用法可参考 LLaMA-Factory 官方微调文档。仓库中并未附带 MiniCPM3 的微调脚本，但同一仓库的 minicpm_sala/finetune 目录提供了面向后续版本的 LLaMA-Factory 与 trainer 配置示例（如 sft_finetune.sh），可作参考。

高级特性一：函数调用（Function Calling）

函数调用是 MiniCPM3 的核心 Agent 能力。仓库 demo/minicpm3/function_call 目录下提供了三种使用方式：vLLM OpenAI 兼容服务端、OpenAI 客户端、本地推理脚本。

方式一：以 vLLM OpenAI 兼容服务启动

安装依赖后启动服务端（requirements.txt 中只需要 datamodel_code_generator 与 vllm 两个依赖）：

cd demo/minicpm3/function_call
pip install -r requirements.txt
python -m vllm.entrypoints.openai.api_server \
    --model openbmb/MiniCPM3-4B \
    --dtype auto \
    --api-key token-abc123 \
    --tensor-parallel-size 1 \
    --trust-remote-code \
    --enable-auto-tool-choice \
    --tool-call-parser minicpm \
    --tool-parser-plugin minicpm_tool_parser.py

其中 --enable-auto-tool-choice 开启自动工具选择，--tool-call-parser minicpm 指定使用仓库提供的 minicpm_tool_parser.py 中注册的解析器（该文件通过 @ToolParserManager.register_module("minicpm") 注册了 MiniCPMToolParser），--tool-parser-plugin 指定插件文件路径。

方式二：OpenAI 客户端调用

服务启动后，使用标准 OpenAI 客户端即可调用，工具定义完全遵循 OpenAI 的 function schema 格式：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="token-abc123")

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_current_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA",
          },
          "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["location"],
      },
    }
  }
]
messages = [{"role": "user", "content": "What's the weather like in Boston today?"}]
completion = client.chat.completions.create(
  model="openbmb/MiniCPM3-4B",
  messages=messages,
  tools=tools,
  tool_choice="auto"
)

print(completion)

方式三：本地推理脚本（源码拆解）

如果不依赖服务端，可直接运行 function_calling.py：

cd demo/minicpm3/function_call
python function_calling.py

该脚本的核心流程（也是理解 MiniCPM3 工具调用协议的最佳入口）：

1. 定义工具：以 OpenAI function schema 描述工具（如 get_delivery_date(order_id: str)），脚本中还以注释形式给出了完整的多轮 tool call 往返消息格式（assistant 的 tool_calls 与 role 为 tool 的返回消息）。
2. 渲染提示词：调用 tokenizer.apply_chat_template(messages, tools=tools, tokenize=False, add_generation_prompt=True)，将工具列表渲染进系统提示词。这里使用的模板正是仓库中的 minicpm_chat_template_with_tool.jinja：该模板会把 JSON Schema 形式的工具定义转换为 Python 函数签名（含 pydantic BaseModel/Enum 类型定义与 Args: 文档），并在系统提示词中写明"函数调用规则与输出格式"。
3. 解析模型输出：模型输出遵循固定格式——<|thought_start|> 内是思考过程，<|tool_call_start|>```python ... ```<|tool_call_end|> 内是待调用的函数调用语句，之后才是面向用户的文本回复。脚本调用 fc2dict(response) 把这段文本解析成结构化消息（minicpm_tool_parser.py 中的 fc2dict 函数负责这一解析）。
4. 循环执行：若解析结果包含 tool_calls，则逐一执行工具（脚本用 fake_tool_execute 模拟），把结果以 {"role": "tool", "content": ..., "tool_call_id": ...} 形式回填到消息列表，继续下一轮生成；直到模型输出不含工具调用、直接给出最终答复为止。

从 minicpm_tool_parser.py 的源码可以看到解析器的实现要点：fc2dict 先剥离 thought 段，再提取 tool_call_start/tool_call_end 之间的 Python 代码块，对代码中与 Python 关键字冲突的参数名做转义（如 class 改为 class_），随后借助 Python 标准库 ast 模块把函数调用表达式解析为"函数名 + 参数名/参数值"的结构化数据。其中 resolve_ast_call 与 resolve_ast_by_type 两个函数用于递归处理嵌套属性调用、列表、字典、负数、布尔值、lambda 等参数类型——该实现思路源自 gorilla 项目。对于流式输出，MiniCPMToolParser.extract_tool_calls_streaming 还会在生成过程中实时识别 thought_end 与 tool_call_start 标记，逐步下发工具调用的增量信息，并将停止 token id 列表设置为 [2, 73440]。

下面是用函数调用驱动搜索引擎回答问题的运行演示：

高级特性二：代码解释器（Code Interpreter）

代码解释器让 MiniCPM3 具备"写代码 → 执行 → 观察结果 → 继续行动"的自主循环能力。运行方式：

cd demo/minicpm3/code_interpreter
pip install -r requirements.txt
python code_interpreter.py openbmb/MiniCPM3-4B

其中 requirements.txt 只需要 fire 一个依赖（vLLM 需预先安装）。

从 code_interpreter.py 的源码可以拆解出完整的工作机制：

• 系统提示词模板：脚本内置一段 Agent 系统提示词，要求模型每一步先写 Analyse（分析当前消息并规划），再写 This Step Todo（本步子任务），然后在 <|execute_start|>```python ... ```<|execute_end|> 标记内输出可执行代码；并强调"没有代码的回复即视为任务完成""绘图用 plt.savefig() 而非 plt.show()""结果保存到 ./output 目录""完成后以 Finished: <答复> 收尾"。
• 生成循环：process 函数把系统提示词与用户问题（示例为"2 的 100 次方是多少？"）组成消息列表，最多循环 max_turns = 5 轮；每轮调用 DemoLLM.generate（内部用 vLLM 生成，采样参数为 temperature=1.0, top_p=0.85, repetition_penalty=1.02, max_tokens=300），若回复中出现 Finished 关键字则终止。
• 代码提取与执行：extract_code 用正则 r'```python\s+(.*?)\s+```' 提取代码块，execute_code 则用 exec 在当前进程内执行代码，并通过重定向 stdout/stderr 捕获输出；若最后一行不是赋值语句还会自动补 print(...) 以模拟 Notebook 的输出语义（源码注释说明更复杂任务可改用 nbclient）。执行结果（输出或报错）作为新的 user 消息回填，驱动下一轮生成。
• 任务完结：当模型认为所有代码均已执行成功、得到满足用户需求的结果后，输出 Finished: <正式答复> 结束整个流程。

下面是用代码解释器生成二维码的演示：

总结

MiniCPM3-4B 以 4B 参数量在综合评测（平均分 66.3）与 BFCL 函数调用评测（76.03%）中交出亮眼成绩，同时具备 32k 原生长上下文与 LLMxMapReduce 超长文本扩展能力。在工程落地上，它可以无缝接入 Hugging Face、SGLang、vLLM、llama.cpp 四种推理栈；在 Agent 能力上，仓库 demo/minicpm3 目录下的函数调用与代码解释器示例覆盖了从 OpenAI 兼容服务到本地 vLLM 脚本的完整链路，其核心解析逻辑（minicpm_tool_parser.py）与工具化 Chat 模板（minicpm_chat_template_with_tool.jinja）可直接复用，是构建轻量级端侧 Agent 的实用底座。