diffsynth.core.loader: 模型下载与加载

本文档介绍 diffsynth.core.loader 中模型下载与加载相关的功能。

ModelConfig

diffsynth.core.loader 中的 ModelConfig 用于标注模型下载来源、本地路径、显存管理配置等信息。

从远程下载并加载模型

以模型DiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny 为例,在 ModelConfig 中填写 model_id 和 origin_file_pattern 后即可自动下载模型。默认下载到 ./models 路径,该路径可通过环境变量 DIFFSYNTH_MODEL_BASE_PATH 修改。

默认情况下,即使模型已经下载完毕,程序仍会向远程查询是否有遗漏文件,如果要完全关闭远程请求,请将环境变量 DIFFSYNTH_SKIP_DOWNLOAD 设置为 True。

from diffsynth.core import ModelConfig

config = ModelConfig(
    model_id="DiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny",
    origin_file_pattern="model.safetensors",
)
# Download models
config.download_if_necessary()
print(config.path)

调用 download_if_necessary 后,模型会自动下载,并将路径返回到 config.path 中。

从本地路径加载模型

如果从本地路径加载模型,则需要填入 path:

from diffsynth.core import ModelConfig

config = ModelConfig(path="models/DiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny/model.safetensors")

如果模型包含多个分片文件,以列表的形式输入即可:

from diffsynth.core import ModelConfig

config = ModelConfig(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"
])

加载预量化模型

预量化模型通常会随权重一起发布一个 JSON 文件,用于描述重建模型所需的信息(即 MODEL_CONFIGS 中包含 quant_config 的条目)。在 ModelConfig 中用 origin_file_pattern 填写权重文件,用 origin_config_file 填写该 JSON 文件;调用 download_if_necessary 后,JSON 文件会被下载到 config.config_file,其中的条目也会自动注册,此后该预量化模型可以像普通模型一样加载:

from diffsynth.core import ModelConfig

config = ModelConfig(
    model_id="DiffSynth-Studio/MiniMax-H3-Image-EntroPack",
    origin_file_pattern="models/dit_extreme_3bpp.safetensors",
    origin_config_file="models/dit_extreme_3bpp.json",
)
config.download_if_necessary()
print(config.path, config.config_file)

如果该 JSON 文件已经在本地,则填入 config_file,并在加载模型前调用 config.register_prequantized()。

配置文件格式

该 JSON 文件包含一个对象,即一个 MODEL_CONFIGS 条目:

字段 是否必填 说明
model_hash 是 量化权重文件的 hash,由 hash_model_file 计算(张量名与形状的 MD5)。加载器用它识别模型类型,必须与权重文件一致。
model_name 是 模型名称,pipeline 用它取用模型,例如 qwen_image_dit。
model_class 是 模型类的导入路径,例如 diffsynth.models.qwen_image_dit.QwenImageDiT。
quant_config 是 传递给 QuantizeConfig 的参数,其中 load_prequantized 必须为 true,其余字段需与保存权重时的量化配置一致。
state_dict_converter 否 权重格式转换器的导入路径,详见模型集成。
extra_kwargs 否 模型构造函数的额外参数。

只使用一种量化方法时,quant_config 直接填写该方法及其参数:

{
    "model_hash": "8c6f5ccfe9ffe861675ca0da95bb9295",
    "model_name": "minimax_h3_text_encoder",
    "model_class": "diffsynth.models.minimax_h3_text_encoder.MiniMaxH3TextEncoder",
    "quant_config": {
        "method": "entropack_lossy_quant",
        "load_prequantized": true,
        "backend_config_kwargs": {"target_bpp": 4.0, "row_rdo_iterations": 2, "row_rdo_candidates": 20}
    }
}

混合量化时用 configs 代替 method,每一项是一个 QuantizeConfig,通过 target_modules / exclude_modules 选择它负责的模块;所有子项需使用相同的 mode,load_prequantized 只写在外层:

{
    "model_hash": "adab44d835193ce1b2bd0f85f0586f0e",
    "model_name": "minimax_h3_image_dit",
    "model_class": "diffsynth.models.minimax_h3_image_dit.MiniMaxH3ImageDiTPruned",
    "quant_config": {
        "load_prequantized": true,
        "configs": [
            {"method": "entropack_lossy_quant", "backend_config_kwargs": {"target_bpp": 2.91}, "exclude_modules": ["video_patch_proj", "condition_proj"]},
            {"method": "entropack_lossy_quant", "backend_config_kwargs": {"target_bpp": 8.5}, "target_modules": ["video_patch_proj", "condition_proj"]}
        ]
    }
}

文件名没有限制,通常按权重文件名命名(如 model.safetensors 对应 model.json)。如果 MODEL_CONFIGS 中已经存在相同 model_hash 的条目,文件中的条目会被忽略。

显存管理配置

ModelConfig 也包含了显存管理配置信息,详见显存管理。

模型文件加载

diffsynth.core.loader 提供了统一的 load_state_dict,用于加载模型文件中的 state dict。

加载单个模型文件:

from diffsynth.core import load_state_dict

state_dict = load_state_dict("models/DiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny/model.safetensors")

加载多个模型文件(合并为一个 state dict):

from diffsynth.core import load_state_dict

state_dict = load_state_dict([
    "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"
])

模型哈希

模型哈希是用于判断模型类型的,哈希值可通过 hash_model_file 获取:

from diffsynth.core import hash_model_file

print(hash_model_file("models/DiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny/model.safetensors"))

也可计算多个模型文件的哈希值,等价于合并 state dict 后计算模型哈希值:

from diffsynth.core import hash_model_file

print(hash_model_file([
    "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"
]))

模型哈希值只与模型文件中 state dict 的 keys 和 tensor shape 有关,与模型参数的数值、文件保存时间等信息无关。在计算 .safetensors 格式文件的模型哈希值时,hash_model_file 是几乎瞬间完成的,无需读取模型的参数;但在计算 .bin、.pth、.ckpt 等二进制文件的模型哈希值时,则需要读取全部模型参数,因此我们不建议开发者继续使用这些格式的文件。

通过编写模型 Config并将模型哈希值等信息填入 diffsynth/configs/model_configs.py,开发者可以让 DiffSynth-Studio 自动识别模型类型并加载。

模型加载

load_model 是 diffsynth.core.loader 中加载模型的外部入口,它会调用 skip_model_initialization 跳过模型参数初始化。如果启用了 Disk Offload,则调用 DiskMap 进行惰性加载;如果没有启用 Disk Offload,则调用 load_state_dict 加载模型参数。如果需要的话,还会调用 state dict converter 进行模型格式转换。最后调用 model.eval() 将其切换到推理模式。

以下是一个启用了 Disk Offload 的使用案例:

from diffsynth.core import load_model, enable_vram_management, AutoWrappedLinear, AutoWrappedModule
from diffsynth.models.qwen_image_dit import QwenImageDiT, RMSNorm
import torch

prefix = "models/Qwen/Qwen-Image/transformer/diffusion_pytorch_model"
model_path = [prefix + f"-0000{i}-of-00009.safetensors" for i in range(1, 10)]

model = load_model(
    QwenImageDiT,
    model_path,
    module_map={
        torch.nn.Linear: AutoWrappedLinear,
        RMSNorm: AutoWrappedModule,
    },
    vram_config={
        "offload_dtype": "disk",
        "offload_device": "disk",
        "onload_dtype": "disk",
        "onload_device": "disk",
        "preparing_dtype": torch.bfloat16,
        "preparing_device": "cuda",
        "computation_dtype": torch.bfloat16,
        "computation_device": "cuda",
    },
    vram_limit=0,
)