Hugging Face's logo

Diffusers documentation

SparseControlNetModel

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

SparseControlNetModel

SparseControlNetModel, AnimateDiff için ControlNet'in bir uygulamasıdır.

ControlNet, Lvmin Zhang, Anyi Rao ve Maneesh Agrawala tarafından Adding Conditional Control to Text-to-Image Diffusion Models makalesinde tanıtılmıştır.

ControlNet'in SparseCtrl sürümü, Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin ve Bo Dai tarafından, metinden videoya difüzyon modellerinde kontrollü üretim sağlamak amacıyla SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models makalesinde tanıtılmıştır.

Makalenin özeti şudur:

Metinden videoya (T2V) üretim, yani verilen bir metin istemine göre video üretme, son yıllarda önemli ölçüde ilerleme kaydetmiştir. Ancak yalnızca metin istemlerine güvenmek, uzamsal belirsizlik nedeniyle genellikle belirsiz kare kompozisyonlarına yol açar. Araştırma topluluğu bu nedenle, örneğin kare başına derinlik/kenar dizileri gibi yoğun yapı sinyallerinden yararlanarak kontrol edilebilirliği artırmaktadır; bunun da toplanması, çıkarım yükünü buna göre artırmaktadır. Bu çalışmada, Şekil 1'de gösterildiği gibi yalnızca bir veya birkaç giriş gerektiren, zaman içinde seyrek sinyallerle esnek yapı kontrolü sağlayan SparseCtrl'i sunuyoruz. Yaklaşım, önceden eğitilmiş T2V modeline dokunmadan bu seyrek sinyalleri işlemek için ek bir koşul kodlayıcı içerir. Önerilen yaklaşım, eskizler, derinlik haritaları ve RGB görüntüler dahil olmak üzere çeşitli modalitelerle uyumludur ve video üretimi için daha pratik bir kontrol sağlayarak storyboard oluşturma, derinlik renderlama, anahtar kare animasyonu ve interpolasyon gibi uygulamaları teşvik eder. Kapsamlı deneyler, SparseCtrl'in hem orijinal hem de kişiselleştirilmiş T2V üreticilerindeki genelleme yeteneğini göstermektedir. Kodlar ve modeller bu https URL adresinde herkese açık olarak kullanılabilir olacaktır.

SparseControlNetModel yükleme örneği

import torch
from diffusers import SparseControlNetModel

# fp32 variant in float16
# 1. Scribble checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-scribble", dtype=torch.float16)

# 2. RGB checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-rgb", dtype=torch.float16)

# For loading fp16 variant, pass `variant="fp16"` as an additional parameter

SparseControlNetModel

sınıf diffusers.SparseControlNetModel

< >

( in_channels: int = 4conditioning_channels: int = 4flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion')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 = 768transformer_layers_per_block: int | tuple[int, ...] = 1transformer_layers_per_mid_block: int | tuple[int] | None = Nonetemporal_transformer_layers_per_block: int | tuple[int, ...] = 1attention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)global_pool_conditions: bool = Falsecontrolnet_conditioning_channel_order: str = 'rgb'motion_max_seq_length: int = 32motion_num_attention_heads: int = 8concat_conditioning_mask: bool = Trueuse_simplified_condition_embedding: bool = True )

Parametreler

  • in_channels (int, varsayılan 4) — Girdi örneğindeki kanal sayısı.
  • conditioning_channels (int, varsayılan 4) — controlnet koşullu gömme modülündeki giriş kanal sayısı. concat_condition_embedding True ise, burada sağlanan değer 1 artırılır.
  • 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.
  • transformer_layers_per_mid_block (int veya tuple[int], isteğe bağlı, varsayılan 1) — Orta blokta her katmanda kullanılacak transformer katman sayısı.
  • attention_head_dim (int veya tuple[int], varsayılan 8) — Dikkat başlarının boyutu.
  • num_attention_heads (int veya tuple[int], isteğe bağlı) — Çok başlı dikkat (multi-head attention) için kullanılacak baş sayısı.
  • use_linear_projection (bool, varsayılan False) —
  • 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.
  • conditioning_embedding_out_channels (tuple[int], 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
  • controlnet_conditioning_channel_order (str, varsayılan rgb) —
  • motion_max_seq_length (int, varsayılan 32) — Hareket modülünde kullanılacak maksimum dizi uzunluğu.
  • motion_num_attention_heads (int veya tuple[int], varsayılan 8) — Hareket modülündeki her dikkat katmanında kullanılacak baş sayısı.
  • concat_conditioning_mask (bool, varsayılan True) —
  • use_simplified_condition_embedding (bool, varsayılan True) —

SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models makalesinde tanımlandığı gibi bir SparseControlNet modeli.

forward

< >

( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0timestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Noneconditioning_mask: typing.Optional[torch.Tensor] = Noneguess_mode: bool = Falsereturn_dict: bool = True ) → ~models.controlnet.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ü.
  • 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.
  • conditioning_mask (torch.Tensor, isteğe bağlı, varsayılan None) — controlnet_cond içinde geçerli koşullama karelerini gösteren isteğe bağlı maske.
  • 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 ~models.controlnet.ControlNetOutput döndürülüp döndürülmemesi.

Dönüş değeri

~models.controlnet.ControlNetOutput veya tuple

return_dict True ise ~models.controlnet.ControlNetOutput döndürülür, aksi halde bir tuple döndürülür ve bu tuple'ın ilk öğesi örnek tensörüdür.

SparseControlNetModel 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) — SparseControlNetModel'e kopyalanacak UNet model ağırlıkları. Uygulanabilir tüm yapılandırma seçenekleri de kopyalanır.

UNet2DConditionModel içinden bir SparseControlNetModel örnekleyin.

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.

SparseControlNetOutput

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

< >

( 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.

SparseControlNetModel'nin çıktısı.

Update on GitHub

←SD3ControlNetModel AceStepTransformer1DModel→