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

SparseControlNetModel

SparseControlNetModel은 AnimateDiff용 ControlNet 구현입니다.

ControlNet은 Lvmin Zhang, Anyi Rao, Maneesh Agrawala가 Adding Conditional Control to Text-to-Image Diffusion Models에서 소개했습니다.

SparseCtrl 버전의 ControlNet은 Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin, Bo Dai가 SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models에서 텍스트-비디오 확산 모델의 제어 생성을 위해 도입했습니다.

해당 논문의 초록은 다음과 같습니다:

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

소스

매개변수:

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에 설명된 SparseControlNet 모델입니다.

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)

소스

매개변수:

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의 forward 메서드입니다.

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)

소스

매개변수:

unet (UNet2DConditionModel) : SparseControlNetModel에 복사할 UNet 모델 가중치입니다. 적용 가능한 모든 구성 옵션도 함께 복사됩니다.

UNet2DConditionModel에서 SparseControlNetModel을(를) 초기화합니다.

set_attention_slice[[diffusers.SparseControlNetModel.set_attention_slice]]

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

소스

매개변수:

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

set_default_attn_processor()

소스

커스텀 어텐션 프로세서를 비활성화하고 기본 어텐션 구현을 설정합니다.

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)

소스

매개변수:

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의 출력입니다.