Hugging Face's logo

Diffusers documentation

SparseControlNetModel

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

SparseControlNetModel

SparseControlNetModel adalah implementasi ControlNet untuk AnimateDiff.

ControlNet diperkenalkan dalam Menambahkan Kontrol Kondisional ke Model Difusi Teks-ke-Gambar oleh Lvmin Zhang, Anyi Rao, dan Maneesh Agrawala.

Versi SparseCtrl dari ControlNet diperkenalkan dalam SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models untuk mencapai generasi terkendali pada model difusi teks-ke-video oleh Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin, dan Bo Dai.

Abstrak dari makalah tersebut adalah:

Pengembangan text-to-video (T2V), yaitu menghasilkan video dengan prompt teks tertentu, telah mengalami kemajuan signifikan dalam beberapa tahun terakhir. Namun, ketergantungan hanya pada prompt teks sering kali menghasilkan komposisi frame yang ambigu karena ketidakpastian spasial. Oleh karena itu, komunitas riset memanfaatkan sinyal struktur yang padat, misalnya urutan kedalaman/tepi per frame, untuk meningkatkan keterkendalian, yang secara bersamaan meningkatkan beban inferensi. Dalam karya ini, kami memperkenalkan SparseCtrl untuk memungkinkan kontrol struktur yang fleksibel dengan sinyal yang jarang secara temporal, yang hanya memerlukan satu atau beberapa input, seperti yang ditunjukkan pada Gambar 1. Pendekatan ini mengintegrasikan encoder kondisi tambahan untuk memproses sinyal-sparse tersebut sambil membiarkan model T2V yang telah dilatih sebelumnya tetap utuh. Pendekatan yang diusulkan kompatibel dengan berbagai modalitas, termasuk sketsa, peta kedalaman, dan gambar RGB, sehingga memberikan kontrol yang lebih praktis untuk generasi video dan mendorong aplikasi seperti storyboarding, rendering kedalaman, animasi keyframe, dan interpolasi. Eksperimen ekstensif menunjukkan generalisasi SparseCtrl pada generator T2V asli maupun yang dipersonalisasi. Kode dan model akan tersedia secara publik di URL https ini.

Contoh untuk memuat SparseControlNetModel

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

kelas diffusers.SparseControlNetModel

< >

( in_channels: int = 4conditioning_channels: int = 4flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple[int, ...] = (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 )

Parameter

  • in_channels (int, defaultnya 4) — Jumlah channel pada sampel input.
  • conditioning_channels (int, default 4) — Jumlah channel input pada modul conditional embedding controlnet. Jika concat_condition_embedding bernilai True, nilai yang diberikan di sini akan ditambah 1.
  • 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.
  • transformer_layers_per_mid_block (int atau tuple[int], opsional, default 1) — Jumlah lapisan transformer yang digunakan di setiap lapisan pada blok tengah.
  • attention_head_dim (int atau tuple[int], defaultnya 8) — Dimensi dari kepala perhatian (attention heads).
  • num_attention_heads (int atau tuple[int], opsional) — Jumlah head yang digunakan untuk multi-head attention.
  • use_linear_projection (bool, defaultnya False) —
  • 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.
  • conditioning_embedding_out_channels (tuple[int], 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
  • controlnet_conditioning_channel_order (str, defaultnya rgb) —
  • motion_max_seq_length (int, defaultnya 32) — Panjang urutan maksimum yang digunakan dalam modul gerak.
  • motion_num_attention_heads (int atau tuple[int], defaultnya 8) — Jumlah head yang digunakan di setiap lapisan perhatian pada modul gerak.
  • concat_conditioning_mask (bool, defaultnya True) —
  • use_simplified_condition_embedding (bool, defaultnya True) —

Model SparseControlNet seperti yang dijelaskan dalam SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models.

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

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.
  • 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”.
  • conditioning_mask (torch.Tensor, opsional, default None) — Mask opsional yang menunjukkan frame mana saja dalam controlnet_cond yang merupakan frame conditioning yang valid.
  • 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 ~models.controlnet.ControlNetOutput alih-alih tuple biasa.

Mengembalikan

~models.controlnet.ControlNetOutput atau tuple

Jika return_dict adalah True, sebuah ~models.controlnet.ControlNetOutput akan dikembalikan, selain itu sebuah tuple akan dikembalikan di mana elemen pertama adalah tensor sampel.

Metode forward dari SparseControlNetModel.

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 SparseControlNetModel. Semua opsi konfigurasi juga disalin jika berlaku.

Instansiasi SparseControlNetModel 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.

SparseControlNetOutput

kelas diffusers.models.controlnets.SparseControlNetOutput

< >

( down_block_res_samples: tuple[torch.Tensor]mid_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 SparseControlNetModel.

Update on GitHub

←SD3ControlNetModel AceStepTransformer1DModel→