mistral.rs LLaVA-Next 实战用 Python SDK 加载并调用多模态视觉语言模型【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本篇基于 mistral.rs 官方文档中的llava_next示例页docs/src/content/docs/examples/python/llava-next.md由 docs/scripts/render_examples.py 从源码示例自动生成展开完整继承其可运行代码并结合仓库中 Python 绑定层与 Rust 核心层的实现讲清楚如何用 Python SDK 的Runner加载 LLaVA-Next 架构模型、构造带图像的 Chat Completion 请求以及模型内部的 CLIP 视觉塔、MM 投影器与 AnyRes 图像切分是怎么工作的。读完本文你可以直接复制示例代码跑通图文对话并能看懂底层输入处理器把图片转成视觉 token 的完整链路。一、完整可运行示例示例源码位于 examples/python/llava_next.py与文档页面中的代码完全一致。这里保留全文并补充关键注释from mistralrs import Runner, Which, ChatCompletionRequest, MultimodalArchitecture # Which.MultimodalPlain 是多模态原始权重加载器 # 直接从 Hugging Face 仓库加载 safetensors 权重并指定架构类型。 runner Runner( whichWhich.MultimodalPlain( model_idllava-hf/llava-v1.6-mistral-7b-hf, archMultimodalArchitecture.LLaVANext, ), ) res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ { role: user, content: [ # 多模态消息content 是 block 列表 # 支持 image_url 与 text 两种类型兼容 OpenAI 消息格式 { type: image_url, image_url: { url: https://www.nhmagazine.com/content/uploads/2019/05/mtwashingtonFranconia-2-19-18-108-Edit-Edit.jpg }, }, { type: text, text: What is shown in this image? Write a detailed response analyzing the scene., }, ], } ], max_tokens256, # 最大生成长度 presence_penalty1.0, # 提高描述多样性鼓励模型描述图中不同元素 top_p0.1, # 核采样阈值 temperature0.1, # 低温采样输出更稳定确定 ) ) print(res.choices[0].message.content) print(res.usage)该示例的三个要点模型来源model_idllava-hf/llava-v1.6-mistral-7b-hf是 Mistral 7B 底座、CLIP 视觉塔的 LLaVA-Next v1.6 检查点首次运行会从 Hugging Face 缓存下载。架构声明MultimodalArchitecture.LLaVANext显式指定多模态架构它会被映射到核心层的加载器类型见下文。采样参数presence_penalty1.0temperature0.1的组合适合看图描述这类任务——既要求覆盖画面细节又要求单条输出稳定。二、Which.MultimodalPlain构造参数全景文档示例只用了model_id与arch两个参数但完整签名定义在 Python 绑定层 mistralrs-pyo3/src/which.rs。所有参数及其用途如下可按需扩展示例参数类型 / 默认值说明model_idstr必填HF 仓库 ID 或本地路径权重与config.json、分词器均从此解析archMultimodalArchitecture \| None架构枚举不指定时从检查点config.json的architectures字段推断tokenizer_jsonstr \| None本地tokenizer.json路径不传则随模型仓库下载topologystr \| None多 GPU 拓扑文件如仓库 topologies/ 中的 YAML指定张量/流水线切分write_uqffPath \| None首次加载时额外写一份 UQFF 量化中间格式from_uqffstr \| list[str] \| None直接从 UQFF 文件加载dtypeModelDType默认Auto权重数据类型max_edgeint \| None图像最长边限制用于控制视觉 token 数calibration_file/imatrixPath \| None在线量化ISQ所需的校准数据 / imatrix 文件参考 calibration_data/ 说明格式auto_map_paramsMultimodalAutoMapParams \| None自动设备映射参数max_seq_len、max_batch_size、max_num_images、max_image_length默认值见 which.rshf_cache_pathPath \| None自定义 HF 缓存目录matformer_config_path/matformer_slice_namePath \| str \| NoneMatformer 模型分片配置organizationIsqOrganization \| NoneISQ 量化组织方式Default/MoQEencoder_cache_memory_bytesint \| None视觉编码器缓存内存预算用于跨请求复用图像特征类型映射关系在 mistralrs-pyo3/src/which.rs 中定义MultimodalArchitecture枚举包含Phi3V、Idefics2、LLaVANext、LLaVA、Qwen2VL、Gemma3、Llama4等二十余种多模态架构其中LLaVANext被一一映射为MultimodalLoaderType::LLaVANext从而在核心层选中对应的加载器与输入处理器。三、架构识别LlavaNextForConditionalGeneration如何路由到加载器核心层的加载器注册逻辑在 mistralrs-core/src/pipeline/loaders/multimodal_loaders.rs。有三条路径都能落到LLaVANext类型检查点config.json中architectures: [LlavaNextForConditionalGeneration]multimodal_loaders.rs架构名直接写llava_nextmultimodal_loaders.rsPython 端显式传archMultimodalArchitecture.LLaVANext。随后 multimodal_loaders.rs 中的LLaVANextLoader负责三件事构建LLaVANext::new(...)模型实例、创建LLaVANextProcessor输入处理器、提供LLaVANextPrefixer提示前缀工具同时它还实现了IsqModelLoader与DeviceMappedModelLoader两个 trait因此同一架构既支持在线量化也支持自动设备映射——这正是Which.MultimodalPlain提供calibration_file、imatrix、auto_map_params参数的底层原因。四、LLaVA-Next 模型结构视觉塔、投影器与语言模型模型实现位于 mistralrs-core/src/vision_models/llava/llava_next.rs核心组件与权重前缀一一对应vision_tower.vision_model.* → ClipVisionTransformerCLIP ViT 视觉塔 multi_modal_projector.* → MMProjectorlinear_1 → GELU → linear_2 image_newline → 每张图像切块之间的图像换行嵌入 text 底座 → LLaVALLM trait 的 Llama / Mistral 实现ClipVisionTowerllava_next.rs前向时取出select_layer指定的中间层 hidden states负索引并按vision_feature_select_strategy决定是否保留 CLS tokencls_patch/full保留其他策略切片去掉首位。MMProjectorllava_next.rs两级线性 GELU 激活把 CLIP 的hidden_size映射到语言模型的hidden_size源码中projector_hidden_act目前只接受gelu否则会报错。模型配置mistralrs-core/src/vision_models/llava/config.rs 定义了image_grid_pinpointsAnyRes 分辨率锚点、vision_feature_layer、vision_feature_select_strategy等字段——这些直接决定图像切分行为。编码器缓存模型内部持有EncoderCacheManager配合Which.MultimodalPlain的encoder_cache_memory_bytes参数可对相同图片的视觉特征做跨请求复用避免重复跑视觉塔。五、输入处理器一张图如何变成变长的视觉 token 段这是 LLaVA-Next 与单分辨率 LLaVA 最大的区别实现位于 mistralrs-core/src/vision_models/llava/llava_next_inputs_processor.rsAnyRes 分辨率选择preprocess方法根据image_grid_pinpoints调用select_best_resolution为原图挑一个最接近的分辨率再经resize_and_pad_image填充最后按crop_size宽×高由divide_to_samples切成 N 个 patch 样本同时原图还会整体缩放到size.shortest_edge尺寸作为第 0 个样本。归一化与精度每个样本经LLaVAImageProcessor::process_one_image转为 BF16 张量默认均值[0.48145466, 0.4578275, 0.40821073]、标准差[0.26862954, 0.26130258, 0.27577711]llava_next_inputs_processor.rs可由preprocessor_config.json中的image_mean/image_std覆盖。注意源码注释表明每个批次只处理一张图像多图需要跨请求处理。视觉 token 数计算get_num_image_tokensllava_next_inputs_processor.rs按 AnyRes 网格形状计算固定patch_per_side²全局缩略图加上未填充区域的 patch 数所以不同尺寸的图片会产生不同长度的占位 token 段。提示词改写llava_next_prompt_tokens用正则image切分提示词校验image标签数量与图像数量一致不一致会抛出LLaVA-Next prompt has {n} image tags but {m} images错误然后把每个image位置替换为变长占位段——段内用负数 token ID 标记图像索引文本 token 正常编码实际送入模型时负数占位被置 0前向阶段再由视觉特征拼回llava_next_inputs_processor.rs。前缀缓存适配prepare_for_paged_prompt_planning与restore_llava_next_image_markers保证在分页注意力的 prompt 规划与 KV 前缀缓存命中场景下图像占位标记能按局部坐标正确恢复。该文件末尾还附带了packed_layout_splices_media_and_preserves_text_request等单元测试验证混合批中视觉嵌入拼接的正确性。六、请求侧注意事项图片输入示例用image_url传远程 URLSDK 的ChatCompletionRequest同样接受本地文件路径与 base64 数据可参考仓库 examples/python/phi3v_local_img.py、examples/python/phi3v_base64.py 的写法同为多模态图文消息的构造方式。响应结构res.choices[0].message.content为生成文本res.usage含 token 用量该请求走的是与 OpenAI 兼容的 Chat Completions 语义服务端对应实现见 mistralrs-server-core/src/chat_completion.rs。纯文本回退输入处理器在无图像时会退回文本处理器路径llava_next_inputs_processor.rs因此同一 Runner 也可以只发纯文本消息。服务端等价用法如果想走 HTTP 服务而非进程内 SDK可参考 examples/server/llava_next.py 的 serve 方式。七、小结与延伸阅读本文覆盖了llava_next示例页的全部内容并补齐了源码依据Which.MultimodalPlain的完整参数表、LLaVANext架构在加载器层的路由逻辑、模型三大组件CLIP 塔 / MM 投影器 / LLaMA-Mistral 底座的权重结构以及 AnyRes 变分辨率下图像 → patch 样本 → 变长占位 token → 视觉嵌入拼接的完整链路。关键源码入口示例与文档页examples/python/llava_next.py、docs/src/content/docs/examples/python/llava-next.mdPython 绑定mistralrs-pyo3/src/which.rs、mistralrs-pyo3/mistralrs.pyi核心实现mistralrs-core/src/vision_models/llava/llava_next.rs、mistralrs-core/src/vision_models/llava/llava_next_inputs_processor.rs、mistralrs-core/src/vision_models/llava/config.rs、mistralrs-core/src/pipeline/loaders/multimodal_loaders.rs需要注意的前提示例面向 CUDA 环境下的原始权重加载模型体积约为 7B 语言模型 CLIP 视觉塔显存需求应据此规划MultimodalArchitecture中另有LLaVA单分辨率版等近似架构两者的图像切分与占位 token 数计算方式不同选模型时应对应区分。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考