mistral.rs Python SDK 实战Phi-4 Multimodal 的「音频 图像」双模态输入推理【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本文基于 mistral.rs 官方 Python 示例文档 examples/python/phi4mm-audio.md 展开完整讲解如何仅用不到 50 行 Python 代码让 Phi-4 Multimodalmicrosoft/Phi-4-multimodal-instruct在同一个请求中同时理解一段音频和一张图像。读完本文你将掌握 mistral.rs Python SDK 的多模态模型加载方式Which.MultimodalPlainMultimodalArchitecture、OpenAI content-part 消息格式中audio_url/image_url的用法以及 mistral.rs 底层将图像编码器与 Conformer 音频编码器投影进词嵌入空间的实现原理。示例定位一条同时「听」与「看」的推理请求该示例的源文件是 examples/python/phi4mm_audio.py文档页标注其为一个可直接运行的 Python SDK 示例Runnable Python SDK example。它的任务场景很具体给定一段鸟鸣录音OGG 文件和一张鸟的照片JPG 图片要求模型「同时引用所听到的与所看到的详细描述正在发生的事情」——这是对多模态融合能力最直接的检验模型不能只复述图像内容还必须真正消费了音频嵌入。Phi-4 Multimodal 是 mistral.rs 中少数同时支持图像与音频两种模态的架构之一。官方多模态输入指南 Send images, audio, and video 明确列出接受audio_urlcontent part 的模型包括 Gemma 4、Gemma 3n、Phi 4 Multimodal、MiniCPM-O 和 Voxtral且 WAV、MP3、FLAC、OGG 四种格式可原生解码其他格式需先用 FFmpeg 转换——示例中特意选用Bird_singing.ogg正是利用了这一点。完整示例代码下面完整继承自示例文档的代码含逐段注释from mistralrs import Runner, Which, ChatCompletionRequest, MultimodalArchitecture # 选择一个同时支持图像与音频两种模态的多模态模型 runner Runner( whichWhich.MultimodalPlain( model_idmicrosoft/Phi-4-multimodal-instruct, archMultimodalArchitecture.Phi4MM, ), ) # 远程媒体资源可替换为你自己的任意资源 IMAGE_URL https://www.allaboutbirds.org/guide/assets/og/528129121-1200px.jpg AUDIO_URL https://upload.wikimedia.org/wikipedia/commons/4/42/Bird_singing.ogg response runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ { role: user, content: [ { # 音频片段 type: audio_url, audio_url: {url: AUDIO_URL}, }, { # 图像 type: image_url, image_url: {url: IMAGE_URL}, }, { type: text, text: Describe in detail what is happening, referencing both what you hear and what you see., }, ], } ], max_tokens256, temperature0.2, top_p0.9, ) ) print(response.choices[0].message.content)代码逐段解析1. 加载模型Which.MultimodalPlain与MultimodalArchitecture.Phi4MMRunner(which...)是 mistral.rs Python SDK 的模型入口。Which枚举区分了纯文本、多模态、LoRA、投机解码等多种加载方式其中Which.MultimodalPlain表示「以非量化方式加载一个多模态模型」对应源文件 mistralrs-pyo3/src/which.rs 中的定义PyO3 绑定同时暴露了MultimodalArchitecture枚举其 Python 类型声明见 mistralrs.pyi。两个关键参数model_idmicrosoft/Phi-4-multimodal-instruct模型仓库标识首次运行会自动下载权重archMultimodalArchitecture.Phi4MM显式指定模型架构。从源码看MultimodalArchitecture枚举包含 Phi3V、Qwen2VL、Gemma3、Llama4、Gemma4、Phi4MM 等二十余种成员mistralrs-pyo3/src/which.rs每个成员都一一映射到 Rust 侧对应的MultimodalLoaderTypemistralrs-pyo3/src/which.rs其中Phi4MM分支负责路由到 Phi-4 Multimodal 的专用加载器与输入处理器。2. 构造请求content-part 消息格式mistral.rs 的多模态消息采用 OpenAI content-part 格式content不再是字符串而是由若干带type字段的部件组成的列表。本示例中一条 user 消息包含三个部件按顺序为音频、图像、文本部件type字段载荷结构说明音频audio_url{audio_url: {url: AUDIO_URL}}远程 OGG 音频请求时经网络拉取图像image_url{image_url: {url: IMAGE_URL}}远程 JPG 图像文本text{text: ...}指令文本URL 有三种合法形式见 Send images, audio, and videofile:///absolute/path本地文件、http(s)://...远程 URL示例即采用此形式、data:mime;base64,...内联 base64。模型按列表顺序「看到」这些部件因此音频在前、图像在后、文本收尾的排列是有意义的。3. 采样参数示例设定max_tokens256限制生成长度、temperature0.2低温度适合「描述事实」类任务减少随机发挥、top_p0.9 nucleus 采样阈值。三者组合属于偏保守的确定性配置符合示例「描述场景」的用途。底层实现Phi4MM 如何同时处理图像与音频示例代码只有 40 多行但引擎侧的多模态融合逻辑值得深入。Phi-4 Multimodal 的核心实现位于 mistralrs-core/src/vision_models/phi4/mod.rs可从以下三个层面理解1. 扩展词嵌入层embed_tokens_extend标准文本模型只有embed_tokens词嵌入表。Phi4MM 额外构建了一个Phi4MMImageAudioEmbedding见Phi4MMModel::new中对embed_tokens_extend前缀的加载mistralrs-core/src/vision_models/phi4/mod.rs它把视觉编码器输出的图像 token 嵌入和 Conformer 音频编码器输出的音频 token 嵌入投影到语言模型的词嵌入空间。模型配置结构Phi4MMConfig中同时携带image_processor/img_processor图像侧配置与audio_processor内含ConformerEncoderConfig即音频走 Conformer 编码器两套字段mistralrs-core/src/vision_models/phi4/config.rs这正是「一个架构、两种模态」的结构来源。2. forward 中的双模态分支与投影模式Phi4MMModel::forward的签名同时接受input_image_embeds/image_attention_mask/image_sizes与input_audio_embeds/audio_embed_sizes/audio_feature_lens/audio_attention_mask两组张量参数mistralrs-core/src/vision_models/phi4/mod.rs。其分派逻辑mistralrs-core/src/vision_models/phi4/mod.rs若请求带packed_layout批量打包 prefill走forward_packed路径否则根据「图像嵌入是否非空 / 音频嵌入是否非空」选择投影模式只要图像侧有数据就用InputMode::Vision纯音频则用InputMode::Speech两者皆无时退化为纯文本的embedding_forward。由于本示例的请求同时包含音频与图像运行时将进入InputMode::Vision分支图像与音频嵌入在同一前向中被投影并与 token 嵌入拼接——这就是模型能够「引用所听与所见」的机制基础。MultimodalModel实现中supports_packed_prefill()与supports_mixed_media_batches()均返回truemistralrs-core/src/vision_models/phi4/mod.rs意味着该架构支持多模态请求的批量合并处理。3. 音频占位符对齐与编码器缓存输入处理器 mistralrs-core/src/vision_models/phi4/inputs_processor.rs 负责把解码后的音频特征喂给 Conformer 编码器并与模板生成的占位符对齐代码中定义了兼容模式\|audio_\d\|的占位符正则COMPATIBLE_AUDIO_SPECIAL_TOKEN_PATTERN并显式校验占位符数量与音频输入数量一致数量不匹配时直接报「more audio placeholders than audio inputs」之类的错误——这是排查多模态请求失败时的首要检查点。处理器还从预处理配置中读取audio_compression_rate、audio_downsample_rate、audio_feat_stride等参数决定音频特征的压缩节奏对应配置结构Phi4MMAudioEmbedConfig中的compression_rate/downsample_rate字段mistralrs-core/src/vision_models/phi4/config.rs。此外模型内部维护一个容量为 32 的EncoderCacheManagermistralrs-core/src/vision_models/phi4/mod.rs对同一会话中重复出现的图像/音频按哈希命中缓存避免视觉/音频编码器重复计算——多轮对话反复引用同一媒体时会有实际收益。运行前提与可扩展方向运行方式安装 Python 包后直接运行示例脚本即可模型权重按model_id自动下载示例媒体为远程 URL需网络可达也可换成file:///本地路径或 base64 data URL。适用前提音频模态仅限支持audio_url的模型Phi 4 Multimodal、Gemma 4、Gemma 3n、MiniCPM-O、Voxtral且 WAV/MP3/FLAC/OGG 之外需先转码每模态的完整支持矩阵见 supported models reference。横向扩展仓库还准备了同一模型的纯图像示例 examples/python/phi4mm.py对应文档 phi4mm.md以及服务端音频示例 examples/server/phi4mm_audio.py、examples/server/responses_audio.py可对照 HTTP 服务形态下的相同请求结构Rust SDK 侧则通过MultimodalMessages的add_image_message/add_audio_message系列方法表达同样的 content-part 结构见 Send images, audio, and video 的 Rust 一节。加载调优MultimodalPlain表示以原生精度加载对显存紧张的部署可在同一Which变体上叠加in_situ_quant如4等量化参数思路与 multimodal-input.mdx 中 Qwen3-VL 的 Python 片段一致。小结该示例的价值不在于代码量而在于它展示了 mistral.rs 多模态推理的完整最小闭环Which.MultimodalPlainMultimodalArchitecture.Phi4MM完成「架构即参数」的模型加载content-part 消息以统一格式承载音频/图像/文本而引擎侧则由扩展词嵌入层把视觉编码器与 Conformer 音频编码器的输出融合进同一条 token 序列并借助占位符对齐校验与编码器缓存保证正确性与效率。以本示例为起点替换model_id、模态部件和量化参数即可迁移到 mistral.rs 支持的其他多模态模型上。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
