结合 Stable Diffusion 3 的 ControlNet
StableDiffusion3ControlNetPipeline 是 Stable Diffusion 3 的 ControlNet 实现。
ControlNet 在 为文本到图像扩散模型添加条件控制 中引入，该论文由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 撰写。
使用 ControlNet 模型，您可以提供额外的控制图像来调节和控制 Stable Diffusion 的生成。例如，如果您提供深度图，ControlNet 模型将生成一张保留深度图空间信息的图像。这是一种更灵活、更准确的控制图像生成过程的方法。
论文摘要如下：
我们提出了 ControlNet，这是一种神经网络架构，用于向大型预训练的文本到图像扩散模型添加空间条件控制。ControlNet 锁定生产就绪的大型扩散模型，并重用其通过数十亿张图像预训练的深度且强大的编码层作为强大的骨干来学习各种条件控制。神经网络架构与“零卷积”（零初始化卷积层）相连，这些卷积层从零开始逐步增加参数，并确保没有任何有害噪声会影响微调。我们使用 Stable Diffusion 测试了各种条件控制，例如边缘、深度、分割、人体姿势等，使用单个或多个条件，带或不带提示词。我们表明，ControlNet 的训练对于小型（<50k）和大型（>1m）数据集都具有鲁棒性。大量结果表明，ControlNet 可以促进更广泛的应用来控制图像扩散模型。
此代码由 InstantX 团队 实现。您可以在 InstantX 团队 的 Hub 个人资料中找到 SD3-ControlNet 的预训练检查点。
StableDiffusion3ControlNetPipeline
类 diffusers.StableDiffusion3ControlNetPipeline
< 源代码 >( transformer: SD3Transformer2DModel scheduler: FlowMatchEulerDiscreteScheduler vae: AutoencoderKL text_encoder: CLIPTextModelWithProjection tokenizer: CLIPTokenizer text_encoder_2: CLIPTextModelWithProjection tokenizer_2: CLIPTokenizer text_encoder_3: T5EncoderModel tokenizer_3: T5TokenizerFast controlnet: Union )
参数
- transformer (SD3Transformer2DModel) — 用于对编码图像潜在变量进行去噪的条件Transformer（MMDiT）架构。
- scheduler (FlowMatchEulerDiscreteScheduler) — 与
transformer结合使用，对编码图像潜在变量进行去噪的调度器。 - vae (AutoencoderKL) — 用于将图像编码和解码为潜在表示的变分自动编码器（VAE）模型。
- text_encoder (
CLIPTextModelWithProjection) — CLIP，特别是 clip-vit-large-patch14 变体，并添加了一个额外的投影层，该层初始化为对角矩阵，其维度为hidden_size。 - text_encoder_2 (
CLIPTextModelWithProjection) — CLIP，特别是 laion/CLIP-ViT-bigG-14-laion2B-39B-b160k 变体。 - text_encoder_3 (
T5EncoderModel) — 冻结的文本编码器。Stable Diffusion 3 使用 T5，特别是 t5-v1_1-xxl 变体。 - tokenizer (
CLIPTokenizer) — CLIPTokenizer 类别的分词器。 - tokenizer_2 (
CLIPTokenizer) — CLIPTokenizer 类别的第二个分词器。 - tokenizer_3 (
T5TokenizerFast) — T5Tokenizer 类别的分词器。 - controlnet (SD3ControlNetModel 或
List[SD3ControlNetModel]或SD3MultiControlNetModel) — 在去噪过程中为unet提供额外的条件。如果将多个 ControlNet 设置为列表，则每个 ControlNet 的输出将相加以创建一个组合的额外条件。
__call__
< 源代码 >( prompt: Union = None prompt_2: Union = None prompt_3: Union = None height: Optional = None width: Optional = None num_inference_steps: int = 28 timesteps: List = None guidance_scale: float = 7.0 control_guidance_start: Union = 0.0 control_guidance_end: Union = 1.0 control_image: Union = None controlnet_conditioning_scale: Union = 1.0 controlnet_pooled_projections: Optional = None negative_prompt: Union = None negative_prompt_2: Union = None negative_prompt_3: Union = None num_images_per_prompt: Optional = 1 generator: Union = None latents: Optional = None prompt_embeds: Optional = None negative_prompt_embeds: Optional = None pooled_prompt_embeds: Optional = None negative_pooled_prompt_embeds: Optional = None output_type: Optional = 'pil' return_dict: bool = True joint_attention_kwargs: Optional = None clip_skip: Optional = None callback_on_step_end: Optional = None callback_on_step_end_tensor_inputs: List = ['latents'] max_sequence_length: int = 256 ) → ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 或 tuple
参数
- prompt (
str或List[str], 可选) — 指导图像生成的提示或提示。如果未定义，则必须传递prompt_embeds代替。 - prompt_2 (
str或List[str], 可选) — 发送到tokenizer_2和text_encoder_2的提示词或提示词列表。如果未定义，则将使用prompt代替 - prompt_3 (
str或List[str], 可选) — 发送到tokenizer_3和text_encoder_3的提示词或提示词列表。如果未定义，则将使用prompt代替 - height (
int, 可选, 默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的高度（以像素为单位）。默认情况下设置为 1024，以获得最佳效果。 - width (
int, 可选, 默认为 self.unet.config.sample_size * self.vae_scale_factor) — 生成图像的宽度（以像素为单位）。默认情况下设置为 1024，以获得最佳效果。 - num_inference_steps (
int, 可选, 默认为 50) — 降噪步骤的数量。更多的降噪步骤通常会导致更高的图像质量，但推理速度会变慢。 - timesteps (
List[int], 可选) — 用于降噪过程的自定义时间步长，适用于在其set_timesteps方法中支持timesteps参数的调度器。如果未定义，则将使用传递num_inference_steps时的默认行为。必须按降序排列。 - guidance_scale (
float, 可选, 默认为 5.0) — 如 Classifier-Free Diffusion Guidance 中所定义的引导尺度。guidance_scale定义为 Imagen 论文 中公式 2 的w。通过将guidance_scale > 1设置为启用引导尺度。更高的引导尺度鼓励生成与文本prompt密切相关的图像，通常以降低图像质量为代价。 - control_guidance_start (
float或List[float], 可选, 默认为 0.0) — ControlNet 开始应用的总步数的百分比。 - control_guidance_end (
float或List[float], 可选, 默认为 1.0) — ControlNet 停止应用的总步数的百分比。 - control_image (
torch.Tensor,PIL.Image.Image,np.ndarray,List[torch.Tensor],List[PIL.Image.Image],List[np.ndarray], —List[List[torch.Tensor]],List[List[np.ndarray]]或List[List[PIL.Image.Image]]): 用于为生成提供unet指导的 ControlNet 输入条件。如果类型指定为torch.Tensor，则按原样传递给 ControlNet。PIL.Image.Image也可作为图像接受。输出图像的尺寸默认为image的尺寸。如果传递了高度和/或宽度，则会相应地调整image的大小。如果在init中指定了多个 ControlNet，则必须将图像作为列表传递，以便列表的每个元素都可以正确地批处理以作为单个 ControlNet 的输入。 - controlnet_conditioning_scale (
float或List[float], 可选, 默认为 1.0) — ControlNet 的输出在添加到原始unet的残差之前，会乘以controlnet_conditioning_scale。如果在init中指定了多个 ControlNet，则可以将相应的比例设置为列表。 - controlnet_pooled_projections (
torch.FloatTensor形状为(batch_size, projection_dim)) — 从 ControlNet 输入条件的嵌入中投影出的嵌入。 - negative_prompt (
str或List[str], 可选) — 用于不引导图像生成的提示或提示。如果未定义，则必须传递negative_prompt_embeds。在不使用引导时将被忽略（即，如果guidance_scale小于1则被忽略）。 - negative_prompt_2 (
str或List[str], 可选) — 要发送到tokenizer_2和text_encoder_2的用于不引导图像生成的提示或提示。如果未定义，则使用negative_prompt代替 - negative_prompt_3 (
str或List[str], 可选) — 要发送到tokenizer_3和text_encoder_3的用于不引导图像生成的提示或提示。如果未定义，则使用negative_prompt代替 - num_images_per_prompt (
int, 可选, 默认为 1) — 每个提示生成图像的数量。 - generator (
torch.Generator或List[torch.Generator], 可选) — 一个或多个 torch 生成器 用于使生成确定性。 - latents (
torch.FloatTensor, 可选) — 预生成的噪声潜变量，从高斯分布采样，用作图像生成的输入。可用于使用不同的提示调整相同的生成。如果未提供，则潜变量张量将通过使用提供的随机generator采样来生成。 - prompt_embeds (
torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示加权。如果未提供，则文本嵌入将从prompt输入参数生成。 - negative_prompt_embeds (
torch.FloatTensor, 可选) — 预生成的负文本嵌入。可用于轻松调整文本输入，例如 提示加权。如果未提供，则负文本嵌入将从negative_prompt输入参数生成。 - pooled_prompt_embeds (
torch.FloatTensor，可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示加权。如果未提供，则将从prompt输入参数生成池化文本嵌入。 - negative_pooled_prompt_embeds (
torch.FloatTensor，可选) — 预生成的负面池化文本嵌入。可用于轻松调整文本输入，例如提示加权。如果未提供，则将从negative_prompt输入参数生成池化负面negative_prompt_embeds。 - output_type (
str，可选，默认为"pil") — 生成图像的输出格式。在PIL：PIL.Image.Image或np.array之间选择。 - return_dict (
bool，可选，默认为True) — 是否返回~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput而不是普通元组。 - joint_attention_kwargs (
dict，可选) — 如果指定，则传递给AttentionProcessor的关键字参数字典，如diffusers.models.attention_processor中的self.processor定义。 - callback_on_step_end (
Callable，可选) — 在推理期间每个去噪步骤结束时调用的函数。该函数使用以下参数调用：callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。callback_kwargs将包含由callback_on_step_end_tensor_inputs指定的所有张量的列表。 - callback_on_step_end_tensor_inputs (
List，可选) —callback_on_step_end函数的张量输入列表。列表中指定的张量将作为callback_kwargs参数传递。您只能包含管道类._callback_tensor_inputs属性中列出的变量。 - max_sequence_length (
int默认为 256) — 与prompt一起使用的最大序列长度。
返回
~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 或 tuple
如果return_dict为 True，则为~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput，否则为tuple。返回元组时，第一个元素是包含生成图像的列表。
调用管道进行生成时调用的函数。
示例
>>> import torch
>>> from diffusers import StableDiffusion3ControlNetPipeline
>>> from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel
>>> from diffusers.utils import load_image
>>> controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny", torch_dtype=torch.float16)
>>> pipe = StableDiffusion3ControlNetPipeline.from_pretrained(
... "stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet, torch_dtype=torch.float16
... )
>>> pipe.to("cuda")
>>> control_image = load_image("https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg")
>>> prompt = "A girl holding a sign that says InstantX"
>>> image = pipe(prompt, control_image=control_image, controlnet_conditioning_scale=0.7).images[0]
>>> image.save("sd3.png")encode_prompt
< source >( prompt: Union prompt_2: Union prompt_3: Union device: Optional = None num_images_per_prompt: int = 1 do_classifier_free_guidance: bool = True negative_prompt: Union = None negative_prompt_2: Union = None negative_prompt_3: Union = None prompt_embeds: Optional = None negative_prompt_embeds: Optional = None pooled_prompt_embeds: Optional = None negative_pooled_prompt_embeds: Optional = None 参数 str 或 List[str], 可选) — 要编码的提示 str 或 List[str], 可选) — 要发送到 tokenizer_2 和 text_encoder_2 的提示或提示。如果未定义，则所有文本编码器都使用 prompt str 或 List[str], 可选) — 要发送到 tokenizer_3 和 text_encoder_3 的提示或提示。如果未定义，则所有文本编码器都使用 prompt device — (torch.device): torch 设备 int) — 每个提示应生成的图像数量 bool) — 是否使用分类器免费引导 str 或 List[str], 可选) — 不引导图像生成的提示或提示。如果未定义，则必须传递 negative_prompt_embeds。在不使用引导时忽略（即，如果 guidance_scale 小于 1，则忽略）。 str 或 List[str], 可选) — 要发送到 tokenizer_2 和 text_encoder_2 的不引导图像生成的提示或提示。如果未定义，则所有文本编码器都使用 negative_prompt。 str 或 List[str], 可选) — 要发送到 tokenizer_3 和 text_encoder_3 的不引导图像生成的提示或提示。如果未定义，则两个文本编码器都使用 negative_prompt torch.FloatTensor, 可选) — 预生成的文本嵌入。可用于轻松调整文本输入，例如 提示加权。如果未提供，则将从 prompt 输入参数生成文本嵌入。 torch.FloatTensor, 可选) — 预生成的负文本嵌入。可用于轻松调整文本输入，例如 提示加权。如果未提供，则将从 negative_prompt 输入参数生成 negative_prompt_embeds。
torch.FloatTensor，可选) — 预生成的池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，则将根据prompt输入参数生成池化文本嵌入。 torch.FloatTensor，可选) — 预生成的负面池化文本嵌入。可用于轻松调整文本输入，例如提示权重。如果未提供，则将根据negative_prompt输入参数生成池化负面提示嵌入。 int，可选) — 计算提示嵌入时要跳过的 CLIP 层数。值为 1 表示将使用倒数第二层的输出计算提示嵌入。 float，可选) — 如果加载了 LoRA 层，则将应用于文本编码器所有 LoRA 层的 LoRA 比例。 StableDiffusion3PipelineOutput
类 diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput
< 源代码 >( images: Union )
Stable Diffusion 管道的输出类。