Diffusers 文件
帶Flux.1的ControlNet
並獲得增強的文件體驗
開始使用
帶Flux.1的ControlNet
FluxControlNetPipeline是ControlNet在Flux.1上的實現。
ControlNet 由 Lvmin Zhang、Anyi Rao 和 Maneesh Agrawala 在 《為文字到影像擴散模型新增條件控制》 中提出。
使用ControlNet模型，您可以提供額外的控制影像來條件化和控制Stable Diffusion生成。例如，如果您提供深度圖，ControlNet模型將生成一張影像，該影像將保留深度圖中的空間資訊。這是一種更靈活、更準確地控制影像生成過程的方法。
論文摘要如下：
我們提出了ControlNet，這是一種神經網路架構，用於為大型預訓練的文字到影像擴散模型新增空間條件控制。ControlNet鎖定生產就緒的大型擴散模型，並重用它們透過數十億張影像預訓練的深度且魯棒的編碼層作為強大的骨幹網路，以學習多樣化的條件控制集。該神經網路架構透過“零卷積”（零初始化卷積層）連線，這些卷積層從零開始逐步增長引數，並確保不會有有害噪聲影響微調。我們使用Stable Diffusion測試了各種條件控制，例如邊緣、深度、分割、人體姿態等，使用單一或多個條件，有或沒有提示詞。我們表明，ControlNets的訓練對於小型（<50k）和大型（>1m）資料集都非常穩定。大量結果表明，ControlNet可能促進影像擴散模型更廣泛的應用。
此ControlNet程式碼由The InstantX Team實現。您可以在下表中找到Flux-ControlNet的預訓練檢查點
| ControlNet型別 | 開發者 | 連結 |
|---|---|---|
| 邊緣檢測 | The InstantX Team | 連結 |
| 深度 | The InstantX Team | 連結 |
| Union | The InstantX Team | 連結 |
還支援XLabs ControlNets，該模型由XLabs團隊貢獻。
| ControlNet型別 | 開發者 | 連結 |
|---|---|---|
| 邊緣檢測 | XLabs團隊 | 連結 |
| 深度 | XLabs團隊 | 連結 |
| HED | XLabs團隊 | 連結 |
FluxControlNetPipeline
class diffusers.FluxControlNetPipeline
< 來源 >( 排程器: FlowMatchEulerDiscreteScheduler vae: AutoencoderKL text_encoder: CLIPTextModel tokenizer: CLIPTokenizer text_encoder_2: T5EncoderModel tokenizer_2: T5TokenizerFast transformer: FluxTransformer2DModel controlnet: typing.Union[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel, typing.List[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel], typing.Tuple[diffusers.models.controlnets.controlnet_flux.FluxControlNetModel], diffusers.models.controlnets.controlnet_flux.FluxMultiControlNetModel] image_encoder: CLIPVisionModelWithProjection = None feature_extractor: CLIPImageProcessor = None )
引數
- transformer (FluxTransformer2DModel) — 用於對編碼影像潛變數進行去噪的條件Transformer (MMDiT) 架構。
- 排程器 (FlowMatchEulerDiscreteScheduler) — 與
transformer結合使用的排程器，用於對編碼影像潛變數進行去噪。 - vae (AutoencoderKL) — 用於將影像編碼和解碼為潛在表示的變分自編碼器 (VAE) 模型。
- text_encoder (
CLIPTextModel) — CLIP，特別是clip-vit-large-patch14變體。 - text_encoder_2 (
T5EncoderModel) — T5，特別是google/t5-v1_1-xxl變體。 - tokenizer (
CLIPTokenizer) — CLIPTokenizer類的分詞器。 - tokenizer_2 (
T5TokenizerFast) — 第二個分詞器，屬於T5TokenizerFast類。
用於文字到影像生成的 Flux 管道。
參考：https://blackforestlabs.ai/announcing-black-forest-labs/
__call__
< 來源 >( prompt: typing.Union[str, typing.List[str]] = None prompt_2: typing.Union[str, typing.List[str], NoneType] = None negative_prompt: typing.Union[str, typing.List[str]] = None negative_prompt_2: typing.Union[str, typing.List[str], NoneType] = None true_cfg_scale: float = 1.0 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_mode: typing.Union[int, typing.List[int], NoneType] = None controlnet_conditioning_scale: typing.Union[float, typing.List[float]] = 1.0 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 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[typing.List[torch.Tensor]] = None negative_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 negative_ip_adapter_image_embeds: typing.Optional[typing.List[torch.Tensor]] = None negative_prompt_embeds: typing.Optional[torch.FloatTensor] = None negative_pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None output_type: typing.Optional[str] = 'pil' return_dict: bool = True joint_attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = 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 = 512 ) → ~pipelines.flux.FluxPipelineOutput 或 tuple
引數
- prompt (
str或List[str]，可選) — 用於引導影像生成的提示詞。如果未定義，則必須傳入prompt_embeds。 - prompt_2 (
str或List[str]，可選) — 將傳送給tokenizer_2和text_encoder_2的提示詞。如果未定義，將使用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，可選，預設為 7.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]]或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，則可以將相應的比例設定為列表。 - control_mode (
int或List[int]，可選，預設為 None) — 應用ControlNet-Union時的控制模式。 - num_images_per_prompt (
int，可選，預設為 1) — 每個提示詞生成的影像數量。 - generator (
torch.Generator或List[torch.Generator], 可選) — 一個或多個 torch 生成器，用於使生成具有確定性。 - latents (
torch.FloatTensor, 可選) — 預生成的噪聲潛在變數，從高斯分佈中取樣，用作影像生成的輸入。可用於使用不同的提示來調整相同的生成。如果未提供，將使用提供的隨機generator進行取樣以生成潛在張量。 - prompt_embeds (
torch.FloatTensor, 可選) — 預生成的文字嵌入。可用於輕鬆調整文字輸入，例如提示權重。如果未提供，將從prompt輸入引數生成文字嵌入。 - pooled_prompt_embeds (
torch.FloatTensor, 可選) — 預生成的池化文字嵌入。可用於輕鬆調整文字輸入，例如提示權重。如果未提供，將從prompt輸入引數生成池化文字嵌入。 - ip_adapter_image — (
PipelineImageInput, 可選)：用於 IP Adapters 的可選影像輸入。 - ip_adapter_image_embeds (
List[torch.Tensor], 可選) — IP-Adapter 預生成的影像嵌入。它應該是一個列表，長度與 IP-adapter 的數量相同。每個元素都應該是一個形狀為(batch_size, num_images, emb_dim)的張量。如果未提供，嵌入將從ip_adapter_image輸入引數計算。 - negative_ip_adapter_image — (
PipelineImageInput, 可選)：用於 IP Adapters 的可選影像輸入。 - negative_ip_adapter_image_embeds (
List[torch.Tensor], 可選) — IP-Adapter 預生成的影像嵌入。它應該是一個列表，長度與 IP-adapter 的數量相同。每個元素都應該是一個形狀為(batch_size, num_images, emb_dim)的張量。如果未提供，嵌入將從ip_adapter_image輸入引數計算。 - output_type (
str, 可選, 預設為"pil") — 生成影像的輸出格式。選擇 PIL:PIL.Image.Image或np.array。 - return_dict (
bool, 可選, 預設為True) — 是否返回~pipelines.flux.FluxPipelineOutput而不是普通元組。 - 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預設為 512) — 與prompt一起使用的最大序列長度。
返回
~pipelines.flux.FluxPipelineOutput 或 tuple
如果 return_dict 為 True，則為 ~pipelines.flux.FluxPipelineOutput，否則為 tuple。返回元組時，第一個元素是生成的影像列表。
呼叫管道進行生成時呼叫的函式。
示例
>>> import torch
>>> from diffusers.utils import load_image
>>> from diffusers import FluxControlNetPipeline
>>> from diffusers import FluxControlNetModel
>>> base_model = "black-forest-labs/FLUX.1-dev"
>>> controlnet_model = "InstantX/FLUX.1-dev-controlnet-canny"
>>> controlnet = FluxControlNetModel.from_pretrained(controlnet_model, torch_dtype=torch.bfloat16)
>>> pipe = FluxControlNetPipeline.from_pretrained(
... base_model, controlnet=controlnet, torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> control_image = load_image("https://huggingface.co/InstantX/SD3-Controlnet-Canny/resolve/main/canny.jpg")
>>> prompt = "A girl in city, 25 years old, cool, futuristic"
>>> image = pipe(
... prompt,
... control_image=control_image,
... control_guidance_start=0.2,
... control_guidance_end=0.8,
... controlnet_conditioning_scale=1.0,
... num_inference_steps=28,
... guidance_scale=3.5,
... ).images[0]
>>> image.save("flux.png")encode_prompt
< 原始檔 >( prompt: typing.Union[str, typing.List[str]] prompt_2: typing.Union[str, typing.List[str]] device: typing.Optional[torch.device] = None num_images_per_prompt: int = 1 prompt_embeds: typing.Optional[torch.FloatTensor] = None pooled_prompt_embeds: typing.Optional[torch.FloatTensor] = None max_sequence_length: int = 512 lora_scale: typing.Optional[float] = None )
引數
- prompt (
str或List[str], 可選) — 待編碼的提示詞。 - prompt_2 (
str或List[str], 可選) — 要傳送到tokenizer_2和text_encoder_2的提示詞。如果未定義，所有文字編碼器都將使用prompt。 - device — (
torch.device)：torch 裝置。 - num_images_per_prompt (
int) — 每個提示詞應生成的影像數量。 - prompt_embeds (
torch.FloatTensor, 可選) — 預生成的文字嵌入。可用於輕鬆調整文字輸入，例如提示權重。如果未提供，將從prompt輸入引數生成文字嵌入。 - pooled_prompt_embeds (
torch.FloatTensor, 可選) — 預生成的池化文字嵌入。可用於輕鬆調整文字輸入，例如提示權重。如果未提供，將從prompt輸入引數生成池化文字嵌入。 - clip_skip (
int, 可選) — 在計算提示嵌入時從 CLIP 跳過的層數。值為 1 表示將使用倒數第二層的輸出計算提示嵌入。 - lora_scale (
float, 可選) — 應用於文字編碼器所有 LoRA 層的 LoRA 比例（如果已載入 LoRA 層）。
FluxPipelineOutput
類 diffusers.pipelines.flux.pipeline_output.FluxPipelineOutput
< 原始檔 >( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )
Stable Diffusion 管道的輸出類。