hf-doc-build/doc / diffusers /main /id /api /pipelines /controlnet_union.md

|

82 kB

ControlNetUnion

ControlNetUnionModel adalah implementasi ControlNet untuk Stable Diffusion XL.

Model ControlNet diperkenalkan dalam ControlNetPlus oleh xinsir6. Model ini mendukung beberapa input kondisioning tanpa meningkatkan komputasi.

Kami merancang arsitektur baru yang dapat mendukung lebih dari 10 jenis kontrol dalam pembuatan gambar dari teks bersyarat dan mampu menghasilkan gambar beresolusi tinggi yang secara visual setara dengan midjourney. Jaringan ini didasarkan pada arsitektur ControlNet asli; kami mengusulkan dua modul baru untuk: 1 Memperluas ControlNet asli agar mendukung kondisi gambar yang berbeda menggunakan parameter jaringan yang sama. 2 Mendukung input kondisi ganda tanpa meningkatkan offload komputasi, yang sangat penting bagi desainer yang ingin mengedit gambar secara detail; kondisi yang berbeda menggunakan encoder kondisi yang sama, tanpa menambah komputasi atau parameter ekstra.

StableDiffusionXLControlNetUnionPipeline[[diffusers.StableDiffusionXLControlNetUnionPipeline]]

diffusers.StableDiffusionXLControlNetUnionPipeline[[diffusers.StableDiffusionXLControlNetUnionPipeline]]

diffusers.StableDiffusionXLControlNetUnionPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet_union.ControlNetUnionModel | list[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | tuple[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | diffusers.models.controlnets.multicontrolnet_union.MultiControlNetUnionModel, scheduler: KarrasDiffusionSchedulers, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None)

Sumber

Parameter:

vae (AutoencoderKL) : Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.

text_encoder (CLIPTextModel) : text-encoder beku (clip-vit-large-patch14).

text_encoder_2 (CLIPTextModelWithProjection) : Text-encoder beku kedua (laion/CLIP-ViT-bigG-14-laion2B-39B-b160k).

tokenizer (CLIPTokenizer) : Sebuah CLIPTokenizer untuk melakukan tokenisasi teks.

tokenizer_2 (CLIPTokenizer) : Sebuah CLIPTokenizer untuk melakukan tokenisasi teks.

unet (UNet2DConditionModel) : Sebuah UNet2DConditionModel untuk menghilangkan noise dari latens gambar yang telah dikodekan.

controlnet (ControlNetUnionModel) : Provides additional conditioning to the unet` during the denoising process.

scheduler (SchedulerMixin) : Penjadwal yang digunakan bersama unet untuk menghilangkan noise pada latens gambar yang telah dikodekan. Bisa berupa DDIMScheduler, LMSDiscreteScheduler, atau PNDMScheduler.

force_zeros_for_empty_prompt (bool, opsional, defaultnya "True") : Apakah embedding prompt negatif harus selalu diatur ke 0. Lihat juga konfigurasi dari stabilityai/stable-diffusion-xl-base-1-0.

add_watermarker (bool, opsional) : Apakah akan menggunakan pustaka invisible_watermark untuk memberi tanda air pada gambar keluaran. Jika tidak didefinisikan, nilainya secara default menjadi True jika paket tersebut terinstal; jika tidak, tidak ada penanda air yang digunakan.

Pipeline untuk generasi teks-ke-gambar menggunakan Stable Diffusion XL dengan panduan ControlNet.

Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

Pipeline juga mewarisi metode pemuatan berikut:

load_textual_inversion() untuk memuat embedding textual inversion
load_lora_weights() untuk memuat bobot LoRA
save_lora_weights() untuk menyimpan bobot LoRA
untuk memuat file .ckpt dengan from_single_file()
load_ip_adapter() untuk memuat IP Adapter

call[[diffusers.StableDiffusionXLControlNetUnionPipeline.call]]

__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]]] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, timesteps: list[int] = None, sigmas: list[float] = None, denoising_end: float | None = None, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 1.0, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_mode: int | list[int] | list[list[int]] | None = None, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])

Sumber

Parameter:

prompt (str atau list[str], opsional) : Prompt atau prompt-prompt untuk memandu generasi gambar. Jika tidak didefinisikan, Anda perlu meneruskan prompt_embeds.

prompt_2 (str atau list[str], opsional) : Prompt atau prompt yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, prompt digunakan di kedua text-encoder.

control_image (PipelineImageInput atau list[PipelineImageInput], opsional) : Kondisi input ControlNet untuk memberikan panduan kepada unet dalam proses generasi. Jika tipe ditentukan sebagai torch.Tensor, nilai tersebut diteruskan ke ControlNet apa adanya. PIL.Image.Image juga dapat diterima sebagai gambar. Dimensi gambar output secara default mengikuti dimensi image. Jika tinggi dan/atau lebar diberikan, image akan di-resize sesuai. Jika beberapa ControlNet ditentukan dalam init, gambar harus diteruskan sebagai daftar sehingga setiap elemen daftar dapat di-batch dengan benar untuk input ke satu ControlNet.

height (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) : Tinggi gambar yang dihasilkan dalam piksel. Nilai di bawah 512 piksel tidak akan berfungsi dengan baik untuk stabilityai/stable-diffusion-xl-base-1.0 dan checkpoint yang tidak secara khusus dihaluskan pada resolusi rendah.

width (int, opsional, defaultnya self.unet.config.sample_size * self.vae_scale_factor) : Lebar gambar yang dihasilkan dalam piksel. Nilai di bawah 512 piksel tidak akan berfungsi dengan baik untuk stabilityai/stable-diffusion-xl-base-1.0 dan checkpoint yang tidak secara khusus dihaluskan pada resolusi rendah.

num_inference_steps (int, opsional, defaultnya 50) : Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.

timesteps (list[int], opsional) : Timesteps kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen timesteps di metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan. Harus dalam urutan menurun.

sigmas (list[float], opsional) : Sigmas kustom untuk digunakan dalam proses denoising dengan scheduler yang mendukung argumen sigmas di metode set_timesteps mereka. Jika tidak didefinisikan, perilaku default saat num_inference_steps diteruskan akan digunakan.

denoising_end (float, opsional) : Jika ditentukan, menentukan fraksi (antara 0.0 dan 1.0) dari total proses denoising yang harus diselesaikan sebelum proses tersebut dihentikan secara dini secara sengaja. Akibatnya, sampel yang dikembalikan masih akan mempertahankan sejumlah besar noise, sebagaimana ditentukan oleh langkah-langkah diskrit yang dipilih oleh scheduler. Parameter denoising_end sebaiknya digunakan ketika pipeline ini merupakan bagian dari setup multi-pipeline "Mixture of Denoisers", seperti yang diuraikan dalam Refining the Image Output

guidance_scale (float, opsional, default 5.0) : Nilai guidance scale yang lebih tinggi mendorong model untuk menghasilkan gambar yang sangat terkait dengan prompt teks, dengan mengorbankan kualitas gambar yang lebih rendah. Guidance scale diaktifkan ketika guidance_scale > 1.

negative_prompt (str atau list[str], opsional) : Prompt atau prompt-prompt untuk mengarahkan apa yang tidak boleh disertakan dalam pembuatan gambar. Jika tidak didefinisikan, Anda perlu meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan panduan (guidance_scale < 1).

negative_prompt_2 (str atau list[str], opsional) : Prompt atau prompt-prompt untuk mengarahkan apa yang tidak boleh disertakan dalam pembuatan gambar. Ini dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, negative_prompt digunakan di kedua text-encoder.

num_images_per_prompt (int, opsional, default 1) : Jumlah gambar yang akan dihasilkan per prompt.

eta (float, opsional, default 0.0) : Bersesuaian dengan parameter eta (η) dari paper DDIM. Hanya berlaku untuk DDIMScheduler, dan diabaikan pada scheduler lainnya.

generator (torch.Generator atau list[torch.Generator], opsional) : Sebuah torch.Generator untuk membuat proses generasi menjadi deterministik.

latents (torch.Tensor, opsional) : Laten berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor laten akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.

prompt_embeds (torch.Tensor, opsional) : Embedding teks yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (pemberian bobot pada prompt). Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.

negative_prompt_embeds (torch.Tensor, opsional) : Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (pemberian bobot pada prompt). Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.

pooled_prompt_embeds (torch.Tensor, opsional) : Embedding teks pooled yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (pemberian bobot pada prompt). Jika tidak disediakan, embedding teks pooled akan dihasilkan dari argumen input prompt.

negative_pooled_prompt_embeds (torch.Tensor, opsional) : Embedding teks negatif yang sudah dipooling sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (penimbangan prompt). Jika tidak disediakan, negative_prompt_embeds yang dipooling akan dihasilkan dari argumen input negative_prompt.

ip_adapter_image : (PipelineImageInput, opsional): Input gambar opsional untuk bekerja dengan IP Adapters.

ip_adapter_image_embeds (list[torch.Tensor], opsional) : Embedding gambar yang telah dibuat sebelumnya untuk IP-Adapter. Ini harus berupa daftar dengan panjang yang sama dengan jumlah IP-adapter. Setiap elemen harus berupa tensor dengan bentuk (batch_size, num_images, emb_dim). Embedding gambar negatif harus disertakan jika do_classifier_free_guidance diatur ke True. Jika tidak disediakan, embedding dihitung dari argumen input ip_adapter_image.

output_type (str, opsional, defaultnya "pil") : Format output dari gambar yang dihasilkan. Pilih antara PIL.Image atau np.array.

return_dict (bool, opsional, defaultnya True) : Apakah akan mengembalikan StableDiffusionPipelineOutput alih-alih tuple biasa.

cross_attention_kwargs (dict, opsional) : Kamus kwargs yang jika ditentukan akan diteruskan ke AttentionProcessor seperti yang didefinisikan dalam self.processor.

controlnet_conditioning_scale (float atau list[float], opsional, default 1.0) : Output dari ControlNet dikalikan dengan controlnet_conditioning_scale sebelum ditambahkan ke residual di unet asli. Jika beberapa ControlNet ditentukan di init, Anda dapat mengatur skala yang sesuai sebagai list.

guess_mode (bool, opsional, defaultnya False) : Encoder ControlNet mencoba mengenali konten gambar input bahkan jika Anda menghapus semua prompt. Nilai guidance_scale antara 3.0 dan 5.0 direkomendasikan.

control_guidance_start (float atau list[float], opsional, default 0.0) : Persentase dari total langkah di mana ControlNet mulai diterapkan.

control_guidance_end (float atau list[float], opsional, default 1.0) : Persentase dari total langkah di mana ControlNet berhenti diterapkan.

control_mode (int or list[int] or list[list[int]], *optional*) : The control condition types for the ControlNet. See the ControlNet's model card forinformation on the available control modes. If multiple ControlNets are specified in init`, control_mode should be a list where each ControlNet should have its corresponding control mode list. Should reflect the order of conditions in control_image.

original_size (tuple[int], opsional, defaultnya (1024, 1024)) : Jika original_size tidak sama dengan target_size, gambar akan tampak di-downsample atau di-upsample. original_size defaultnya (height, width) jika tidak ditentukan. Bagian dari micro-conditioning SDXL seperti dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952.

crops_coords_top_left (tuple[int], opsional, defaultnya (0, 0)) : crops_coords_top_left dapat digunakan untuk menghasilkan gambar yang tampak "dipotong" dari posisi crops_coords_top_left ke bawah. Gambar yang bagus dan terpusat biasanya dicapai dengan mengatur crops_coords_top_left ke (0, 0). Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952.

target_size (tuple[int], opsional, defaultnya (1024, 1024)) : Untuk sebagian besar kasus, target_size sebaiknya diatur ke tinggi dan lebar yang diinginkan dari gambar yang dihasilkan. Jika tidak ditentukan, nilainya akan default ke (height, width). Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952.

negative_original_size (tuple[int], opsional, defaultnya (1024, 1024)) : Untuk mengondisikan proses generasi secara negatif berdasarkan resolusi gambar tertentu. Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952. Untuk informasi lebih lanjut, lihat thread issue ini: https://github.com/huggingface/diffusers/issues/4208.

negative_crops_coords_top_left (tuple[int], opsional, defaultnya (0, 0)) : Untuk mengondisikan proses generasi secara negatif berdasarkan koordinat crop tertentu. Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952. Untuk informasi lebih lanjut, lihat thread issue ini: https://github.com/huggingface/diffusers/issues/4208.

negative_target_size (tuple[int], opsional, defaultnya (1024, 1024)) : Untuk mengondisikan proses generasi secara negatif berdasarkan resolusi gambar target. Sebaiknya sama dengan target_size untuk sebagian besar kasus. Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952. Untuk informasi lebih lanjut, lihat thread issue ini: https://github.com/huggingface/diffusers/issues/4208.

clip_skip (int, opsional) : Jumlah lapisan yang akan dilewati dari CLIP saat menghitung prompt embeddings. Nilai 1 berarti bahwa output dari lapisan sebelum terakhir akan digunakan untuk menghitung prompt embeddings.

callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, opsional) : Fungsi atau subkelas dari PipelineCallback atau MultiPipelineCallbacks yang dipanggil di akhir setiap langkah denoising selama inferensi, dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (list, opsional) : Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.

Mengembalikan: StableDiffusionPipelineOutput atau tuple

Jika return_dict adalah True, StableDiffusionPipelineOutput dikembalikan, selain itu sebuah tuple yang berisi gambar output dikembalikan.

Fungsi panggilan untuk pipeline pada generasi.

Contoh:

>>> # !pip install controlnet_aux
>>> from controlnet_aux import LineartAnimeDetector
>>> from diffusers import StableDiffusionXLControlNetUnionPipeline, ControlNetUnionModel, AutoencoderKL
>>> from diffusers.utils import load_image
>>> import torch

>>> prompt = "A cat"
>>> # download an image
>>> image = load_image(
...     "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky/cat.png"
... ).resize((1024, 1024))
>>> # initialize the models and pipeline
>>> controlnet = ControlNetUnionModel.from_pretrained(
...     "xinsir/controlnet-union-sdxl-1.0", torch_dtype=torch.float16
... )
>>> vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16)
>>> pipe = StableDiffusionXLControlNetUnionPipeline.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0",
...     controlnet=controlnet,
...     vae=vae,
...     torch_dtype=torch.float16,
...     variant="fp16",
... )
>>> pipe.enable_model_cpu_offload()
>>> # prepare image
>>> processor = LineartAnimeDetector.from_pretrained("lllyasviel/Annotators")
>>> controlnet_img = processor(image, output_type="pil")
>>> # generate image
>>> image = pipe(prompt, control_image=[controlnet_img], control_mode=[3], height=1024, width=1024).images[0]

encode_prompt[[diffusers.StableDiffusionXLControlNetUnionPipeline.encode_prompt]]

encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)

Sumber

Parameter:

prompt (str atau list[str], opsional) : prompt yang akan dienkod

prompt_2 (str atau list[str], opsional) : Prompt atau prompt yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, prompt digunakan di kedua text-encoder

device : (torch.device): perangkat torch

num_images_per_prompt (int) : jumlah gambar yang harus dihasilkan per prompt

do_classifier_free_guidance (bool) : apakah akan menggunakan classifier free guidance atau tidak

negative_prompt (str atau list[str], opsional) : Prompt atau prompt-prompt yang tidak akan memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).

negative_prompt_2 (str atau list[str], opsional) : Prompt atau prompt-prompt yang tidak akan memandu generasi gambar untuk dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, negative_prompt digunakan di kedua text-encoder

prompt_embeds (torch.Tensor, opsional) : Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.

negative_prompt_embeds (torch.Tensor, opsional) : Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.

pooled_prompt_embeds (torch.Tensor, opsional) : Pooled text embeddings yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, pooled text embeddings akan dihasilkan dari argumen input prompt.

negative_pooled_prompt_embeds (torch.Tensor, opsional) : Embedding teks negatif yang sudah dipooling sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, pooled negative_prompt_embeds akan dihasilkan dari argumen input negative_prompt.

lora_scale (float, opsional) : Skala lora yang akan diterapkan ke semua lapisan LoRA dari text encoder jika lapisan LoRA dimuat.

clip_skip (int, opsional) : Jumlah lapisan yang akan dilewati dari CLIP saat menghitung prompt embeddings. Nilai 1 berarti bahwa output dari lapisan sebelum terakhir akan digunakan untuk menghitung prompt embeddings.

Mengkodekan prompt menjadi hidden states dari text encoder.

get_guidance_scale_embedding[[diffusers.StableDiffusionXLControlNetUnionPipeline.get_guidance_scale_embedding]]

get_guidance_scale_embedding(w: Tensor, embedding_dim: int = 512, dtype: dtype = torch.float32)

Sumber

Parameter:

w (torch.Tensor) : Menghasilkan vektor embedding dengan skala panduan yang ditentukan untuk selanjutnya memperkaya embedding timestep.

embedding_dim (int, opsional, default 512) : Dimensi dari embedding yang akan dihasilkan.

dtype (torch.dtype, opsional, defaultnya torch.float32) : Tipe data dari embedding yang dihasilkan.

Mengembalikan: torch.Tensor

Vektor embedding dengan bentuk (len(w), embedding_dim).

Lihat https://github.com/google-research/vdm/blob/dc27b98a554f65cdc654b800da5aa1846545d41b/model_vdm.py#L298

StableDiffusionXLControlNetUnionImg2ImgPipeline[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline]]

diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline]]

diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline(vae: AutoencoderKL, text_encoder: CLIPTextModel, text_encoder_2: CLIPTextModelWithProjection, tokenizer: CLIPTokenizer, tokenizer_2: CLIPTokenizer, unet: UNet2DConditionModel, controlnet: diffusers.models.controlnets.controlnet_union.ControlNetUnionModel | list[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | tuple[diffusers.models.controlnets.controlnet_union.ControlNetUnionModel] | diffusers.models.controlnets.multicontrolnet_union.MultiControlNetUnionModel, scheduler: KarrasDiffusionSchedulers, requires_aesthetics_score: bool = False, force_zeros_for_empty_prompt: bool = True, add_watermarker: bool | None = None, feature_extractor: CLIPImageProcessorPil = None, image_encoder: CLIPVisionModelWithProjection = None)

Sumber

Parameter:

vae (AutoencoderKL) : Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten.

text_encoder (CLIPTextModel) : Text-encoder yang dibekukan. Stable Diffusion menggunakan bagian teks dari CLIP, khususnya varian clip-vit-large-patch14.

text_encoder_2 ( CLIPTextModelWithProjection) : Text-encoder beku kedua. Stable Diffusion XL menggunakan bagian teks dan pool dari CLIP, khususnya varian laion/CLIP-ViT-bigG-14-laion2B-39B-b160k.

tokenizer (CLIPTokenizer) : Tokenizer dari kelas CLIPTokenizer.

tokenizer_2 (CLIPTokenizer) : Tokenizer kedua dari kelas CLIPTokenizer.

unet (UNet2DConditionModel) : Arsitektur U-Net bersyarat untuk mendenoise latens gambar yang telah dikodekan.

controlnet (ControlNetUnionModel) : Menyediakan kondisioning tambahan ke unet selama proses denoising.

scheduler (SchedulerMixin) : Penjadwal yang digunakan bersama unet untuk menghilangkan noise pada latens gambar yang telah dikodekan. Bisa berupa DDIMScheduler, LMSDiscreteScheduler, atau PNDMScheduler.

requires_aesthetics_score (bool, opsional, defaultnya "False") : Apakah unet memerlukan kondisi aesthetic_score untuk diteruskan selama inferensi. Lihat juga konfigurasi dari stabilityai/stable-diffusion-xl-refiner-1-0.

force_zeros_for_empty_prompt (bool, opsional, defaultnya "True") : Apakah embedding prompt negatif harus dipaksa selalu diatur ke 0. Lihat juga konfigurasi dari stabilityai/stable-diffusion-xl-base-1-0.

add_watermarker (bool, opsional) : Apakah akan menggunakan invisible_watermark library untuk memberi watermark pada gambar output. Jika tidak didefinisikan, nilainya akan default ke True jika paket tersebut terinstal, jika tidak, tidak akan ada watermarker yang digunakan.

feature_extractor (CLIPImageProcessor) : Sebuah CLIPImageProcessor untuk mengekstrak fitur dari gambar yang dihasilkan; digunakan sebagai input untuk safety_checker.

Pipeline untuk generasi gambar-ke-gambar menggunakan Stable Diffusion XL dengan panduan ControlNet.

Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua pipeline (seperti mengunduh atau menyimpan, menjalankan pada perangkat tertentu, dll.)

Pipeline juga mewarisi metode pemuatan berikut:

load_textual_inversion() untuk memuat embedding textual inversion
load_lora_weights() untuk memuat bobot LoRA
save_lora_weights() untuk menyimpan bobot LoRA
load_ip_adapter() untuk memuat IP Adapter

call[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline.call]]

__call__(prompt: str | list[str] = None, prompt_2: str | list[str] | None = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], list[typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]]] = None, height: int | None = None, width: int | None = None, strength: float = 0.8, num_inference_steps: int = 50, guidance_scale: float = 5.0, negative_prompt: str | list[str] | None = None, negative_prompt_2: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, ip_adapter_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, ip_adapter_image_embeds: list[torch.Tensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, cross_attention_kwargs: dict[str, typing.Any] | None = None, controlnet_conditioning_scale: float | list[float] = 0.8, guess_mode: bool = False, control_guidance_start: float | list[float] = 0.0, control_guidance_end: float | list[float] = 1.0, control_mode: int | list[int] | list[list[int]] | None = None, original_size: tuple[int, int] = None, crops_coords_top_left: tuple[int, int] = (0, 0), target_size: tuple[int, int] = None, negative_original_size: tuple[int, int] | None = None, negative_crops_coords_top_left: tuple[int, int] = (0, 0), negative_target_size: tuple[int, int] | None = None, aesthetic_score: float = 6.0, negative_aesthetic_score: float = 2.5, clip_skip: int | None = None, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], **kwargs)

Sumber

Parameter:

prompt (str atau list[str], opsional) : Prompt atau prompt-prompt untuk mengarahkan generasi gambar. Jika tidak didefinisikan, Anda harus melewatkan prompt_embeds sebagai gantinya.

prompt_2 (str atau list[str], opsional) : Prompt atau prompt yang akan dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, prompt digunakan di kedua text-encoder

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]] atau list[list[PIL.Image.Image]]): Gambar awal akan digunakan sebagai titik awal untuk proses generasi gambar. Dapat juga menerima latents gambar sebagai image; jika latents diberikan secara langsung, latents tersebut tidak akan di-encode ulang.

control_image (PipelineImageInput atau list[PipelineImageInput], opsional) : Kondisi input ControlNet untuk memberikan panduan kepada unet dalam proses generasi. Jika tipe ditentukan sebagai torch.Tensor, nilai tersebut diteruskan ke ControlNet apa adanya. PIL.Image.Image juga dapat diterima sebagai gambar. Dimensi gambar output secara default mengikuti dimensi image. Jika tinggi dan/atau lebar diberikan, image akan di-resize sesuai. Jika beberapa ControlNet ditentukan dalam init, gambar harus diteruskan sebagai daftar sehingga setiap elemen daftar dapat di-batch dengan benar untuk input ke satu ControlNet.

height (int, opsional, defaultnya adalah ukuran control_image) : Tinggi gambar yang dihasilkan dalam piksel. Nilai di bawah 512 piksel tidak akan berfungsi dengan baik untuk stabilityai/stable-diffusion-xl-base-1.0 dan checkpoint yang tidak secara khusus dihaluskan pada resolusi rendah.

width (int, opsional, defaultnya adalah ukuran dari control_image) : Lebar gambar yang dihasilkan dalam piksel. Nilai di bawah 512 piksel tidak akan berfungsi dengan baik untuk stabilityai/stable-diffusion-xl-base-1.0 dan checkpoint yang tidak secara khusus dihaluskan pada resolusi rendah.

strength (float, opsional, default 0.8) : Menunjukkan sejauh mana image referensi akan ditransformasi. Nilai harus berada di antara 0 dan 1. image digunakan sebagai titik awal, dan semakin tinggi nilai strength, semakin banyak noise yang ditambahkan. Jumlah langkah denoising bergantung pada jumlah noise yang ditambahkan di awal. Ketika strength bernilai 1, noise yang ditambahkan maksimal dan proses denoising berjalan untuk jumlah iterasi penuh yang ditentukan dalam num_inference_steps. Nilai 1 pada dasarnya mengabaikan image.

num_inference_steps (int, opsional, defaultnya 50) : Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat.

guidance_scale (float, opsional, default 7.5) : Skala panduan seperti yang didefinisikan dalam Classifier-Free Diffusion Guidance. guidance_scale didefinisikan sebagai w dari persamaan 2. pada Imagen Paper. Skala panduan diaktifkan dengan mengatur guidance_scale > 1. Skala panduan yang lebih tinggi mendorong generasi gambar yang sangat terkait dengan prompt teks, biasanya dengan mengorbankan kualitas gambar yang lebih rendah.

negative_prompt (str atau list[str], opsional) : Prompt atau prompt-prompt yang tidak akan memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan negative_prompt_embeds sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika guidance_scale kurang dari 1).

negative_prompt_2 (str atau list[str], opsional) : Prompt atau prompt-prompt yang tidak akan memandu generasi gambar untuk dikirim ke tokenizer_2 dan text_encoder_2. Jika tidak didefinisikan, negative_prompt digunakan di kedua text-encoder

num_images_per_prompt (int, opsional, default 1) : Jumlah gambar yang akan dihasilkan per prompt.

eta (float, opsional, default 0.0) : Bersesuaian dengan parameter eta (η) dalam paper DDIM: https://huggingface.co/papers/2010.02502. Hanya berlaku untuk schedulers.DDIMScheduler, akan diabaikan untuk yang lain.

generator (torch.Generator atau list[torch.Generator], opsional) : Satu atau daftar generator torch untuk membuat proses generasi menjadi deterministik.

latents (torch.Tensor, opsional) : Laten berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor laten akan dibuat dengan pengambilan sampel menggunakan generator acak yang diberikan.

prompt_embeds (torch.Tensor, opsional) : Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input prompt.

negative_prompt_embeds (torch.Tensor, opsional) : Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input negative_prompt.

pooled_prompt_embeds (torch.Tensor, opsional) : Pooled text embeddings yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya pembobotan prompt. Jika tidak disediakan, pooled text embeddings akan dihasilkan dari argumen input prompt.

negative_pooled_prompt_embeds (torch.Tensor, opsional) : Embedding teks negatif yang sudah dipooling sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, misalnya penimbangan prompt. Jika tidak disediakan, pooled negative_prompt_embeds akan dihasilkan dari argumen input negative_prompt.

ip_adapter_image : (PipelineImageInput, opsional): Input gambar opsional untuk bekerja dengan IP Adapters.

ip_adapter_image_embeds (list[torch.Tensor], opsional) : Embedding gambar yang telah dibuat sebelumnya untuk IP-Adapter. Ini harus berupa daftar dengan panjang yang sama dengan jumlah IP-adapter. Setiap elemen harus berupa tensor dengan bentuk (batch_size, num_images, emb_dim). Embedding gambar negatif harus disertakan jika do_classifier_free_guidance diatur ke True. Jika tidak disediakan, embedding dihitung dari argumen input ip_adapter_image.

output_type (str, opsional, defaultnya "pil") : Format output dari gambar yang dihasilkan. Pilih antara PIL: PIL.Image.Image atau np.array.

return_dict (bool, opsional, defaultnya True) : Apakah akan mengembalikan StableDiffusionPipelineOutput alih-alih tuple biasa.

cross_attention_kwargs (dict, opsional) : Kamus kwargs yang jika ditentukan akan diteruskan ke AttentionProcessor seperti yang didefinisikan di bawah self.processor dalam diffusers.models.attention_processor.

controlnet_conditioning_scale (float atau list[float], opsional, default 1.0) : Output dari ControlNet dikalikan dengan controlnet_conditioning_scale sebelum ditambahkan ke residual di unet asli. Jika beberapa ControlNet ditentukan di init, Anda dapat mengatur skala yang sesuai sebagai list.

guess_mode (bool, opsional, defaultnya False) : Dalam mode ini, encoder ControlNet akan berusaha semaksimal mungkin untuk mengenali konten gambar input meskipun Anda menghapus semua prompt. guidance_scale antara 3.0 dan 5.0 direkomendasikan.

control_guidance_start (float atau list[float], opsional, default 0.0) : Persentase dari total langkah di mana ControlNet mulai diterapkan.

control_guidance_end (float atau list[float], opsional, default 1.0) : Persentase dari total langkah di mana ControlNet berhenti diterapkan.

control_mode (int or list[int] or list[list[int]], *optional*) : The control condition types for the ControlNet. See the ControlNet's model card forinformation on the available control modes. If multiple ControlNets are specified in init`, control_mode should be a list where each ControlNet should have its corresponding control mode list. Should reflect the order of conditions in control_image

original_size (tuple[int], opsional, defaultnya (1024, 1024)) : Jika original_size tidak sama dengan target_size, gambar akan tampak di-downsample atau di-upsample. original_size defaultnya (height, width) jika tidak ditentukan. Bagian dari micro-conditioning SDXL seperti dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952.

crops_coords_top_left (tuple[int], opsional, defaultnya (0, 0)) : crops_coords_top_left dapat digunakan untuk menghasilkan gambar yang tampak "dipotong" dari posisi crops_coords_top_left ke bawah. Gambar yang bagus dan terpusat biasanya dicapai dengan mengatur crops_coords_top_left ke (0, 0). Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952.

target_size (tuple[int], opsional, defaultnya (1024, 1024)) : Untuk sebagian besar kasus, target_size sebaiknya diatur ke tinggi dan lebar yang diinginkan dari gambar yang dihasilkan. Jika tidak ditentukan, nilainya akan default ke (height, width). Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952.

negative_original_size (tuple[int], opsional, defaultnya (1024, 1024)) : Untuk mengondisikan proses generasi secara negatif berdasarkan resolusi gambar tertentu. Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952. Untuk informasi lebih lanjut, lihat thread issue ini: https://github.com/huggingface/diffusers/issues/4208.

negative_crops_coords_top_left (tuple[int], opsional, defaultnya (0, 0)) : Untuk mengondisikan proses generasi secara negatif berdasarkan koordinat crop tertentu. Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952. Untuk informasi lebih lanjut, lihat thread issue ini: https://github.com/huggingface/diffusers/issues/4208.

negative_target_size (tuple[int], opsional, defaultnya (1024, 1024)) : Untuk mengondisikan proses generasi secara negatif berdasarkan resolusi gambar target. Sebaiknya sama dengan target_size untuk sebagian besar kasus. Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952. Untuk informasi lebih lanjut, lihat thread issue ini: https://github.com/huggingface/diffusers/issues/4208.

aesthetic_score (float, opsional, default 6.0) : Digunakan untuk mensimulasikan skor estetika dari gambar yang dihasilkan dengan memengaruhi kondisi teks positif. Bagian dari micro-conditioning SDXL seperti yang dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952.

negative_aesthetic_score (float, opsional, default 2.5) : Bagian dari micro-conditioning SDXL seperti dijelaskan di bagian 2.2 dari https://huggingface.co/papers/2307.01952. Dapat digunakan untuk mensimulasikan skor estetika dari gambar yang dihasilkan dengan memengaruhi kondisi teks negatif.

clip_skip (int, opsional) : Jumlah lapisan yang akan dilewati dari CLIP saat menghitung prompt embeddings. Nilai 1 berarti bahwa output dari lapisan sebelum terakhir akan digunakan untuk menghitung prompt embeddings.

callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, opsional) : Fungsi atau subkelas dari PipelineCallback atau MultiPipelineCallbacks yang dipanggil di akhir setiap langkah denoising selama inferensi, dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (list, opsional) : Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.

Mengembalikan: StableDiffusionPipelineOutput atau tuple

StableDiffusionPipelineOutput jika return_dict bernilai True, selain itu berupa tuple yang berisi gambar output.

Fungsi yang dipanggil saat memanggil pipeline untuk generasi.

Contoh:

# !pip install controlnet_aux
from diffusers import (
    StableDiffusionXLControlNetUnionImg2ImgPipeline,
    ControlNetUnionModel,
    AutoencoderKL,
)
from diffusers.utils import load_image
import torch
from PIL import Image
import numpy as np

prompt = "A cat"
# download an image
image = load_image(
    "https://huggingface.co/datasets/hf-internal-testing/diffusers-images/resolve/main/kandinsky/cat.png"
)
# initialize the models and pipeline
controlnet = ControlNetUnionModel.from_pretrained(
    "brad-twinkl/controlnet-union-sdxl-1.0-promax", torch_dtype=torch.float16
)
vae = AutoencoderKL.from_pretrained("madebyollin/sdxl-vae-fp16-fix", torch_dtype=torch.float16)
pipe = StableDiffusionXLControlNetUnionImg2ImgPipeline.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0",
    controlnet=controlnet,
    vae=vae,
    torch_dtype=torch.float16,
    variant="fp16",
).to("cuda")
# `enable_model_cpu_offload` is not recommended due to multiple generations
height = image.height
width = image.width
ratio = np.sqrt(1024.0 * 1024.0 / (width * height))
# 3 * 3 upscale correspond to 16 * 3 multiply, 2 * 2 correspond to 16 * 2 multiply and so on.
scale_image_factor = 3
base_factor = 16
factor = scale_image_factor * base_factor
W, H = int(width * ratio) // factor * factor, int(height * ratio) // factor * factor
image = image.resize((W, H))
target_width = W // scale_image_factor
target_height = H // scale_image_factor
images = []
crops_coords_list = [
    (0, 0),
    (0, width // 2),
    (height // 2, 0),
    (width // 2, height // 2),
    0,
    0,
    0,
    0,
    0,
]
for i in range(scale_image_factor):
    for j in range(scale_image_factor):
        left = j * target_width
        top = i * target_height
        right = left + target_width
        bottom = top + target_height
        cropped_image = image.crop((left, top, right, bottom))
        cropped_image = cropped_image.resize((W, H))
        images.append(cropped_image)
# set ControlNetUnion input
result_images = []
for sub_img, crops_coords in zip(images, crops_coords_list):
    new_width, new_height = W, H
    out = pipe(
        prompt=[prompt] * 1,
        image=sub_img,
        control_image=[sub_img],
        control_mode=[6],
        width=new_width,
        height=new_height,
        num_inference_steps=30,
        crops_coords_top_left=(W, H),
        target_size=(W, H),
        original_size=(W * 2, H * 2),
    )
    result_images.append(out.images[0])
new_im = Image.new("RGB", (new_width * scale_image_factor, new_height * scale_image_factor))
new_im.paste(result_images[0], (0, 0))
new_im.paste(result_images[1], (new_width, 0))
new_im.paste(result_images[2], (new_width * 2, 0))
new_im.paste(result_images[3], (0, new_height))
new_im.paste(result_images[4], (new_width, new_height))
new_im.paste(result_images[5], (new_width * 2, new_height))
new_im.paste(result_images[6], (0, new_height * 2))
new_im.paste(result_images[7], (new_width, new_height * 2))
new_im.paste(result_images[8], (new_width * 2, new_height * 2))

encode_prompt[[diffusers.StableDiffusionXLControlNetUnionImg2ImgPipeline.encode_prompt]]

encode_prompt(prompt: str, prompt_2: str | None = None, device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, negative_prompt_2: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_pooled_prompt_embeds: typing.Optional[torch.Tensor] = None, lora_scale: float | None = None, clip_skip: int | None = None)