Hugging Face 的 logo

Diffusers 文档

加载社区管道和组件

Hugging Face's logo
加入 Hugging Face 社区

并获得增强文档体验

开始使用

加载社区管道和组件

社区管道

查看 GitHub Issue #841 以获取更多关于我们为何添加社区管道以帮助每个人轻松共享其工作而不会减慢速度的上下文。

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

有很多很棒的社区管道，例如 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(
    "runwayml/stable-diffusion-v1-5",
    custom_pipeline="./path/to/pipeline_directory/",
    clip_model=clip_model,
    feature_extractor=feature_extractor,
    use_safetensors=True,
)

从特定版本加载

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

主
旧版本

例如，要从主分支加载

pipeline = DiffusionPipeline.from_pretrained(
    "runwayml/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() 方法的更多信息。

Marigold
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 更新

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