# SparseControlNetModel

SparseControlNetModel は、[AnimateDiff](https://huggingface.co/papers/2307.04725) 向けの ControlNet の実装です。

ControlNetは、Lvmin Zhang、Anyi Rao、Maneesh Agrawalaによる論文[Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543)で提案されました。

ControlNet の SparseCtrl バージョンは、Yuwei Guo、Ceyuan Yang、Anyi Rao、Maneesh Agrawala、Dahua Lin、Bo Dai によって、テキストから動画への拡散モデルにおける制御付き生成を実現するために、[SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) で紹介されました。

論文の抄録は以下の通りです：

*テキストから動画を生成する（T2V）技術、すなわち与えられたテキストプロンプトから動画を生成する技術は、近年大きく発展してきました。しかし、テキストプロンプトのみを頼りにすると、空間的な不確実性により、フレームの構図が曖昧になりがちです。そのため、研究コミュニティでは、フレームごとの深度やエッジのシーケンスといった高密度な構造シグナルを活用して制御性を高めるアプローチがとられていますが、これに伴い推論時の負荷が増大するという問題があります。本稿では、図1に示すように、1つまたは数個の入力のみで柔軟な構造制御を可能にする SparseCtrl を提案します。SparseCtrl は、事前学習済みの T2V モデルを変更せずに、これらのスパースなシグナルを処理するための追加の条件エンコーダを組み込んでいます。提案手法は、スケッチ、深度マップ、RGB 画像など、さまざまなモダリティに対応しており、動画生成におけるより実用的な制御を提供するとともに、ストーリーボード作成、深度レンダリング、キーフレームアニメーション、補間などの応用を促進します。広範な実験により、SparseCtrl はオリジナルおよびパーソナライズされた T2V 生成器の両方で汎化能力を示すことが確認されました。コードとモデルは [this https URL](https://guoyww.github.io/projects/SparseCtrl) で公開予定です。*

## SparseControlNetModel を読み込む例

```python
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]]

```python
diffusers.SparseControlNetModel(in_channels: int = 4, conditioning_channels: int = 4, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion'), 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, 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)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L97)

**パラメータ:**

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 ブロック用の時間スケールシフト設定（`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](https://huggingface.co/papers/2311.16933) に記載されている SparseControlNet モデル。

#### forward[[diffusers.SparseControlNetModel.forward]]

```python
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)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L534)

**パラメータ:**

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`) : タイムステップ用の追加の条件埋め込みです。指定された場合、これらの埋め込みは`self.time_embedding`層を介して渡されるtimestep_embeddingに足し合わされ、最終的なタイムステップ埋め込みが得られます。

attention_mask (`torch.Tensor`, *任意*、デフォルトは`None`) : 形状`(batch, key_tokens)`のattention maskが`encoder_hidden_states`に適用されます。`1`の場合はマスクが保持され、`0`の場合は破棄されます。マスクはバイアスに変換され、「破棄」トークンに対応するattention scoreに大きな負の値が加算されます。

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](/docs/diffusers/v0.43.0/ja/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel)のforwardメソッド。

#### from_unet[[diffusers.SparseControlNetModel.from_unet]]

```python
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)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L388)

**パラメータ:**

unet (`UNet2DConditionModel`) : [SparseControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel) にコピーする UNet モデルの重みです。適用可能なすべての設定オプションもコピーされます。

[UNet2DConditionModel](/docs/diffusers/v0.43.0/ja/api/models/unet2d-cond#diffusers.UNet2DConditionModel)から[SparseControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel)をインスタンス化します。

#### set_attention_slice[[diffusers.SparseControlNetModel.set_attention_slice]]

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

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L469)

**パラメータ:**

slice_size (`str` または `int` または `list(int)`、*任意*、デフォルトは `"auto"`) : `"auto"` の場合、アテンションヘッドへの入力が半分になり、アテンションは2段階で計算されます。`"max"` の場合、一度に1つのスライスのみを実行することで、最大限のメモリを節約します。数値が指定された場合、`attention_head_dim // slice_size` 個のスライスを使用します。この場合、`attention_head_dim` は `slice_size` の倍数である必要があります。

スライスされたアテンションの計算を有効にします。

このオプションを有効にすると、attention モジュールは入力テンソルをスライスに分割し、複数ステップで attention を計算します。これは、わずかな速度低下を代償にメモリを節約するのに役立ちます。

#### set_default_attn_processor[[diffusers.SparseControlNetModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L453)

カスタムアテンションプロセッサを無効にし、デフォルトのアテンション実装を設定します。

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

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

```python
diffusers.models.controlnets.SparseControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L44)

**パラメータ:**

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](/docs/diffusers/v0.43.0/ja/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel)の出力です。