Diffusers documentation
SparseControlNetModel
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 parameterSparseControlNetModel
클래스 diffusers.SparseControlNetModel
< source >( in_channels: int = 4conditioning_channels: int = 4flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple = (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) — 미드 블록에 사용할 스케일 팩터입니다. - 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], 선택 사항) — multi-head attention에 사용할 헤드 수입니다. - 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 모듈에서 사용할 최대 시퀀스 길이입니다. - motion_num_attention_heads (
int또는tuple[int], 기본값8) — motion 모듈의 각 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
< 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) —(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 or 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) — SparseControlNetModel에 복사할 UNet 모델 가중치입니다. 적용 가능한 모든 구성 옵션도 함께 복사됩니다.
UNet2DConditionModel에서 SparseControlNetModel을(를) 초기화합니다.
set_attention_slice
< source >( slice_size: str | int | list[int] )
슬라이스된 어텐션 계산을 활성화합니다.
이 옵션이 활성화되면 attention 모듈은 입력 텐서를 슬라이스로 분할하여 여러 단계에 걸쳐 attention을 계산합니다. 이는 속도가 약간 감소하는 대신 메모리를 절약하는 데 유용합니다.
커스텀 어텐션 프로세서를 비활성화하고 기본 어텐션 구현을 설정합니다.
SparseControlNetOutput
클래스 diffusers.models.controlnets.SparseControlNetOutput
< source >( down_block_res_samples: tuplemid_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의 출력입니다.