# WanAnimate2Transformer3DModel

Alibaba Wan Team의 [Wan-Animate-2](https://github.com/Wan-Video/Wan2.2)에 사용되는 3D 비디오 유사 데이터용 Diffusion Transformer 모델입니다. 인-컨텍스트 참조 메커니즘을 통해 구동 비디오의 움직임으로 캐릭터 이미지를 애니메이션화합니다. 각 세그먼트는 먼저 모든 레이어의 참조 K/V를 캐시하는 참조 패스(`kv_cache_mode="extract"`)를 실행한 후, 디노이징 패스(`kv_cache_mode="cached"`)에서 생성 토큰과 캐시된 참조 토큰을 flex `BlockMask`를 통해 함께 어텐션합니다.

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

```python
from diffusers import WanAnimate2Transformer3DModel

transformer = WanAnimate2Transformer3DModel.from_pretrained("Wan-AI/Wan2.2-Animate-2-14B-Diffusers", subfolder="transformer", dtype=torch.bfloat16)
```

## WanAnimate2Transformer3DModel[[diffusers.WanAnimate2Transformer3DModel]]

#### diffusers.WanAnimate2Transformer3DModel[[diffusers.WanAnimate2Transformer3DModel]]

```python
diffusers.WanAnimate2Transformer3DModel(patch_size: tuple = (1, 2, 2), text_len: int = 512, in_dim: int = 36, dim: int = 5120, ffn_dim: int = 13824, freq_dim: int = 256, text_dim: int = 4096, out_dim: int = 16, num_heads: int = 40, num_layers: int = 40, cross_attn_norm: bool = True, eps: float = 1e-06, use_img_emb: bool = True, refer_offset_t: int = 1, refer_offset_h: int = 0, refer_offset_w: int = -1, refer_stride: int = 1)
```

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

**매개변수:**

patch_size (*tuple[int]*, 기본값 *(1, 2, 2)*) : 비디오 임베딩을 위한 3D 패치 차원 (t_patch, h_patch, w_patch).

text_len (*int*, 기본값 *512*) : 텍스트 임베딩의 고정 길이입니다.

in_dim (*int*, 기본값 *36*) : 입력의 채널 수 (마스크 채널을 위한 2 * latent_channels + 4).

dim (*int*, 기본값 *5120*) : transformer의 채널 수입니다.

ffn_dim (*int*, 기본값 *13824*) : 피드포워드 네트워크의 중간 차원.

freq_dim (*int*, 기본값 *256*) : 사인 시간 임베딩의 차원.

text_dim (*int*, 기본값 *4096*) : 텍스트 임베딩의 입력 차원입니다.

out_dim (*int*, 기본값 *16*) : 출력의 채널 수.

num_heads (*int*, 기본값 *40*) : 어텐션 헤드의 수입니다.

num_layers (*int*, 기본값 *40*) : 사용할 transformer 블록의 레이어 수입니다.

cross_attn_norm (*bool*, 기본값 *True*) : cross-attention 정규화를 활성화합니다.

eps (*float*, 기본값 *1e-6*) : 정규화 레이어에 사용되는 Epsilon 값입니다.

use_img_emb (*bool*, 기본값 *True*) : CLIP 이미지 임베딩을 사용할지 여부.

refer_offset_t (*int*, 기본값 *1*) : 참조의 시간 차원에 대한 RoPE offset입니다.

refer_offset_h (*int*, 기본값 *0*) : 참조의 높이 차원에 대한 RoPE offset입니다.

refer_offset_w (*int*, 기본값 *-1*) : 참조의 폭 차원에 대한 RoPE offset입니다. -1은 생성 그리드 크기를 사용함을 의미합니다.

refer_stride (*int*, 기본값 *1*) : 참조에 RoPE를 적용할 때 사용할 스트라이드입니다.

Wan-Animate-2 모델에서 사용되는 비디오 유사 데이터용 Transformer 모델입니다.

Wan-Animate-2는 KV 캐시를 사용하는 인-컨텍스트 어텐션 메커니즘을 사용합니다. 먼저 참조 비디오를 인코딩(`kv_cache_mode="extract"`)하여 [*WanAnimate2KVCache*]를 채운 후, 각 디노이징 단계(`kv_cache_mode="cached"`)에서 생성 토큰과 캐시된 참조 K/V에 대해 flex `BlockMask`를 통해 함께 어텐션을 수행합니다. 따라서 생성 셀프-어텐션은 `flex` 어텐션 백엔드에서만 실행되며, 모델의 나머지 모든 어텐션은 어떤 백엔드에서도 동작합니다.

#### forward[[diffusers.WanAnimate2Transformer3DModel.forward]]

```python
forward(hidden_states: list, timestep: Tensor, encoder_hidden_states: list, condition_latents: list, kv_cache: WanAnimate2KVCache, kv_cache_mode: str, seq_len: int, encoder_hidden_states_image: typing.Optional[torch.Tensor] = None, offset_grid_sizes: typing.Optional[torch.Tensor] = None, reference_grid_sizes: typing.Optional[torch.Tensor] = None, origin_len: int | None = None, origin_area: list[int] | None = None, is_uncondtion: bool = False, return_dict: bool = True)
```

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

**매개변수:**

hidden_states (`list[torch.Tensor]`) : 이 패스의 Latents — `kv_cache_mode="extract"`인 경우 참조 latents, `kv_cache_mode="cached"`인 경우 노이즈 생성 latents.

timestep (`torch.Tensor`) : Denoising timestep. `kv_cache_mode="extract"`에서는 1이라는 고정 timestep을 사용하므로 무시됩니다.

encoder_hidden_states (`list[torch.Tensor]`) : 이 패스에 대한 텍스트 임베딩.

condition_latents (`list[torch.Tensor]`) : 패치 임베딩 전에 `hidden_states`에 연결되는 조건부 잠재 변수.

kv_cache (`WanAnimate2KVCache`) : `kv_cache_mode="extract"`로 작성되고 `"cached"`로 읽힙니다.

kv_cache_mode (`str`) : `"extract"`은 reference pass를 실행하여 `kv_cache`를 채웁니다. `"cached"`는 캐시된 reference tokens에 대해 denoising step을 실행합니다.

seq_len (`int`) : 패치 임베딩 이후 각 샘플이 유지해야 하는 토큰 수.

encoder_hidden_states_image (`torch.Tensor`, *선택 사항*) : `use_img_emb`로 모델이 구성된 경우 사용되는 CLIP 이미지 임베딩입니다.

offset_grid_sizes (`torch.Tensor`, *선택 사항*) : 참조 latents의 patch grid으로, -1로 설정된 `refer_offset_*` 값을 해결하는 데 사용됩니다. `kv_cache_mode="extract"`인 경우 필수이며, `"cached"`인 경우 `reference_grid_sizes`가 동일한 grid를 설명하므로 대신 사용됩니다.

reference_grid_sizes (`torch.Tensor`, *선택 사항*) : 참조 로테리 임베딩에 사용되는 참조 잠재 변수의 패치 그리드입니다. `kv_cache_mode="cached"`인 경우 필수입니다.

origin_len (`int`, *선택 사항*) : 인-컨텍스트 블록 마스크가 구축되는 전체 비디오의 프레임 수입니다. `kv_cache_mode="cached"`인 경우 필수입니다.

origin_area (`list[int]`, *선택 사항*) : 전체 비디오의 공간 크기 `[height, width]`입니다. 인-컨텍스트 블록 마스크는 이 크기를 기반으로 구성됩니다. `kv_cache_mode="cached"`인 경우 필수입니다.

is_uncondtion (`bool`, *선택 사항*) : classifier-free guidance의 unconditional branch인지 여부.

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

**반환값:** [Transformer2DModelOutput](/docs/diffusers/main/ko/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) 또는 `tuple(list[torch.Tensor])`

`return_dict`가 `False`인 경우, 패치화되지 않은 각 입력 잠재 변수당 예측 샘플.

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