PowerInfer 多模态推理实战：libmtmd 图像与音频输入的配置与使用指南

人工智能大模型推理引擎本地部署【免费下载链接】PowerInferHigh-speed Large Language Model Serving for Local Deployment项目地址https://gitcode.com/gh_mirrors/po/PowerInfer点击查看免费下载多模态能力让本地部署的大语言模型能够直接看见图片、听见音频从而支撑视觉问答、图文理解、语音交互等场景。本文以仓库smallthinker/docs/multimodal.md为核心系统讲解libmtmd多模态支持的工作原理、llama-mtmd-cli与llama-server两种入口的启用方式、全部命令行参数与预量化模型清单并结合仓库源码深入剖析其底层数据流帮助读者从零开始跑通本地多模态推理。一、多模态支持概览libmtmd 与两种使用入口根据 smallthinker/docs/multimodal.md本项目smallthinker子树对应 llama.cpp 生态的多模态实现通过libmtmd库提供多模态输入支持。当前支持两种模态图像image稳定可用是主要支持对象音频audio高度实验性highly experimental输出质量可能有所下降。目前有两个工具支持该特性llama-mtmd-cli命令行交互工具详见 smallthinker/tools/mtmd/README.mdllama-serverHTTP 服务通过 OpenAI 兼容的/chat/completionsAPI 提供多模态推理详见 smallthinker/tools/server/README.md。从 smallthinker/tools/mtmd/README.md 的历史梳理可以看到多模态支持最初以 LLaVA 为起点llava.cppclip.cppllava-cli随后陆续加入 MobileVLM、Qwen2-VL、MiniCPM-V、Gemma 3 等架构。由于各模型的 chat template 差异越来越大llava-cli难以统一支撑社区一度演化出qwen2vl-cli、minicpmv-cli、gemma3-cli等各自独立的二进制。libmtmd的引入正是为了统一这些碎片化的入口它提供单一、统一的多模态命令行界面同时支持音频与图像输入。在 smallthinker/tools/mtmd/CMakeLists.txt 中可以看到llama-llava-cli、llama-gemma3-cli、llama-minicpmv-cli、llama-qwen2vl-cli现在都仅由deprecation-warning.cpp编译而成即这些旧工具已被统一到llama-mtmd-cli之下。注意多模态支持在llama.cpp生态中属于重度开发中的子项目libmtmd的 API 处于实验阶段预期会有破坏性变更breaking changes官方也明确提示与 API 使用相关的问题可能得到较低优先级支持。二、核心概念mmproj 多模态投影器理解多模态推理首先要理解mmprojmultimodal projector这个文件。为什么需要两个 GGUF 文件多模态支持的工作方式是使用一个独立的模型组件把图像编码为 embeddings再把 embeddings 喂给语言模型。这种设计让多模态组件与核心libllama库解耦从而获得更快、更独立的开发迭代速度。虽然现代视觉模型大多基于 Vision TransformerViT但各自的预处理与投影步骤差异很大把这种复杂多样性直接集成进libllama目前仍有挑战。因此运行一个多模态模型通常需要两个 GGUF 文件标准语言模型文件text model对应的多模态投影器文件mmproj负责图像编码与投影。mmproj 文件是按模型架构特异性的——不同架构Gemma 3、SmolVLM、Pixtral、Qwen2-VL、InternVL 等的 mmproj 不能混用。如何获取 mmproj对于新架构模型可以使用convert_hf_to_gguf.py配合--mmproj标志从 Hugging Face checkpoint 转换得到 mmproj 文件支持的模型包括 Gemma 3、SmolVLM / SmolVLM2、Pixtral 12B、Qwen2-VL / Qwen2.5-VL、Mistral Small 3.1 24B、InternVL 2.5 / 3 等注意InternVL3-*-hf变体不支持转换仅支持非 HF 版本InternLM2Model纯文本模型不支持。对于 LLaVA、MobileVLM、GLM-Edge、MiniCPM-V 2.5 / 2.6、MiniCPM-o 2.6、IBM Granite Vision 等老架构则需参考 smallthinker/docs/multimodal 目录下各自的指南如 llava.md、gemma3.md转换脚本位于 smallthinker/tools/mtmd/legacy-models 下如llava_surgery.py、minicpmv-convert-image-encoder-to-gguf.py等。对于想快速上手的用户绝大多数常用多模态模型都已有官方预量化版本见下文第六节直接通过-hf下载即可无需自行转换。三、启用多模态的两种方式与完整参数说明根据 smallthinker/docs/multimodal.md启用多模态有以下两种方法方式一使用-hf自动拉取模型与投影器使用-hf选项加载受支持的模型列表见下文预量化模型清单系统会自动下载配套的 mmproj若用-hf加载模型但想禁用多模态加--no-mmproj若用-hf加载模型但想指定自定义 mmproj 文件加--mmproj local_file.gguf。方式二本地文件显式指定使用-m model.gguf指定文本模型配合--mmproj file.gguf指定多模态投影器。关键参数与默认行为从 smallthinker/tools/server/README.md 的参数表中可以提取出与多模态相关的完整参数及其环境变量对应关系参数说明环境变量-hf, -hfr, --hf-repo user/model[:quant]Hugging Face 模型仓库quant可选、大小写不敏感默认Q4_K_M若仓库中没有 Q4_K_M 则回退到仓库第一个文件mmproj 可用时也会自动下载可通过--no-mmproj禁用LLAMA_ARG_HF_REPO--mmproj FILE多模态投影器文件路径使用-hf时可省略LLAMA_ARG_MMPROJ--mmproj-url URL多模态投影器文件的 URLLLAMA_ARG_MMPROJ_URL--no-mmproj显式禁用多模态投影器适合与-hf一起使用LLAMA_ARG_NO_MMPROJ--no-mmproj-offload不将多模态投影器卸载offload到 GPULLAMA_ARG_NO_MMPROJ_OFFLOAD默认行为多模态投影器默认会被 offload 到 GPU 上运行如需禁用 GPU offload追加--no-mmproj-offload例如显存紧张、或在纯 CPU 环境运行时。官方示例命令# 命令行工具的基本用法 llama-mtmd-cli -hf ggml-org/gemma-3-4b-it-GGUF # 服务端的基本用法 llama-server -hf ggml-org/gemma-3-4b-it-GGUF # 使用本地文件 llama-server -m gemma-3-4b-it-Q4_K_M.gguf --mmproj mmproj-gemma-3-4b-it-Q4_K_M.gguf # 不使用 GPU offload llama-server -hf ggml-org/gemma-3-4b-it-GGUF --no-mmproj-offload四、命令行工具 llama-mtmd-cli 使用详解llama-mtmd-cli是当前统一的多模态命令行入口。从 smallthinker/tools/mtmd/mtmd-cli.cpp 的用法说明看其完整形态为llama-mtmd-cli [options] -m model --mmproj mmproj --image image --audio audio -p prompt约束条件-m与--mmproj是必需的除非用-hf user/repo替代二者--image、--audio、-p均为可选若都不提供CLI 会进入聊天模式chat mode需要禁用 mmproj 的 GPU 使用时追加--no-mmproj-offload若同时提供-p与--image则进入单轮single-turn模式处理完一次问答即结束。单轮模式与媒体标记marker单轮模式下代码会自动检测 prompt 中是否包含默认媒体标记mtmd_default_marker()默认标记为__media__若没有则把每个--image依次追加到 prompt 末尾。也就是说图片会以__media__占位符的形式嵌入对话文本流中libmtmd在 tokenize 阶段会将该标记替换为图像 token 序列。聊天模式与交互命令进入聊天模式后CLI 会输出可用命令依据模型能力动态显示 /image path 加载一张图片 /audio path 加载一段音频 /clear 清空聊天历史 /quit 或 /exit 退出程序其中/image、/audio仅在该模型mmproj支持对应模态时才会出现在帮助中——这正是通过mtmd_support_vision()/mtmd_support_audio()运行时检测的。旧模型与 chat template从 smallthinker/tools/mtmd/mtmd-cli.cpp 可以看到如果模型本身没有内置 chat template运行时会报错并提示用户显式指定例如旧版 LLaVA 模型--chat-template vicunaMobileVLM--chat-template deepseekMistral Small 3.1--chat-template mistral-v7这一点与 smallthinker/tools/mtmd/tests.sh 中测试矩阵的做法一致如second-state/Llava-v1.5-7B-GGUF配vicuna。五、服务端 llama-server 与 OpenAI 兼容 APIllama-server在 smallthinker/tools/server/README.md 中被明确标注为支持多模态其/v1/chat/completions接口提供了两种图像输入途径1.image_urlcontent part推荐如果模型支持多模态可以直接在messages的 content 中使用image_url类型的 content part 传入媒体文件base64 数据与远程 URL 都支持。2.image_data id 引用服务端同样支持通过image_data数组传入 base64 编码的图像数据并在 prompt 中以[img-id]占位符引用。示例构造{..., image_data: [{data: BASE64_STRING, id: 12}]}后在 prompt 中写USER:[img-12]Describe the image in detail.\nASSISTANT:[img-12]会被替换为 id 为 12 的图片的 embeddings。该方式仅用于多模态模型如 LLaVA。环境变量配置llama-server还支持通过环境变量完成多模态配置便于容器化部署如 Docker ComposeLLAMA_ARG_MODEL: /models/my_model.gguf LLAMA_ARG_MMPROJ: /models/mmproj.gguf # 多模态投影器 LLAMA_ARG_CTX_SIZE: 4096 LLAMA_ARG_N_PARALLEL: 2六、预量化模型清单以下模型大多默认带Q4_K_M量化可直接通过-hf加载可在ggml-org的 Hugging Face 多模态 GGUF 集合页中查找。将(tool_name)替换为你要使用的二进制名llama-mtmd-cli或llama-server。注意部分模型需要较大的上下文窗口例如加-c 8192。视觉模型Vision models# Gemma 3 (tool_name) -hf ggml-org/gemma-3-4b-it-GGUF (tool_name) -hf ggml-org/gemma-3-12b-it-GGUF (tool_name) -hf ggml-org/gemma-3-27b-it-GGUF # SmolVLM (tool_name) -hf ggml-org/SmolVLM-Instruct-GGUF (tool_name) -hf ggml-org/SmolVLM-256M-Instruct-GGUF (tool_name) -hf ggml-org/SmolVLM-500M-Instruct-GGUF (tool_name) -hf ggml-org/SmolVLM2-2.2B-Instruct-GGUF (tool_name) -hf ggml-org/SmolVLM2-256M-Video-Instruct-GGUF (tool_name) -hf ggml-org/SmolVLM2-500M-Video-Instruct-GGUF # Pixtral 12B (tool_name) -hf ggml-org/pixtral-12b-GGUF # Qwen 2 VL (tool_name) -hf ggml-org/Qwen2-VL-2B-Instruct-GGUF (tool_name) -hf ggml-org/Qwen2-VL-7B-Instruct-GGUF # Qwen 2.5 VL (tool_name) -hf ggml-org/Qwen2.5-VL-3B-Instruct-GGUF (tool_name) -hf ggml-org/Qwen2.5-VL-7B-Instruct-GGUF (tool_name) -hf ggml-org/Qwen2.5-VL-32B-Instruct-GGUF (tool_name) -hf ggml-org/Qwen2.5-VL-72B-Instruct-GGUF # Mistral Small 3.1 24BIQ2_M 量化 (tool_name) -hf ggml-org/Mistral-Small-3.1-24B-Instruct-2503-GGUF # InternVL 2.5 和 3 (tool_name) -hf ggml-org/InternVL2_5-1B-GGUF (tool_name) -hf ggml-org/InternVL2_5-4B-GGUF (tool_name) -hf ggml-org/InternVL3-1B-Instruct-GGUF (tool_name) -hf ggml-org/InternVL3-2B-Instruct-GGUF (tool_name) -hf ggml-org/InternVL3-8B-Instruct-GGUF (tool_name) -hf ggml-org/InternVL3-14B-Instruct-GGUF # Llama 4 Scout (tool_name) -hf ggml-org/Llama-4-Scout-17B-16E-Instruct-GGUF # Moondream2 20250414 版本 (tool_name) -hf ggml-org/moondream2-20250414-GGUF音频模型Audio models# Ultravox 0.5 (tool_name) -hf ggml-org/ultravox-v0_5-llama-3_2-1b-GGUF (tool_name) -hf ggml-org/ultravox-v0_5-llama-3_1-8b-GGUF # Qwen2-Audio 和 SeaLLM-Audio # 注意这两个模型没有预量化 GGUF因为效果很差混合模态Mixed modalities# Qwen2.5 Omni # 能力音频输入、视觉输入 (tool_name) -hf ggml-org/Qwen2.5-Omni-3B-GGUF (tool_name) -hf ggml-org/Qwen2.5-Omni-7B-GGUF从 smallthinker/tools/mtmd/tests.sh 可以看到官方测试矩阵覆盖了上述绝大部分模型并且按体积分为三档默认如 SmolVLM-500M、Gemma 3 4B、InternVL2_5-1B、Ultravox 1B 等、big如 Pixtral-12B、Qwen2-VL-7B、InternVL3-14B 等用./tests.sh big触发与huge如 Qwen2.5-VL-72B、Llama-4-Scout用./tests.sh huge触发。测试图片为test-1.jpeg音频为test-2.mp3结果日志保存在output/目录。七、源码级原理libmtmd 的数据流smallthinker/tools/mtmd/mtmd.h 完整定义了libmtmd的 C API其核心数据流可以概括为bitmap → input chunks → encode → llama_decode。1. bitmap统一封装图像与音频mtmd_bitmap是对多模态原始数据的统一抽象若为图像数据长度为nx * ny * 3按RGBRGBRGB...排列若为音频数据长度为n_samples * sizeof(float)为 PCM F32 格式。mtmd_helper_bitmap_init_from_file()可从文件直接构造 bitmap支持格式为图像stb_image 支持的 jpg、png、bmp、gif 等、音频miniaudio 支持的 wav、mp3、flac音频文件通过 magic bytes 自动识别。bitmap 还支持可选的id便于 KV cache 追踪例如基于像素数据计算图像哈希。2. mtmd_tokenize把 prompt 切分为 chunksmtmd_tokenize()接收文本 prompt 与 bitmap 列表输出一个mtmd_input_chunks列表。输入文本必须包含默认媒体标记__media__标记会被替换为媒体 chunk。例如here is an image: __media__\ndescribe it in detail.会被拆成 3 个 chunk文本here is an image: start_of_image图像/音频 token文本end_of_image\ndescribe it in detail.约束与返回码bitmap 数量必须与 prompt 中标记数量一致否则返回 1图像预处理出错返回 2成功返回 0该函数线程安全共享 ctx。chunk 类型由mtmd_input_chunk_type枚举定义MTMD_INPUT_CHUNK_TYPE_TEXT/_IMAGE/_AUDIO。对 M-RoPE 类模型如 Qwen2-VLchunk 还记录时间维位置数n_posM-RoPE 恒为 1其他模型等于 token 数。3. 编码与解码mtmd_encode_chunk()对图像/音频 chunk 执行编码mtmd_get_output_embd()取出上次 encode 的输出 embeddings字节数 llama_model_n_embd(model) * n_tokens * sizeof(float)smallthinker/tools/mtmd/mtmd-helper.h 中的mtmd_helper_eval_chunks()把完整流程串起来对文本 chunk 执行llama_decode()对媒体 chunk 执行mtmd_encode()后再取 embeddings 喂给llama_decode()并自动处理批处理与前后解码设置例如Gemma 3 需要非因果注意力 non-causal attentionQwen2-VL 类模型使用M-RoPE这些都可以通过mtmd_decode_use_non_causal()、mtmd_decode_use_mrope()运行时查询。4. 底层 clip 实现libmtmd构建于clip.cpp之上继承自原llava.cpp的视觉编码基础设施。从 smallthinker/tools/mtmd/clip.h 可见clip 层同时维护视觉vision与音频audio两个上下文clip_init返回ctx_v/ctx_a并通过clip_has_vision_encoder()、clip_has_audio_encoder()、clip_has_whisper_encoder()判断能力同时提供clip_is_minicpmv()、clip_is_glm()、clip_is_qwen2vl()、clip_is_llava()、clip_is_gemma3()等架构识别函数用于区分不同架构在预处理、patch merge、位置编码上的差异。音频分支mtmd-audio.cpp会做 Mel 频谱预处理采样率可通过mtmd_get_audio_bitrate()查询如 Whisper 为 16000 Hz。5. 构建目标在 smallthinker/tools/mtmd/CMakeLists.txt 中libmtmd作为库add_library(mtmd ...)链接ggml与llama与llama-mtmd-cli可执行文件一起构建可通过以下命令完成cmake -B build cmake --build build --config Release -t llama-mtmd-cli cmake --build build --config Release -t llama-serverllama-server的二进制位于./build/bin/llama-serverllama-mtmd-cli同理。八、注意事项与限制音频高度实验性libmtmd的音频支持仍在早期阶段质量可能不达预期文档明确标注 Qwen2-Audio 与 SeaLLM-Audio 因效果很差而未提供预量化 GGUF。上下文窗口多模态模型尤其是视频类与超大视觉模型需要较大上下文例如官方建议-c 8192测试脚本中对 32B 参数模型标注了在我的机器上无法运行的硬件前提72B / Llama-4-Scout 等巨型模型对显存与算力要求很高。mmproj 的 GPU offload默认 mmproj 会 offload 到 GPU显存不足时可加--no-mmproj-offload改为 CPU 推理性能会下降。chat template旧模型LLaVA、MobileVLM 等没有内置 chat template必须用--chat-template显式指定部分模型存在损坏的 chat template如测试脚本中注释掉的 Yi-VL-6B不可直接使用。API 稳定性libmtmd是实验性 API破坏性变更频繁mtmd.h中多个函数如mtmd_encode、mtmd_image_tokens_get_*已标注TODO: deprecate未来可能调整。综上只需两条路径即可上手追求快速验证用llama-mtmd-cli -hf ggml-org/...一行命令追求服务化部署用llama-server配合 OpenAI 兼容 API。结合本文的参数表、模型清单与源码级数据流分析读者可以针对具体模型与硬件环境完成多模态推理从选型、配置到部署的全流程。赞分享人工智能大模型推理引擎本地部署【免费下载链接】PowerInferHigh-speed Large Language Model Serving for Local Deployment项目地址https://gitcode.com/gh_mirrors/po/PowerInfer点击查看免费下载相关推荐llama.cpp 多模态推理实战指南用 libmtmd 与 mmproj 接入图像、音频与视频输入llama.cpp 多模态推理实战指南用 libmtmd 与 mmproj 接入图像、音频与视频输入 本文围绕 llama.cpp 的多模态输入能力展开完整人工智能大模型模型推理服务推理引擎本地部署后端Agno 多模态 Agent 实战图像、音频与视频输入输出的完整模式解析Agno 多模态 Agent 实战图像、音频与视频输入输出的完整模式解析 Agno 的 Agent 不只是处理文本它能像人一样看图、听音、读文档人工智能大模型AI AgentAgent 框架多智能体工具调用RAGAgent 工作流Agent 记忆ik_llama.cpp 多模态推理完全指南libmtmd、mmproj 与 llama-mtmd-cli 实战ik_llama.cpp 多模态推理完全指南libmtmd、mmproj 与 llama mtmd cli 实战 导读 本文面向希望在本仓库ik_llama人工智能大模型推理引擎本地部署模型量化上一篇F´ 健康检查模式Health Checking Pattern实践指南用 Svc.Health 守护飞行软件关键组件下一篇终极指南如何高效部署Django Unfold到生产环境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考