
mistral.rs 多模态入门实战用 Rust 加载视觉语言模型并完成图片问答【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本文以 mistral.rs 仓库中的 Rust SDK 入门示例 multimodal 示例 为主线讲解如何在 Rust 中构建视觉语言模型VLM、加载本地图片并发送多模态聊天请求。读完本文你将掌握ModelBuilder加载模型、MultimodalMessages构造图文消息、send_chat_request发起推理的完整链路并了解 mistral.rs 底层如何为不同模型自动注入媒体前缀 token。示例概览一个多模态Hello World仓库中mistralrscrate 的入门示例multimodal_basic源码见 mistralrs/examples/getting_started/multimodal/main.rs是一个最小可运行的多模态程序加载 Gemma 4 E4B 视觉模型从网络下载一张花朵图片向模型提问 What is this flower? 并打印回答。整个过程约 30 行代码覆盖了多模态推理的四个核心步骤通过ModelBuilder构建并加载模型下载/读取图片字节并解码为DynamicImage用MultimodalMessages组装带图片的用户消息调用send_chat_request获取文本回答。该示例在 mistralrs/Cargo.toml 中以[[example]]形式注册example 名为multimodal_basic可用以下命令直接运行首次运行会编译全部依赖并下载模型权重耗时较长cargo run --release --example multimodal_basic -p mistralrs完整示例代码示例完整代码如下与仓库源码一致/// Simple multimodal model hello world. /// /// For a comprehensive example with all supported multimodal model IDs, /// see examples/models/multimodal_models/. /// /// Run with: cargo run --release --example multimodal_basic -p mistralrs use anyhow::Result; use mistralrs::{IsqBits, ModelBuilder, MultimodalMessages, TextMessageRole}; #[tokio::main] async fn main() - Result() { let model ModelBuilder::new(google/gemma-4-E4B-it) .with_auto_isq(IsqBits::Four) .with_logging() .build() .await?; let bytes match reqwest::blocking::get( https://cdn.britannica.com/45/5645-050-B9EC0205/head-treasure-flower-disk-flowers-inflorescence-ray.jpg, ) { Ok(http_resp) http_resp.bytes()?.to_vec(), Err(e) anyhow::bail!(e), }; let image image::load_from_memory(bytes)?; let messages MultimodalMessages::new().add_image_message( TextMessageRole::User, What is this flower?, vec![image], ); let response model.send_chat_request(messages).await?; println!({}, response.choices[0].message.content.as_ref().unwrap()); Ok(()) }关键点解读程序入口使用#[tokio::main]因为build()与send_chat_request()都是异步操作reqwest负责从 URL 下载图片字节imagecrate 的load_from_memory将其解码为DynamicImagemistralrs内部正是以image::DynamicImage作为图片载体见 mistralrs/src/messages.rsanyhow::Result提供便捷的错误传播下载失败时通过anyhow::bail!直接终止。构建模型ModelBuilder 与常用配置项ModelBuilder是 mistralrs Rust SDK 中自动检测类型的模型构建器Auto类别会自动根据模型 ID 判断模型架构、类别文本/多模态/语音/扩散等并加载对应权重。在 mistralrs/src/auto_model.rs 中可以看到它维护了完整的配置字段集合其构造器ModelBuilder::new(model_id)会施加一组默认值见 mistralrs/src/auto_model.rs默认 token 来源为缓存.cache/huggingface/token最大并发序列数max_num_seqs为 32前缀缓存序列数prefix_cache_n为 16自动设备映射AutoDeviceMapParams默认 dtype 为Auto自动选择。示例中用到的三个配置方法都定义在构建器宏 mistralrs/src/builder_macros.rs 中被多个 builder 共享方法作用说明with_auto_isq(IsqBits)自动选择最优 ISQ 量化类型根据目标平台在构建时解析Metal 上选择 AFQ 变体如 4-bit 对应 AFQ4CUDA/CPU 上选择 Q*K 变体如 4-bit 对应 Q4K见 mistralrs/src/builder_macros.rswith_logging()开启日志输出便于观察模型加载与推理过程中的状态信息with_chat_template(path)指定自定义聊天模板参数可以是字面 Jinja 模板或指向.json模板文件的路径默认从模型仓库自动获取除此之外构建多模态模型时常用的配置还包括with_max_edge(u32)自动将图片缩放/填充到该最大边长保持宽高比仅对支持此特性的多模态模型生效如 Qwen2-VL、Idefics 2见 mistralrs/src/auto_model.rswith_isq(IsqType)显式指定量化类型如Q8_0与with_auto_isq二选一使用with_device(Device)/with_device_mapping(...)指定主设备与设备映射多 GPU 场景下配合自动设备映射使用with_paged_attn(cfg)启用 PagedAttention平台不支持时静默忽略with_max_num_seqs(usize)调整最大并发序列数。构造多模态消息MultimodalMessages 与 TextMessageRoleMultimodalMessages是承载文字 图片 音频 视频请求的核心类型定义在 mistralrs/src/messages.rs内部维护四个集合messagesOpenAI 风格的消息列表role contentimages/audios/videos分别保存DynamicImage、AudioInput、VideoInput媒体数据pending_prefixes记录每条消息对应哪些媒体索引用于发送时自动注入模型专属的媒体前缀 token。TextMessageRole消息角色TextMessageRole枚举mistralrs/src/messages.rs定义了五种角色User人类用户序列化为userAssistant模型/助手序列化为assistantSystem系统提示词序列化为systemTool工具调用输出序列化为toolCustom(String)任意自定义角色字符串。常用方法均为链式、消费self返回新实例方法签名要点说明new()- Self创建空消息列表add_message(role, text)追加纯文本消息序列化为{role: ..., content: text}add_image_message(role, text, images: VecDynamicImage)追加图文消息等效于add_multimodal_message(role, text, images, [], [])add_audio_message(role, text, audios: VecAudioInput)追加音频消息见 mistralrs/src/messages.rsadd_video_message(role, text, videos: VecVideoInput)追加视频消息见 mistralrs/src/messages.rsadd_multimodal_message(role, text, images, audios, videos)追加混合媒体消息底层统一实现见 mistralrs/src/messages.rsenable_thinking(bool)启用/关闭思考模式仅对支持 extended thinking 的模型生效with_reasoning_effort(ReasoningEffort)设置推理强度同上见 mistralrs/src/messages.rsclear()清空所有消息与媒体见 mistralrs/src/messages.rs媒体前缀 token 的自动注入机制add_multimodal_message在内部为每条消息记录其图片/音频/视频的全局索引到pending_prefixesmistralrs/src/messages.rs并将消息内容组织成 OpenAI 风格的多内容块数组[{type: image}, ..., {type: text, text: ...}]mistralrs/src/messages.rs。关键在于此时并不立即写入模型专属的媒体前缀 token。当请求通过Model::send_chat_request/stream_chat_request发送时SDK 会先调用resolve_pending_prefixes(category)见 mistralrs/src/model.rs 与 mistralrs/src/messages.rs依据模型类别ModelCategory自动为文本内容补上对应的前缀标记例如视觉模型的图片 token、音频模型的音频 token 等。这意味着同一个MultimodalMessages结构可以被不同架构的模型复用无需手写模型特有的 token。发起推理send_chat_request 与响应结构Model::send_chat_request接受任何实现了RequestLiketrait 的类型TextMessages、MultimodalMessages、RequestBuilder均可定义在 mistralrs/src/model.rspub async fn send_chat_requestR: RequestLike(self, request: R) - crate::error::ResultChatResponse;响应为 OpenAI 兼容结构示例中取response.choices[0].message.content即为模型生成的文本。若需要流式输出可改用stream_chat_requestmistralrs/src/model.rs它返回一个可逐 token 迭代的Stream。此外MultimodalMessages可以无损转换为RequestBuilderRequestBuilder::from(messages)见 mistralrs/src/messages.rs从而获得更细粒度的控制采样参数、logits processors、工具调用、logprobs、thinking 配置等。多轮对话时还可以直接复用累积的消息结构。支持更多模型multimodal_models 综合示例入门示例的注释明确指出完整的多模态模型支持列表参见examples/models/multimodal_models/。对应源码 mistralrs/examples/models/multimodal_models/main.rs 通过MODEL_ID常量切换模型并附带了仓库中已验证的模型清单模型MODEL_IDLlama 3.2 Visionlamm-mit/Cephalo-Llama-3.2-11B-Vision-Instruct-128kPhi-3.5 Visionmicrosoft/Phi-3.5-vision-instructPhi-4 Multimodalmicrosoft/Phi-4-multimodal-instructLLaVA 1.5llava-hf/llava-1.5-7b-hf需.with_chat_template(chat_templates/vicuna.json)LLaVA-NeXTllava-hf/llava-v1.6-mistral-7b-hfLFM2.5-VLLiquidAI/LFM2.5-VL-450MIdefics2HuggingFaceM4/idefics2-8b-chattyIdefics3HuggingFaceM4/Idefics3-8B-Llama3Qwen2-VLQwen/Qwen2-VL-2B-InstructQwen2.5-VLQwen/Qwen2.5-VL-3B-InstructQwen3-VLQwen/Qwen3-VL-4B-InstructSmolVLMHuggingFaceTB/SmolVLM-InstructGemma 3google/gemma-3-4b-itGemma 3ngoogle/gemma-3n-E4B-itGemma 4google/gemma-4-E4B-itDiffusionGemmagoogle/diffusiongemma-26B-A4B-itMiniCPM-o 2.6openbmb/MiniCPM-o-2_6Mistral Small 3.1mistralai/Mistral-Small-3.1-24B-Instruct-2503Llama 4 Scoutmeta-llama/Llama-4-Scout-17B-16E-Instruct该示例运行方式cargo run --release --example multimodal_models -p mistralrs运行时只需修改文件顶部的MODEL_ID常量即可切换模型LLaVA 1.5 还需取消注释with_chat_template调用模板文件为 chat_templates/vicuna.json。该示例在输出回答后还会通过dbg!打印avg_prompt_tok_per_sec与avg_compl_tok_per_sec两项吞吐指标方便对比不同量化配置下的推理速度。进阶多轮图文对话multimodal_multiturn仓库还提供了多轮多模态对话示例 mistralrs/examples/models/multimodal_multiturn/main.rs展示了MultimodalMessages的可变用法——每轮把模型回答以Assistant角色追加回消息列表再继续插入新的图片消息let mut messages MultimodalMessages::new().add_message(TextMessageRole::User, Hello!); let resp model .send_chat_request(RequestBuilder::from(messages.clone()).set_sampler_max_len(100)) .await?.choices[0].message.content.clone().unwrap(); messages messages.add_message(TextMessageRole::Assistant, resp); // 下载图片后…… messages messages.add_image_message( TextMessageRole::User, What is depicted here? Please describe the scene in detail., vec![image], );它采用 Qwen3-VL 4B Instruct 模型并用with_isq(mistralrs::IsqType::Q8_0)显式指定 8-bit 量化。运行命令cargo run --release --example multimodal_multiturn -p mistralrs常见问题与运行提示网络与模型下载ModelBuilder::build()会从 Hugging Face 拉取模型权重与配置首次运行务必保证网络可用reqwest下载图片同理若 URL 不可达可将reqwest::blocking::get替换为本地文件读取如std::fs::readimage::load_from_memory。量化选择with_auto_isq(IsqBits::Four)适合快速上手、降低显存占用对精度敏感或显存充足的场景可改用with_isq(IsqType::Q8_0)或直接不量化加载。CPU 运行可添加with_force_cpu()强制 CPU 推理但注意文档明确提示 CPU 模式不要与 PagedAttention 搭配使用见 mistralrs/src/builder_macros.rs。自定义聊天模板部分模型如 LLaVA 1.5需要显式指定模板仓库预置模板位于 chat_templates 目录例如 chat_templates/vicuna.json。多模态代码路径ModelBuilder属于Auto类别构建时通过build_auto_pipelinemistralrs/src/model_builder_trait.rs自动路由到多模态 pipeline 构建逻辑如需强制指定也可直接使用MultimodalModelBuilder。小结通过 multimodal 入门示例 可以看到mistralrs 的 Rust SDK 将加载视觉模型、读取图片、图文提问、获得回答封装成了高度一致的异步 APIModelBuilder负责模型装配与量化MultimodalMessages负责消息与媒体的结构化组织send_chat_request负责推理与 OpenAI 兼容响应的返回而媒体前缀 token 的注入则由 SDK 根据模型类别自动完成。以此为基础你可以轻松扩展到 multimodal_models 中列出的数十种视觉模型或借助RequestBuilder与多轮消息复用构建更复杂的视觉 Agent 应用。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考