llama.cpp 加载多模态 GGUF 模型实战

环境注意事项

目前 llama.cpp 的预编译包对 CUDA 12.6 的支持尚未完善，若遇到相关问题可能需要自行编译。此外，编译过程本身也存在一些依赖项的坑，建议仔细核对环境。

命令行加载示例

通过命令行工具可以直接加载多模态模型进行测试。运行命令时，确保模型主文件和 mmproj 文件来自同一来源，否则极易出现兼容性问题。推荐直接从 ggml 官方库获取资源。

llama-mtmd-cli -m Qwen2.5-VL-3B-Instruct-q8_0.gguf --mmproj Qwen2.5-VL-3B-Instruct-mmproj-f16.gguf -p "Describe this image." --image ./car-1.jpg

注意： 模型主 gguf 文件要和 mmproj 文件从一个库里下载，否则会有兼容问题，建议从 ggml 的官方库 下载。

Python 集成方式

在 Python 环境中，主要使用 llama-cpp-python 库。官方已经封装好不少多模态模型的加载类，比如 Qwen2.5-VL 的写法，实际开发中直接实例化 Llama 类并指定投影路径即可。

from llama_cpp import Llama

# 初始化模型，需同时指定模型路径和投影文件路径
llm = Llama(
    model_path="Qwen2.5-VL-3B-Instruct-q8_0.gguf",
    mmproj_path="Qwen2.5-VL-3B-Instruct-mmproj-f16.gguf"
)

# 后续调用 chat 或 completion 接口处理图像输入
response = llm.create_chat_completion(messages=[...])

详细用法可查阅 官方文档。