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

ControlNet modeli, Lvmin Zhang, Anyi Rao ve Maneesh Agrawala tarafından Adding Conditional Control to Text-to-Image Diffusion Models makalesinde tanıtılmıştır. Kenar haritaları, derinlik haritaları, segmentasyon haritaları ve poz algılama için anahtar noktalar gibi ek girdiler üzerinde modeli koşullandırarak metinden görüntüye üretim üzerinde daha yüksek bir kontrol derecesi sağlar.

Makalenin özeti şudur:

ControlNet'i sunuyoruz; bu, büyük, önceden eğitilmiş metinden görüntüye difüzyon modellerine uzamsal koşullandırma kontrolleri eklemek için tasarlanmış bir sinir ağı mimarisidir. ControlNet, üretim için hazır büyük difüzyon modellerini kilitler ve milyarlarca görüntüyle önceden eğitilmiş derin ve sağlam kodlama katmanlarını, çeşitli bir koşullu kontrol seti öğrenmek için güçlü bir omurga olarak yeniden kullanır. Sinir mimarisi, parametreleri sıfırdan kademeli olarak büyüten ve finetuning'i (ince ayar) etkileyebilecek zararlı gürültünün olmasını engelleyen “sıfır konvolüsyonlar” (sıfır başlatılmış konvolüsyon katmanları) ile bağlanır. Stable Diffusion ile tekil veya birden fazla koşul kullanarak, istemlerle (prompt) veya istemsiz olarak kenarlar, derinlik, segmentasyon, insan pozu gibi çeşitli koşullandırma kontrollerini test ediyoruz. ControlNet'lerin eğitiminin küçük (<50k) ve büyük (>1m) veri setleriyle sağlam olduğunu gösteriyoruz. Kapsamlı sonuçlar, ControlNet'in görüntü difüzyon modellerini kontrol etmek için daha geniş uygulamaları kolaylaştırabileceğini göstermektedir.

Orijinal formattan yükleme

Varsayılan olarak ControlNetModel, from_pretrained() ile yüklenmelidir; ancak aşağıdaki gibi FromOriginalModelMixin.from_single_file kullanılarak orijinal biçimden de yüklenebilir:

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)

Control LoRA'dan yükleme

Control-LoRA, Stability AI tarafından stabilityai/control-lora ile ControlNet'e düşük rütbeli, parametre verimli ince ayar eklenerek tanıtılmıştır. Bu yaklaşım, model kontrolünü daha geniş bir tüketici GPU yelpazesine getirmek için daha verimli ve kompakt bir yöntem sunar.

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

sınıf 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 )

Parametreler

  • in_channels (int, varsayılan 4) — Girdi örneğindeki kanal sayısı.
  • flip_sin_to_cos (bool, varsayılan True) — Zaman gömme (embedding) içinde sin'in cos'a çevrilip çevrilmeyeceğini belirtir.
  • freq_shift (int, varsayılan 0) — Zaman gömümüne uygulanacak frekans kaydırması.
  • down_block_types (tuple[str], varsayılan ("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) — Kullanılacak örnekleme azaltma bloklarının demeti.
  • only_cross_attention (bool | tuple[bool], varsayılan False) —
  • block_out_channels (tuple[int], varsayılan (320, 640, 1280, 1280)) — Her blok için çıktı kanalları demeti.
  • layers_per_block (int, varsayılan 2) — Blok başına katman sayısı.
  • downsample_padding (int, varsayılan 1) — Aşağı örnekleme konvolüsyonu için kullanılacak dolgu.
  • mid_block_scale_factor (float, varsayılan 1) — Orta blok için kullanılacak ölçekleme faktörü.
  • act_fn (str, varsayılan “silu”) — Kullanılacak aktivasyon fonksiyonu.
  • norm_num_groups (int, isteğe bağlı, varsayılan 32) — Normalizasyon için kullanılacak grup sayısı. None ise, son işlemede normalizasyon ve aktivasyon katmanları atlanır.
  • norm_eps (float, varsayılan 1e-5) — Normalizasyon için kullanılacak epsilon.
  • cross_attention_dim (int, varsayılan 1280) — Çapraz dikkat (cross attention) özelliklerinin boyutu.
  • transformer_layers_per_block (int veya tuple[int], isteğe bağlı, varsayılan 1) — BasicTransformerBlock türündeki transformer bloklarının sayısı. Yalnızca ~models.unet_2d_blocks.CrossAttnDownBlock2D, ~models.unet_2d_blocks.CrossAttnUpBlock2D, ~models.unet_2d_blocks.UNetMidBlock2DCrossAttn için geçerlidir.
  • encoder_hid_dim (int, isteğe bağlı, varsayılanı None) — encoder_hid_dim_type tanımlıysa, encoder_hidden_states, encoder_hid_dim boyutundan cross_attention_dim boyutuna yansıtılır.
  • encoder_hid_dim_type (str, isteğe bağlı, varsayılan None) — Verilirse, encoder_hidden_states ve potansiyel olarak diğer gömlemeler, encoder_hid_dim_type'e göre cross_attention boyutlu metin gömlemelerine indirgenir.
  • attention_head_dim (int | tuple[int], varsayılan 8) — Dikkat başlarının boyutu.
  • use_linear_projection (bool, varsayılan False) —
  • class_embed_type (str, isteğe bağlı, varsayılan None) — Zaman gömme değerleriyle nihai olarak toplanacak sınıf gömme türü. None, "timestep", "identity", "projection" veya "simple_projection" seçeneklerinden birini seçin.
  • addition_embed_type (str, isteğe bağlı, varsayılan None) — Zaman gömme vektörleriyle toplanacak isteğe bağlı bir gömme vektörü yapılandırır. None veya “text” seçeneklerinden birini seçin. “text”, TextTimeEmbedding katmanını kullanır.
  • num_class_embeds (int, isteğe bağlı, varsayılan 0) — class_embed_type None olduğunda sınıf koşullandırması yapılırken time_embed_dim'e yansıtılacak öğrenilebilir gömme matrisinin giriş boyutu.
  • upcast_attention (bool, varsayılan False) —
  • resnet_time_scale_shift (str, varsayılan "default") — ResNet blokları için zaman ölçek kaydırma yapılandırması (bkz. ResnetBlock2D). default veya scale_shift seçeneklerinden birini seçin.
  • projection_class_embeddings_input_dim (int, isteğe bağlı, varsayılan None) — class_embed_type="projection" olduğunda class_labels girdisinin boyutu. class_embed_type="projection" olduğunda zorunludur.
  • controlnet_conditioning_channel_order (str, varsayılan "rgb") — Koşullu görüntünün kanal sırası. bgr ise rgb olarak dönüştürülür.
  • conditioning_embedding_out_channels (tuple[int], isteğe bağlı, varsayılan (16, 32, 96, 256)) — conditioning_embedding katmanındaki her blok için çıktı kanalının tuple'ı.
  • global_pool_conditions (bool, varsayılan False) — TODO(Patrick) - kullanılmayan parametre.
  • addition_embed_type_num_heads (int, varsayılan 64) — TextTimeEmbedding katmanı için kullanılacak baş sayısı.

Bir ControlNet modeli.

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

Parametreler

  • sample (torch.Tensor) — Gürültülü girdi tensörü.
  • timestep (torch.Tensor | float | int) — Gürültüden arındırılacak girdi için adım sayısı.
  • encoder_hidden_states (torch.Tensor) — Kodlayıcı gizli durumları.
  • controlnet_cond (torch.Tensor) — (batch_size, sequence_length, hidden_size) biçiminde koşullu girdi tensörü.
  • conditioning_scale (float, varsayılan 1.0) — ControlNet çıktıları için ölçekleme faktörü.
  • class_labels (torch.Tensor, isteğe bağlı, varsayılan None) — Koşullandırma için isteğe bağlı sınıf etiketleri. Gömümleri, zaman adımları gömümleriyle toplanır.
  • timestep_cond (torch.Tensor, isteğe bağlı, varsayılan None) — Zaman adımı için ek koşullu gömme değerleri. Sağlanırsa, gömme değerleri self.time_embedding katmanından geçirilen timestep_embedding ile toplanarak nihai zaman adımı gömme değerleri elde edilir.
  • attention_mask (torch.Tensor, isteğe bağlı, varsayılan None) — (batch, key_tokens) biçiminde bir dikkat maskesi, encoder_hidden_states üzerine uygulanır. Değer 1 ise maske korunur, aksi halde 0 ise atılır. Maske, “at” tokenlarına karşılık gelen dikkat puanlarına büyük negatif değerler ekleyen bir önyargıya dönüştürülür.
  • added_cond_kwargs (dict) — Stable Diffusion XL UNet için ek koşullar.
  • cross_attention_kwargs (dict[str], isteğe bağlı, varsayılan None) — Belirtilirse AttnProcessor'a iletilen bir kwargs sözlüğü.
  • guess_mode (bool, varsayılan False) — Bu modda, tüm istemleri (prompts) kaldırsanız bile ControlNet kodlayıcısı, girdi içeriğini tanımayı en iyi şekilde yapmaya çalışır. guidance_scale için 3.0 ile 5.0 arasında bir değer önerilir.
  • return_dict (bool, varsayılan True) — Düz bir tuple yerine ControlNetOutput döndürülüp döndürülmemesi.

Dönüş değeri

ControlNetOutput veya tuple

return_dict True ise ControlNetOutput döndürülür, aksi halde bir tuple döndürülür ve bunun ilk öğesi örnek tensörüdür.

ControlNetModel ileri yöntemi.

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 )

Parametreler

  • unet (UNet2DConditionModel) — ControlNetModel'e kopyalanacak UNet model ağırlıkları. Uygulanabilir tüm yapılandırma seçenekleri de kopyalanır.

UNet2DConditionModel'den bir ControlNetModel örneği oluşturun.

set_attention_slice

< >

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

Parametreler

  • slice_size (str veya int veya list(int), isteğe bağlı, varsayılan "auto") — "auto" olduğunda, dikkat başlarına giden girdi ikiye bölünür ve dikkat iki adımda hesaplanır. "max" ise, bir seferde yalnızca bir dilim çalıştırılarak maksimum miktarda bellek tasarrufu sağlanır. Bir sayı verilirse, attention_head_dim // slice_size kadar dilim kullanılır. Bu durumda attention_head_dim değeri, slice_size değerinin katı olmalıdır.

Dilimlenmiş dikkat (attention) hesaplamasını etkinleştirin.

Bu seçenek etkinleştirildiğinde, dikkat modülü dikkat hesabını birkaç adımda gerçekleştirmek için girdi tensörünü dilimlere ayırır. Bu, hızda küçük bir düşüş karşılığında bellek tasarrufu sağlamak için faydalıdır.

set_default_attn_processor

< >

( )

Özel dikkat işleyicilerini devre dışı bırakır ve varsayılan dikkat uygulamasını ayarlar.

ControlNetOutput

sınıf diffusers.models.controlnets.ControlNetOutput

< >

( down_block_res_samples: tuplemid_block_res_sample: Tensor )

Parametreler

  • down_block_res_samples (tuple[torch.Tensor]) — Her indirgeme bloğu için farklı çözünürlüklerdeki indirgeme aktivasyonlarından oluşan bir demet. Her tensörün şekli (batch_size, channel * resolution, height //resolution, width // resolution) olmalıdır. Çıktı, orijinal UNet'in indirgeme aktivasyonlarını koşullandırmak için kullanılabilir.
  • mid_down_block_re_sample (torch.Tensor) — Orta bloğun aktivasyonu (en düşük örnek çözünürlüğü). Her tensörün şekli (batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution) olmalıdır. Çıktı, orijinal UNet'in orta blok aktivasyonunu koşullandırmak için kullanılabilir.

ControlNetModel'nin çıktısı.

Update on GitHub

←AutoModel ControlNetUnionModel→