llama.cpp 多模态实战指南：MiniCPM-Llama3-V 2.5 的手术拆分、GGUF 转换与 mtmd 推理

本篇指南基于 llama.cpp 仓库的官方多模态文档 MiniCPM-Llama3-V 2.5 指南，完整覆盖 MiniCPM-Llama3-V 2.5 视觉语言模型从 PyTorch 权重到 GGUF 推理的全部流程：模型准备、llama.cpp 构建、"手术"拆分（surgery）、图像编码器转 mmproj、语言模型转换与量化，以及 llama-mtmd-cli 的单轮与对话两种推理用法。读完后你能够在 Linux 或 macOS 上独立跑通该模型的图文问答，并理解仓库内转换脚本与推理算子图的实际分工。

整体流程概览

MiniCPM-Llama3-V 2.5 与 Qwen2-VL、MiniCPM-V 4.6 等"新式"模型不同，它的 PyTorch 权重把视觉塔（ViT）、多模态投影器（resampler）和 LLM 混在同一个 checkpoint 里，llama.cpp 无法直接消费。因此转换采用典型的"先拆后转"策略：

1. 手术拆分（minicpmv-surgery.py）：从混合 checkpoint 中分离出 LLM、视觉编码器（minicpmv.clip）与投影器（minicpmv.projector）三部分；
2. 视觉编码器转 GGUF（minicpmv-convert-image-encoder-to-gguf.py）：生成 mmproj-model-f16.gguf 多模态投影文件；
3. 语言模型转 GGUF（convert_hf_to_gguf.py）：对拆分后的纯 LLM 目录生成标准 GGUF；
4. （可选）量化（llama-quantize）：压缩为 Q4_K_M 以降低显存占用；
5. 推理（llama-mtmd-cli）：单轮提问或交互式对话。

llama.cpp 的多模态体系本身也在快速演进：早期的 llava-cli 及各模型专属 CLI 已被统一的 libmtmd 库与 mtmd-cli 取代，详见 多模态支持说明。其中 mmproj 概念是多模态推理的核心：图像由 mmproj 文件编码为嵌入向量后再送入语言模型，因此运行时必须同时指定语言模型（-m）与投影器（--mmproj）两个 GGUF 文件。

第一步：准备模型与代码

获取 PyTorch 权重

将 openbmb/MiniCPM-Llama3-V-2_5 的 PyTorch 权重下载到本地 MiniCPM-Llama3-V-2_5 目录（后续命令均以该目录名为基准）。若不想自行转换，官方也提供了已转换好的 GGUF 版本可直接下载（文档原文提供了 Hugging Face 上的 MiniCPM-Llama3-V-2_5-gguf 仓库），可跳过下面的转换步骤直接进入推理。

构建 llama.cpp

克隆仓库并构建（原文档注明其构建说明以 2025-02-06 为准，若有出入以仓库最新的构建文档为准）：

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

cmake -B build
cmake --build build --config Release

Python 依赖

两个转换脚本依赖 PyTorch 生态：minicpmv-surgery.py 通过 AutoModel.from_pretrained(..., trust_remote_code=True) 加载模型，需要安装 torch 与 transformers；minicpmv-convert-image-encoder-to-gguf.py 顶部还有 from gguf import *，所需的 gguf 包可直接使用仓库内的 gguf-py 子项目（pip install ./gguf-py）。

第二步：模型转换

2.1 surgery：拆分混合 checkpoint

python ./tools/mtmd/legacy-models/minicpmv-surgery.py -m ../MiniCPM-Llama3-V-2_5

minicpmv-surgery.py 只接收一个参数 -m/--model（模型目录），内部完成了三件事：

1. 提取投影器：扫描 checkpoint 中所有以 resampler 开头的张量，整体保存为 {模型目录}/minicpmv.projector。源码中还有一个细节（第 19-20 行）：若 LLM 配置带 scale_emb，会把 resampler.proj 除以 scale_emb 做归一化补偿，保证转换后的投影结果与原始推理一致；
2. 提取视觉编码器：所有以 vpm 开头的张量去掉前缀后保存为 {模型目录}/minicpmv.clip（第 23-26 行），供下一步编码器转换加载；
3. 剥离纯 LLM：把 model.llm 单独保存为 {模型目录}/model/ 子目录（含权重与 tokenizer），并改写其 auto_map 指向标准 MiniCPMConfig/MiniCPMModel，使其能作为"普通 LLaMA 风格"模型被 convert_hf_to_gguf.py 直接转换。脚本注释里还说明：若存在 added_tokens.json（如 MiniCPM-o 系的多模态特殊 token），会将其清空为 {}，以免干扰 Mistral 类文本模型的转换。

脚本运行结束会打印提示：接下来可以把 model/ 目录转成常规 GGUF，并用 minicpmv.projector 准备编码器 GGUF 文件——正是文档给出的后续两条命令。

2.2 视觉编码器 + 投影器 → mmproj GGUF

python ./tools/mtmd/legacy-models/minicpmv-convert-image-encoder-to-gguf.py \
  -m ../MiniCPM-Llama3-V-2_5 \
  --minicpmv-projector ../MiniCPM-Llama3-V-2_5/minicpmv.projector \
  --output-dir ../MiniCPM-Llama3-V-2_5/ \
  --minicpmv_version 2

转换脚本 的关键参数：

参数	说明
-m/--model-dir	HF 风格的模型目录（必填）。脚本会读取其中的 config.json 获取 hidden_size、vision_config 等真实结构参数；minicpmv.clip 与 minicpmv.projector 也从该目录自动发现
--minicpmv-projector	surgery 产出的 minicpmv.projector 文件路径；指定后输出即为 MiniCPM-V 的图像编码器（文件名带 mmproj- 前缀），且不带文本编码器
--output-dir/-o	GGUF 输出目录，默认与模型目录相同
--minicpmv_version	MiniCPM 版本标识。脚本帮助中给出的映射为：1 = MiniCPM-V-2；2 = MiniCPM-V-2.5（本文场景）；3 = MiniCPM-V-2.6；4 = MiniCPM-o-2.6；5 = MiniCPM-V-4.0；6 = MiniCPM-o-4.0；100045 = MiniCPM-o-4.5。不同版本决定视觉塔结构（Idefics2 风格 vs SigLIP 风格）与回退的 emb_dim/block_count，因此 2.5 必须传 2
--use-f32	用 f32 替代 f16 存储（卷积核权重仍强制 f16，GGML 的卷积算子暂不支持 32 位卷积核）
--image-mean/--image-std	覆盖图像归一化均值/方差，默认 [0.5, 0.5, 0.5]，写入 clip.vision.image_mean/image_std 元数据

脚本产出的 mmproj-model-f16.gguf 内写入的元数据（第 677-724 行）对运行期行为影响很大：

• clip.has_minicpmv_projector = true、clip.projector_type = "resampler"、clip.minicpmv_version = 2——推理端据此选择 clip_graph_minicpmv 算子图；
• 视觉塔结构参数：clip.vision.image_size（取自 config 的 image_size）、patch_size、嵌入/FFN 维度、注意力头数、clip.vision.block_count（视觉层数）；
• clip.minicpmv_query_num：取自 config 的 query_num，即 resampler 的查询向量数量，决定图像编码后输出给 LLM 的 token 数；
• 图像归一化 image_mean/image_std。

对投影器张量，脚本的 _replace_name_resampler（第 783-800 行）做两处关键变换：resampler.pos_embed 会被展开为学习式 pos_embed 加一份 70×70 网格的 sincos 位置编码 pos_embed_k；resampler.attn.in_proj_*（融合式 QKV 权重）会被 chunk(3) 拆分为独立的 attn.q./k./v. 三组权重——这与推理端算子图期望的张量布局一一对应。

2.3 语言模型 → 常规 GGUF

python ./convert_hf_to_gguf.py ../MiniCPM-Llama3-V-2_5/model

对 surgery 产出的纯 LLM 子目录执行标准的 HF→GGUF 转换。对 MiniCPM-Llama3-V 2.5，产物为 MiniCPM-Llama3-V-2_5/model/model-8B-F16.gguf（F16 精度，文件名以实际输出为准）。

2.4 可选：量化为 Q4_K_M

./build/bin/llama-quantize ../MiniCPM-Llama3-V-2_5/model/model-8B-F16.gguf \
  ../MiniCPM-Llama3-V-2_5/model/ggml-model-Q4_K_M.gguf Q4_K_M

Q4_K_M 是 4-bit 混合块量化档位，可显著降低内存占用；mmproj 文件本身保持 F16 不量化（文档中的两条推理命令均使用 mmproj-model-f16.gguf）。

第三步：推理（Linux / macOS）

llama.cpp 统一的多模态 CLI 为 llama-mtmd-cli（见 mtmd-cli 入口），由 libmtmd 驱动。

单轮模式

./build/bin/llama-mtmd-cli -m ../MiniCPM-Llama3-V-2_5/model/model-8B-F16.gguf \
  --mmproj ../MiniCPM-Llama3-V-2_5/mmproj-model-f16.gguf \
  -c 4096 --temp 0.7 --top-p 0.8 --top-k 100 --repeat-penalty 1.05 \
  --image xx.jpg -p "What is in the image?"

对话模式

./build/bin/llama-mtmd-cli -m ../MiniCPM-Llama3-V-2_5/model/ggml-model-Q4_K_M.gguf \
  --mmproj ../MiniCPM-Llama3-V-2_5/mmproj-model-f16.gguf

文档中给出的采样参数含义：

参数	值	作用
-c	4096	上下文长度；图像 token 也占用上下文，多图或长对话时注意余量
--temp	0.7	采样温度
--top-p	0.8	nucleus 采样阈值
--top-k	100	每步候选 token 数上限
--repeat-penalty	1.05	轻度重复惩罚
--image	xx.jpg	单轮模式下指定待描述图片
-p	"What is in the image?"	单轮模式的提示词

单轮模式适合一次性描述/问答脚本；对话模式进入交互会话，可直接贴图继续多轮交流。

源码纵深：resampler 投影器在推理端如何执行

mmproj GGUF 中 clip.minicpmv_version = 2 会在运行期路由到 clip_graph_minicpmv 算子图，其实现见 tools/mtmd/models/minicpmv.cpp。从源码结构看，整条前向链与 PyTorch 侧的 resampler 结构完全对应：

1. ViT 主干（build_vit，第 31-36 行）：图像 patch 嵌入 + 学习式位置编码后过 27 层视觉 Transformer，输出逐 patch 嵌入；
2. resampler 即一个小型 Transformer（注释原话 "it is just another transformer"）：
   • 查询向量 mm_model_query 与 ViT 输出经 mm_model_kv_proj 投影后分别做 LayerNorm（第 40-45 行）；
   • 位置编码采用 sincos 双轴拼接：基频 omega 外乘水平/垂直位置，sin/cos 各自 concat 后再沿通道拼接（第 47-68 行），与转换脚本中 _replace_name_resampler 生成的 70×70 pos_embed_k 严格对应；k = v + pos_embed（第 71 行）；
   • 多头注意力中固定 d_head = 128，头数由投影嵌入维推导，num_query 直接读取 hparams.minicpmv_query_num（即 mmproj 元数据里的 clip.minicpmv_query_num，第 78 行），注意力尺度为 1/sqrt(128)；
3. 输出投影：注意力结果经 mm_model_ln_post 归一化与 mm_model_proj 线性投影，得到送入 LLM 的最终视觉 token 序列（第 105-111 行）。

这也解释了转换脚本为何要把 in_proj 拆成 q/k/v 三组、为何要在 GGUF 中额外写入 sincos 位置编码：算子图消费的就是这份布局。

参考与延伸阅读

• 原文档：MiniCPM-Llama3-V 2.5 指南
• 转换脚本：minicpmv-surgery.py、minicpmv-convert-image-encoder-to-gguf.py，以及通用转换器 convert_hf_to_gguf.py
• 多模态架构与 mmproj/libmtmd 说明：tools/mtmd/README.md
• 推理算子图：clip_graph_minicpmv 实现
• 同族模型指南（同一套 surgery + 转换流程，仅 --minicpmv_version 不同）：MiniCPM-V 2.6、MiniCPM-o 2.6、MiniCPM-V 4.0、MiniCPM-o 4.0、MiniCPM-V 4.5、走新式 --mmproj 直转路线的 MiniCPM-V 4.6

适用前提：本文流程对应仓库当前 tools/mtmd/legacy-models 下的脚本与 llama-mtmd-cli 二进制；多模态支持被官方标记为"快速演进、可能有破坏性变更"的子项目，脚本参数与文件名若与仓库最新提交有出入，应以 tools/mtmd 目录下的实际代码为准。