# 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)에서 소개했습니다.

SparseCtrl 버전의 ControlNet은 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), 즉 주어진 텍스트 프롬프트로 비디오를 생성하는 기술은 최근 몇 년간 크게 발전했습니다. 그러나 텍스트 프롬프트에만 의존하면 공간적 불확실성으로 인해 프레임 구성이 모호해지기 쉽습니다. 이에 연구 커뮤니티는 프레임별 깊이/엣지 시퀀스와 같은 밀집된 구조 신호를 활용하여 제어 가능성을 높이고자 하지만, 이로 인해 추론 시 수집해야 할 부하가 증가합니다. 본 연구에서는 Figure 1에 제시된 바와 같이, 시간적으로 희소(sparse)한 신호를 사용하여 유연한 구조 제어를 가능하게 하는 SparseCtrl을 제안합니다. 이 방법은 입력으로 하나 또는 소수의 신호만 필요로 하며, 사전 학습된 T2V 모델은 그대로 유지하면서 이러한 희소 신호를 처리하기 위한 추가 조건 인코더를 통합합니다. 제안된 접근법은 스케치, 깊이 맵, RGB 이미지 등 다양한 모달리티와 호환되어 비디오 생성에 보다 실용적인 제어를 제공하며, 스토리보딩, 깊이 렌더링, 키프레임 애니메이션, 보간과 같은 응용 분야를 촉진합니다. 광범위한 실험을 통해 SparseCtrl이 원래의 T2V 생성기 및 개인화된 T2V 생성기 모두에서 일반화됨을 입증했습니다. 코드와 모델은 [이 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 = ('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)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L97)

**매개변수:**

in_channels (`int`, 기본값 4) : 입력 샘플의 채널 수.

conditioning_channels (`int`, 기본값 4) : controlnet conditional embedding 모듈의 입력 채널 수입니다. `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) : 중간 블록에 사용할 스케일 팩터입니다.

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) : attention head의 차원입니다.

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 module에서 사용할 최대 시퀀스 길이입니다.

motion_num_attention_heads (`int` 또는 `tuple[int]`, 기본값 `8`) : motion module의 각 attention layer에서 사용할 head의 수입니다.

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/main/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`) : timestep에 대한 추가 조건부 임베딩입니다. 제공되면, `self.time_embedding` 레이어를 통해 전달된 timestep_embedding과 합산되어 최종 timestep 임베딩을 얻습니다.

attention_mask (`torch.Tensor`, *선택 사항*, 기본값 `None`) : `(batch, key_tokens)` 모양의 attention mask가 `encoder_hidden_states`에 적용됩니다. `1`인 경우 mask가 유지되고, `0`인 경우 폐기됩니다. Mask는 bias로 변환되어 "폐기" 토큰에 해당하는 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/main/ko/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/main/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L388)

**매개변수:**

unet (`UNet2DConditionModel`) : [SparseControlNetModel](/docs/diffusers/main/ko/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel)에 복사할 UNet 모델 가중치입니다. 적용 가능한 모든 구성 옵션도 함께 복사됩니다.

[UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel)에서 [SparseControlNetModel](/docs/diffusers/main/ko/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/main/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L469)

**매개변수:**

slice_size (`str` 또는 `int` 또는 `list(int)`, *선택 사항*, 기본값은 `"auto"`) : `"auto"`인 경우, attention head에 입력되는 값이 절반으로 줄어 attention이 두 단계로 계산됩니다. `"max"`인 경우, 한 번에 하나의 slice만 실행하여 최대의 메모리를 절약합니다. 숫자가 제공되면 `attention_head_dim // slice_size`만큼의 slice를 사용합니다. 이 경우 `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/main/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, mid_block_res_sample: Tensor)
```

[소스](https://github.com/huggingface/diffusers/blob/main/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/main/ko/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel)의 출력입니다.