Hugging Face 的 LOGO

Diffusers 文件

ControlNet 與 Stable Diffusion 3

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

ControlNet 與 Stable Diffusion 3

LoRA

StableDiffusion3ControlNetPipeline 是 ControlNet 在 Stable Diffusion 3 上的實現。

ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 《為文字到影像擴散模型新增條件控制》 中提出。

使用 ControlNet 模型，您可以提供一個額外的控制影像來調整和控制 Stable Diffusion 的生成。例如，如果您提供深度圖，ControlNet 模型將生成一張保留深度圖空間資訊的影像。這是一種更靈活、更準確地控制影像生成過程的方法。

論文摘要如下：

我們提出了 ControlNet，一種神經網路架構，用於為大型、預訓練的文字到影像擴散模型新增空間條件控制。ControlNet 鎖定生產級大型擴散模型，並重新利用其經過數十億影像預訓練的深層且魯棒的編碼層作為強大的骨幹，以學習多樣化的條件控制。該神經網路架構與“零卷積”（零初始化卷積層）連線，這些卷積層逐步從零增長引數，並確保不會有害噪聲影響微調。我們使用 Stable Diffusion 測試了各種條件控制，例如邊緣、深度、分割、人體姿態等，可以使用單個或多個條件，帶提示或不帶提示。我們證明了 ControlNet 的訓練對於小型（<50k）和大型（>1m）資料集都非常穩定。大量結果表明，ControlNet 可以促進影像擴散模型在更廣泛的應用中進行控制。

此 ControlNet 程式碼主要由 InstantX 團隊實現。與影像修復相關的程式碼由 阿里巴巴媽媽創意團隊開發。您可以在下表中找到 SD3-ControlNet 的預訓練檢查點

ControlNet 型別 開發者 連結
邊緣檢測 InstantX 團隊 連結
深度 InstantX 團隊 連結
姿態 InstantX 團隊 連結
平鋪 InstantX 團隊 連結
影像修復 阿里巴巴媽媽創意團隊 連結

務必檢視排程器指南，瞭解如何探索排程器速度和質量之間的權衡，並參閱跨流水線重用元件部分，瞭解如何有效地將相同元件載入到多個流水線中。

StableDiffusion3ControlNetPipeline

類 diffusers.StableDiffusion3ControlNetPipeline

< >

( 轉換器: SD3Transformer2DModel 排程器: FlowMatchEulerDiscreteScheduler vae: AutoencoderKL 文字編碼器: CLIPTextModelWithProjection 分詞器: CLIPTokenizer 文字編碼器_2: CLIPTextModelWithProjection 分詞器_2: CLIPTokenizer 文字編碼器_3: T5EncoderModel 分詞器_3: T5TokenizerFast ControlNet: typing.Union[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel, typing.List[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel], typing.Tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel], diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModel] 影像編碼器: typing.Optional[transformers.models.siglip.modeling_siglip.SiglipVisionModel] = None 特徵提取器: typing.Optional[transformers.models.siglip.image_processing_siglip.SiglipImageProcessor] = None )

引數

  • 轉換器 (SD3Transformer2DModel) — 用於對編碼影像潛變數進行去噪的條件轉換器 (MMDiT) 架構。
  • 排程器 (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 變體。
  • 分詞器 (CLIPTokenizer) — CLIPTokenizer 類的分詞器。
  • tokenizer_2 (CLIPTokenizer) — 第二個 CLIPTokenizer 類的分詞器。
  • tokenizer_3 (T5TokenizerFast) — T5Tokenizer 類的分詞器。
  • controlnet (SD3ControlNetModel 或 List[SD3ControlNetModel] 或 SD3MultiControlNetModel) — 在去噪過程中為 unet 提供額外的條件。如果將多個 ControlNet 設定為列表，則每個 ControlNet 的輸出將相加，以建立一個組合的額外條件。
  • 影像編碼器 (SiglipVisionModel, 可選) — 用於 IP Adapter 的預訓練視覺模型。
  • 特徵提取器 (SiglipImageProcessor, 可選) — 用於 IP Adapter 的影像處理器。

__call__

< >

( prompt: typing.Union[str, typing.List[str]] = None prompt_2: typing.Union[str, typing.List[str], NoneType] = None prompt_3: typing.Union[str, typing.List[str], NoneType] = None height: typing.Optional[int] = None width: typing.Optional[int] = None num_inference_steps: int = 28 sigmas: typing.Optional[typing.List[float]] = None guidance_scale: float = 7.0 control_guidance_start: typing.Union[float, typing.List[float]] = 0.0 control_guidance_end: typing.Union[float, typing.List[float]] = 1.0 control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] = None controlnet_conditioning_scale: typing.Union[float, typing.List[float]] = 1.0 controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = None negative_prompt: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_2: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_3: typing.Union[str, typing.List[str], NoneType] = None num_images_per_prompt: typing.Optional[int] = 1 generator: typing.Union[torch._C.Generator, typing.List[torch._C.Generator], NoneType] = None latents: typing.Optional[torch.FloatTensor] = None prompt_embeds: typing.Optional[torch.FloatTensor] = None negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor], NoneType] = None ip_adapter_image_embeds: typing.Optional[torch.Tensor] = None output_type: typing.Optional[str] = 'pil' return_dict: bool = True joint_attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None clip_skip: typing.Optional[int] = None callback_on_step_end: typing.Optional[typing.Callable[[int, int, typing.Dict], NoneType]] = None callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'] max_sequence_length: int = 256 ) → ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 或 tuple

引數

  • 提示詞 (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) — 去噪步驟的數量。更多的去噪步驟通常會帶來更高質量的影像，但會以更慢的推理速度為代價。
  • sigmas (List[float], 可選) — 用於去噪過程的自定義 sigmas，適用於支援其 set_timesteps 方法中 sigmas 引數的排程器。如果未定義，將使用傳遞 num_inference_steps 時的預設行為。
  • guidance_scale (float, 可選, 預設為 5.0) — Classifier-Free Diffusion Guidance 中定義的引導比例。guidance_scale 定義為 Imagen Paper 方程 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]] or List[List[PIL.Image.Image]]): ControlNet 輸入條件，用於為 unet 提供生成指導。如果型別指定為 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 (形狀為 (batch_size, projection_dim) 的 torch.FloatTensor) — 從 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 輸入引數生成。
  • ip_adapter_image (PipelineImageInput, 可選) — 用於 IP Adapters 的可選影像輸入。
  • ip_adapter_image_embeds (torch.Tensor, 可選) — 為 IP-Adapter 預先生成的影像嵌入。應為形狀 (batch_size, num_images, emb_dim) 的張量。如果 do_classifier_free_guidance 設定為 True，則應包含負影像嵌入。如果未提供，則根據 ip_adapter_image 輸入引數計算嵌入。
  • output_type (str, 可選, 預設為 "pil") — 生成影像的輸出格式。選擇 PIL: PIL.Image.Image 或 np.array。
  • return_dict (bool, 可選, 預設為 True) — 是否返回 ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 而不是普通元組。
  • joint_attention_kwargs (dict, 可選) — 一個 kwargs 字典，如果指定，將傳遞給 diffusers.models.attention_processor 中定義的 self.processor 的 AttentionProcessor。
  • 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/datasets/hf-internal-testing/diffusers-images/resolve/main/sd_controlnet/bird_canny.png"
... )
>>> prompt = "A bird in space"
>>> image = pipe(
...     prompt, control_image=control_image, height=1024, width=768, controlnet_conditioning_scale=0.7
... ).images[0]
>>> image.save("sd3.png")

encode_image

< >

( 影像: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] 裝置: device ) → torch.Tensor

引數

  • image (PipelineImageInput) — 要編碼的輸入影像。
  • device — (torch.device): Torch 裝置。

返回

torch.Tensor

編碼後的影像特徵表示。

使用預訓練的影像編碼器將給定影像編碼為特徵表示。

encode_prompt

< >

( 提示: typing.Union[str, typing.List[str]] 提示_2: typing.Union[str, typing.List[str]] 提示_3: typing.Union[str, typing.List[str]] 裝置: typing.Optional[torch.device] = None 每個提示的影像數量: int = 1 do_classifier_free_guidance: bool = True 負提示: typing.Union[str, typing.List[str], NoneType] = None 負提示_2: typing.Union[str, typing.List[str], NoneType] = None 負提示_3: typing.Union[str, typing.List[str], NoneType] = None 提示嵌入: typing.Optional[torch.FloatTensor] = None 負提示嵌入: typing.Optional[torch.FloatTensor] = None 池化提示嵌入: typing.Optional[torch.FloatTensor] = None 負池化提示嵌入: typing.Optional[torch.FloatTensor] = None clip_skip: typing.Optional[int] = None 最大序列長度: int = 256 lora_scale: typing.Optional[float] = None )

引數

  • prompt (str 或 List[str], 可選) — 要編碼的提示。
  • prompt_2 (str 或 List[str], 可選) — 要傳送到 tokenizer_2 和 text_encoder_2 的提示。如果未定義，則在所有文字編碼器中都使用 prompt。
  • prompt_3 (str 或 List[str], 可選) — 要傳送到 tokenizer_3 和 text_encoder_3 的提示。如果未定義，則在所有文字編碼器中都使用 prompt。
  • device — (torch.device): torch 裝置。
  • num_images_per_prompt (int) — 每個提示應生成的影像數量。
  • do_classifier_free_guidance (bool) — 是否使用分類器自由指導。
  • 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。
  • 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 輸入引數生成。
  • clip_skip (int, 可選) — 在計算提示嵌入時，從 CLIP 跳過的層數。值為 1 表示使用倒數第二層的輸出計算提示嵌入。
  • lora_scale (float, 可選) — 將應用於文字編碼器所有 LoRA 層的 LoRA 比例（如果載入了 LoRA 層）。

prepare_ip_adapter_image_embeds

< >

( ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor], NoneType] = None ip_adapter_image_embeds: typing.Optional[torch.Tensor] = None 裝置: typing.Optional[torch.device] = None 每個提示的影像數量: int = 1 do_classifier_free_guidance: bool = True )

引數

  • ip_adapter_image (PipelineImageInput, 可選) — 用於從 IP-Adapter 中提取特徵的輸入影像。
  • ip_adapter_image_embeds (torch.Tensor, 可選) — 預計算的影像嵌入。
  • device — (torch.device, 可選): Torch 裝置。
  • num_images_per_prompt (int, 預設為 1) — 每個提示應生成的影像數量。
  • do_classifier_free_guidance (bool, 預設為 True) — 是否使用分類器自由指導。

準備影像嵌入以供 IP-Adapter 使用。

必須傳遞 ip_adapter_image 或 ip_adapter_image_embeds。

StableDiffusion3ControlNetInpaintingPipeline

class diffusers.StableDiffusion3ControlNetInpaintingPipeline

< >

( 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: typing.Union[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel, typing.List[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel], typing.Tuple[diffusers.models.controlnets.controlnet_sd3.SD3ControlNetModel], diffusers.models.controlnets.controlnet_sd3.SD3MultiControlNetModel] image_encoder: SiglipModel = None feature_extractor: typing.Optional[transformers.models.siglip.image_processing_siglip.SiglipImageProcessor] = None )

引數

  • 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) — 在去噪過程中為 `transformer` 提供額外的條件。如果將多個 ControlNet 設定為列表，則每個 ControlNet 的輸出將被相加，以建立一個組合的額外條件。
  • image_encoder (PreTrainedModel, 可選) — 用於 IP Adapter 的預訓練視覺模型。
  • feature_extractor (BaseImageProcessor, 可選) — 用於 IP Adapter 的影像處理器。

__call__

< >

( prompt: typing.Union[str, typing.List[str]] = None prompt_2: typing.Union[str, typing.List[str], NoneType] = None prompt_3: typing.Union[str, typing.List[str], NoneType] = None height: typing.Optional[int] = None width: typing.Optional[int] = None num_inference_steps: int = 28 sigmas: typing.Optional[typing.List[float]] = None guidance_scale: float = 7.0 control_guidance_start: typing.Union[float, typing.List[float]] = 0.0 control_guidance_end: typing.Union[float, typing.List[float]] = 1.0 control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] = None control_mask: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] = None controlnet_conditioning_scale: typing.Union[float, typing.List[float]] = 1.0 controlnet_pooled_projections: typing.Optional[torch.FloatTensor] = None negative_prompt: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_2: typing.Union[str, typing.List[str], NoneType] = None negative_prompt_3: typing.Union[str, typing.List[str], NoneType] = None num_images_per_prompt: typing.Optional[int] = 1 generator: typing.Union[torch._C.Generator, typing.List[torch._C.Generator], NoneType] = None latents: typing.Optional[torch.FloatTensor] = None prompt_embeds: typing.Optional[torch.FloatTensor] = None negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor], NoneType] = None ip_adapter_image_embeds: typing.Optional[torch.Tensor] = None output_type: typing.Optional[str] = 'pil' return_dict: bool = True joint_attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None clip_skip: typing.Optional[int] = None callback_on_step_end: typing.Optional[typing.Callable[[int, int, typing.Dict], NoneType]] = None callback_on_step_end_tensor_inputs: typing.List[str] = ['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) — 去噪步數。更多的去噪步數通常會帶來更高質量的影像，但推理速度會變慢。
  • sigmas (List[float], 可選) — 用於去噪過程的自定義 sigmas，與支援 `sigmas` 引數的排程器結合使用（在它們的 `set_timesteps` 方法中）。如果未定義，則在傳入 `num_inference_steps` 時將使用預設行為。
  • guidance_scale (float, 可選, 預設為 5.0) — Classifier-Free Diffusion Guidance 中定義的引導比例。`guidance_scale` 在 Imagen Paper 的公式 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]) — 要進行修復的影像（需要使用 `control_mask` 遮罩的部分將根據 `prompt` 重新繪製）。對於 numpy 陣列和 pytorch 張量，預期值範圍在 `[0, 1]` 之間。如果是張量或張量列表，預期形狀應為 `(B, C, H, W)`。如果是 numpy 陣列或陣列列表，預期形狀應為 `(B, H, W, C)` 或 `(H, W, C)`。
  • control_mask (torch.Tensor, PIL.Image.Image, np.ndarray, List[torch.Tensor], List[PIL.Image.Image], List[np.ndarray]) — 影像、numpy 陣列或張量，表示用於遮罩 `image` 的影像批次。遮罩中的白色畫素將被重新繪製，而黑色畫素將被保留。如果 `mask_image` 是 PIL 影像，它在使用前將轉換為單通道（亮度）。如果它是 numpy 陣列或 pytorch 張量，它應該包含一個顏色通道（L）而不是 3，因此 pytorch 張量的預期形狀為 `(B, 1, H, W)`。對於 numpy 陣列，預期形狀為 `(B, H, W, 1)`、`(B, H, W)`、`(H, W, 1)` 或 `(H, W)`。
  • controlnet_conditioning_scale (float 或 List[float], 可選, 預設為 1.0) — ControlNet 的輸出在新增到原始 `unet` 中的殘差之前，乘以 `controlnet_conditioning_scale`。如果在 `init` 中指定了多個 ControlNet，則可以將相應的比例設定為列表。
  • controlnet_pooled_projections (形狀為 (batch_size, projection_dim) 的 torch.FloatTensor) — 從 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_embeds` 將從 `negative_prompt` 輸入引數生成。
  • pooled_prompt_embeds (torch.FloatTensor, 可選) — 預生成的池化文字嵌入。可用於輕鬆調整文字輸入，例如提示詞權重。如果未提供，池化文字嵌入將從 `prompt` 輸入引數生成。
  • negative_pooled_prompt_embeds (torch.FloatTensor, 可選) — 預生成的負池化文字嵌入。可用於輕鬆調整文字輸入，例如提示詞權重。如果未提供，池化負 `negative_prompt_embeds` 將從 `negative_prompt` 輸入引數生成。
  • ip_adapter_image (PipelineImageInput, 可選) — 與 IP Adapters 配合使用的可選影像輸入。
  • ip_adapter_image_embeds (torch.Tensor, 可選) — 預生成的 IP-Adapter 影像嵌入。應為形狀 `(batch_size, num_images, emb_dim)` 的張量。如果 `do_classifier_free_guidance` 設定為 `True`，則應包含負影像嵌入。如果未提供，嵌入將從 `ip_adapter_image` 輸入引數計算。
  • output_type (str, 可選, 預設為 "pil") — 生成影像的輸出格式。在 PIL: PIL.Image.Image 或 np.array 之間選擇。
  • return_dict (bool, 可選, 預設為 True) — 是否返回 ~pipelines.stable_diffusion_xl.StableDiffusionXLPipelineOutput 而不是普通的元組。
  • joint_attention_kwargs (dict, 可選) — 一個 kwargs 字典，如果指定，將傳遞給 diffusers.models.attention_processor 中定義的 `self.processor` 的 `AttentionProcessor`。
  • 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.utils import load_image, check_min_version
>>> from diffusers.pipelines import StableDiffusion3ControlNetInpaintingPipeline
>>> from diffusers.models.controlnet_sd3 import SD3ControlNetModel

>>> controlnet = SD3ControlNetModel.from_pretrained(
...     "alimama-creative/SD3-Controlnet-Inpainting", use_safetensors=True, extra_conditioning_channels=1
... )
>>> pipe = StableDiffusion3ControlNetInpaintingPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-3-medium-diffusers",
...     controlnet=controlnet,
...     torch_dtype=torch.float16,
... )
>>> pipe.text_encoder.to(torch.float16)
>>> pipe.controlnet.to(torch.float16)
>>> pipe.to("cuda")

>>> image = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog.png"
... )
>>> mask = load_image(
...     "https://huggingface.co/alimama-creative/SD3-Controlnet-Inpainting/resolve/main/images/dog_mask.png"
... )
>>> width = 1024
>>> height = 1024
>>> prompt = "A cat is sitting next to a puppy."
>>> generator = torch.Generator(device="cuda").manual_seed(24)
>>> res_image = pipe(
...     negative_prompt="deformed, distorted, disfigured, poorly drawn, bad anatomy, wrong anatomy, extra limb, missing limb, floating limbs, mutated hands and fingers, disconnected limbs, mutation, mutated, ugly, disgusting, blurry, amputation, NSFW",
...     prompt=prompt,
...     height=height,
...     width=width,
...     control_image=image,
...     control_mask=mask,
...     num_inference_steps=28,
...     generator=generator,
...     controlnet_conditioning_scale=0.95,
...     guidance_scale=7,
... ).images[0]
>>> res_image.save(f"sd3.png")

encode_image

< >

( 影像: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor]] 裝置: device ) → torch.Tensor

引數

  • image (PipelineImageInput) — 要編碼的輸入影像。
  • device — (torch.device): Torch 裝置。

返回

torch.Tensor

編碼後的影像特徵表示。

使用預訓練的影像編碼器將給定影像編碼為特徵表示。

encode_prompt

< >

( 提示: typing.Union[str, typing.List[str]] 提示_2: typing.Union[str, typing.List[str]] 提示_3: typing.Union[str, typing.List[str]] 裝置: typing.Optional[torch.device] = None 每個提示的影像數量: int = 1 do_classifier_free_guidance: bool = True 負提示: typing.Union[str, typing.List[str], NoneType] = None 負提示_2: typing.Union[str, typing.List[str], NoneType] = None 負提示_3: typing.Union[str, typing.List[str], NoneType] = None 提示嵌入: typing.Optional[torch.FloatTensor] = None 負提示嵌入: typing.Optional[torch.FloatTensor] = None 池化提示嵌入: typing.Optional[torch.FloatTensor] = None 負池化提示嵌入: typing.Optional[torch.FloatTensor] = None clip_skip: typing.Optional[int] = None 最大序列長度: int = 256 lora_scale: typing.Optional[float] = None )

引數

  • prompt (str 或 List[str], 可選) — 要編碼的提示詞。
  • prompt_2 (str 或 List[str], 可選) — 將傳送到 `tokenizer_2` 和 `text_encoder_2` 的提示詞或提示詞列表。如果未定義，所有文字編碼器都將使用 `prompt`。
  • prompt_3 (str 或 List[str], 可選) — 要傳送到 tokenizer_3 和 text_encoder_3 的提示詞。如果未定義，則在所有文字編碼器中使用 prompt。
  • device — (torch.device): torch 裝置
  • num_images_per_prompt (int) — 每個提示詞應生成的影像數量
  • do_classifier_free_guidance (bool) — 是否使用分類器自由引導
  • 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。
  • 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 輸入引數生成池化負向提示詞嵌入。
  • clip_skip (int, 可選) — 計算提示詞嵌入時要跳過的 CLIP 層數。值為 1 表示將使用倒數第二層的輸出計算提示詞嵌入。
  • lora_scale (float, 可選) — 將應用於文字編碼器所有 LoRA 層的 LoRA 縮放因子（如果 LoRA 層已載入）。

prepare_ip_adapter_image_embeds

< >

( ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, typing.List[PIL.Image.Image], typing.List[numpy.ndarray], typing.List[torch.Tensor], NoneType] = None ip_adapter_image_embeds: typing.Optional[torch.Tensor] = None 裝置: typing.Optional[torch.device] = None 每個提示的影像數量: int = 1 do_classifier_free_guidance: bool = True )

引數

  • ip_adapter_image (PipelineImageInput, 可選) — 用於 IP-Adapter 提取特徵的輸入影像。
  • ip_adapter_image_embeds (torch.Tensor, 可選) — 預計算的影像嵌入。
  • device — (torch.device, 可選): Torch 裝置。
  • num_images_per_prompt (int, 預設為 1) — 每個提示詞應生成的影像數量。
  • do_classifier_free_guidance (bool, 預設為 True) — 是否使用分類器自由引導。

準備影像嵌入以供 IP-Adapter 使用。

必須傳遞 ip_adapter_image 或 ip_adapter_image_embeds。

StableDiffusion3PipelineOutput

class diffusers.pipelines.stable_diffusion_3.pipeline_output.StableDiffusion3PipelineOutput

< >

( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )

引數

  • images (List[PIL.Image.Image] 或 np.ndarray) — 經過去噪的 PIL 影像列表，長度為 batch_size，或形狀為 (batch_size, height, width, num_channels) 的 numpy 陣列。PIL 影像或 numpy 陣列表示擴散管道的去噪影像。

Stable Diffusion 管道的輸出類。

< > 在 GitHub 上更新

←ControlNet with Hunyuan-DiT ControlNet with Stable Diffusion XL→
© . This site is unofficial and not affiliated with Hugging Face, Inc.