Diffusers 单文件模型怎么转换成组件目录格式

Diffusers 单文件模型转换成组件目录格式，关键不是重命名 .safetensors 或 .ckpt，而是先用匹配的 Pipeline 调用 from_single_file() 读出模型对象，再调用 save_pretrained() 写目录。这样配置、调度器、UNet、文本编码器、VAE 等组件才会按 Diffusers 能识别的结构保存。

官方地址：https://huggingface.co/docs/diffusers/using-diffusers/other-formats

先分清单文件与组件目录的差别

单文件格式把 UNet、transformer、文本编码器等模型权重集中在一个文件里，分享和下载很方便；Diffusers format 则把组件放进不同子目录，便于复用单个组件、并行初始化或只加载需要的部分。两者不是“文件扩展名不同”这么简单，所以直接把文件复制到一个新目录并改名，通常不会得到可加载的 Diffusers 模型。

先把单文件模型加载成 Pipeline 对象

先按模型实际架构选择 Pipeline。下面的示例以 SDXL 为例，路径可以是本地文件，也可以是 Hub 上的单文件地址。示例中的 config 不是随便填一个仓库名，而是与检查点架构和配置兼容的 Diffusers 配置来源。

import torch
from diffusers import StableDiffusionXLPipeline

# 这里替换成实际的单文件路径；Pipeline 类必须与模型架构匹配
checkpoint = "./models/sdxl-base.safetensors"

# 先把集中存放的权重还原成可操作的 Pipeline 对象
pipeline = StableDiffusionXLPipeline.from_single_file(
    checkpoint,
    config="stabilityai/stable-diffusion-xl-base-1.0",
    dtype=torch.float16,
    device_map="cuda",
)

# 目录格式由对象保存产生，不是通过复制或修改扩展名产生
pipeline.save_pretrained("./models/sdxl-diffusers")

如果自动推断配置成功，可以省略 config；但遇到自定义训练、模型结构改过、网络不可用或元数据不足时，显式指定配置更稳。离线环境还要提前把配置和检查点放进本地缓存，并使用与本地文件边界一致的参数。

save_pretrained 会写出什么目录

保存完成后，重点检查目录是否同时拥有入口配置、组件目录和对应权重。不同 Pipeline 的组件名可能不同，例如某些模型使用 transformer 而不是 unet，不能把下面的示意目录当成所有模型的固定清单。

sdxl-diffusers/
├── model_index.json       # 记录 Pipeline 类型和组件配置
├── scheduler/              # 调度器配置
├── unet/                   # 去噪网络及其配置、权重
├── text_encoder/           # 文本编码器
├── tokenizer/              # 分词器资源
└── vae/                    # 图像编码器/解码器

实际目录还可能出现第二个文本编码器、额外 tokenizer 或不同权重后缀。判断转换是否完成，不是数目录数量，而是确认目标 Pipeline 能从这个目录读取。

用重新加载处理配置与兼容边界

转换后可以用同一个 Pipeline 类从目录加载，作为发布前的结构检查。这里的“检查”只针对目录是否具备可读取结构；如果单文件本身与 Pipeline 不匹配，保存阶段就会在组件解析处失败，应回到模型架构和配置来源排查。

from diffusers import StableDiffusionXLPipeline

# 从刚保存的组件目录读取，确认入口配置和组件路径能够对应
reloaded = StableDiffusionXLPipeline.from_pretrained(
    "./models/sdxl-diffusers",
    local_files_only=True,
)

# 推理设备和精度按本机显存与部署方案决定，不把它们写死成目录格式
reloaded = reloaded.to("cuda")

常见故障可以按下面的边界判断：

• 提示缺少配置：补充正确的 config，不要只改文件名。
• 组件名称或键不匹配：检查 Pipeline 类型、模型架构和转换脚本是否对应。
• 目录能保存但不能加载：逐项查看 model_index.json、组件配置和权重文件是否来自同一模型。
• 想转成单文件：方向相反时应使用官方转换脚本，并按脚本参数决定输出类型；不能把目录压成 zip 代替模型转换。

相关问题

单文件一定要先转成目录才能推理吗

不一定。Diffusers 可以直接用 from_single_file() 加载；只有需要组件复用、目录式部署或与 from_pretrained() 工作流衔接时，才有必要另存为目录。

ckpt 和 safetensors 的转换入口一样吗

都属于单文件加载场景，但具体兼容性取决于模型架构、Pipeline 和文件元数据。优先使用安全、明确的权重来源，遇到 ckpt 时特别注意其加载风险与配置匹配。

为什么保存后的目录没有我预期的文件夹

组件集合由 Pipeline 决定，不同架构会使用不同组件。应以对应 Pipeline 的配置和重新加载结果为准，不要套用另一种模型的固定目录模板。