Hugging Face 的 LOGO

Diffusers 文档

加载社区管道和组件

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

加载社区管道和组件

社区管道

请参阅 GitHub Issue #841，了解更多关于为什么我们要添加社区管道的背景信息，以帮助每个人轻松分享他们的工作而不会被拖慢速度。

社区管道是任何与原始论文实现不同（例如，StableDiffusionControlNetPipeline 对应于 使用 ControlNet 条件进行文本到图像生成 论文）的 DiffusionPipeline 类。它们提供附加功能或扩展管道的原始实现。

有许多很棒的社区管道，例如 Marigold 深度估计 或 InstantID，您可以在此处找到所有官方社区管道。

社区管道有两种类型：存储在 Hugging Face Hub 上的管道和存储在 Diffusers GitHub 仓库上的管道。Hub 管道完全可定制（调度器、模型、管道代码等），而 Diffusers GitHub 管道仅限于自定义管道代码。

GitHub 社区管道 HF Hub 社区管道
用法 相同 相同
评审流程 在 GitHub 上打开拉取请求并经过 Diffusers 团队的评审流程才能合并；可能较慢 直接上传到 Hub 仓库，无需任何评审；这是最快的工作流程
可见性 包含在官方 Diffusers 仓库和文档中 包含在您的 HF Hub 个人资料中，依赖您自己的使用/推广来获得可见性
Hub 管道
GitHub 管道

要加载 Hugging Face Hub 社区管道，请将社区管道的仓库 ID 传递给 custom_pipeline 参数，以及要从中加载管道权重和组件的模型仓库。例如，以下示例从 hf-internal-testing/diffusers-dummy-pipeline 加载一个虚拟管道，并从 google/ddpm-cifar10-32 加载管道权重和组件。

通过从 Hugging Face Hub 加载社区管道，您将信任您正在加载的代码是安全的。请务必在加载和自动运行之前在线检查代码！

from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
    "google/ddpm-cifar10-32", custom_pipeline="hf-internal-testing/diffusers-dummy-pipeline", use_safetensors=True
)

从本地文件加载

如果传递文件路径，社区管道也可以从本地文件加载。传递目录的路径必须包含一个包含管道类的 pipeline.py 文件。

pipeline = DiffusionPipeline.from_pretrained(
    "stable-diffusion-v1-5/stable-diffusion-v1-5",
    custom_pipeline="./path/to/pipeline_directory/",
    clip_model=clip_model,
    feature_extractor=feature_extractor,
    use_safetensors=True,
)

从特定版本加载

默认情况下，社区管道从 Diffusers 的最新稳定版本加载。要从另一个版本加载社区管道，请使用 custom_revision 参数。

main
旧版本

例如，从主分支加载

pipeline = DiffusionPipeline.from_pretrained(
    "stable-diffusion-v1-5/stable-diffusion-v1-5",
    custom_pipeline="clip_guided_stable_diffusion",
    custom_revision="main",
    clip_model=clip_model,
    feature_extractor=feature_extractor,
    use_safetensors=True,
)

使用 from_pipe 加载

社区管道也可以使用 from_pipe() 方法加载，该方法允许您加载和重用多个管道而无需额外的内存开销（在重用管道指南中了解更多信息）。内存需求由加载的最大单个管道决定。

例如，让我们加载一个支持长提示和权重的社区管道，该管道来自 Stable Diffusion 管道。

import torch
from diffusers import DiffusionPipeline

pipe_sd = DiffusionPipeline.from_pretrained("emilianJR/CyberRealistic_V3", torch_dtype=torch.float16)
pipe_sd.to("cuda")
# load long prompt weighting pipeline
pipe_lpw = DiffusionPipeline.from_pipe(
    pipe_sd,
    custom_pipeline="lpw_stable_diffusion",
).to("cuda")

prompt = "cat, hiding in the leaves, ((rain)), zazie rainyday, beautiful eyes, macro shot, colorful details, natural lighting, amazing composition, subsurface scattering, amazing textures, filmic, soft light, ultra-detailed eyes, intricate details, detailed texture, light source contrast, dramatic shadows, cinematic light, depth of field, film grain, noise, dark background, hyperrealistic dslr film still, dim volumetric cinematic lighting"
neg_prompt = "(deformed iris, deformed pupils, semi-realistic, cgi, 3d, render, sketch, cartoon, drawing, anime, mutated hands and fingers:1.4), (deformed, distorted, disfigured:1.3), poorly drawn, bad anatomy, wrong anatomy, extra limb, missing limb, floating limbs, disconnected limbs, mutation, mutated, ugly, disgusting, amputation"
generator = torch.Generator(device="cpu").manual_seed(20)
out_lpw = pipe_lpw(
    prompt,
    negative_prompt=neg_prompt,
    width=512,
    height=512,
    max_embeddings_multiples=3,
    num_inference_steps=50,
    generator=generator,
    ).images[0]
out_lpw
带有长提示权重的 Stable Diffusion
Stable Diffusion

社区管道示例

社区管道是一种非常有趣和富有创意的方式，可以扩展原始管道的功能，添加新的独特功能。您可以在 diffusers/examples/community 文件夹中找到所有社区管道，并附带了如何使用它们的推理和训练示例。

本节展示了一些社区管道，希望它能激发您创建自己的管道（欢迎为您的社区管道提交 PR 并提醒我们进行审查）！

from_pipe() 方法对于加载社区管道特别有用，因为其中许多管道没有预训练权重，并且在现有管道（如 Stable Diffusion 或 Stable Diffusion XL）之上添加了功能。您可以在使用 from_pipe 加载部分了解更多关于 from_pipe() 方法的信息。

万寿菊
HD-Painter

Marigold 是一种深度估计扩散管道，它利用了扩散模型中丰富的现有固有视觉知识。它接收输入图像并对其进行去噪和解码，生成深度图。Marigold 即使在以前未见过的图像上也能表现良好。

import torch
from PIL import Image
from diffusers import DiffusionPipeline
from diffusers.utils import load_image

pipeline = DiffusionPipeline.from_pretrained(
    "prs-eth/marigold-lcm-v1-0",
    custom_pipeline="marigold_depth_estimation",
    torch_dtype=torch.float16,
    variant="fp16",
)

pipeline.to("cuda")
image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/community-marigold.png")
output = pipeline(
    image,
    denoising_steps=4,
    ensemble_size=5,
    processing_res=768,
    match_input_res=True,
    batch_size=0,
    seed=33,
    color_map="Spectral",
    show_progress_bar=True,
)
depth_colored: Image.Image = output.depth_colored
depth_colored.save("./depth_colored.png")
原始图像
彩色深度图像

社区组件

社区组件允许用户构建可能包含 Diffusers 中不包含的自定义组件的管道。如果您的管道包含 Diffusers 尚未支持的自定义组件，您需要将其实现作为 Python 模块提供。这些自定义组件可以是 VAE、UNet 和调度器。在大多数情况下，文本编码器是从 Transformers 库导入的。管道代码本身也可以自定义。

本节展示了用户应如何使用社区组件来构建社区管道。

您将使用 showlab/show-1-base 管道检查点作为示例。

  1. 从 Transformers 导入并加载文本编码器
from transformers import T5Tokenizer, T5EncoderModel

pipe_id = "showlab/show-1-base"
tokenizer = T5Tokenizer.from_pretrained(pipe_id, subfolder="tokenizer")
text_encoder = T5EncoderModel.from_pretrained(pipe_id, subfolder="text_encoder")
  1. 加载调度器
from diffusers import DPMSolverMultistepScheduler

scheduler = DPMSolverMultistepScheduler.from_pretrained(pipe_id, subfolder="scheduler")
  1. 加载图像处理器
from transformers import CLIPImageProcessor

feature_extractor = CLIPImageProcessor.from_pretrained(pipe_id, subfolder="feature_extractor")

在步骤 4 和 5 中，自定义 UNet 和 管道 实现必须与其文件所示格式匹配，此示例才能正常工作。

  1. 现在您将加载一个自定义 UNet，在此示例中，为方便起见，它已在 showone_unet_3d_condition.py 中实现。您会注意到 UNet3DConditionModel 类名已更改为 ShowOneUNet3DConditionModel，因为 UNet3DConditionModel 在 Diffusers 中已经存在。ShowOneUNet3DConditionModel 类所需的任何组件都应放在 showone_unet_3d_condition.py 中。

    完成此操作后，您可以初始化 UNet

    from showone_unet_3d_condition import ShowOneUNet3DConditionModel

unet = ShowOneUNet3DConditionModel.from_pretrained(pipe_id, subfolder="unet")

  2. 最后，您将加载自定义管道代码。在此示例中，它已为您创建在 pipeline_t2v_base_pixel.py 中。此脚本包含一个自定义的 TextToVideoIFPipeline 类，用于从文本生成视频。就像自定义 UNet 一样，自定义管道正常工作所需的任何代码都应放在 pipeline_t2v_base_pixel.py 中。

一旦一切就绪，您可以使用 ShowOneUNet3DConditionModel 初始化 TextToVideoIFPipeline

from pipeline_t2v_base_pixel import TextToVideoIFPipeline
import torch

pipeline = TextToVideoIFPipeline(
    unet=unet,
    text_encoder=text_encoder,
    tokenizer=tokenizer,
    scheduler=scheduler,
    feature_extractor=feature_extractor
)
pipeline = pipeline.to(device="cuda")
pipeline.torch_dtype = torch.float16

将管道推送到 Hub 与社区共享！

pipeline.push_to_hub("custom-t2v-pipeline")

管道成功推送后，您需要进行一些更改

  1. 将 model_index.json 中的 _class_name 属性更改为 "pipeline_t2v_base_pixel" 和 "TextToVideoIFPipeline"。
  2. 将 showone_unet_3d_condition.py 上传到 unet 子文件夹。
  3. 将 pipeline_t2v_base_pixel.py 上传到管道仓库。

要运行推理，在初始化管道时添加 trust_remote_code 参数以处理所有“幕后”的“魔法”。

作为 trust_remote_code=True 的额外预防措施，我们强烈建议您将提交哈希值传递给 from_pretrained() 中的 revision 参数，以确保代码没有被恶意更新（除非您完全信任模型所有者）。

from diffusers import DiffusionPipeline
import torch

pipeline = DiffusionPipeline.from_pretrained(
    "<change-username>/<change-id>", trust_remote_code=True, torch_dtype=torch.float16
).to("cuda")

prompt = "hello"

# Text embeds
prompt_embeds, negative_embeds = pipeline.encode_prompt(prompt)

# Keyframes generation (8x64x40, 2fps)
video_frames = pipeline(
    prompt_embeds=prompt_embeds,
    negative_prompt_embeds=negative_embeds,
    num_frames=8,
    height=40,
    width=64,
    num_inference_steps=2,
    guidance_scale=9.0,
    output_type="pt"
).frames

作为额外参考，请查看 stabilityai/japanese-stable-diffusion-xl 的仓库结构，它也使用了 trust_remote_code 功能。

from diffusers import DiffusionPipeline
import torch

pipeline = DiffusionPipeline.from_pretrained(
    "stabilityai/japanese-stable-diffusion-xl", trust_remote_code=True
)
pipeline.to("cuda")
< > 在 GitHub 上更新

←加载管道 加载调度器和模型→