MAX Pipelines 的 Idefics3 多模态架构在 MAX Engine 中运行 Idefics3-8B 视觉语言模型【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo导读Idefics3 是 Hugging Face 社区推出的开源视觉语言模型VLM能够同时理解文本与图像输入并生成自然语言输出。本篇文章聚焦 MAX Python 包中max.pipelines.architectures.idefics3模块的实现从模块结构、配置体系、双图vision/language推理流程到 Batch Processor 与 Tokenizer 的输入处理细节逐层拆解该架构在 MAX Engine 中是如何被编译、加载与执行的。读完本文你将掌握 Idefics3 在 MAX Pipelines 中的完整调用链与关键源码位置并能基于仓库中的实际代码理解多模态模型的图构建、权重适配与推理路径。说明max/python/docs/pipelines.architectures.idefics3.rst是 Sphinx autodoc 生成的 API 文档页正文由automodule指令从源码 docstring 自动渲染。本文以该文档对应的源码模块为主体结合仓库实现深入展开。Idefics3 模块在仓库中的位置与文件结构idefics3模块位于max/python/max/pipelines/architectures/idefics3/是一个完整的 VLM 流水线架构包主要文件如下arch.py— 注册SupportedArchitecture元数据将模型接入 MAX Pipelines 的架构调度体系model.py— 定义Idefics3Model负责构建 vision 与 language 两张计算图并执行推理model_config.py— 定义Idefics3Config与Idefics3VisionConfig承载全部模型超参batch_processor.py— 实现 ragged 批处理与图像输入打包tokenizer.py— 基于 transformersAutoTokenizer/AutoProcessor的多模态文本与图像编码text_model/idefics3_text.py— 文本侧语言模型继承 Llama3 结构vision_model/— 视觉编码器SigLIP 风格 ViT及连接器weight_adapters.py— 将 HuggingFace 检查点权重名映射为 MAX 期望的权重名。模块通过__init__.py对外导出Idefics3Config、Idefics3Inputs、Idefics3Model、Idefics3VisionConfig与idefics3_arch见init.py。架构注册idefics3_arch 接入 MAX Pipelines在 arch.py 中idefics3_arch是一个SupportedArchitecture实例用于把 Idefics3 注册进 MAX Pipelines 的模型发现机制idefics3_arch SupportedArchitecture( nameIdefics3ForConditionalGeneration, taskPipelineTask.TEXT_GENERATION, input_modalities{InputModality.TEXT, InputModality.IMAGE}, example_repo_ids[HuggingFaceM4/Idefics3-8B-Llama3], default_encodingIdefics3Config.DEFAULT_ENCODING, supported_encodingsIdefics3Config.SUPPORTED_ENCODINGS, pipeline_modelIdefics3Model, tokenizerIdefics3Tokenizer, context_typeTextAndVisionContext, default_weights_formatWeightsFormat.safetensors, required_arguments{ enable_chunked_prefill: False, enable_prefix_caching: False, }, configIdefics3Config, batchingIdefics3BatchProcessor, memory_plannerPagedMemoryPlanner, supports_overlap_schedulerFalse, supports_device_graph_captureFalse, )要点模型名Idefics3ForConditionalGeneration对应 HuggingFace 仓库中的模型类名仓库自带的示例仓库为HuggingFaceM4/Idefics3-8B-Llama3即 Idefics3-8B文本骨干为 Llama3可以直接按此仓库 ID 加载同时支持文本与图像两种输入模态InputModality.TEXT | IMAGE默认与唯一支持的权重编码为bfloat16见Idefics3Config.DEFAULT_ENCODING/SUPPORTED_ENCODINGS权重格式默认safetensors明确要求关闭enable_chunked_prefill与enable_prefix_caching且不支持 overlap scheduler 与 device graph capture说明该架构在调度能力上有特定约束内存规划使用PagedMemoryPlannerPaged KV Cache 体系。在架构目录索引 architectures/init.py 中Idefics3ForConditionalGeneration通过懒加载映射到.idefics3模块的idefics3_arch由此进入统一的架构注册表。配置体系Idefics3Config 与 Idefics3VisionConfigmodel_config.py 定义了双层配置结构整体配置Idefics3Config继承ArchVLConfigWithTextSubconfig与ArchConfigWithKVCache内嵌文本子配置text_config: Llama3Config与视觉子配置vision_config: Idefics3VisionConfig。视觉配置 Idefics3VisionConfig该 dataclass 描述 SigLIP 风格的视觉编码器超参字段包括hidden_size— 视觉编码器隐藏维度intermediate_size— FFN 中间维度image_size— 输入图像尺寸patch_size— ViT patch 尺寸num_channels— 输入通道数RGB 通常为 3num_attention_heads/head_dim— 注意力头数与每头维度head_dim hidden_size // num_attention_headslayer_norm_eps— LayerNorm 的 epsilon默认 1e-6hidden_act— 激活函数默认gelu_pytorch_tanhnum_hidden_layers— 编码器层数initializer_range— 初始化标准差默认 0.02scale_factor— 连接器中 pixel shuffle 的空间缩放因子默认 2text_config_hidden_size— 文本侧隐藏维度用于模态投影。initialize_from_config从 HuggingFace 的AutoConfig读取vision_config子段并推断dtype由量化编码决定。若 HF 配置中缺失vision_config会抛出ValueError(vision_config not found in huggingface_config)。整体配置 Idefics3Configdevices: list[DeviceRef]— 模型并行所跨设备scale_factor与image_token_id— 多模态关键参数其中image_token_id默认取 HF 配置中的值缺省为 128257图像占位 tokenquantization_encoding— 默认bfloat16image_seq_len属性 — 计算连接器处理后的图像 token 数(image_size // patch_size)^2 // (scale_factor^2)即 patch 总数除以scale_factor²get_kv_params()— 委托给text_config的 KV cache 参数get_num_layers()— 从 HFtext_config.num_hidden_layers取语言模型层数initialize()— 从PipelineConfig构建完整配置分别用Llama3Config.initialize_from_config构造文本子配置、用Idefics3VisionConfig.initialize_from_config构造视觉子配置finalize()— 在拿到权重 state_dict 后回填依赖权重的字段如各层权重 shape对文本子配置调用finalize(..., attention_biasFalse, ...)。注意initialize要求模型路径必须能加载 HFconfig.jsonhuggingface_config不能为None否则报错提示检查模型仓库。双图架构Idefics3Model 的构建与执行model.py 定义了核心的Idefics3Model继承MultiGraphPipelineModelWithKVCache[TextAndVisionContext]其设计核心是视觉图 语言图两张独立计算图vision_model: Model | None— 编译后的视觉模型负责pixel_values - image_embeddingslanguage_model: Model— 编译后的语言模型负责tokens image_embeddings - logits。权重加载与适配_load_state_dict强制要求权重为SafetensorWeights否则抛ValueError(Idefics3 currently only supports safetensors weights)随后分别调用convert_idefics3_language_model_state_dict— 过滤language_model.前缀权重并去掉language_model.model.前缀convert_idefics3_vision_model_state_dict— 处理model.vision_model.与model.connector.前缀。权重名映射表定义在 weight_adapters.pyIDEFICS3_LANGUAGE_MODEL_MAPPING {model.text_model.: } IDEFICS3_VISION_MODEL_MAPPING { model.vision_model.: , model.connector.: connector., }视觉图构建_build_vision_graph使用Graph(idefics3_vision, ...)构建视觉图输入pixel_values_typebfloat16、shape[batch_size, 3, image_size, image_size]显式要求放在 GPUDeviceRef.GPU()图内实例化Idefics3VisionModel并load_state_dict(strictTrue)输出为image_embeddings张量。语言图构建_language_graph_input_types定义语言图输入tokens—int64shape[total_seq_len]input_row_offsets—uint32ragged 序列行偏移return_n_logits—int64返回 logits 个数供投机解码等使用image_embeddings— 模型 dtypeshape[num_image_tokens, text_config.hidden_size]纯文本输入时可为空image_token_indices—int32图像 token 在序列中的位置之后拼接所有kv_params.flattened_kv_inputs()。_build_language_graph实例化Idefics3LanguageModel传入config.text_config与config.image_token_idload_state_dict(override_quantization_encodingTrue, strictTrue)然后执行language_model(tokens, kv_collection, return_n_logits, input_row_offsets, image_embeddings, image_token_indices)并输出 logits。执行流程 execute()execute是推理入口若model_inputs.has_vision_inputspixel_values非空先执行vision_model得到image_embeddings随后调用_assert_image_embeddings_invariant校验图像嵌入数量与图像 token 索引数量一致防止 scatter 越界否则纯文本模式使用batch_processor.empty_image_embeddings()与empty_image_token_indices()生成零长度占位缓冲最后执行language_model把image_embeddings与image_token_indices一并传入输出next_token_logits以及可选的完整logits与logit_offsets。Idefics3Inputs继承ModelInputs字段包括tokens、input_row_offsets、return_n_logits以及可选的pixel_values与image_token_indices通过has_vision_inputs属性区分是否有视觉输入。语言模型组件基于 Llama3 的多模态文本骨干text_model/idefics3_text.py 中的Idefics3LanguageModel直接继承Llama3构造函数接收Llama3Config、image_token_id、dtype与device前向__call__的执行顺序h self.embed_tokens(tokens)得到文本嵌入调用merge_multimodal_embeddings(h, image_embeddings, image_token_indices)来自max.pipelines.lib.vlm_utils把图像嵌入 scatter 到对应 token 位置逐层遍历继承的 Llama3 decoder layers传入freqs_cis、input_row_offsets与kv_collection_postprocess_logits输出最终 logits。这解释了该模型的文本能力为何与 Llama3 一致多模态信息只通过嵌入合并注入之后完全走标准 Llama3 前向。视觉模型组件SigLIP 风格 ViT 连接器vision_model/idefics3_vision.py 中的Idefics3VisionModel组成Idefics3VisionEmbeddingsembeddings.py— patch 嵌入层Idefics3VisionEncoderencoder.py— 堆叠的 Transformer 编码器层内含Idefics3VisionMLP与基于MultiheadAttention的Idefics3VisionAttentionattention.pypost_layernorm— 编码器输出的 LayerNormIdefics3Connectorconnector.py— 模态桥接模块。前向流程pixel_values - embeddings - encoder - post_layernorm - connector最后ops.reshape(hidden_states, (-1, hidden_states.shape[-1]))展平空间维度得到供语言模型使用的图像嵌入序列。源码注释明确指出该视觉模型目前仅限单设备执行。连接器的两大操作Idefics3Connector完成两项关键工作详见 connector.pyPixel shuffle空间折叠把[batch, seq_len, embed_dim]seq_len 为 h×w patch 数通过多次 reshape transpose 变为[batch, seq_len/(scale_factor²), embed_dim×scale_factor²]即图像 token 数缩减为原来的1/scale_factor²同时嵌入维度按比例扩张以保留信息模态投影Idefics3SimpleMLP把视觉嵌入投影到文本隐藏空间text_config_hidden_size。Idefics3Config.image_seq_len属性正是对这一过程的数学抽象(image_size // patch_size)^2 // (scale_factor * scale_factor)。Batch Processorragged 批处理与视觉输入打包batch_processor.py 中的Idefics3BatchProcessor继承BatchProcessor[TextAndVisionContext, Idefics3Inputs]负责把一批多模态请求转成图输入_prepare_vision_inputs— 收集各 context 中next_images的pixel_values经VisionStacker.stack打包再cast_dlpack_to(float32 - bfloat16)转到 device 0_batch_image_token_indices— 扫描各序列中等于image_token_id的位置累加 batch offset 得到展平后的图像 token 全局索引int32prepare_initial_token_inputs— 组装Idefics3Inputstokens拼接所有序列、input_row_offsetsnp.cumsum累加各序列长度、return_n_logits、pixel_values与image_token_indices显式限制DP 1不支持多副本数据并行会抛ValueErrorempty_image_embeddings/empty_image_token_indices— 缓存零长度占位缓冲供纯文本解码使用process_outputs— 委托process_ragged_kv_outputs处理 ragged KV 输出。TokenizerAutoProcessor 驱动的多模态编码tokenizer.py 中的Idefics3Tokenizer继承TextAndVisionTokenizer同时持有AutoTokenizer文本与AutoProcessor多模态负责pixel_values与 chat templateapply_chat_template— 把消息中的ImageContentPart映射为{type: image}、TextContentPart映射为{type: text}代码注释特别说明 Idefics3 微调格式为图在前、文在后User:imagetextend_of_utterance\nAssistant:因此内容按image_parts text_parts排列new_context— 处理流程应用 chat template或直接用 prompt→ 用open_image打开图片并强制转 RGB、校验非零尺寸 →processor(text..., images..., return_tensorsnp)得到input_ids与pixel_values→ 去除return_tensorsnp引入的额外 batch 维ndim 5时squeeze(0)→ 用find_contiguous_ranges定位图像 token 的起止区间并校验区间数与图像数一致 → 构造TextAndVisionContext内含每个图像的ImageMetadata启用前缀缓存时计算image_hash→ 超过max_length时抛PromptTooLongErrordecode— 解码时强制skip_special_tokensTrue过滤end_of_utterance等特殊 tokenmax_tokens_to_generate— 计算可生成的最大新 token 数取max_new_tokens与max_length - prompt_size的较小者。在 MAX Pipelines 中运行 Idefics3基于以上模块使用 MAX Pipelines 部署 Idefics3 的典型入口是max serve/max generate系列命令模型架构按名称自动路由到idefics3_arch。运行前置条件模型权重为safetensors格式当前唯一受支持格式权重编码为bfloat16视觉图输入显式要求 GPU 设备视觉模型仅支持单设备执行且 batch processor 不支持数据并行副本DP 1需要能加载 HFconfig.json含vision_config与text_config子段。多模态服务请求体可直接复用 OpenAI 兼容的 content parts 格式{type: image}/{type: text}例如{ model: HuggingFaceM4/Idefics3-8B-Llama3, messages: [ { role: user, content: [ {type: image, image_url: {url: ...}}, {type: text, text: 描述这张图片的内容} ] } ] }请求进入new_context后由Idefics3Tokenizer完成图像解码与编码再经Idefics3BatchProcessor打包最终由Idefics3Model.execute依次驱动视觉图与语言图完成生成。小结Idefics3 架构在 MAX Pipelines 中的实现呈现出一条清晰的分层链路SupportedArchitecture注册 → 双层配置文本侧复用 Llama3Config、视觉侧独立 VisionConfig→ 双图构建SigLIP 风格 ViT 视觉图 基于 Llama3 的语言图→ 权重适配前缀剥离→ 批处理与 tokenizer 负责的多模态输入编排。其中视觉编码 → pixel shuffle MLP 投影 → 嵌入 scatter 进文本序列 → 标准 Llama3 解码是理解整个架构的关键主线所有代码均可在 architectures/idefics3 目录下找到对应实现是学习 VLM 在 MAX Engine 上落地的极佳参考。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MAX Pipelines 的 Idefics3 多模态架构：在 MAX Engine 中运行 Idefics3-8B 视觉语言模型
MAX Pipelines 的 Idefics3 多模态架构在 MAX Engine 中运行 Idefics3-8B 视觉语言模型【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo导读Idefics3 是 Hugging Face 社区推出的开源视觉语言模型VLM能够同时理解文本与图像输入并生成自然语言输出。本篇文章聚焦 MAX Python 包中max.pipelines.architectures.idefics3模块的实现从模块结构、配置体系、双图vision/language推理流程到 Batch Processor 与 Tokenizer 的输入处理细节逐层拆解该架构在 MAX Engine 中是如何被编译、加载与执行的。读完本文你将掌握 Idefics3 在 MAX Pipelines 中的完整调用链与关键源码位置并能基于仓库中的实际代码理解多模态模型的图构建、权重适配与推理路径。说明max/python/docs/pipelines.architectures.idefics3.rst是 Sphinx autodoc 生成的 API 文档页正文由automodule指令从源码 docstring 自动渲染。本文以该文档对应的源码模块为主体结合仓库实现深入展开。Idefics3 模块在仓库中的位置与文件结构idefics3模块位于max/python/max/pipelines/architectures/idefics3/是一个完整的 VLM 流水线架构包主要文件如下arch.py— 注册SupportedArchitecture元数据将模型接入 MAX Pipelines 的架构调度体系model.py— 定义Idefics3Model负责构建 vision 与 language 两张计算图并执行推理model_config.py— 定义Idefics3Config与Idefics3VisionConfig承载全部模型超参batch_processor.py— 实现 ragged 批处理与图像输入打包tokenizer.py— 基于 transformersAutoTokenizer/AutoProcessor的多模态文本与图像编码text_model/idefics3_text.py— 文本侧语言模型继承 Llama3 结构vision_model/— 视觉编码器SigLIP 风格 ViT及连接器weight_adapters.py— 将 HuggingFace 检查点权重名映射为 MAX 期望的权重名。模块通过__init__.py对外导出Idefics3Config、Idefics3Inputs、Idefics3Model、Idefics3VisionConfig与idefics3_arch见init.py。架构注册idefics3_arch 接入 MAX Pipelines在 arch.py 中idefics3_arch是一个SupportedArchitecture实例用于把 Idefics3 注册进 MAX Pipelines 的模型发现机制idefics3_arch SupportedArchitecture( nameIdefics3ForConditionalGeneration, taskPipelineTask.TEXT_GENERATION, input_modalities{InputModality.TEXT, InputModality.IMAGE}, example_repo_ids[HuggingFaceM4/Idefics3-8B-Llama3], default_encodingIdefics3Config.DEFAULT_ENCODING, supported_encodingsIdefics3Config.SUPPORTED_ENCODINGS, pipeline_modelIdefics3Model, tokenizerIdefics3Tokenizer, context_typeTextAndVisionContext, default_weights_formatWeightsFormat.safetensors, required_arguments{ enable_chunked_prefill: False, enable_prefix_caching: False, }, configIdefics3Config, batchingIdefics3BatchProcessor, memory_plannerPagedMemoryPlanner, supports_overlap_schedulerFalse, supports_device_graph_captureFalse, )要点模型名Idefics3ForConditionalGeneration对应 HuggingFace 仓库中的模型类名仓库自带的示例仓库为HuggingFaceM4/Idefics3-8B-Llama3即 Idefics3-8B文本骨干为 Llama3可以直接按此仓库 ID 加载同时支持文本与图像两种输入模态InputModality.TEXT | IMAGE默认与唯一支持的权重编码为bfloat16见Idefics3Config.DEFAULT_ENCODING/SUPPORTED_ENCODINGS权重格式默认safetensors明确要求关闭enable_chunked_prefill与enable_prefix_caching且不支持 overlap scheduler 与 device graph capture说明该架构在调度能力上有特定约束内存规划使用PagedMemoryPlannerPaged KV Cache 体系。在架构目录索引 architectures/init.py 中Idefics3ForConditionalGeneration通过懒加载映射到.idefics3模块的idefics3_arch由此进入统一的架构注册表。配置体系Idefics3Config 与 Idefics3VisionConfigmodel_config.py 定义了双层配置结构整体配置Idefics3Config继承ArchVLConfigWithTextSubconfig与ArchConfigWithKVCache内嵌文本子配置text_config: Llama3Config与视觉子配置vision_config: Idefics3VisionConfig。视觉配置 Idefics3VisionConfig该 dataclass 描述 SigLIP 风格的视觉编码器超参字段包括hidden_size— 视觉编码器隐藏维度intermediate_size— FFN 中间维度image_size— 输入图像尺寸patch_size— ViT patch 尺寸num_channels— 输入通道数RGB 通常为 3num_attention_heads/head_dim— 注意力头数与每头维度head_dim hidden_size // num_attention_headslayer_norm_eps— LayerNorm 的 epsilon默认 1e-6hidden_act— 激活函数默认gelu_pytorch_tanhnum_hidden_layers— 编码器层数initializer_range— 初始化标准差默认 0.02scale_factor— 连接器中 pixel shuffle 的空间缩放因子默认 2text_config_hidden_size— 文本侧隐藏维度用于模态投影。initialize_from_config从 HuggingFace 的AutoConfig读取vision_config子段并推断dtype由量化编码决定。若 HF 配置中缺失vision_config会抛出ValueError(vision_config not found in huggingface_config)。整体配置 Idefics3Configdevices: list[DeviceRef]— 模型并行所跨设备scale_factor与image_token_id— 多模态关键参数其中image_token_id默认取 HF 配置中的值缺省为 128257图像占位 tokenquantization_encoding— 默认bfloat16image_seq_len属性 — 计算连接器处理后的图像 token 数(image_size // patch_size)^2 // (scale_factor^2)即 patch 总数除以scale_factor²get_kv_params()— 委托给text_config的 KV cache 参数get_num_layers()— 从 HFtext_config.num_hidden_layers取语言模型层数initialize()— 从PipelineConfig构建完整配置分别用Llama3Config.initialize_from_config构造文本子配置、用Idefics3VisionConfig.initialize_from_config构造视觉子配置finalize()— 在拿到权重 state_dict 后回填依赖权重的字段如各层权重 shape对文本子配置调用finalize(..., attention_biasFalse, ...)。注意initialize要求模型路径必须能加载 HFconfig.jsonhuggingface_config不能为None否则报错提示检查模型仓库。双图架构Idefics3Model 的构建与执行model.py 定义了核心的Idefics3Model继承MultiGraphPipelineModelWithKVCache[TextAndVisionContext]其设计核心是视觉图 语言图两张独立计算图vision_model: Model | None— 编译后的视觉模型负责pixel_values - image_embeddingslanguage_model: Model— 编译后的语言模型负责tokens image_embeddings - logits。权重加载与适配_load_state_dict强制要求权重为SafetensorWeights否则抛ValueError(Idefics3 currently only supports safetensors weights)随后分别调用convert_idefics3_language_model_state_dict— 过滤language_model.前缀权重并去掉language_model.model.前缀convert_idefics3_vision_model_state_dict— 处理model.vision_model.与model.connector.前缀。权重名映射表定义在 weight_adapters.pyIDEFICS3_LANGUAGE_MODEL_MAPPING {model.text_model.: } IDEFICS3_VISION_MODEL_MAPPING { model.vision_model.: , model.connector.: connector., }视觉图构建_build_vision_graph使用Graph(idefics3_vision, ...)构建视觉图输入pixel_values_typebfloat16、shape[batch_size, 3, image_size, image_size]显式要求放在 GPUDeviceRef.GPU()图内实例化Idefics3VisionModel并load_state_dict(strictTrue)输出为image_embeddings张量。语言图构建_language_graph_input_types定义语言图输入tokens—int64shape[total_seq_len]input_row_offsets—uint32ragged 序列行偏移return_n_logits—int64返回 logits 个数供投机解码等使用image_embeddings— 模型 dtypeshape[num_image_tokens, text_config.hidden_size]纯文本输入时可为空image_token_indices—int32图像 token 在序列中的位置之后拼接所有kv_params.flattened_kv_inputs()。_build_language_graph实例化Idefics3LanguageModel传入config.text_config与config.image_token_idload_state_dict(override_quantization_encodingTrue, strictTrue)然后执行language_model(tokens, kv_collection, return_n_logits, input_row_offsets, image_embeddings, image_token_indices)并输出 logits。执行流程 execute()execute是推理入口若model_inputs.has_vision_inputspixel_values非空先执行vision_model得到image_embeddings随后调用_assert_image_embeddings_invariant校验图像嵌入数量与图像 token 索引数量一致防止 scatter 越界否则纯文本模式使用batch_processor.empty_image_embeddings()与empty_image_token_indices()生成零长度占位缓冲最后执行language_model把image_embeddings与image_token_indices一并传入输出next_token_logits以及可选的完整logits与logit_offsets。Idefics3Inputs继承ModelInputs字段包括tokens、input_row_offsets、return_n_logits以及可选的pixel_values与image_token_indices通过has_vision_inputs属性区分是否有视觉输入。语言模型组件基于 Llama3 的多模态文本骨干text_model/idefics3_text.py 中的Idefics3LanguageModel直接继承Llama3构造函数接收Llama3Config、image_token_id、dtype与device前向__call__的执行顺序h self.embed_tokens(tokens)得到文本嵌入调用merge_multimodal_embeddings(h, image_embeddings, image_token_indices)来自max.pipelines.lib.vlm_utils把图像嵌入 scatter 到对应 token 位置逐层遍历继承的 Llama3 decoder layers传入freqs_cis、input_row_offsets与kv_collection_postprocess_logits输出最终 logits。这解释了该模型的文本能力为何与 Llama3 一致多模态信息只通过嵌入合并注入之后完全走标准 Llama3 前向。视觉模型组件SigLIP 风格 ViT 连接器vision_model/idefics3_vision.py 中的Idefics3VisionModel组成Idefics3VisionEmbeddingsembeddings.py— patch 嵌入层Idefics3VisionEncoderencoder.py— 堆叠的 Transformer 编码器层内含Idefics3VisionMLP与基于MultiheadAttention的Idefics3VisionAttentionattention.pypost_layernorm— 编码器输出的 LayerNormIdefics3Connectorconnector.py— 模态桥接模块。前向流程pixel_values - embeddings - encoder - post_layernorm - connector最后ops.reshape(hidden_states, (-1, hidden_states.shape[-1]))展平空间维度得到供语言模型使用的图像嵌入序列。源码注释明确指出该视觉模型目前仅限单设备执行。连接器的两大操作Idefics3Connector完成两项关键工作详见 connector.pyPixel shuffle空间折叠把[batch, seq_len, embed_dim]seq_len 为 h×w patch 数通过多次 reshape transpose 变为[batch, seq_len/(scale_factor²), embed_dim×scale_factor²]即图像 token 数缩减为原来的1/scale_factor²同时嵌入维度按比例扩张以保留信息模态投影Idefics3SimpleMLP把视觉嵌入投影到文本隐藏空间text_config_hidden_size。Idefics3Config.image_seq_len属性正是对这一过程的数学抽象(image_size // patch_size)^2 // (scale_factor * scale_factor)。Batch Processorragged 批处理与视觉输入打包batch_processor.py 中的Idefics3BatchProcessor继承BatchProcessor[TextAndVisionContext, Idefics3Inputs]负责把一批多模态请求转成图输入_prepare_vision_inputs— 收集各 context 中next_images的pixel_values经VisionStacker.stack打包再cast_dlpack_to(float32 - bfloat16)转到 device 0_batch_image_token_indices— 扫描各序列中等于image_token_id的位置累加 batch offset 得到展平后的图像 token 全局索引int32prepare_initial_token_inputs— 组装Idefics3Inputstokens拼接所有序列、input_row_offsetsnp.cumsum累加各序列长度、return_n_logits、pixel_values与image_token_indices显式限制DP 1不支持多副本数据并行会抛ValueErrorempty_image_embeddings/empty_image_token_indices— 缓存零长度占位缓冲供纯文本解码使用process_outputs— 委托process_ragged_kv_outputs处理 ragged KV 输出。TokenizerAutoProcessor 驱动的多模态编码tokenizer.py 中的Idefics3Tokenizer继承TextAndVisionTokenizer同时持有AutoTokenizer文本与AutoProcessor多模态负责pixel_values与 chat templateapply_chat_template— 把消息中的ImageContentPart映射为{type: image}、TextContentPart映射为{type: text}代码注释特别说明 Idefics3 微调格式为图在前、文在后User:imagetextend_of_utterance\nAssistant:因此内容按image_parts text_parts排列new_context— 处理流程应用 chat template或直接用 prompt→ 用open_image打开图片并强制转 RGB、校验非零尺寸 →processor(text..., images..., return_tensorsnp)得到input_ids与pixel_values→ 去除return_tensorsnp引入的额外 batch 维ndim 5时squeeze(0)→ 用find_contiguous_ranges定位图像 token 的起止区间并校验区间数与图像数一致 → 构造TextAndVisionContext内含每个图像的ImageMetadata启用前缀缓存时计算image_hash→ 超过max_length时抛PromptTooLongErrordecode— 解码时强制skip_special_tokensTrue过滤end_of_utterance等特殊 tokenmax_tokens_to_generate— 计算可生成的最大新 token 数取max_new_tokens与max_length - prompt_size的较小者。在 MAX Pipelines 中运行 Idefics3基于以上模块使用 MAX Pipelines 部署 Idefics3 的典型入口是max serve/max generate系列命令模型架构按名称自动路由到idefics3_arch。运行前置条件模型权重为safetensors格式当前唯一受支持格式权重编码为bfloat16视觉图输入显式要求 GPU 设备视觉模型仅支持单设备执行且 batch processor 不支持数据并行副本DP 1需要能加载 HFconfig.json含vision_config与text_config子段。多模态服务请求体可直接复用 OpenAI 兼容的 content parts 格式{type: image}/{type: text}例如{ model: HuggingFaceM4/Idefics3-8B-Llama3, messages: [ { role: user, content: [ {type: image, image_url: {url: ...}}, {type: text, text: 描述这张图片的内容} ] } ] }请求进入new_context后由Idefics3Tokenizer完成图像解码与编码再经Idefics3BatchProcessor打包最终由Idefics3Model.execute依次驱动视觉图与语言图完成生成。小结Idefics3 架构在 MAX Pipelines 中的实现呈现出一条清晰的分层链路SupportedArchitecture注册 → 双层配置文本侧复用 Llama3Config、视觉侧独立 VisionConfig→ 双图构建SigLIP 风格 ViT 视觉图 基于 Llama3 的语言图→ 权重适配前缀剥离→ 批处理与 tokenizer 负责的多模态输入编排。其中视觉编码 → pixel shuffle MLP 投影 → 嵌入 scatter 进文本序列 → 标准 Llama3 解码是理解整个架构的关键主线所有代码均可在 architectures/idefics3 目录下找到对应实现是学习 VLM 在 MAX Engine 上落地的极佳参考。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考