如何用 llama.cpp 转换 MiniCPM-V 4.6 为 GGUF 并用 llama-mtmd-cli 跑通图像推理

如何用 llama.cpp 转换 MiniCPM-V 4.6 为 GGUF 并用 llama-mtmd-cli 跑通图像推理

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp

本文完成一个具体任务：把 Hugging Face 上的 MiniCPM-V 4.6 PyTorch 模型转换成 llama.cpp 可运行的 GGUF 文件，再用llama-mtmd-cli加载图像跑通一次视觉问答。MiniCPM-V 4.6 与其他 MiniCPM-V 变体不同，它通过convert_hf_to_gguf.py直接转换，整个流程只需两次转换命令加一次推理命令。适用环境为 Linux 或 Mac（文档中推理部分明确写的是 Linux 或 Mac）。

准备条件：源码、Python 依赖与模型文件

1. 克隆并编译 llama.cpp

git clone https://gitcode.com/GitHub_Trending/ll/llama.cpp cd llama.cpp cmake -B build cmake --build build --config Release

编译产物位于build/bin/，后文的llama-mtmd-cli和llama-quantize都在这里。若编译方式有差异，可参考 tools/mtmd 目录说明 中对多模态子项目的定位——该模块处于快速开发阶段，存在 breaking changes 的可能。

2. 安装 Python 转换依赖

在 llama.cpp 仓库根目录执行：

python3 -m pip install -r requirements.txt

requirements.txt是覆盖所有顶层 Python 脚本依赖的总清单，包含convert_hf_to_gguf.py所需的 convert_hf_to_gguf 依赖。该依赖清单固定了torch==2.11.0等版本，用uv的读者可改用uv pip install -r requirements.txt --index-strategy unsafe-best-match（见 tools/quantize/README.md）。

3. 下载模型

从 Hugging Face 下载openbmb/MiniCPM-V-4_6的 PyTorch 模型，放到 llama.cpp 仓库同级的上一级目录中的MiniCPM-V-4_6文件夹里。文档给出的转换命令都以../MiniCPM-V-4_6引用它，即模型目录必须位于llama.cpp/的上一级，且目录名保持MiniCPM-V-4_6。

检查点要求（来自 docs/multimodal/minicpmv4.6.md）：

• 必须是标准transformersv5.7.0+ 的 checkpoint，不使用trust_remote_code；
• config.json中的架构应为MiniCPMV4_6ForConditionalGeneration，文本模型为qwen3_5_text，视觉部分为基于 SigLIP 的 vision tower 加带 window-attention 的vit_merger。

如果下载到的 checkpoint 需要trust_remote_code才能加载，说明版本不对，转换前应先换一个符合上述要求的版本。

转换：两次调用 convert_hf_to_gguf.py

llama.cpp 的多模态模型运行需要两个GGUF 文件：语言模型文件和多模态投影器（mmproj）文件（见 tools/mtmd/README.md 的说明）。MiniCPM-V 4.6 用同一个脚本转换两次即可得到两者。在 llama.cpp 仓库根目录执行：

# 语言模型 python ./convert_hf_to_gguf.py ../MiniCPM-V-4_6 --outfile ../MiniCPM-V-4_6/ggml-model-f16.gguf # 多模态投影器（vision tower + window-attention vit_merger + DownsampleMLP merger） python ./convert_hf_to_gguf.py ../MiniCPM-V-4_6 --mmproj --outfile ../MiniCPM-V-4_6/mmproj-model-f16.gguf

第一条命令产出语言模型ggml-model-f16.gguf；第二条加--mmproj后产出mmproj-model-f16.gguf。两个文件都写入模型目录../MiniCPM-V-4_6/。

可选：量化语言模型。如果想缩小文件体积，可以对语言模型做 Q4_K_M 量化（mmproj文件不参与该命令）：

./build/bin/llama-quantize ../MiniCPM-V-4_6/ggml-model-f16.gguf ../MiniCPM-V-4_6/ggml-model-Q4_K_M.gguf Q4_K_M

量化属于可选项，f16 模型已经可以直接推理；量化后的文件用于下文对话模式的示例。

用 llama-mtmd-cli 跑通图像推理

llama-mtmd-cli是编译后的统一多模态命令行工具（构建目标见 tools/mtmd/CMakeLists.txt），支持单轮与对话两种模式。

单轮模式——直接给一张图片和一个问题，--image后跟你的图片路径，-p后跟问题：

./build/bin/llama-mtmd-cli -m ../MiniCPM-V-4_6/ggml-model-f16.gguf \ --mmproj ../MiniCPM-V-4_6/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?"

xx.jpg是文档示例中的图片路径占位，替换为你自己的图片文件。如果想先用仓库自带的测试图验证工具链是否正常，可以直接使用 tools/mtmd/test-1.jpeg 的相对路径tools/mtmd/test-1.jpeg。参数含义沿用文档原样：-c 4096是上下文长度，其余为采样参数（temperature 0.7、top-p 0.8、top-k 100、repeat-penalty 1.05）。

判断结果：命令成功执行后，模型会针对图片内容输出一段回答（例如对 "What is in the image?" 的描述）。这是文档给出的取数方式，文档未提供固定预期输出；能收到针对图像内容的自然语言回答即说明模型、mmproj 与图片三者都加载成功。

对话模式——不带--image与-p，进入交互式会话：

./build/bin/llama-mtmd-cli -m ../MiniCPM-V-4_6/ggml-model-Q4_K_M.gguf --mmproj ../MiniCPM-V-4_6/mmproj-model-f16.gguf

示例使用量化后的ggml-model-Q4_K_M.gguf，未做量化的读者换成ggml-model-f16.gguf即可。

限制与后续

• 该流程依赖 checkpoint 版本：非标准transformersv5.7.0+ checkpoint（需要trust_remote_code的那一类）不支持直接转换。
• 多模态模块（libmtmd/llama-mtmd-cli）仍在快速开发中，后续版本的参数和文件名可能出现 breaking changes，行为异常时可对照 tools/mtmd/README.md 的时间线确认当前工具演进情况。
• 更多预量化多模态模型列表见 docs/multimodal.md。

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp