Diffusers：Hugging Face 官方扩散模型工具箱｜部署与使用全指南

项目仓库： https://github.com/huggingface/diffusers

许可证：Apache 2.0 · 语言：Python · 框架：PyTorch · 形态：Python 库 · 文档：huggingface.co/docs/diffusers

1 项目简介

Diffusers 是 Hugging Face 官方维护的扩散模型工具箱，用于加载与运行最先进的预训练扩散模型，覆盖图像生成、音频生成、3D 分子结构生成等场景。它提供三大核心组件：

• Pipelines（流水线）：几行代码即可完成推理，Hub 上有 30000+ checkpoint 可直接加载。
• Schedulers（调度器）：可插拔的噪声调度，不同调度器在速度与质量间取舍。
• Models（模型）：预训练模型作为积木，与调度器组合可搭出自己的扩散系统。

它是 SD 1.5 / SDXL / FLUX / HunyuanVideo / Stable Cascade 等大量官方模型在社区的标准接入方式。

1.1 核心信息一览

1.2 适用场景

• 用几行代码加载 SD、SDXL、FLUX、HunyuanVideo 等模型做推理。
• 自己组合模型与调度器搭建定制扩散系统。
• 用官方训练脚本做微调 / 训练自己的扩散模型。
• 在 Apple Silicon（M1/M2）上跑 MPS 推理。

1.3 能力边界（官方口径）

• 库的设计哲学是"易用优先于性能、简单优先于易写、可定制优先于抽象"。
• 它本身不绑定具体模型；模型权重从 Hugging Face Hub 按需下载，各模型有自己的许可证。
• 生产级加速（fp16、xFormers、torch.compile、CPU offload）需按官方优化指南配置。

2 功能特性

• Pipelines：DiffusionPipeline.from_pretrained() 一行加载，支持文生图、图生图、inpaint、深度图、超分、视频等。
• 可插拔调度器：DDPM、DDIM、PNDM、Euler、Euler a、DEIS、UniPC、DPMSolver 等随时切换。
• 模块化积木：UNet、VAE、文本编码器可单独加载替换。
• 训练工具：官方提供 LoRA、DreamBooth、文本到图像训练脚本。
• 优化指南：fp16、xFormers、torch.compile、CINN、torch2.0 等加速方案。
• Apple Silicon MPS：官方支持 M1/M2 本地推理。

3 官方界面预览

Diffusers 是 Python 库，没有独立 Web 界面。官方文档提供 Quickstart Notebook 与 Colab。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Python 3.9+。
• PyTorch（建议按官方指南安装 CUDA 版本）。
• 虚拟环境（venv / conda）。

5.2 硬件建议

5.3 端口

库形态，无 HTTP 服务端口。

6 方式一：pip 安装（推荐）

# 建议在虚拟环境中
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install --upgrade diffusers[torch]

conda 安装（社区维护）：

conda install -c conda-forge diffusers

6.1 最简文生图

from diffusers import DiffusionPipeline
import torch

pipeline = DiffusionPipeline.from_pretrained(
    "stable-diffusion-v1-5/stable-diffusion-v1-5",
    dtype=torch.float16,
)
pipeline.to("cuda")
image = pipeline("An image of a squirrel in Picasso style").images[0]
image.save("squirrel.png")

7 方式二：模块化自建扩散系统

from diffusers import DDPMScheduler, UNet2DModel
from PIL import Image
import torch

scheduler = DDPMScheduler.from_pretrained("google/ddpm-cat-256")
model = UNet2DModel.from_pretrained("google/ddpm-cat-256").to("cuda")
scheduler.set_timesteps(50)

sample_size = model.config.sample_size
noise = torch.randn((1, 3, sample_size, sample_size), device="cuda")
input = noise

for t in scheduler.timesteps:
    with torch.no_grad():
        noisy_residual = model(input, t).sample
        prev_noisy_sample = scheduler.step(noisy_residual, t, input).prev_sample
        input = prev_noisy_sample

image = (input / 2 + 0.5).clamp(0, 1)
image = image.cpu().permute(0, 2, 3, 1).numpy()[0]
Image.fromarray((image * 255).round().astype("uint8")).save("cat.png")

8 配置项与关键概念

9 常用运维命令

# 查看版本
pip show diffusers

# 升级
pip install --upgrade diffusers[torch]

# 查看已缓存的模型
ls ~/.cache/huggingface/hub/

10 常见故障排查

• 显存不足：用 fp16、enable_model_cpu_offload()、xFormers、或降低分辨率。
• 模型下载慢：配置 HF_ENDPOINT 镜像或手动下载到本地目录后用本地路径加载。
• CUDA 版本不匹配：按 PyTorch 官方指南重装对应 CUDA 版本。
• Apple Silicon MPS 报错：按官方 MPS 指南配置，部分算子在 MPS 上仍需回退 CPU。

11 风险与合规说明

• Diffusers 本身是 Apache 2.0 库，无传染性；但它加载的每个模型权重有自己的许可证（SD 1.5、SDXL、FLUX 等各不相同），商用前需逐一对账。
• 生成内容版权与责任由使用者承担。
• 训练脚本示例仅供学习，商用数据集需自行确认授权。

本文基于官方 README 与文档整理，仅供学习与部署参考；以仓库最新说明为准。