PowerInfer 多模态推理实战：LLaVA v1.5 的本地部署、llava-cli 使用与 GGUF 模型转换指南

PowerInfer 多模态推理实战LLaVA v1.5 的本地部署、llava-cli 使用与 GGUF 模型转换指南【免费下载链接】PowerInferHigh-speed Large Language Model Serving for Local Deployment项目地址: https://gitcode.com/gh_mirrors/po/PowerInfer导读本文以仓库中 examples/llava/README.md 为骨架完整讲解如何在 PowerInfer一个面向本地部署的高速大模型推理框架中运行 LLaVALarge Language and Vision Assistant视觉-语言模型。你将掌握三件事如何用 CMake 或 Makefile 构建llava-cli并在本地对图片进行图文对话如何将 HuggingFace 上的 LLaVA v1.5 与 CLIP 模型转换为 GGUF 格式以及图像嵌入从 CLIP 预处理、编码到送入 LLaMA 上下文的全链路实现原理。一、背景PowerInfer 中的 LLaVA 支持PowerInfer 仓库在examples/llava/目录下提供了一个完整的 LLaVA 视觉-语言推理实现当前版本支持 llava-v1.5 系列模型7B 与 13B 两个规格。该实现的核心思路是用LLaMA 主干GGUF 格式负责语言生成用CLIP 视觉编码器单独的 mmproj GGUF 文件负责把图片编码为视觉嵌入image embedding通过一个多模态投影器multimodal projector把视觉嵌入投影到 LLaMA 的词嵌入空间中从而让模型看懂图片。整个示例由以下几个关键源文件组成全部位于 examples/llava/文件职责llava-cli.cpp命令行入口参数解析、图片加载、对话 prompt 组装、流式生成llava.cpp / llava.h图像嵌入构建与评估的核心逻辑llava_image_embed_make_*、llava_eval_image_embedclip.cpp / clip.hCLIP 视觉模型的加载、图片预处理与编码llava-surgery.py把 LLaVA 模型拆分为 LLaMA 主干 多模态投影器convert-image-encoder-to-gguf.py把 CLIP 图像编码器 投影器转换为 GGUFCMakeLists.txt定义llava库与llava-cli可执行目标的构建规则二、快速开始构建 llava-cli 并运行2.1 构建构建llava-cli有两种方式任选其一方式一CMakemkdir build cd build cmake .. make llava-cli方式二Makefilemake llava-cli构建成功后可执行文件名为llava-cli。从 examples/llava/CMakeLists.txt 可以看到它会链接common、llama、llava三个库其中llava目标由llava.cpp与clip.cpp共同编译而来并在非 MSVC 环境下对stb_image.h关闭-Wno-cast-qual警告图片解码依赖 stb_image 头文件。2.2 命令行参数直接运行./llava-cli可查看完整用法。核心参数如下参数作用-m pathLLaVA 的 LLaMA 语言模型部分GGUF 文件如ggml-model-q5_k.gguf--mmproj path多模态投影器 CLIP 视觉编码器GGUF 文件如mmproj-model-f16.gguf--image path要分析的图片路径-p prompt文本提问默认为describe the image in detail.--temp float采样温度README 明确建议使用较低温度如0.1以获得更好生成质量-n count最大生成 token 数对应n_predict默认 256见 llava-cli.cpp-t count线程数n_threads用于图片编码与文本解码-b count批大小n_batch-c count上下文长度程序会强制至少 2048见 2.4 节2.3 一个完整的运行示例./llava-cli -m llava-v1.5-7b/ggml-model-q5_k.gguf \ --mmproj llava-v1.5-7b/mmproj-model-f16.gguf \ --image path/to/an/image.jpg \ --temp 0.1 \ -p describe the image in detail.注意README 特别强调较低的 temperature如0.1能显著提升回答质量建议在命令中添加--temp 0.1。如果仓库没有预转换模型也可以先使用社区/官方已转换好的 7b 和 13b GGUF 版本直接体验。2.4 推理流程与源码对照llava-cli的完整推理链路在 llava-cli.cpp 中大致分四步初始化双模型llava_init先用clip_model_load加载 mmproj 文件得到ctx_clip再用llama_load_model_from_file加载语言模型。值得注意的是代码在创建llama_context时会将上下文强制拉高到至少 2048ctx_params.n_ctx params-n_ctx 2048 ? 2048 : params-n_ctx; // we need a longer context size to process image embeddings这是因为一张 336×336 的图片经过 CLIP patch 化后会占据大量 token 位置普通文本上下文的默认值不够用。加载并编码图片load_image优先从 prompt 中解析 base64 图片标签否则从--image指定的路径读取文件。组装对话 promptprocess_prompt中按 LLaVA 的 chat 模板构造输入eval_string(ctx, A chat between a curious human and an artificial intelligence assistant. The assistant gives helpful, detailed, and polite answers to the humans questions.\nUSER:, ...); llava_eval_image_embed(ctx, image_embed, n_batch, n_past); eval_string(ctx, (prompt \nASSISTANT:).c_str(), ...);即系统提示语 →USER:→ 图像嵌入 → 用户文本 →ASSISTANT:然后进入生成循环。逐 token 采样与输出sample循环读取 logits遇到/sEOS即停止支持 greedy、temperature/top-k/top-p、tail-free、typical 与 mirostat 等多种采样策略见 llava-cli.cpp最后调用llama_print_timings打印性能统计。三、两种图片输入方式文件路径与 Base64除了--image指定本地图片文件llava-cli还支持把图片以base64 内嵌的形式直接写在 prompt 里格式为img srcdata:image/jpeg;base64,base64 byte string其实现位于 llava-cli.cpp程序用find_image_tag_in_prompt定位img ...标签通过base64::decode解码出原始图片字节再调用llava_image_embed_make_with_bytes生成嵌入随后remove_image_from_prompt会把该标签从 prompt 中剔除只保留纯文本问题。当 prompt 中存在 base64 图片时即使同时传了--image也会以 prompt 中的图片为准程序会打印 using base64 encoded image instead of command line image path。这一特性非常实用它为服务端 API 调用场景例如 HTTP 上传图片后拼 prompt提供了便利无需在磁盘上临时落盘图片文件。四、模型转换从 HuggingFace 到 GGUF 的完整流程如果无法直接下载预转换模型可以按照 README 提供的四步流程自行转换。转换目标是产出两个文件ggml-model-q5_k.gguf或任意量化等级的 LLaMA GGUF由convert.py产出并可选量化mmproj-model-f16.ggufCLIP 视觉编码器 多模态投影器由convert-image-encoder-to-gguf.py产出。4.1 前置准备克隆两个模型仓库git clone https://huggingface.co/liuhaotian/llava-v1.5-7b git clone https://huggingface.co/openai/clip-vit-large-patch14-336llava-v1.5-7bLLaVA 完整模型包含 LLaMA 权重、多模态投影器mm_projector、CLIP 视觉塔clip-vit-large-patch14-336CLIP ViT-L/14 视觉编码器输入分辨率 336×336用于提供纯视觉主干权重。4.2 第一步用 llava-surgery.py 拆分模型LLaVA 的原始 checkpoint 里同时包含语言模型、多模态投影器和视觉塔三部分权重需要先把它们拆开python ./examples/llava/llava-surgery.py -m ../llava-v1.5-7b从 llava-surgery.py 的源码看它做了三件事加载最后一个pytorch_model*.bincheckpoint把键名以model.mm_projector开头的张量抽取出来以 float32 精度保存为llava.projector从原 checkpoint 中删除这些张量后再保存使剩余部分成为一个干净的纯 LLaMA 模型可以直接走常规convert.py流程。脚本还兼容 BakLLaVA 类模型若发现model.vision_tower前缀的 CLIP 张量会额外抽成llava.clip并清理added_tokens.json这是为 Mistral 主干模型准备的兼容处理。4.3 第二步转换图像编码器CLIP 投影器python ./examples/llava/convert-image-encoder-to-gguf.py \ -m ../clip-vit-large-patch14-336 \ --llava-projector ../llava-v1.5-7b/llava.projector \ --output-dir ../llava-v1.5-7b注意README 中此命令省略了.py后缀实际脚本文件名为convert-image-encoder-to-gguf.py参数-m对应脚本中的--model-dir请以源码为准。该脚本convert-image-encoder-to-gguf.py的关键逻辑通过--llava-projector指定上一步拆出的投影器文件后脚本会进入has_llava_projector分支将输出文件名定为mmproj-model-ftype.gguf并在 GGUF 元数据中写入clip.has_llava_projector true加载CLIPModel与CLIPProcessor从config.json的vision_config/text_config读取image_size、patch_size、hidden_size等超参数写入 GGUF KV视觉编码器部分会弹出最后一层 encoder layermodel.vision_model.encoder.layers.pop(-1)因为 LLaVA 不需要 CLIP 的最终投射层投影器张量则以mm.*命名加入卷积层权重固定以 f16 保存GGML 卷积算子暂不支持 32 位 kernel其余权重默认 f16可用--use-f32强制浮点 32--image-mean/--image-std可覆盖默认归一化参数。4.4 第三步转换 LLaMA 语言模型部分python ./convert.py ../llava-v1.5-7bconvert.py位于仓库根目录是标准的 HuggingFace → GGUF 转换器。因为llava-surgery.py已剥离了投影器与视觉塔张量此时输入的目录就是一个纯 LLaMA 模型可直接转换。若想得到量化模型可继续用quantize工具见 examples/quantize/README.md对ggml-model-f16.gguf做 Q5_K 等量化与 README 示例中的ggml-model-q5_k.gguf对应。完成以上步骤后llava-v1.5-7b目录下应同时拥有ggml-model-f16.gguf语言模型与mmproj-model-f16.gguf图像编码器即可按第二节的命令运行。五、图像编码原理从像素到视觉嵌入为了深入理解 mmproj 文件的用途这里梳理 clip.cpp 中的图像处理管线对应llava_image_embed_make_with_clip_img→encode_image_with_clip的调用链解码与加载clip_image_load_from_bytes借助 stb_image 把 JPEG/PNG 解码为 RGB uint8 图像clip_image_u8。预处理clip_image_preprocess见 clip.cpp若图片非正方形先把短边用背景色rgb(122, 116, 104)填充到与长边等长pad2square与 LLaVA 官方对话代码保持一致按image_size336做等比缩放用双线性插值重采样按(x/255 - mean) / std做通道归一化默认 mean ≈ {0.4815, 0.4578, 0.4082}std ≈ {0.2686, 0.2613, 0.2758}这些值写入 GGUF 的clip.vision.image_mean/clip.vision.image_std。编码clip_image_encode把预处理后的 f32 图像送入 CLIP ViT 网络前向输出视觉特征。n_image_pos由clip_n_patches给出patch 数量代表这张图在语言模型中占据的位置数编码耗时会被打印为 image encoded in X ms by CLIP (Y ms per image patch)见 llava.cpp。投影与校验投影器把 CLIP 特征映射到 LLaMA 词嵌入维度。llava_validate_embed_size会比对llama_n_embd与clip_n_mmproj_embd二者不一致时报警并建议检查 mmproj 文件是否配对见 llava.cpp——这是用错 mmproj 文件导致推理异常时最典型的排查点。注入上下文llava_eval_image_embed把嵌入按n_batch分批通过llama_decode写入 KV 缓存作为 prompt 中USER:之后的视觉 token见 llava.cpp。六、已知限制与演进方向README 中列出了当前实现明确记录的 TODO可作为评估使用范围的参考图像编码部分暂不支持非 CPU 后端CLIP 编码目前只在 CPU 上执行llava_image_embed_make_with_*均接收n_threads线程参数采样方法有限虽然llava-cli内部实现了 greedy / temperature / top-k / top-p / mirostat 等多种采样但官方 TODO 仍计划支持更多采样方式与更统一的采样抽象源码中sample_id也留有 TODO: use common/sampling.h 注释模型变体支持范围待扩展当前聚焦 llava-v1.5 系列README 表示待 API 稳定后支持并上传更多模型。七、小结PowerInfer 的 LLaVA 示例为本地多模态推理提供了一个开箱即用的参考实现llava-cli一条命令即可对图片进行图文对话llava-surgery.pyconvert-image-encoder-to-gguf.pyconvert.py三件套打通了从 HuggingFace 权重到 GGUF 的完整转换链路而clip.cpp/llava.cpp则清晰展示了 CLIP 预处理、图像编码、维度校验与上下文注入的底层机制。若你在部署中遇到mmproj 与语言模型维度不匹配或图片编码异常的问题可优先回到本文第五节的源码链路逐层排查。【免费下载链接】PowerInferHigh-speed Large Language Model Serving for Local Deployment项目地址: https://gitcode.com/gh_mirrors/po/PowerInfer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考