Diffusers documentation
SparseControlNetModel
SparseControlNetModel
SparseControlNetModel は、AnimateDiff 向けの ControlNet の実装です。
ControlNetは、Lvmin Zhang、Anyi Rao、Maneesh Agrawalaによる論文Adding Conditional Control to Text-to-Image Diffusion Modelsで提案されました。
ControlNet の SparseCtrl バージョンは、Yuwei Guo、Ceyuan Yang、Anyi Rao、Maneesh Agrawala、Dahua Lin、Bo Dai によって、テキストから動画への拡散モデルにおける制御付き生成を実現するために、SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models で紹介されました。
論文の抄録は以下の通りです：
テキストから動画を生成する（T2V）技術、すなわち与えられたテキストプロンプトから動画を生成する技術は、近年大きく発展してきました。しかし、テキストプロンプトのみを頼りにすると、空間的な不確実性により、フレームの構図が曖昧になりがちです。そのため、研究コミュニティでは、フレームごとの深度やエッジのシーケンスといった高密度な構造シグナルを活用して制御性を高めるアプローチがとられていますが、これに伴い推論時の負荷が増大するという問題があります。本稿では、図1に示すように、1つまたは数個の入力のみで柔軟な構造制御を可能にする SparseCtrl を提案します。SparseCtrl は、事前学習済みの T2V モデルを変更せずに、これらのスパースなシグナルを処理するための追加の条件エンコーダを組み込んでいます。提案手法は、スケッチ、深度マップ、RGB 画像など、さまざまなモダリティに対応しており、動画生成におけるより実用的な制御を提供するとともに、ストーリーボード作成、深度レンダリング、キーフレームアニメーション、補間などの応用を促進します。広範な実験により、SparseCtrl はオリジナルおよびパーソナライズされた T2V 生成器の両方で汎化能力を示すことが確認されました。コードとモデルは this https URL で公開予定です。
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 parameterSparseControlNetModel
class diffusers.SparseControlNetModel
< source >( 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 )
パラメータ
- in_channels (
int、デフォルト値は 4) — 入力サンプルのチャネル数。 - conditioning_channels (
int、デフォルト値は 4) — ControlNet の条件埋め込みモジュールにおける入力チャネル数です。concat_condition_embeddingが True の場合、ここで指定した値に 1 が加算されます。 - flip_sin_to_cos (
bool、デフォルトはTrue) — 時間埋め込みにおいて sin を cos に反転させるかどうか。 - freq_shift (
int、デフォルト値は 0) — 時間埋め込みに適用する周波数シフト。 - down_block_types (
tuple[str]、デフォルトは("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) — 使用するダウンサンプリングブロックのタプルです。 - only_cross_attention (
bool | tuple[bool]、デフォルトはFalse) — - block_out_channels (
tuple[int]、デフォルトは(320, 640, 1280, 1280)) — 各ブロックの出力チャネル数を表すタプルです。 - layers_per_block (
int、デフォルト値は 2) — ブロックあたりのレイヤー数です。 - downsample_padding (
int、デフォルト値は 1) — ダウンサンプリング用畳み込みで使用するパディング。 - mid_block_scale_factor (
float、デフォルト値は 1) — mid block に使用するスケール係数です。 - act_fn (
str、デフォルトは “silu”) — 使用する活性化関数。 - norm_num_groups (
int、任意、デフォルトは 32) — 正規化に使用するグループ数です。None の場合、後処理で正規化層と活性化層はスキップされます。 - norm_eps (
float、デフォルト値は 1e-5) — 正規化に使用する epsilon です。 - cross_attention_dim (
int、デフォルト値は 1280)— クロスアテンション特徴量の次元数です。 - transformer_layers_per_block (
intまたはtuple[int]、省略可、デフォルトは 1) —BasicTransformerBlock型の Transformer ブロックの数。~models.unet_2d_blocks.CrossAttnDownBlock2D、~models.unet_2d_blocks.CrossAttnUpBlock2D、~models.unet_2d_blocks.UNetMidBlock2DCrossAttnの場合にのみ関連します。 - transformer_layers_per_mid_block (
intまたはtuple[int]、省略可、デフォルトは 1) — ミドルブロックの各レイヤーで使用する transformer レイヤーの数です。 - attention_head_dim (
intまたはtuple[int]、デフォルトは 8) — アテンションヘッドの次元です。 - num_attention_heads (
intまたはtuple[int]、任意) — マルチヘッドアテンションに使用するヘッドの数。 - use_linear_projection (
bool、デフォルトはFalse) — - upcast_attention（
bool、デフォルトはFalse）— - resnet_time_scale_shift (
str、デフォルトは"default") — ResNet ブロック用の time scale shift 設定(ResnetBlock2Dを参照)。defaultまたはscale_shiftから選択します。 - conditioning_embedding_out_channels (
tuple[int]、デフォルトは(16, 32, 96, 256)) —conditioning_embeddingレイヤー内の各ブロックの出力チャネル数を表すタプルです。 - global_pool_conditions (
bool、デフォルトはFalse) — TODO(Patrick) - 未使用のパラメータ - controlnet_conditioning_channel_order（
str、デフォルトはrgb）— - motion_max_seq_length (
int、デフォルトは32) — モーションモジュールで使用するシーケンス長の最大値です。 - motion_num_attention_heads (
intまたはtuple[int]、デフォルトは8) — モーションモジュールの各アテンション層で使用するヘッド数です。 - concat_conditioning_mask (
bool、デフォルトはTrue) — - use_simplified_condition_embedding (
bool、デフォルトはTrue) —
SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models に記載されている SparseControlNet モデル。
forward
< source >( 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
パラメータ
- sample (
torch.Tensor) — ノイズ付きの入力テンソルです。 - timestep (
torch.Tensor | float | int) — 入力ノイズを除去するためのタイムステップ数です。 - encoder_hidden_states (
torch.Tensor) — エンコーダーの隠れ状態です。 - controlnet_cond (
torch.Tensor) —(batch_size, sequence_length, hidden_size)の形状を持つ条件付き入力テンソルです。 - conditioning_scale (
float、デフォルト値は1.0) — ControlNet の出力に対するスケール係数です。 - timestep_cond (
torch.Tensor、任意、デフォルトはNone) — timestep 用の追加の条件埋め込みです。指定された場合、これらの埋め込みはself.time_embeddingレイヤーを介して渡される timestep_embedding に加算され、最終的な timestep 埋め込みが得られます。 - attention_mask (
torch.Tensor、任意、デフォルトはNone) —encoder_hidden_statesに適用される、形状が(batch, key_tokens)のアテンションマスクです。1の場合はマスクが保持され、0の場合は破棄されます。マスクはバイアスに変換され、「破棄」対象のトークンに対応するアテンションスコアに大きな負の値が加算されます。 - conditioning_mask (
torch.Tensor、任意、デフォルトはNone) —controlnet_cond内のどのフレームが有効な条件付けフレームであるかを示す任意のマスク。 - cross_attention_kwargs (
dict[str]、省略可、デフォルトはNone) — 指定された場合、AttnProcessorに渡される kwargs の辞書です。 - guess_mode (
bool、デフォルトはFalse) — このモードでは、すべてのプロンプトを削除した場合でも、ControlNet エンコーダーは入力内容の認識に最大限努めます。guidance_scaleは 3.0 から 5.0 の範囲が推奨されます。 - return_dict (
bool、デフォルトはTrue) —~models.controlnet.ControlNetOutputを返すか、プレーンなタプルを返すかを指定します。
戻り値
~models.controlnet.ControlNetOutput または tuple
return_dict が True の場合、~models.controlnet.ControlNetOutput が返され、それ以外の場合は、最初の要素がサンプルテンソルであるタプルが返されます。
SparseControlNetModelのforwardメソッド。
from_unet
< source >( 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 )
パラメータ
- unet (
UNet2DConditionModel) — The UNet model weights to copy to the SparseControlNetModel. All configuration options are also copied where applicable.
UNet2DConditionModelからSparseControlNetModelをインスタンス化します。
set_attention_slice
< source >( slice_size: str | int | list[int] )
スライスされたアテンションの計算を有効にします。
このオプションが有効な場合、attention モジュールは入力テンソルをスライスに分割し、複数ステップで attention を計算します。これは、わずかな速度低下を代償にメモリを節約するために有用です。
カスタムアテンションプロセッサを無効にし、デフォルトのアテンション実装を設定します。
SparseControlNetOutput
クラス diffusers.models.controlnets.SparseControlNetOutput
< source >( down_block_res_samples: tuple[torch.Tensor]mid_block_res_sample: Tensor )
パラメータ
- down_block_res_samples (
tuple[torch.Tensor]) — 各ダウンサンプリングブロックにおける、異なる解像度のダウンサンプル活性化値のタプルです。各テンソルの形状は(batch_size, channel * resolution, height //resolution, width // resolution)である必要があります。出力は、元の UNet のダウンサンプリング活性化値の条件付けに使用できます。 - mid_down_block_re_sample (
torch.Tensor) — 中間ブロックの活性化（最も低いサンプル解像度）です。各テンソルの形状は(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)である必要があります。出力は、元の UNet の中間ブロックの活性化を条件付けするために使用できます。
SparseControlNetModelの出力です。