尧图网站建设 
MAX 模型架构注册体系全解解读 max.pipelines.architectures 与 SupportedArchitecture【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojoMAXModular Platform的 pipeline 系统内置了对大量主流模型架构的原生支持这些支持全部由max.pipelines.architectures模块统一承载。本篇指南以 max/python/docs/pipelines.architectures.rst 为骨架结合仓库源码arch_lookup.py、registry.py、architectures/init.py深入讲解架构注册表的内部机制、面向不同任务的架构分类全景以及如何在此基础上扩展自定义模型架构帮助你掌握 MAX pipeline 从识别模型到构建执行管线的完整路径。一、架构模块在整个 pipeline 体系中的位置在 MAX 的 Python 侧max.pipelines提供了从模型加载、配置解析、内存规划到推理执行的一整套端到端管线。其中max/pipelines/architectures/目录存放了全部内置模型架构每个架构模块都会注册一个SupportedArchitecture实例对应文档中所述 Each architecture module registers a SupportedArchitecture instance它向 pipeline 系统声明如何加载、配置并执行某一类特定模型家族how to load, configure, and execute a particular model family架构目录的说明见 max/python/max/pipelines/architectures/README.md每个架构定义了 MAX 如何从 Hugging Face 检查点重建为性能优化的 MAX 计算图reconstruct models from Hugging Face as performance-optimized MAX graphs。该模块的 Python 包入口 max/python/max/pipelines/architectures/init.py 暴露了register_all_models()函数它会在导入max.pipelines时被自动调用把全部内置架构以惰性注册lazy registration方式登记进全局注册表PIPELINE_REGISTRY。二、核心数据结构SupportedArchitectureSupportedArchitecture是架构注册的基本单元定义在 max/python/max/pipelines/lib/arch_lookup.py#L75-L459。它通过 dataclass 聚合了一个模型家族运行所需的全部组件与配置主要字段如下字段类型含义namestr架构名称必须与 Hugging Face 模型类名一致如LlamaForCausalLM、FluxPipeline是查找的主键example_repo_idslist[str]用于测试验证的 Hugging Face 仓库 ID 列表default_encodingSupportedEncoding未显式指定量化编码时的默认编码如q4_k、bfloat16supported_encodingsset[SupportedEncoding]该架构支持的量化编码集合pipeline_modelPipelineModelType定义计算图结构与执行逻辑的模型类既可以是PipelineModel子类LLM 等 token 生成架构也可以是PipelineExecutor子类扩散等新一代 executor 架构taskPipelineTask该架构所属的 pipeline 任务类型文本生成 / Embeddings / 图像生成 / 音频生成等tokenizercallable返回PipelineTokenizer实例、用于预处理输入的可调用对象default_weights_formatWeightsFormat权重格式如safetensors、ggufcontext_typetype管理请求状态与输入的上下文类TextContext、EmbeddingsContext、PixelContext、AudioContext之一configtype[ArchConfig]架构专属配置类需实现ArchConfig协议带 KV Cache 的模型应实现ArchConfigWithKVCache以支持内存估算weight_adaptersdict[WeightsFormat, WeightsAdapter]将不同格式检查点转换到默认格式的权重适配器multi_gpu_supportedbool是否支持多 GPU 执行input_modalitiesset[InputModality]接受的输入模态默认纯文本多模态架构需显式声明如{TEXT, IMAGE}required_argumentsdict对PipelineConfig选项的必填值约束context_validatorslist[Callable]在上下文创建期校验输入如该模型只支持 1 张图片尽早报错以免浪费昂贵的模型计算batchingtype | None批量处理器类如Llama3BatchProcessor注册时绑定到pipeline_modelmemory_plannertype[MemoryPlanner] | None自回归模型应设置为PagedMemoryPlanner或其子类用于估算权重、激活与 signal buffer 内存reasoning_parserstr | None默认推理内容解析器如 Kimi K2.5 的think.../think格式tool_parserstr | Callable | None默认工具调用解析器可用 callable 形式按检查点版本区分如 DeepSeek V3 vs V3.1supports_overlap_scheduler/supports_device_graph_capturebool是否支持自动启用 overlap 调度器 / 设备图捕获pipeline_clstype | None覆盖任务默认 pipeline 的自定义 pipeline 类如 block-diffusion 文本生成arch_lookup.py的 docstring 中给出了一个完整的自定义注册示例从max.graph.weights引入WeightsFormat从max.pipelines.context引入TextContext从max.pipelines.lib.registry引入SupportedArchitecture然后声明pipeline_model、tokenizer、config等字段完成实例化——这是理解整个架构体系最直接的起点。三、注册机制惰性导入与全局注册表1. 全局注册表 PipelineRegistry所有架构统一由 registry.py 中的PipelineRegistry管理。文档指出每个架构模块注册一个 SupportedArchitecture 实例而PipelineRegistry就是存放这些实例的地方不要直接实例化PipelineRegistry应使用全局单例PIPELINE_REGISTRY导入max.pipelines时它会被自动填充所有内置架构register()注册新架构或Speculator投机解码变体retrieve_architecture()按名称查询架构如LlamaForCausalLM或FluxPipelineprefer_module_v3True时自动追加_ModuleV3后缀查找新一代 Module API 变体all_architectures()返回全部已注册架构会强制导入所有惰性架构仅适用于真正需要完整列表的场景如列出支持模型retrieve_factory()核心入口返回 tokenizer、pipeline 工厂函数与内存规划RetrievedPipeline三元组get_active_huggingface_config()/get_active_tokenizer()带缓存的 HF 配置与分词器获取避免重复发起 Hub 调用。2. 惰性注册不导入模型代码即可注册register_all_models()architectures/init.py#L49-L452并不会真正导入每个架构模块而是通过PIPELINE_REGISTRY.register_lazy(name, module, symbol, package, speculates_on)记录如何导入架构模块在首次被查询时才通过importlib导入对应ArchLookup.materialize见 arch_lookup.py#L711-L736好处是导入max.pipelines不再把每个架构的模型代码全部拉进内存显著降低启动开销该函数通过模块级标志_MODELS_ALREADY_REGISTERED保证幂等重复调用安全注册表同时支持可选私有扩展包如kimi_k3、qwen4_exp、minimax_m3等的try/except ModuleNotFoundError动态挂载。ArchLookuparch_lookup.py#L556-L873是注册表的底层实现维护了四张表architectures按名称索引的主表_architectures_by_task同名的多任务架构以(name, task)键消歧例如Qwen3ForCausalLM同时服务文本生成与 Embeddings 任务_lazy_architectures/_lazy_speculators惰性注册的导入描述_speculators投机解码器索引按目标架构分组。3. 同名多任务消歧当多个架构共享同一名称但任务不同时它们会被存入(name, task)次级查找表ArchLookup.register。运行时通过task参数选择正确实例——这正是文档中Text generation / Embeddings / Image generation / Audio generation四大分类在注册表层面的落点。例如 architectures/init.py#L291-L298 中Qwen3ForCausalLM既被注册为.qwen3的文本生成架构又被注册为.qwen3_embedding的 Embeddings 架构。四、架构全景按任务分类的内置支持文档将全部内置架构按任务分为四类。以下结合 architectures/init.py 的注册表和 Bazel 清单 all_arches.bzl 整理所列均为仓库中实际存在的架构目录1. 文本生成Text generation覆盖最广的一类包括 LLM 及其投机解码变体主流 LLMDeepSeekDeepseekV2ForCausalLM、DeepseekV3ForCausalLM、DeepseekV3_2、LlamaLlamaForCausalLM、Llama4ForCausalLM、QwenQwen2ForCausalLM、Qwen3ForCausalLM、Qwen3MoeForCausalLM、Qwen3_5、GemmaGemma3ForCausalLM、Gemma3ForConditionalGeneration、Gemma4ForConditionalGeneration、Gemma4AssistantForCausalLM、MistralMistralForCausalLM、Mistral3ForConditionalGeneration、以及 Phi-3、Granite、GLMGlmMoeDsaForCausalLM、GPT-OSS、Olmo1/2/3、Mamba、MiniMax-M2、Nemotron-H、HY-V3、Laguna、LFM2、Inkling、Step3p5、Kimi K2.5 等多模态生成Pixtral、Idefics3、InternVL、Qwen2.5-VL、Qwen3-VL、KimiVL、dflash2_qwen3_5 等投机解码Speculative decodingDFlashdflash_llama3、dflash2_qwen3_5、DSparkdspark_draft、EAGLEeagle_llama3、eagle3_deepseekV3、eagle3_deepseekV2、以及大量 fused 统一架构unified_dflash_*、unified_dspark_*、unified_eagle_*、unified_mtp_*。其中_ModuleV3后缀表示基于新一代 Module API 的实现变体块扩散文本生成DiffusionGemmaForBlockDiffusion其pipeline_cls字段正是文档中架构可声明自定义 pipeline 类机制的实例。2. EmbeddingsBertModelbert、MPNetForMaskedLMmpnet含_ModuleV3变体、Qwen3ForCausalLMqwen3_embedding。3. 图像生成Image generationFlux2Pipeline/Flux2KleinPipeline、Ideogram4Pipeline、QwenImagePipeline、QwenImageEditPipeline/QwenImageEditPlusPipeline、WanPipeline/WanImageToVideoPipeline、ZImagePipelinez_image_modulev3。4. 音频生成Audio generationMiniMaxMusic3ModularPipelineminimax_music3。此外目录中还有autoencoders、clip、t5、umt5、whisper等组件目录作为上述架构的共享子模块存在。五、典型架构实例以 Llama3 为例以 max/python/max/pipelines/architectures/llama3/arch.py#L28-L55 为范本看一个真实架构的注册代码llama_arch SupportedArchitecture( nameLlamaForCausalLM, example_repo_ids[ meta-llama/Llama-3.1-8B-Instruct, deepseek-ai/DeepSeek-R1-Distill-Llama-8B, meta-llama/Llama-Guard-3-8B, meta-llama/Llama-3.2-1B-Instruct, meta-llama/Llama-3.2-3B-Instruct, deepseek-ai/deepseek-coder-6.7b-instruct, modularai/Llama-3.1-8B-Instruct-GGUF, ], default_encodingLlama3Config.DEFAULT_ENCODING, supported_encodingsLlama3Config.SUPPORTED_ENCODINGS, pipeline_modelLlama3Model, tokenizerTextTokenizer, context_typeTextContext, default_weights_formatWeightsFormat.safetensors, multi_gpu_supportedTrue, weight_adapters{ WeightsFormat.safetensors: weight_adapters.convert_safetensor_state_dict, WeightsFormat.gguf: weight_adapters.convert_gguf_state_dict, }, taskPipelineTask.TEXT_GENERATION, configLlama3Config, batchingLlama3BatchProcessor, memory_plannerPagedMemoryPlanner, cascade_pipeline_factoryCommonTextGenPipeline, )可从中读出的关键信息nameLlamaForCausalLM与 HF 类名严格一致这是自动识别模型仓库的依据同时支持 safetensors 与 GGUF 两种权重格式通过weight_adapters适配memory_plannerPagedMemoryPlanner说明该架构走分页 KV Cache 内存规划cascade_pipeline_factory为该架构挂接了级联cascade推理路径同目录下还包含batch_processor.py批量处理、model.py/model_config.py模型与配置、weight_adapters.py权重转换等配套模块完整体现了一个架构 一个包的组织方式。六、运行时消费链路从配置到 pipeline 工厂架构注册之后如何被消费核心链路在 registry.py#L688-L978 的retrieve_factory()架构解析先导入用户通过--custom-architectures指定的自定义架构再根据配置中的主模型名调用architecture_for_config()解析出实际架构若配置了投机解码还会通过select_speculator()选出 fused 架构见 arch_lookup.py#L908-L945草稿模型解析投机解码场景下预解析 draft 模型架构用于内存规划若 draft 只有_ModuleV3实现会提示使用--prefer-module-v3标志内存规划基于架构的memory_planner与MemoryEstimator.plan()计算MemoryPlanbatch size、序列长度、缓存预算pipeline 类选择get_pipeline_for_task()按任务返回默认 pipelineTextGenerationPipeline/EmbeddingsPipeline/PixelGenerationPipeline/AudioGenerationPipeline架构若声明了pipeline_cls则优先采用Tokenizer 构建使用架构声明的tokenizer类构建分词器应用max_length、chat_template、trust_remote_code等参数图像/音频生成会从tokenizer子目录加载专属分词器如 Flux2 固定max_length512上下文校验与思考区将架构声明的context_validators包装进 tokenizer 的new_context_apply_context_validators并在配置了 reasoning parser 且启用约束解码时配置 thinking region_apply_thinking_region返回工厂最终返回RetrievedPipeline(tokenizer, factory, memory_plan)供上层 serving 层调用构建 pipeline 实例。整个过程印证了文档的表述SupportedArchitecture实例告诉 pipeline 系统如何加载、配置并执行特定模型家族。七、扩展自定义架构仓库在 max/docs/contributing-models.md 中提供了完整的自定义模型贡献指南架构目录 README 也引用了该文档。结合源码自定义架构有两种接入路径内置式参照llama3/的组织方式在architectures/下新建架构包通过SupportedArchitecture(...)声明架构再在register_all_models()的注册表中追加_LazyArch条目外部挂载通过--custom-architectures参数指定模块路径module_path或directory:module_name模块需暴露一个包含SupportedArchitecture或Speculator实例的ARCHITECTURES列表由ArchLookup.import_custom_architectures()arch_lookup.py#L753-L795幂等导入注册。Python API 层面则直接调用PIPELINE_REGISTRY.register(arch)。值得注意的是register()对同名同任务的重复注册默认会抛出ValueError拒绝覆盖可通过allow_overrideTrue显式放行——这保证了注册表的确定性。八、进一步查阅指引架构模块索引文档max/python/docs/pipelines.architectures.rst架构注册表源码max/python/max/pipelines/lib/registry.py架构查找与SupportedArchitecture定义max/python/max/pipelines/lib/arch_lookup.py内置架构惰性注册表max/python/max/pipelines/architectures/init.py架构目录与 Bazel 清单max/python/max/pipelines/architectures/ 及 all_arches.bzl自定义模型架构指南max/docs/contributing-models.md。综上所述max.pipelines.architectures是 MAX pipeline 系统的模型能力目录它以SupportedArchitecture为统一契约用惰性注册机制把近百个模型家族的组织方式模型类、分词器、量化编码、权重格式、批量处理、内存规划、投机解码等声明式地登记在全局注册表中再经由PIPELINE_REGISTRY.retrieve_factory()在运行时按需解析、规划并构建出可执行的 pipeline——理解这套机制是使用 MAX 部署模型、以及向 MAX 贡献新模型的第一步。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MAX 模型架构注册体系全解：解读 max.pipelines.architectures 与 SupportedArchitecture
MAX 模型架构注册体系全解解读 max.pipelines.architectures 与 SupportedArchitecture【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojoMAXModular Platform的 pipeline 系统内置了对大量主流模型架构的原生支持这些支持全部由max.pipelines.architectures模块统一承载。本篇指南以 max/python/docs/pipelines.architectures.rst 为骨架结合仓库源码arch_lookup.py、registry.py、architectures/init.py深入讲解架构注册表的内部机制、面向不同任务的架构分类全景以及如何在此基础上扩展自定义模型架构帮助你掌握 MAX pipeline 从识别模型到构建执行管线的完整路径。一、架构模块在整个 pipeline 体系中的位置在 MAX 的 Python 侧max.pipelines提供了从模型加载、配置解析、内存规划到推理执行的一整套端到端管线。其中max/pipelines/architectures/目录存放了全部内置模型架构每个架构模块都会注册一个SupportedArchitecture实例对应文档中所述 Each architecture module registers a SupportedArchitecture instance它向 pipeline 系统声明如何加载、配置并执行某一类特定模型家族how to load, configure, and execute a particular model family架构目录的说明见 max/python/max/pipelines/architectures/README.md每个架构定义了 MAX 如何从 Hugging Face 检查点重建为性能优化的 MAX 计算图reconstruct models from Hugging Face as performance-optimized MAX graphs。该模块的 Python 包入口 max/python/max/pipelines/architectures/init.py 暴露了register_all_models()函数它会在导入max.pipelines时被自动调用把全部内置架构以惰性注册lazy registration方式登记进全局注册表PIPELINE_REGISTRY。二、核心数据结构SupportedArchitectureSupportedArchitecture是架构注册的基本单元定义在 max/python/max/pipelines/lib/arch_lookup.py#L75-L459。它通过 dataclass 聚合了一个模型家族运行所需的全部组件与配置主要字段如下字段类型含义namestr架构名称必须与 Hugging Face 模型类名一致如LlamaForCausalLM、FluxPipeline是查找的主键example_repo_idslist[str]用于测试验证的 Hugging Face 仓库 ID 列表default_encodingSupportedEncoding未显式指定量化编码时的默认编码如q4_k、bfloat16supported_encodingsset[SupportedEncoding]该架构支持的量化编码集合pipeline_modelPipelineModelType定义计算图结构与执行逻辑的模型类既可以是PipelineModel子类LLM 等 token 生成架构也可以是PipelineExecutor子类扩散等新一代 executor 架构taskPipelineTask该架构所属的 pipeline 任务类型文本生成 / Embeddings / 图像生成 / 音频生成等tokenizercallable返回PipelineTokenizer实例、用于预处理输入的可调用对象default_weights_formatWeightsFormat权重格式如safetensors、ggufcontext_typetype管理请求状态与输入的上下文类TextContext、EmbeddingsContext、PixelContext、AudioContext之一configtype[ArchConfig]架构专属配置类需实现ArchConfig协议带 KV Cache 的模型应实现ArchConfigWithKVCache以支持内存估算weight_adaptersdict[WeightsFormat, WeightsAdapter]将不同格式检查点转换到默认格式的权重适配器multi_gpu_supportedbool是否支持多 GPU 执行input_modalitiesset[InputModality]接受的输入模态默认纯文本多模态架构需显式声明如{TEXT, IMAGE}required_argumentsdict对PipelineConfig选项的必填值约束context_validatorslist[Callable]在上下文创建期校验输入如该模型只支持 1 张图片尽早报错以免浪费昂贵的模型计算batchingtype | None批量处理器类如Llama3BatchProcessor注册时绑定到pipeline_modelmemory_plannertype[MemoryPlanner] | None自回归模型应设置为PagedMemoryPlanner或其子类用于估算权重、激活与 signal buffer 内存reasoning_parserstr | None默认推理内容解析器如 Kimi K2.5 的think.../think格式tool_parserstr | Callable | None默认工具调用解析器可用 callable 形式按检查点版本区分如 DeepSeek V3 vs V3.1supports_overlap_scheduler/supports_device_graph_capturebool是否支持自动启用 overlap 调度器 / 设备图捕获pipeline_clstype | None覆盖任务默认 pipeline 的自定义 pipeline 类如 block-diffusion 文本生成arch_lookup.py的 docstring 中给出了一个完整的自定义注册示例从max.graph.weights引入WeightsFormat从max.pipelines.context引入TextContext从max.pipelines.lib.registry引入SupportedArchitecture然后声明pipeline_model、tokenizer、config等字段完成实例化——这是理解整个架构体系最直接的起点。三、注册机制惰性导入与全局注册表1. 全局注册表 PipelineRegistry所有架构统一由 registry.py 中的PipelineRegistry管理。文档指出每个架构模块注册一个 SupportedArchitecture 实例而PipelineRegistry就是存放这些实例的地方不要直接实例化PipelineRegistry应使用全局单例PIPELINE_REGISTRY导入max.pipelines时它会被自动填充所有内置架构register()注册新架构或Speculator投机解码变体retrieve_architecture()按名称查询架构如LlamaForCausalLM或FluxPipelineprefer_module_v3True时自动追加_ModuleV3后缀查找新一代 Module API 变体all_architectures()返回全部已注册架构会强制导入所有惰性架构仅适用于真正需要完整列表的场景如列出支持模型retrieve_factory()核心入口返回 tokenizer、pipeline 工厂函数与内存规划RetrievedPipeline三元组get_active_huggingface_config()/get_active_tokenizer()带缓存的 HF 配置与分词器获取避免重复发起 Hub 调用。2. 惰性注册不导入模型代码即可注册register_all_models()architectures/init.py#L49-L452并不会真正导入每个架构模块而是通过PIPELINE_REGISTRY.register_lazy(name, module, symbol, package, speculates_on)记录如何导入架构模块在首次被查询时才通过importlib导入对应ArchLookup.materialize见 arch_lookup.py#L711-L736好处是导入max.pipelines不再把每个架构的模型代码全部拉进内存显著降低启动开销该函数通过模块级标志_MODELS_ALREADY_REGISTERED保证幂等重复调用安全注册表同时支持可选私有扩展包如kimi_k3、qwen4_exp、minimax_m3等的try/except ModuleNotFoundError动态挂载。ArchLookuparch_lookup.py#L556-L873是注册表的底层实现维护了四张表architectures按名称索引的主表_architectures_by_task同名的多任务架构以(name, task)键消歧例如Qwen3ForCausalLM同时服务文本生成与 Embeddings 任务_lazy_architectures/_lazy_speculators惰性注册的导入描述_speculators投机解码器索引按目标架构分组。3. 同名多任务消歧当多个架构共享同一名称但任务不同时它们会被存入(name, task)次级查找表ArchLookup.register。运行时通过task参数选择正确实例——这正是文档中Text generation / Embeddings / Image generation / Audio generation四大分类在注册表层面的落点。例如 architectures/init.py#L291-L298 中Qwen3ForCausalLM既被注册为.qwen3的文本生成架构又被注册为.qwen3_embedding的 Embeddings 架构。四、架构全景按任务分类的内置支持文档将全部内置架构按任务分为四类。以下结合 architectures/init.py 的注册表和 Bazel 清单 all_arches.bzl 整理所列均为仓库中实际存在的架构目录1. 文本生成Text generation覆盖最广的一类包括 LLM 及其投机解码变体主流 LLMDeepSeekDeepseekV2ForCausalLM、DeepseekV3ForCausalLM、DeepseekV3_2、LlamaLlamaForCausalLM、Llama4ForCausalLM、QwenQwen2ForCausalLM、Qwen3ForCausalLM、Qwen3MoeForCausalLM、Qwen3_5、GemmaGemma3ForCausalLM、Gemma3ForConditionalGeneration、Gemma4ForConditionalGeneration、Gemma4AssistantForCausalLM、MistralMistralForCausalLM、Mistral3ForConditionalGeneration、以及 Phi-3、Granite、GLMGlmMoeDsaForCausalLM、GPT-OSS、Olmo1/2/3、Mamba、MiniMax-M2、Nemotron-H、HY-V3、Laguna、LFM2、Inkling、Step3p5、Kimi K2.5 等多模态生成Pixtral、Idefics3、InternVL、Qwen2.5-VL、Qwen3-VL、KimiVL、dflash2_qwen3_5 等投机解码Speculative decodingDFlashdflash_llama3、dflash2_qwen3_5、DSparkdspark_draft、EAGLEeagle_llama3、eagle3_deepseekV3、eagle3_deepseekV2、以及大量 fused 统一架构unified_dflash_*、unified_dspark_*、unified_eagle_*、unified_mtp_*。其中_ModuleV3后缀表示基于新一代 Module API 的实现变体块扩散文本生成DiffusionGemmaForBlockDiffusion其pipeline_cls字段正是文档中架构可声明自定义 pipeline 类机制的实例。2. EmbeddingsBertModelbert、MPNetForMaskedLMmpnet含_ModuleV3变体、Qwen3ForCausalLMqwen3_embedding。3. 图像生成Image generationFlux2Pipeline/Flux2KleinPipeline、Ideogram4Pipeline、QwenImagePipeline、QwenImageEditPipeline/QwenImageEditPlusPipeline、WanPipeline/WanImageToVideoPipeline、ZImagePipelinez_image_modulev3。4. 音频生成Audio generationMiniMaxMusic3ModularPipelineminimax_music3。此外目录中还有autoencoders、clip、t5、umt5、whisper等组件目录作为上述架构的共享子模块存在。五、典型架构实例以 Llama3 为例以 max/python/max/pipelines/architectures/llama3/arch.py#L28-L55 为范本看一个真实架构的注册代码llama_arch SupportedArchitecture( nameLlamaForCausalLM, example_repo_ids[ meta-llama/Llama-3.1-8B-Instruct, deepseek-ai/DeepSeek-R1-Distill-Llama-8B, meta-llama/Llama-Guard-3-8B, meta-llama/Llama-3.2-1B-Instruct, meta-llama/Llama-3.2-3B-Instruct, deepseek-ai/deepseek-coder-6.7b-instruct, modularai/Llama-3.1-8B-Instruct-GGUF, ], default_encodingLlama3Config.DEFAULT_ENCODING, supported_encodingsLlama3Config.SUPPORTED_ENCODINGS, pipeline_modelLlama3Model, tokenizerTextTokenizer, context_typeTextContext, default_weights_formatWeightsFormat.safetensors, multi_gpu_supportedTrue, weight_adapters{ WeightsFormat.safetensors: weight_adapters.convert_safetensor_state_dict, WeightsFormat.gguf: weight_adapters.convert_gguf_state_dict, }, taskPipelineTask.TEXT_GENERATION, configLlama3Config, batchingLlama3BatchProcessor, memory_plannerPagedMemoryPlanner, cascade_pipeline_factoryCommonTextGenPipeline, )可从中读出的关键信息nameLlamaForCausalLM与 HF 类名严格一致这是自动识别模型仓库的依据同时支持 safetensors 与 GGUF 两种权重格式通过weight_adapters适配memory_plannerPagedMemoryPlanner说明该架构走分页 KV Cache 内存规划cascade_pipeline_factory为该架构挂接了级联cascade推理路径同目录下还包含batch_processor.py批量处理、model.py/model_config.py模型与配置、weight_adapters.py权重转换等配套模块完整体现了一个架构 一个包的组织方式。六、运行时消费链路从配置到 pipeline 工厂架构注册之后如何被消费核心链路在 registry.py#L688-L978 的retrieve_factory()架构解析先导入用户通过--custom-architectures指定的自定义架构再根据配置中的主模型名调用architecture_for_config()解析出实际架构若配置了投机解码还会通过select_speculator()选出 fused 架构见 arch_lookup.py#L908-L945草稿模型解析投机解码场景下预解析 draft 模型架构用于内存规划若 draft 只有_ModuleV3实现会提示使用--prefer-module-v3标志内存规划基于架构的memory_planner与MemoryEstimator.plan()计算MemoryPlanbatch size、序列长度、缓存预算pipeline 类选择get_pipeline_for_task()按任务返回默认 pipelineTextGenerationPipeline/EmbeddingsPipeline/PixelGenerationPipeline/AudioGenerationPipeline架构若声明了pipeline_cls则优先采用Tokenizer 构建使用架构声明的tokenizer类构建分词器应用max_length、chat_template、trust_remote_code等参数图像/音频生成会从tokenizer子目录加载专属分词器如 Flux2 固定max_length512上下文校验与思考区将架构声明的context_validators包装进 tokenizer 的new_context_apply_context_validators并在配置了 reasoning parser 且启用约束解码时配置 thinking region_apply_thinking_region返回工厂最终返回RetrievedPipeline(tokenizer, factory, memory_plan)供上层 serving 层调用构建 pipeline 实例。整个过程印证了文档的表述SupportedArchitecture实例告诉 pipeline 系统如何加载、配置并执行特定模型家族。七、扩展自定义架构仓库在 max/docs/contributing-models.md 中提供了完整的自定义模型贡献指南架构目录 README 也引用了该文档。结合源码自定义架构有两种接入路径内置式参照llama3/的组织方式在architectures/下新建架构包通过SupportedArchitecture(...)声明架构再在register_all_models()的注册表中追加_LazyArch条目外部挂载通过--custom-architectures参数指定模块路径module_path或directory:module_name模块需暴露一个包含SupportedArchitecture或Speculator实例的ARCHITECTURES列表由ArchLookup.import_custom_architectures()arch_lookup.py#L753-L795幂等导入注册。Python API 层面则直接调用PIPELINE_REGISTRY.register(arch)。值得注意的是register()对同名同任务的重复注册默认会抛出ValueError拒绝覆盖可通过allow_overrideTrue显式放行——这保证了注册表的确定性。八、进一步查阅指引架构模块索引文档max/python/docs/pipelines.architectures.rst架构注册表源码max/python/max/pipelines/lib/registry.py架构查找与SupportedArchitecture定义max/python/max/pipelines/lib/arch_lookup.py内置架构惰性注册表max/python/max/pipelines/architectures/init.py架构目录与 Bazel 清单max/python/max/pipelines/architectures/ 及 all_arches.bzl自定义模型架构指南max/docs/contributing-models.md。综上所述max.pipelines.architectures是 MAX pipeline 系统的模型能力目录它以SupportedArchitecture为统一契约用惰性注册机制把近百个模型家族的组织方式模型类、分词器、量化编码、权重格式、批量处理、内存规划、投机解码等声明式地登记在全局注册表中再经由PIPELINE_REGISTRY.retrieve_factory()在运行时按需解析、规划并构建出可执行的 pipeline——理解这套机制是使用 MAX 部署模型、以及向 MAX 贡献新模型的第一步。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考