# SanaVideoTransformer3DModel

NVIDIA와 MIT HAN Lab의 Junsong Chen, Yuyang Zhao, Jincheng Yu, Ruihang Chu, Junyu Chen, Shuai Yang, Xianbang Wang, Yicheng Pan, Daquan Zhou, Huan Ling, Haozhe Liu, Hongwei Yi, Hao Zhang, Muyang Li, Yukang Chen, Han Cai, Sanja Fidler, Ping Luo, Song Han, Enze Xie가 발표한 [SANA-Video: Efficient Video Generation with Block Linear Diffusion Transformer](https://huggingface.co/papers/2509.24695)의 3D 데이터(비디오)용 Diffusion Transformer 모델입니다.

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

*SANA-Video를 소개합니다. SANA-Video는 최대 720x1280 해상도와 분 단위 길이의 영상을 효율적으로 생성할 수 있는 소형 diffusion 모델입니다. SANA-Video는 놀라울 정도로 빠른 속도로 텍스트-영상 정합성이 강한 고해상도, 고품질, 장시간 영상을 합성하며, RTX 5090 GPU에 배포할 수 있습니다. 효율적이고 효과적이며 긴 영상 생성을 보장하는 두 가지 핵심 설계가 있습니다. (1) Linear DiT: 영상 생성에서 처리되는 토큰 수가 많기 때문에, 기존 attention보다 효율적인 linear attention을 핵심 연산으로 활용합니다. (2) Block Linear Attention을 위한 Constant-Memory KV cache: linear attention의 누적 특성에서 파생된 constant-memory state를 사용하여 장시간 영상 생성을 위한 블록 단위 자기회귀(block-wise autoregressive) 접근법을 설계했습니다. 이 KV cache는 고정된 메모리 비용으로 Linear DiT에 전역 컨텍스트를 제공하여, 기존 KV cache의 필요성을 제거하고 효율적인 분 단위 영상 생성을 가능하게 합니다. 또한, 효과적인 데이터 필터와 모델 학습 전략을 탐구하여 64개의 H100 GPU에서 학습 비용을 12일로 줄였으며, 이는 MovieGen 비용의 1%에 불과합니다. 이러한 낮은 비용에도 불구하고, SANA-Video는 측정된 지연 시간에서 16배 더 빠른 속도로, 최신 state-of-the-art 소형 diffusion 모델(예: Wan 2.1-1.3B 및 SkyReel-V2-1.3B)과 경쟁하는 성능을 달성합니다. 나아가, SANA-Video는 NVFP4 정밀도로 RTX 5090 GPU에 배포할 수 있으며, 5초 720p 영상 생성의 추론 속도를 71초에서 29초로 단축시켜 2.4배의 속도 향상을 실현합니다. 요약하자면, SANA-Video는 저비용 고품질 영상 생성을 가능하게 합니다.*

다음 코드 스니펫으로 모델을 로드할 수 있습니다.

```python
from diffusers import SanaVideoTransformer3DModel
import torch

transformer = SanaVideoTransformer3DModel.from_pretrained("Efficient-Large-Model/SANA-Video_2B_480p_diffusers", subfolder="transformer", dtype=torch.bfloat16)
```

## SanaVideoTransformer3DModel[[diffusers.SanaVideoTransformer3DModel]]

#### diffusers.SanaVideoTransformer3DModel[[diffusers.SanaVideoTransformer3DModel]]

```python
diffusers.SanaVideoTransformer3DModel(in_channels: int = 16, out_channels: int | None = 16, num_attention_heads: int = 20, attention_head_dim: int = 112, num_layers: int = 20, num_cross_attention_heads: int | None = 20, cross_attention_head_dim: int | None = 112, cross_attention_dim: int | None = 2240, caption_channels: int = 2304, mlp_ratio: float = 2.5, dropout: float = 0.0, attention_bias: bool = False, sample_size: int = 30, patch_size: tuple = (1, 2, 2), norm_elementwise_affine: bool = False, norm_eps: float = 1e-06, interpolation_scale: int | None = None, guidance_embeds: bool = False, guidance_embeds_scale: float = 0.1, qk_norm: str | None = 'rms_norm_across_heads', rope_max_seq_len: int = 1024)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_video.py#L459)

**매개변수:**

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

out_channels (`int`, *선택 사항*, 기본값 `16`) : 출력의 채널 수입니다.

num_attention_heads (`int`, 기본값 `20`) : multi-head attention에 사용할 head의 수입니다.

attention_head_dim (`int`, 기본값 `112`) : 각 헤드(head)의 채널 수.

num_layers (`int`, 기본값 `20`) : 사용할 Transformer 블록의 레이어 수입니다.

num_cross_attention_heads (`int`, *선택 사항*, 기본값 `20`) : cross-attention에 사용할 헤드 수입니다.

cross_attention_head_dim (`int`, *선택 사항*, 기본값 `112`) : cross-attention의 각 head당 채널 수입니다.

cross_attention_dim (`int`, *선택 사항*, 기본값 `2240`) : cross-attention 출력의 채널 수입니다.

caption_channels (`int`, 기본값 `2304`) : 캡션 임베딩의 채널 수입니다.

mlp_ratio (`float`, 기본값 `2.5`) : GLUMBConv 레이어에서 사용할 확장 비율입니다.

dropout (`float`, 기본값 `0.0`) : dropout 확률입니다.

attention_bias (`bool`, 기본값 `False`) : attention layer에서 bias를 사용할지 여부.

sample_size (`int`, 기본값 `32`) : 입력 latent의 기본 크기입니다.

patch_size (`int`, 기본값 `1`) : 패치 임베딩 레이어에서 사용할 패치의 크기입니다.

norm_elementwise_affine (`bool`, 기본값 `False`) : 정규화 레이어에서 요소별 어피니티(elementwise affinity)를 사용할지 여부.

norm_eps (`float`, 기본값 `1e-6`) : 정규화 레이어의 epsilon 값입니다.

qk_norm (`str`, *선택 사항*, 기본값 `None`) : 쿼리와 키에 사용할 정규화입니다.

[Sana-Video](https://huggingface.co/papers/2509.24695) 모델 계열에서 소개된 3D Transformer 모델입니다.

#### forward[[diffusers.SanaVideoTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, guidance: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, attention_kwargs: dict[str, typing.Any] | None = None, controlnet_block_samples: tuple[torch.Tensor] | None = None, return_dict: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_video.py#L575)

**매개변수:**

hidden_states (`torch.Tensor`, shape `(batch_size, in_channels, num_frames, height, width)`) : 입력 `hidden_states`.

encoder_hidden_states (`torch.Tensor`, shape `(batch_size, sequence_len, embed_dims)`) : 사용할 조건 임베딩(프롬프트와 같은 입력 조건에서 계산된 임베딩).

timestep (`torch.LongTensor`) : 노이즈 제거 단계를 나타내는 데 사용됩니다.

guidance (`torch.Tensor`, *선택 사항*) : Guidance scale 임베딩.

encoder_attention_mask (`torch.Tensor`, *선택 사항*) : `encoder_hidden_states`에 적용되는 크로스 어텐션 마스크.

attention_mask (`torch.Tensor`, *선택 사항*) : `hidden_states`에 적용되는 자기 주의(self-attention) 마스크입니다.

attention_kwargs (`dict`, *선택 사항*) : 지정된 경우 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py)의 `self.processor` 아래에서 정의된 `AttentionProcessor`로 전달되는 kwargs 사전입니다.

controlnet_block_samples (`tuple` of `torch.Tensor`, *선택 사항*) : 지정된 경우, Transformer 블록의 잔차(residuals)에 추가되는 텐서 목록입니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 `~models.transformer_2d.Transformer2DModelOutput`을 반환할지 여부.

**반환값:**

`return_dict`가 True이면 `~models.transformer_2d.Transformer2DModelOutput`이 반환되고, 그렇지 않으면 첫 번째 요소가 샘플 텐서인 `tuple`이 반환됩니다.

[SanaVideoTransformer3DModel](/docs/diffusers/main/ko/api/models/sana_video_transformer3d#diffusers.SanaVideoTransformer3DModel)의 forward 메서드입니다.

## Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

#### diffusers.models.modeling_outputs.Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

```python
diffusers.models.modeling_outputs.Transformer2DModelOutput(sample: torch.Tensor)
```

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

**매개변수:**

sample (`torch.Tensor`, shape `(batch_size, num_channels, height, width)` 또는 [Transformer2DModel](/docs/diffusers/main/ko/api/models/transformer2d#diffusers.Transformer2DModel)이 discrete인 경우 `(batch size, num_vector_embeds - 1, num_latent_pixels)`) : `encoder_hidden_states` 입력에 조건부인 hidden states 출력입니다. discrete인 경우, 노이즈가 제거된 latent 픽셀에 대한 확률 분포를 반환합니다.

[Transformer2DModel](/docs/diffusers/main/ko/api/models/transformer2d#diffusers.Transformer2DModel)의 출력입니다.