Hugging Face's logo

Diffusers documentation

ControlNetModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ControlNetModel

Model ControlNet diperkenalkan dalam Adding Conditional Control to Text-to-Image Diffusion Models oleh Lvmin Zhang, Anyi Rao, Maneesh Agrawala. Model ini memberikan tingkat kendali yang lebih besar terhadap generasi teks-ke-gambar dengan mengondisikan model pada input tambahan seperti peta tepi, peta kedalaman, peta segmentasi, dan titik kunci untuk deteksi pose.

Abstrak dari makalah tersebut adalah:

Kami memperkenalkan ControlNet, sebuah arsitektur jaringan saraf untuk menambahkan kontrol kondisional spasial ke model difusi teks-ke-gambar besar yang telah dilatih sebelumnya. ControlNet mengunci model difusi besar yang siap produksi, dan memanfaatkan ulang lapisan enkoding yang dalam dan robust yang telah dilatih sebelumnya dengan miliaran gambar sebagai tulang punggung yang kuat untuk mempelajari berbagai set kontrol kondisional. Arsitektur saraf ini terhubung dengan “zero convolutions” (lapisan konvolusi yang diinisialisasi nol) yang secara bertahap mengembangkan parameter dari nol dan memastikan bahwa tidak ada noise berbahaya yang dapat memengaruhi finetuning. Kami menguji berbagai kontrol kondisional, misalnya, tepi, kedalaman, segmentasi, pose manusia, dll., dengan Stable Diffusion, menggunakan satu atau beberapa kondisi, dengan atau tanpa prompt. Kami menunjukkan bahwa pelatihan ControlNet bersifat robust dengan dataset kecil (<50k) dan besar (>1m). Hasil ekstensif menunjukkan bahwa ControlNet dapat memfasilitasi aplikasi yang lebih luas untuk mengontrol model difusi gambar.

Memuat dari format asli

Secara default, ControlNetModel harus dimuat dengan from_pretrained(), tetapi model juga dapat dimuat dari format aslinya menggunakan FromOriginalModelMixin.from_single_file sebagai berikut:

from diffusers import StableDiffusionControlNetPipeline, ControlNetModel

url = "https://huggingface.co/lllyasviel/ControlNet-v1-1/blob/main/control_v11p_sd15_canny.pth"  # can also be a local path
controlnet = ControlNetModel.from_single_file(url)

url = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.safetensors"  # can also be a local path
pipe = StableDiffusionControlNetPipeline.from_single_file(url, controlnet=controlnet)

Memuat dari Control LoRA

Control-LoRA diperkenalkan oleh Stability AI di stabilityai/control-lora dengan menambahkan fine tuning parameter efisien ber-rank rendah ke ControlNet. Pendekatan ini menawarkan metode yang lebih efisien dan ringkas untuk membawa kontrol model ke berbagai GPU konsumen yang lebih luas.

from diffusers import ControlNetModel, UNet2DConditionModel

lora_id = "stabilityai/control-lora"
lora_filename = "control-LoRAs-rank128/control-lora-canny-rank128.safetensors"

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
controlnet = ControlNetModel.from_unet(unet).to(device="cuda", dtype=torch.bfloat16)
controlnet.load_lora_adapter(lora_id, weight_name=lora_filename, prefix=None, controlnet_config=controlnet.config)

ControlNetModel

kelas diffusers.ControlNetModel

< >

( in_channels: int = 4conditioning_channels: int = 3flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D')mid_block_type: str | None = 'UNetMidBlock2DCrossAttn'only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple = (320, 640, 1280, 1280)layers_per_block: int = 2downsample_padding: int = 1mid_block_scale_factor: float = 1act_fn: str = 'silu'norm_num_groups: int | None = 32norm_eps: float = 1e-05cross_attention_dim: int = 1280transformer_layers_per_block: int | tuple[int, ...] = 1encoder_hid_dim: int | None = Noneencoder_hid_dim_type: str | None = Noneattention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseclass_embed_type: str | None = Noneaddition_embed_type: str | None = Noneaddition_time_embed_dim: int | None = Nonenum_class_embeds: int | None = Noneupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'projection_class_embeddings_input_dim: int | None = Nonecontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)global_pool_conditions: bool = Falseaddition_embed_type_num_heads: int = 64 )

Parameter

  • in_channels (int, defaultnya 4) — Jumlah channel pada sampel input.
  • flip_sin_to_cos (bool, defaultnya True) — Apakah akan membalik sin menjadi cos pada time embedding.
  • freq_shift (int, defaultnya 0) — Pergeseran frekuensi yang diterapkan ke penanaman waktu.
  • down_block_types (tuple[str], defaultnya ("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) — Tuple dari blok downsample yang akan digunakan.
  • only_cross_attention (bool | tuple[bool], defaultnya False) —
  • block_out_channels (tuple[int], defaultnya (320, 640, 1280, 1280)) — Tuple dari kanal output untuk setiap blok.
  • layers_per_block (int, defaultnya 2) — Jumlah lapisan per blok.
  • downsample_padding (int, defaultnya 1) — Padding yang digunakan untuk konvolusi downsampling.
  • mid_block_scale_factor (float, defaultnya 1) — Faktor skala yang digunakan untuk blok tengah.
  • act_fn (str, defaultnya “silu”) — Fungsi aktivasi yang akan digunakan.
  • norm_num_groups (int, opsional, default 32) — Jumlah grup yang digunakan untuk normalisasi. Jika None, lapisan normalisasi dan aktivasi akan dilewati dalam pascapemrosesan.
  • norm_eps (float, defaultnya 1e-5) — Epsilon yang digunakan untuk normalisasi.
  • cross_attention_dim (int, defaultnya 1280) — Dimensi dari fitur cross attention.
  • transformer_layers_per_block (int atau tuple[int], opsional, default 1) — Jumlah blok transformer bertipe BasicTransformerBlock. Hanya relevan untuk ~models.unet_2d_blocks.CrossAttnDownBlock2D, ~models.unet_2d_blocks.CrossAttnUpBlock2D, ~models.unet_2d_blocks.UNetMidBlock2DCrossAttn.
  • encoder_hid_dim (int, opsional, default None) — Jika encoder_hid_dim_type didefinisikan, encoder_hidden_states akan diproyeksikan dari dimensi encoder_hid_dim ke cross_attention_dim.
  • encoder_hid_dim_type (str, opsional, default None) — Jika diberikan, encoder_hidden_states dan kemungkinan embedding lainnya akan diproyeksikan ke bawah menjadi embedding teks dengan dimensi cross_attention sesuai dengan encoder_hid_dim_type.
  • attention_head_dim (int | tuple[int], defaultnya 8) — Dimensi dari kepala perhatian (attention heads).
  • use_linear_projection (bool, defaultnya False) —
  • class_embed_type (str, opsional, defaultnya None) — Jenis class embedding yang akan digunakan, yang pada akhirnya dijumlahkan dengan time embeddings. Pilih dari None, "timestep", "identity", "projection", atau "simple_projection".
  • addition_embed_type (str, opsional, default None) — Mengonfigurasi embedding opsional yang akan dijumlahkan dengan time embeddings. Pilih dari None atau “text”. “text” akan menggunakan layer TextTimeEmbedding.
  • num_class_embeds (int, opsional, default 0) — Dimensi input dari matriks embedding yang dapat dipelajari untuk diproyeksikan ke time_embed_dim, saat melakukan kondisioning kelas dengan class_embed_type yang sama dengan None.
  • upcast_attention (bool, defaultnya False) —
  • resnet_time_scale_shift (str, defaultnya "default") — Konfigurasi pergeseran skala waktu untuk blok ResNet (lihat ResnetBlock2D). Pilih dari default atau scale_shift.
  • projection_class_embeddings_input_dim (int, opsional, defaultnya None) — Dimensi dari input class_labels ketika class_embed_type="projection". Wajib diisi ketika class_embed_type="projection".
  • controlnet_conditioning_channel_order (str, defaultnya "rgb") — Urutan channel dari gambar kondisional. Akan dikonversi menjadi rgb jika nilainya bgr.
  • conditioning_embedding_out_channels (tuple[int], opsional, defaultnya (16, 32, 96, 256)) — Tuple dari kanal output untuk setiap blok di lapisan conditioning_embedding.
  • global_pool_conditions (bool, defaultnya False) — TODO(Patrick) - parameter yang tidak digunakan.
  • addition_embed_type_num_heads (int, defaultnya 64) — Jumlah head yang digunakan untuk lapisan TextTimeEmbedding.

Model ControlNet.

forward

< >

( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0class_labels: typing.Optional[torch.Tensor] = Nonetimestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneadded_cond_kwargs: dict[str, torch.Tensor] | None = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Noneguess_mode: bool = Falsereturn_dict: bool = True ) → ControlNetOutput or tuple

Parameter

  • sample (torch.Tensor) — Tensor input berisik.
  • timestep (torch.Tensor | float | int) — Jumlah timestep untuk mendenoise input.
  • encoder_hidden_states (torch.Tensor) — State tersembunyi encoder.
  • controlnet_cond (torch.Tensor) — Tensor input kondisional dengan bentuk (batch_size, sequence_length, hidden_size).
  • conditioning_scale (float, defaultnya 1.0) — Faktor skala untuk output ControlNet.
  • class_labels (torch.Tensor, opsional, default None) — Label kelas opsional untuk kondisioning. Embedding-nya akan dijumlahkan dengan embedding timestep.
  • timestep_cond (torch.Tensor, opsional, default None) — Embedding kondisional tambahan untuk timestep. Jika diberikan, embedding akan dijumlahkan dengan timestep_embedding yang diteruskan melalui lapisan self.time_embedding untuk mendapatkan embedding timestep akhir.
  • attention_mask (torch.Tensor, opsional, default None) — Mask perhatian dengan bentuk (batch, key_tokens) diterapkan pada encoder_hidden_states. Jika 1, mask dipertahankan, sedangkan jika 0, mask dibuang. Mask akan dikonversi menjadi bias, yang menambahkan nilai negatif besar ke skor perhatian yang sesuai dengan token “buang”.
  • added_cond_kwargs (dict) — Kondisi tambahan untuk UNet Stable Diffusion XL.
  • cross_attention_kwargs (dict[str], opsional, default None) — Kamus kwargs yang jika ditentukan akan diteruskan ke AttnProcessor.
  • guess_mode (bool, defaultnya False) — Pada mode ini, encoder ControlNet akan berusaha semaksimal mungkin untuk mengenali konten input dari input meskipun Anda menghapus semua prompt. guidance_scale antara 3.0 dan 5.0 direkomendasikan.
  • return_dict (bool, defaultnya True) — Apakah akan mengembalikan ControlNetOutput alih-alih tuple biasa.

Mengembalikan

ControlNetOutput atau tuple

Jika return_dict adalah True, sebuah ControlNetOutput dikembalikan, sebaliknya sebuah tuple dikembalikan di mana elemen pertama adalah tensor sampel.

Metode forward dari ControlNetModel.

from_unet

< >

( unet: UNet2DConditionModelcontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)load_weights_from_unet: bool = Trueconditioning_channels: int = 3 )

Parameter

  • unet (UNet2DConditionModel) — Bobot model UNet yang akan disalin ke ControlNetModel. Semua opsi konfigurasi juga disalin sejauh berlaku.

Instansiasi ControlNetModel dari UNet2DConditionModel.

set_attention_slice

< >

( slice_size: str | int | list[int] )

Parameter

  • slice_size (str atau int atau list(int), opsional, defaultnya "auto") — Jika "auto", input ke attention heads dibagi dua, sehingga attention dihitung dalam dua langkah. Jika "max", jumlah memori yang dihemat maksimal dengan hanya menjalankan satu slice pada satu waktu. Jika angka diberikan, digunakan sebanyak slice sebanyak attention_head_dim // slice_size. Dalam kasus ini, attention_head_dim harus merupakan kelipatan dari slice_size.

Aktifkan perhitungan perhatian terpotong.

Ketika opsi ini diaktifkan, modul perhatian membagi tensor input menjadi beberapa potongan untuk menghitung perhatian dalam beberapa langkah. Hal ini berguna untuk menghemat sebagian memori dengan mengorbankan sedikit penurunan kecepatan.

set_default_attn_processor

< >

( )

Menonaktifkan prosesor perhatian kustom dan mengatur implementasi perhatian default.

ControlNetOutput

kelas diffusers.models.controlnets.ControlNetOutput

< >

( down_block_res_samples: tuplemid_block_res_sample: Tensor )

Parameter

  • down_block_res_samples (tuple[torch.Tensor]) — Tuple dari aktivasi downsampling pada resolusi yang berbeda untuk setiap blok downsampling. Setiap tensor harus berbentuk (batch_size, channel * resolution, height //resolution, width // resolution). Output dapat digunakan untuk mengondisikan aktivasi downsampling dari UNet asli.
  • mid_down_block_re_sample (torch.Tensor) — Aktivasi dari blok tengah (resolusi sampel terendah). Setiap tensor harus memiliki bentuk (batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution). Output dapat digunakan untuk mengondisikan aktivasi blok tengah dari UNet asli.

Output dari ControlNetModel.

Update on GitHub

←AutoModel ControlNetUnionModel→