mistral.rs Python SDK 实战用 base64 Data URL 向 Phi-3.5 Vision 输入本地图片做视觉推理【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本文基于 mistral.rs 官方 Python SDK 示例 phi3v_base64讲解如何把本地图片编码为 base64 Data URL通过RunnerChatCompletionRequest提交给 Phi-3.5 Vision 多模态模型完成视觉问答并深入到 Python 绑定层源码说明 Data URL 是如何被解析、解码并送入模型输入处理器的帮助读者在无外网访问条件下安全地完成图片理解任务。一、示例总览完整的可运行代码官方示例 examples/python/phi3v_base64.py 的完整代码如下它是 phi3v.py使用远程图片 URL的“本地图片版”变体两者唯一差异在于图片的传入方式from mistralrs import Runner, Which, ChatCompletionRequest, MultimodalArchitecture import base64 runner Runner( whichWhich.MultimodalPlain( model_idmicrosoft/Phi-3.5-vision-instruct, archMultimodalArchitecture.Phi3V, ), ) FILENAME picture.jpg with open(FILENAME, rb) as image_file: encoded_string base64.b64encode(image_file.read()).decode(utf-8) res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ { role: user, content: [ { type: image_url, image_url: { url: fdata:image/png;base64,{encoded_string}, }, }, { 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)整个流程分为四步创建 Runner 并加载多模态模型 → 读取本地图片并 base64 编码 → 组装 OpenAI 风格的多模态消息 → 发送请求并读取响应。下面逐步拆解。二、模型加载Which.MultimodalPlain与MultimodalArchitecture.Phi3VRunner通过which参数描述“加载什么模型、如何加载”。对于多模态明文权重safetensors 原始权重场景SDK 使用Which.MultimodalPlain构造器。从 Python 绑定层源码 mistralrs-pyo3/src/which.rs 可以看到其完整签名约 L561–L596#[pyo3(constructor ( model_id, arch None, tokenizer_json None, topology None, write_uqff None, from_uqff None, dtype ModelDType::Auto, max_edge None, calibration_file None, imatrix None, auto_map_params None, hf_cache_path None, matformer_config_path None, matformer_slice_name None, organization None, encoder_cache_memory_bytes None, ))] MultimodalPlain { ... }示例只用到前两个参数其余均有默认值参数示例取值说明model_idmicrosoft/Phi-3.5-vision-instructHugging Face 模型仓库 id权重缓存于本地 HF 缓存目录archMultimodalArchitecture.Phi3V显式指定架构。源码中MultimodalArchitecture枚举which.rs L110–L136还包含Idefics2、LLaVANext、Qwen2VL、Gemma3、Mistral3、Llama4、Qwen3VL等 20 余种多模态架构dtype默认ModelDType::Auto未指定时自动选择权重精度max_edge默认None限制图像最长边降低显存与 token 数auto_map_params默认None需要跨设备自动放置时传MultimodalAutoMapParams其中max_num_images、max_image_length控制多模态缓存预算arch参数在 Rust 侧会经由impl FromMultimodalArchitecture for MultimodalLoaderTypewhich.rs L138–L166转换为内核加载器类型MultimodalLoaderType::Phi3V最终路由到 Phi-3.5 Vision 的管线实现mistralrs-core/src/pipeline/loaders/multimodal_loaders.rs。三、本地图片转 base64 Data URL示例的核心差异点在于图片获取方式FILENAME picture.jpg with open(FILENAME, rb) as image_file: encoded_string base64.b64encode(image_file.read()).decode(utf-8)base64.b64encode(...)把二进制图片字节编码为 ASCII 字符串.decode(utf-8)转成 Pythonstr随后拼接为标准的 RFC 2397Data URLdata:image/png;base64,payload塞进 OpenAI 兼容的image_url.url字段。这样做的实际价值是请求体完全自包含推理端不需要再去访问外部图片服务器。在网络受限、内网部署或图片涉及隐私不能外发的场景下这是唯一可行的传图方式相比 phi3v.py 中直接写https://...远程 URL 的做法。一个值得注意的细节示例中文件是picture.jpg但 Data URL 前缀写的是data:image/png。从源码看这是可以正常工作的——Python 绑定层最终用imagecrate 按实际字节内容做格式嗅探解码见下一节前缀中的 MIME 仅作为元数据但工程实践中仍应写成真实类型如data:image/jpeg;base64,...以保持语义正确。仓库中另有 examples/python/phi3v_local_img.py 演示直接传本地文件路径的第三种方式可作为对照。四、源码级解析Data URL 在 mistral.rs 中的处理链路请求提交后image_url字段字符串会进入 Python 绑定层的统一图片入口函数parse_image_urlmistralrs-pyo3/src/util.rs。该函数完整支持三种图片来源pub(crate) fn parse_image_url(url_unparsed: str) - PyApiResultDynamicImage { let url if let Ok(url) url::Url::parse(url_unparsed) { url } else if File::open(url_unparsed).is_ok() { // 既不是合法 URL 又能按文件打开当作本地路径 url::Url::from_file_path(std::path::absolute(url_unparsed)?)... } else { ... }; let bytes if url.scheme() http || url.scheme() https { reqwest::blocking::get(url.clone())?.bytes()?.to_vec() } else if url.scheme() file { // 按路径读取本地文件 ... } else if url.scheme() data { // Decode with base64 let data_url data_url::DataUrl::process(url.as_str()).map_err(|e| format!({e}))?; data_url.decode_to_vec().map_err(|e| format!({e}))?.0 } else { return Err(PyApiErr::from(format!(Unsupported URL scheme: {}, url.scheme()))); }; image::load_from_memory(bytes).map_err(|e| PyApiErr::from(format!({e}))) }要点三种来源统一收敛http/https走reqwest下载file或裸路径走本地文件读取data方案走data_urlcrate 的DataUrl::process解析头部元数据再decode_to_vec()完成 base64 还原失败时有明确报错无法解析为 URL、文件不存在时错误信息为Invalid source ...: not a valid URL (http/https/data) and file not found. Use a full URL, a data URL, or a file path that exists.scheme 不支持时返回Unsupported URL scheme——排错时可直接对照解码后交给imagecrate 做内容嗅探image::load_from_memory(bytes)不信任前缀里的 MIME 声明而是根据字节流判断真实图像格式并解码为DynamicImage。这就是上文 PNG 前缀 JPEG 字节混用依然可用的原因同一文件中的parse_audio_urlL255 起是镜像实现说明该 Data URL 机制是全模态输入的统一入口不局限于图片。五、进入模型Phi-3.5 Vision 的输入处理器DynamicImage拿到后会交给 Phi-3.5 专用的输入处理器 mistralrs-core/src/vision_models/phi3/phi3_inputs_processor.rs。其中几个与“图片如何变成 token”直接相关的事实图片 token 数可预测phi3_image_token_countL48–L54先按preprocessor_config.json中的num_crops做 HD 变换再以 336×336 的网格估算每张图的 token 数fn phi3_image_token_count(image: DynamicImage, config: PreProcessorConfig) - usize { let image Phi3InputsProcessor::hd_transform(image, config.num_crops.expect(Need num_crops)); let h image.height() as usize / 336; let w image.width() as usize / 336; (h * w 1) * 144 (h 1) * 12 1 }由此可推断分辨率越高的图片占用的 prompt token 越多max_tokens256只是输出上限输入侧的图像 token 会额外消耗上下文预算图像标签必须升序且不缺号phi3_prompt_tokensL56 起校验对话模板生成的图像标签若数量不匹配会报Phi3 prompt has {} image tags but {} images若编号不从 1 开始连续递增会报Phi3 image ids must appear once in ascending order starting at 1——多条消息多图混排时需要遵守此顺序特征抽取在模型侧完成mistralrs-core/src/vision_models/phi3/mod.rs 中的get_image_featuresL682 起负责把预处理后的像素值送入视觉编码器编码器输出嵌入后被映射到语言模型序列中对应图像占位符的位置。六、采样参数说明示例请求体中的四个采样参数值得逐一说明参数取值作用max_tokens256限制最长输出 token 数图像描述类任务足够temperature0.1接近贪心输出稳定可复现适合“客观描述图片”类任务top_p0.1核采样阈值很低与低温配合进一步收窄候选 tokenpresence_penalty1.0对已出现过的 token 施加惩罚鼓励模型展开不同措辞、减少重复描述响应对象遵循 OpenAI 风格res.choices[0].message.content为模型文本res.usage返回本次请求的 token 用量含图像展开后的 prompt token可用于核算成本与配额。七、落地检查清单运行环境已安装mistralrsPython 包mistralrs-pyo3见 mistralrs-pyo3/pyproject.toml模型可从 Hugging Face 拉取或已放入本地缓存可用hf_cache_path参数指定图片文件需放在当前工作目录示例中FILENAME picture.jpg为相对路径或改写为绝对路径base64 前缀建议与真实图像格式一致image/jpeg、image/png等若图片过大导致 token 预算紧张可在Which.MultimodalPlain中传max_edge限制最长边或传auto_map_paramsMultimodalAutoMapParams(...)调整max_num_images/max_image_length默认值见 which.rs 中的MultimodalAutoMapParams构造器排错顺序先看是Invalid source来源解析失败还是Could not open file文件读取失败再检查 base64 是否被截断。该示例展示了 mistral.rs Python SDK 多模态输入的最小闭环一条 Data URL 字符串即可承载完整图片数据从 util.rs 的解码路径到 phi3_inputs_processor.rs 的图像 token 展开链路清晰且全部可在仓库源码中复核。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
mistral.rs Python SDK 实战用 base64 Data URL 向 Phi-3.5 Vision 输入本地图片做视觉推理【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs本文基于 mistral.rs 官方 Python SDK 示例 phi3v_base64讲解如何把本地图片编码为 base64 Data URL通过RunnerChatCompletionRequest提交给 Phi-3.5 Vision 多模态模型完成视觉问答并深入到 Python 绑定层源码说明 Data URL 是如何被解析、解码并送入模型输入处理器的帮助读者在无外网访问条件下安全地完成图片理解任务。一、示例总览完整的可运行代码官方示例 examples/python/phi3v_base64.py 的完整代码如下它是 phi3v.py使用远程图片 URL的“本地图片版”变体两者唯一差异在于图片的传入方式from mistralrs import Runner, Which, ChatCompletionRequest, MultimodalArchitecture import base64 runner Runner( whichWhich.MultimodalPlain( model_idmicrosoft/Phi-3.5-vision-instruct, archMultimodalArchitecture.Phi3V, ), ) FILENAME picture.jpg with open(FILENAME, rb) as image_file: encoded_string base64.b64encode(image_file.read()).decode(utf-8) res runner.send_chat_completion_request( ChatCompletionRequest( modeldefault, messages[ { role: user, content: [ { type: image_url, image_url: { url: fdata:image/png;base64,{encoded_string}, }, }, { 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)整个流程分为四步创建 Runner 并加载多模态模型 → 读取本地图片并 base64 编码 → 组装 OpenAI 风格的多模态消息 → 发送请求并读取响应。下面逐步拆解。二、模型加载Which.MultimodalPlain与MultimodalArchitecture.Phi3VRunner通过which参数描述“加载什么模型、如何加载”。对于多模态明文权重safetensors 原始权重场景SDK 使用Which.MultimodalPlain构造器。从 Python 绑定层源码 mistralrs-pyo3/src/which.rs 可以看到其完整签名约 L561–L596#[pyo3(constructor ( model_id, arch None, tokenizer_json None, topology None, write_uqff None, from_uqff None, dtype ModelDType::Auto, max_edge None, calibration_file None, imatrix None, auto_map_params None, hf_cache_path None, matformer_config_path None, matformer_slice_name None, organization None, encoder_cache_memory_bytes None, ))] MultimodalPlain { ... }示例只用到前两个参数其余均有默认值参数示例取值说明model_idmicrosoft/Phi-3.5-vision-instructHugging Face 模型仓库 id权重缓存于本地 HF 缓存目录archMultimodalArchitecture.Phi3V显式指定架构。源码中MultimodalArchitecture枚举which.rs L110–L136还包含Idefics2、LLaVANext、Qwen2VL、Gemma3、Mistral3、Llama4、Qwen3VL等 20 余种多模态架构dtype默认ModelDType::Auto未指定时自动选择权重精度max_edge默认None限制图像最长边降低显存与 token 数auto_map_params默认None需要跨设备自动放置时传MultimodalAutoMapParams其中max_num_images、max_image_length控制多模态缓存预算arch参数在 Rust 侧会经由impl FromMultimodalArchitecture for MultimodalLoaderTypewhich.rs L138–L166转换为内核加载器类型MultimodalLoaderType::Phi3V最终路由到 Phi-3.5 Vision 的管线实现mistralrs-core/src/pipeline/loaders/multimodal_loaders.rs。三、本地图片转 base64 Data URL示例的核心差异点在于图片获取方式FILENAME picture.jpg with open(FILENAME, rb) as image_file: encoded_string base64.b64encode(image_file.read()).decode(utf-8)base64.b64encode(...)把二进制图片字节编码为 ASCII 字符串.decode(utf-8)转成 Pythonstr随后拼接为标准的 RFC 2397Data URLdata:image/png;base64,payload塞进 OpenAI 兼容的image_url.url字段。这样做的实际价值是请求体完全自包含推理端不需要再去访问外部图片服务器。在网络受限、内网部署或图片涉及隐私不能外发的场景下这是唯一可行的传图方式相比 phi3v.py 中直接写https://...远程 URL 的做法。一个值得注意的细节示例中文件是picture.jpg但 Data URL 前缀写的是data:image/png。从源码看这是可以正常工作的——Python 绑定层最终用imagecrate 按实际字节内容做格式嗅探解码见下一节前缀中的 MIME 仅作为元数据但工程实践中仍应写成真实类型如data:image/jpeg;base64,...以保持语义正确。仓库中另有 examples/python/phi3v_local_img.py 演示直接传本地文件路径的第三种方式可作为对照。四、源码级解析Data URL 在 mistral.rs 中的处理链路请求提交后image_url字段字符串会进入 Python 绑定层的统一图片入口函数parse_image_urlmistralrs-pyo3/src/util.rs。该函数完整支持三种图片来源pub(crate) fn parse_image_url(url_unparsed: str) - PyApiResultDynamicImage { let url if let Ok(url) url::Url::parse(url_unparsed) { url } else if File::open(url_unparsed).is_ok() { // 既不是合法 URL 又能按文件打开当作本地路径 url::Url::from_file_path(std::path::absolute(url_unparsed)?)... } else { ... }; let bytes if url.scheme() http || url.scheme() https { reqwest::blocking::get(url.clone())?.bytes()?.to_vec() } else if url.scheme() file { // 按路径读取本地文件 ... } else if url.scheme() data { // Decode with base64 let data_url data_url::DataUrl::process(url.as_str()).map_err(|e| format!({e}))?; data_url.decode_to_vec().map_err(|e| format!({e}))?.0 } else { return Err(PyApiErr::from(format!(Unsupported URL scheme: {}, url.scheme()))); }; image::load_from_memory(bytes).map_err(|e| PyApiErr::from(format!({e}))) }要点三种来源统一收敛http/https走reqwest下载file或裸路径走本地文件读取data方案走data_urlcrate 的DataUrl::process解析头部元数据再decode_to_vec()完成 base64 还原失败时有明确报错无法解析为 URL、文件不存在时错误信息为Invalid source ...: not a valid URL (http/https/data) and file not found. Use a full URL, a data URL, or a file path that exists.scheme 不支持时返回Unsupported URL scheme——排错时可直接对照解码后交给imagecrate 做内容嗅探image::load_from_memory(bytes)不信任前缀里的 MIME 声明而是根据字节流判断真实图像格式并解码为DynamicImage。这就是上文 PNG 前缀 JPEG 字节混用依然可用的原因同一文件中的parse_audio_urlL255 起是镜像实现说明该 Data URL 机制是全模态输入的统一入口不局限于图片。五、进入模型Phi-3.5 Vision 的输入处理器DynamicImage拿到后会交给 Phi-3.5 专用的输入处理器 mistralrs-core/src/vision_models/phi3/phi3_inputs_processor.rs。其中几个与“图片如何变成 token”直接相关的事实图片 token 数可预测phi3_image_token_countL48–L54先按preprocessor_config.json中的num_crops做 HD 变换再以 336×336 的网格估算每张图的 token 数fn phi3_image_token_count(image: DynamicImage, config: PreProcessorConfig) - usize { let image Phi3InputsProcessor::hd_transform(image, config.num_crops.expect(Need num_crops)); let h image.height() as usize / 336; let w image.width() as usize / 336; (h * w 1) * 144 (h 1) * 12 1 }由此可推断分辨率越高的图片占用的 prompt token 越多max_tokens256只是输出上限输入侧的图像 token 会额外消耗上下文预算图像标签必须升序且不缺号phi3_prompt_tokensL56 起校验对话模板生成的图像标签若数量不匹配会报Phi3 prompt has {} image tags but {} images若编号不从 1 开始连续递增会报Phi3 image ids must appear once in ascending order starting at 1——多条消息多图混排时需要遵守此顺序特征抽取在模型侧完成mistralrs-core/src/vision_models/phi3/mod.rs 中的get_image_featuresL682 起负责把预处理后的像素值送入视觉编码器编码器输出嵌入后被映射到语言模型序列中对应图像占位符的位置。六、采样参数说明示例请求体中的四个采样参数值得逐一说明参数取值作用max_tokens256限制最长输出 token 数图像描述类任务足够temperature0.1接近贪心输出稳定可复现适合“客观描述图片”类任务top_p0.1核采样阈值很低与低温配合进一步收窄候选 tokenpresence_penalty1.0对已出现过的 token 施加惩罚鼓励模型展开不同措辞、减少重复描述响应对象遵循 OpenAI 风格res.choices[0].message.content为模型文本res.usage返回本次请求的 token 用量含图像展开后的 prompt token可用于核算成本与配额。七、落地检查清单运行环境已安装mistralrsPython 包mistralrs-pyo3见 mistralrs-pyo3/pyproject.toml模型可从 Hugging Face 拉取或已放入本地缓存可用hf_cache_path参数指定图片文件需放在当前工作目录示例中FILENAME picture.jpg为相对路径或改写为绝对路径base64 前缀建议与真实图像格式一致image/jpeg、image/png等若图片过大导致 token 预算紧张可在Which.MultimodalPlain中传max_edge限制最长边或传auto_map_paramsMultimodalAutoMapParams(...)调整max_num_images/max_image_length默认值见 which.rs 中的MultimodalAutoMapParams构造器排错顺序先看是Invalid source来源解析失败还是Could not open file文件读取失败再检查 base64 是否被截断。该示例展示了 mistral.rs Python SDK 多模态输入的最小闭环一条 Data URL 字符串即可承载完整图片数据从 util.rs 的解码路径到 phi3_inputs_processor.rs 的图像 token 展开链路清晰且全部可在仓库源码中复核。【免费下载链接】mistral.rsFast, flexible LLM inference项目地址: https://gitcode.com/GitHub_Trending/mi/mistral.rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
