DiffSynth-Studio 模型接入指南从模型结构代码到显存管理的五步集成实战【免费下载链接】DiffSynth-StudioEnjoy the magic of Diffusion models!项目地址: https://gitcode.com/GitHub_Trending/dif/DiffSynth-Studio本篇技术指南围绕DiffSynth-Studio官方开发者文档《接入模型结构》展开系统讲解如何将任意扩散模型DiT、Text Encoder、VAE、ControlNet 等接入该框架供Pipeline等模块统一调用。读者完成阅读后将掌握五步完整的接入流程编写模型结构代码、编写 state dict 格式转换器、注册模型 Config、用ModelPool验证加载、并为模型接入显存管理方案从而让新模型能够直接复用框架的加载、量化、LoRA 与显存管理能力。一、接入总览一切模型都汇聚到 ModelPoolDiffSynth-Studio采用模型结构代码统一管理 配置驱动加载的架构所有模型结构的实现统一放在diffsynth/models目录下每个.py文件实现一个模型结构所有模型文件则通过 diffsynth/models/model_loader.py 中的ModelPool类来加载。接入一个新模型时核心工作就是为它补齐结构代码 格式转换 配置注册三件套。从 model_loader.py 中ModelPool.auto_load_model的实现可以看到加载的完整链路def auto_load_model(self, path, vram_configNone, vram_limitNone, clear_parametersFalse, state_dictNone, quantizeNone): print(fLoading models from: {json.dumps(path, indent4)}) if vram_config is None: vram_config self.default_vram_config() model_hash hash_model_file(path) loaded False for config in MODEL_CONFIGS: if config[model_hash] model_hash: model self.load_model_file(config, path, vram_config, vram_limitvram_limit, state_dictstate_dict, quantizequantize) ...也就是说框架先对模型文件计算哈希再与MODEL_CONFIGS中逐条注册的model_hash比对命中后按该配置指定的model_class、state_dict_converter、extra_kwargs完成实例化与权重加载。这条哈希 → 匹配 → 加载的链路就是下文所有接入步骤的落脚点。二、Step 1集成模型结构代码2.1 代码放置位置与目录结构所有模型结构实现统一放在diffsynth/models目录下接入新模型时在此路径下新建.py文件。以 Qwen-Image 系列为例目录结构如下diffsynth/models/ ├── general_modules.py ├── model_loader.py ├── qwen_image_controlnet.py ├── qwen_image_dit.py ├── qwen_image_text_encoder.py ├── qwen_image_vae.py └── ...2.2 方式一原生 PyTorch 代码推荐绝大多数情况下建议以原生 PyTorch 代码形式集成模型让模型结构类直接继承torch.nn.Moduleimport torch class NewDiffSynthModel(torch.nn.Module): def __init__(self, dim1024): super().__init__() self.linear torch.nn.Linear(dim, dim) self.activation torch.nn.Sigmoid() def forward(self, x): x self.linear(x) x self.activation(x) return x重要原则删掉额外依赖。如果模型实现包含额外的第三方包依赖强烈建议将其删除否则会给整个项目带来沉重的包依赖问题。仓库中 Qwen-Image 的 Blockwise ControlNet 就是以这种方式集成的代码非常轻量可参考 diffsynth/models/qwen_image_controlnet.py。从该文件可以看到整个 ControlNet 仅依赖torch与框架内部的RMSNorm来自 general_modules.py并通过BlockWiseControlBlock与QwenImageBlockWiseControlNet两个类组织且提供了零初始化权重的init_weight方法与按块前向的blockwise_forward接口——这正是为了在推理时逐块注入 DiT 而设计体现了轻量、可被框架编排的集成风格。2.3 方式二包装 Huggingface Library 风格模型如果模型已被 Huggingface 生态transformers、diffusers等集成可以更简单地包装。这类模型在 Huggingface Library 中的加载方式通常为from transformers import XXX_Model model XXX_Model.from_pretrained(path_to_your_model)但DiffSynth-Studio不支持通过from_pretrained加载模型因为这与显存管理等功能存在冲突from_pretrained会在内部自行处理权重加载与设备放置无法被框架的加载管线接管。因此需要将模型结构改写成以下格式import torch class DiffSynth_XXX_Model(torch.nn.Module): def __init__(self): super().__init__() from transformers import XXX_Config, XXX_Model config XXX_Config(**{ architectures: [XXX_Model], other_configs: Please copy and paste the other configs here., }) self.model XXX_Model(config) def forward(self, x): outputs self.model(x) return outputs其中XXX_Config为模型对应的 Config 类。例如Qwen2_5_VLModel对应的 Config 类是Qwen2_5_VLConfig可通过查阅其源代码找到。Config 内部的参数通常可以在模型库的config.json文件中找到DiffSynth-Studio不会读取config.json文件因此需要把其中的内容手动复制粘贴到代码中。仓库中的典型范例是 diffsynth/models/qwen_image_text_encoder.py该类在__init__中构造Qwen2_5_VLConfig将architectures、hidden_size、intermediate_size、num_hidden_layers、rope_scaling、vision_config等完整配置逐项写入再以Qwen2_5_VLModel(config)实例化并包装为torch.nn.Module子类。注意事项在少数情况下transformers与diffusers的版本更新会导致部分模型无法导入。因此如果可能的话仍建议优先采用 2.2 节的原生 PyTorch 集成方式以彻底解耦对 Huggingface 生态的版本依赖。三、Step 2模型文件格式转换state dict converter3.1 为什么需要转换开源社区中开发者提供的模型文件格式多种多样有时需要对模型文件格式进行转换以形成格式正确的 state dict。常见于以下几种情况模型文件由不同代码库构建例如 Wan2.1-T2V-1.3B 官方仓库与 Diffusers 重封装仓库的权重组织结构不一致模型在接入中做了修改例如 Qwen-Image 的 Text Encoder 在 qwen_image_text_encoder.py 中增加了model.前缀导致键名需要重映射模型文件包含多个模型例如 Wan2.1-VACE-14B 的 VACE Adapter 与基础 DiT 模型混合存储在同一组模型文件中加载时需要按需分离。3.2 转换逻辑放在哪里DiffSynth-Studio专门增加了diffsynth/utils/state_dict_converters模块用于在模型加载过程中进行文件格式转换。之所以采用加载时转换而非重新封装模型文件是出于对模型原作者意愿的尊重如果对模型文件进行重新封装例如 Qwen-Image 的 ComfyUI 重封装仓库虽然调用更方便但流量模型页面浏览量、下载量等会被引向他处模型原作者也会失去删除模型的权力。因此在框架内部完成转换可以保证始终直接使用原作者发布的模型文件。3.3 一个 10 行代码的转换器范例转换逻辑本身非常简单以 Qwen-Image 的 Text Encoder 为例对应实现见 diffsynth/utils/state_dict_converters/qwen_image_text_encoder.py只需 10 行代码def QwenImageTextEncoderStateDictConverter(state_dict): state_dict_ {} for k in state_dict: v state_dict[k] if k.startswith(visual.): k model. k elif k.startswith(model.): k k.replace(model., model.language_model.) state_dict_[k] v return state_dict_这段逻辑把官方权重中visual.*前缀的键改写为model.visual.*把model.*改写为model.language_model.*从而与 qwen_image_text_encoder.py 中包装的Qwen2_5_VLModel的参数结构对齐。转换器会在加载管线中被调用在 diffsynth/core/loader/model.py 中加载后的 state dict 会先经过state_dict_converter(state_dict)转换再执行model.load_state_dict(state_dict, assignTrue)随后统一调用model.to(dtype..., device...)。从源码注释可以看出转换器的存在正是为了兼容各种复杂格式的权重文件。四、Step 3编写模型 Config4.1 字段说明模型 Config 位于 diffsynth/configs/model_configs.py用于识别模型类型并完成加载。需要填写的字段如下字段是否必填说明model_hash必填模型文件哈希值通过hash_model_file函数获取该哈希仅与模型文件中 state dict 的 keys 和张量 shape 有关与文件中其他信息如元数据、实际数值无关model_name必填模型名称供Pipeline识别所需模型若不同结构的模型在Pipeline中发挥相同作用可使用相同model_name接入新模型时只需保证model_name与现有功能模型不同即可model_class必填模型结构导入路径指向 Step 1 中实现的模型结构类例如diffsynth.models.qwen_image_text_encoder.QwenImageTextEncoderstate_dict_converter可选模型文件格式转换逻辑的导入路径例如diffsynth.utils.state_dict_converters.qwen_image_text_encoder.QwenImageTextEncoderStateDictConverterextra_kwargs可选模型初始化时需传入的额外参数例如 Canny 与 Inpaint 两种 Blockwise ControlNet 共用QwenImageBlockWiseControlNet结构但 Inpaint 版本还需additional_in_dim4这部分差异就通过extra_kwargs表达以 Qwen-Image 系列在 model_configs.py 中的真实注册为例{ model_hash: 8004730443f55db63092006dd9f7110e, model_name: qwen_image_text_encoder, model_class: diffsynth.models.qwen_image_text_encoder.QwenImageTextEncoder, state_dict_converter: diffsynth.utils.state_dict_converters.qwen_image_text_encoder.QwenImageTextEncoderStateDictConverter, }, { model_hash: a9e54e480a628f0b956a688a81c33bab, model_name: qwen_image_blockwise_controlnet, model_class: diffsynth.models.qwen_image_controlnet.QwenImageBlockWiseControlNet, extra_kwargs: {additional_in_dim: 4}, },所有系列的 Config 在文件末尾聚合成MODEL_CONFIGS元组见 model_configs.py并由 diffsynth/configs/init.py 导出供ModelPool在加载时逐条匹配。仓库中已有 Wan、FLUX、FLUX2、LTX-2、MiniMax、SDXL 等数十个模型系列新模型的 Config 注册到对应系列或新建系列后即可生效。4.2 关于model_hash的计算model_hash通过hash_model_file函数获得其实现位于 diffsynth/core/loader/file.py函数读取模型文件中每个张量的键名与 shape按字典序拼接为字符串后进行 MD5 哈希。因此同一份权重文件无论内容数值如何变化只要键名与形状不变哈希就保持不变而键名或形状的任何变化都会导致哈希改变——这正是格式转换器 哈希配合工作的基础哈希用于识别文件转换器用于适配结构。4.3 加载机制全流程演示以下代码来自官方文档可以快速理解模型是如何通过上述配置信息完成加载的其中skip_model_initialization用于跳过随机初始化以加速加载并节省显存from diffsynth.core import hash_model_file, load_state_dict, skip_model_initialization from diffsynth.models.qwen_image_text_encoder import QwenImageTextEncoder from diffsynth.utils.state_dict_converters.qwen_image_text_encoder import QwenImageTextEncoderStateDictConverter import torch model_hash 8004730443f55db63092006dd9f7110e model_name qwen_image_text_encoder model_class QwenImageTextEncoder state_dict_converter QwenImageTextEncoderStateDictConverter extra_kwargs {} model_path [ models/Qwen/Qwen-Image/text_encoder/model-00001-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00002-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00003-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00004-of-00004.safetensors, ] if hash_model_file(model_path) model_hash: with skip_model_initialization(): model model_class(**extra_kwargs) state_dict load_state_dict(model_path, torch_dtypetorch.bfloat16, devicecuda) state_dict state_dict_converter(state_dict) model.load_state_dict(state_dict, assignTrue) print(Done!)Q上述代码的逻辑看起来很简单为什么DiffSynth-Studio中的这部分代码极为复杂A因为框架提供了激进的显存管理功能它与模型加载逻辑深度耦合导致框架结构复杂但暴露给开发者的接口已经尽可能简化即本文描述的这一套 Config 字段。注意model_configs.py中的model_hash并不是唯一的同一模型文件中可能包含多个模型例如 Wan2.1-VACE 中 Adapter 与 DiT 共存。对于这种情况请使用多个模型 Config 分别加载每个模型并为每个 Config 编写相应的state_dict_converter来分离每个模型所需的参数。仓库中wan_series就是这一做法的典型同一个model_hash如7a513e1f257a861512b1afd387a8ecd9同时注册了wan_video_dit与wan_video_vace两条 Config分别由不同的state_dict_converter从同一组文件中抽取各自参数。五、Step 4检验模型能否被识别和加载模型接入之后可通过以下代码验证模型能否被正确识别和加载。以下代码会试图将模型加载到内存中from diffsynth.models.model_loader import ModelPool model_pool ModelPool() model_pool.auto_load_model( [ models/Qwen/Qwen-Image/text_encoder/model-00001-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00002-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00003-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00004-of-00004.safetensors, ], )如果模型能够被识别和加载则终端会输出以下内容Loading models from: [ models/Qwen/Qwen-Image/text_encoder/model-00001-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00002-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00003-of-00004.safetensors, models/Qwen/Qwen-Image/text_encoder/model-00004-of-00004.safetensors ] Loaded model: { model_name: qwen_image_text_encoder, model_class: diffsynth.models.qwen_image_text_encoder.QwenImageTextEncoder, extra_kwargs: null }从源码看这段输出由 model_loader.py 中的打印语句直接产生。需要特别注意如果哈希无法命中任何 Configauto_load_model会抛出ValueError: Cannot detect the model type. File: ... Model hash: ...异常并直接打印计算出的model_hash——此时只需将该哈希填入 Config 即可。加载成功后Pipeline通过ModelPool.fetch_model(model_name, index)按model_name取用模型见 model_loader.py同一model_name下可能加载了多个模型实例index参数用于选择具体取哪个例如多阶段流水线中的第一个或前几个模型。六、Step 5编写模型显存管理方案DiffSynth-Studio支持复杂的显存管理机制。接入模型后如需让模型在低显存环境下运行请参阅文档 docs/zh/Developer_Guide/Enabling_VRAM_management.md英文版见 docs/en/Developer_Guide/Enabling_VRAM_management.md。从源码层面看显存管理与模型加载是深度耦合的在 model_loader.py 中fetch_module_map会根据显存配置决定是否为模型包装AutoWrappedModule或使用 vram_management_module_maps.py 中注册的自定义模块映射在 core/loader/model.py 中load_model会根据module_map调用enable_vram_management完成层级的按需卸载与重载。因此接入模型时通常无需改动加载逻辑只需在显存管理模块映射表中注册结构对应的包装类即可复用框架的 offload 能力。七、接入流程自查清单完成上述五个步骤后可用以下清单快速自查结构代码新模型的.py文件已放入diffsynth/models/类继承torch.nn.Module不引入多余的外部依赖格式转换如权重键名与结构类参数名不一致已在diffsynth/utils/state_dict_converters/中编写转换函数Config 注册已在 model_configs.py 中注册model_hash、model_name、model_class必要时含state_dict_converter与extra_kwargs且model_hash与hash_model_file计算结果一致加载验证ModelPool().auto_load_model(...)输出Loaded model且无ValueError显存方案如需低显存运行已按 Enabling_VRAM_management.md 完成模块映射注册Pipeline 集成确认Pipeline中能通过model_name正确获取到该模型并完成端到端推理验证。完成以上步骤后新模型即可与 Qwen-Image、Wan、FLUX 等既有模型一样在Pipeline中被from_pretrained统一调度并完整享受框架提供的量化加载、LoRA 注入与显存管理等基础设施能力。【免费下载链接】DiffSynth-StudioEnjoy the magic of Diffusion models!项目地址: https://gitcode.com/GitHub_Trending/dif/DiffSynth-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考