diffusers/main/tr/api/models/controlnet_sparsectrl.md

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[[diffusers.SparseControlNetModel]]

diffusers.SparseControlNetModel[[diffusers.SparseControlNetModel]]

diffusers.SparseControlNetModel(in_channels: int = 4, conditioning_channels: int = 4, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion'), only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple = (320, 640, 1280, 1280), layers_per_block: int = 2, downsample_padding: int = 1, mid_block_scale_factor: float = 1, act_fn: str = 'silu', norm_num_groups: int | None = 32, norm_eps: float = 1e-05, cross_attention_dim: int = 768, transformer_layers_per_block: int | tuple[int, ...] = 1, transformer_layers_per_mid_block: int | tuple[int] | None = None, temporal_transformer_layers_per_block: int | tuple[int, ...] = 1, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), global_pool_conditions: bool = False, controlnet_conditioning_channel_order: str = 'rgb', motion_max_seq_length: int = 32, motion_num_attention_heads: int = 8, concat_conditioning_mask: bool = True, use_simplified_condition_embedding: bool = True)

Kaynak

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ömümünde sin'in cos'a çevrilip çevrilmeyeceğini belirtir.

freq_shift (int, varsayılan 0) : Zaman gömümüne uygulanacak frekans kayması.

down_block_types (tuple[str], varsayılan ("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) : Kullanılacak indirgeme 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) : Küçültme 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, işleme sonrası aşamasında 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 ö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 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çeği 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ı sayısı içeren 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[[diffusers.SparseControlNetModel.forward]]

forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, conditioning_mask: typing.Optional[torch.Tensor] = None, guess_mode: bool = False, return_dict: bool = True)

Kaynak

Parametreler:

sample (torch.Tensor) : Gürültülü girdi tensörü.

timestep (torch.Tensor | float | int) : Bir girdiyi gürültüden arındırmak için kullanılacak zaman adımı sayısı.

encoder_hidden_states (torch.Tensor) : Kodlayıcı gizli durumları.

controlnet_cond (torch.Tensor) : (batch_size, sequence_length, hidden_size) biçimindeki 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) : timestep için ek koşullu gömme (embeddings). Sağlanırsa, gömme, self.time_embedding katmanından geçirilen timestep_embedding ile toplanarak nihai timestep gömmeleri elde edilir.

attention_mask (torch.Tensor, isteğe bağlı, varsayılan None) : (batch, key_tokens) biçimindeki bir dikkat maskesi, encoder_hidden_states üzerine uygulanır. Değer 1 ise maske korunur, aksi halde 0 ise atılır. Maske, "at" token'ları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çindeki geçerli koşullandırma 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ülecek mi?

Dönüş: ~models.controlnet.ControlNetOutput veya tuple

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

SparseControlNetModel ileri yöntemi.

from_unet[[diffusers.SparseControlNetModel.from_unet]]

from_unet(unet: UNet2DConditionModel, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), load_weights_from_unet: bool = True, conditioning_channels: int = 3)

Kaynak

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[[diffusers.SparseControlNetModel.set_attention_slice]]

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

Kaynak

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 yarıya indirilir, böylece dikkat iki adımda hesaplanır. "max" ise, her seferinde yalnızca bir dilim çalıştırılarak maksimum miktarda bellek tasarrufu sağlanır. Bir sayı sağlanırsa, attention_head_dim // slice_size kadar dilim kullanılır. Bu durumda attention_head_dim, slice_size'ın katı olmalıdır.

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

Bu seçenek etkinleştirildiğinde, dikkat modülü dikkat hesaplaması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[[diffusers.SparseControlNetModel.set_default_attn_processor]]

set_default_attn_processor()

Kaynak

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

SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

diffusers.models.controlnets.SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

diffusers.models.controlnets.SparseControlNetOutput(down_block_res_samples: tuple, mid_block_res_sample: Tensor)

Kaynak

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 tuple. Her tensorin ş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ı.