# WanAnimate2Transformer3DModel

Một mô hình Diffusion Transformer cho dữ liệu dạng video 3D được sử dụng trong [Wan-Animate-2](https://github.com/Wan-Video/Wan2.2) của nhóm Alibaba Wan. Mô hình này tạo chuyển động cho một hình ảnh nhân vật bằng chuyển động của một video điều khiển thông qua cơ chế tham chiếu trong ngữ cảnh: mỗi đoạn trước tiên chạy một lượt tham chiếu (`kv_cache_mode="extract"`) để lưu trữ bộ nhớ đệm K/V tham chiếu của mọi lớp, sau đó các lượt khử nhiễu (`kv_cache_mode="cached"`) chú ý đồng thời trên các token sinh và các token tham chiếu đã được lưu trong bộ nhớ đệm thông qua một `BlockMask` linh hoạt.

Mô hình có thể được tải bằng đoạn mã sau.

```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)
```

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

**Tham số:**

patch_size (*tuple[int]*, mặc định là *(1, 2, 2)*) : Kích thước patch 3D cho nhúng video (t_patch, h_patch, w_patch).

text_len (*int*, mặc định là *512*) : Độ dài cố định cho các vector nhúng văn bản.

in_dim (*int*, mặc định là *36*) : Số kênh trong đầu vào (2 * latent_channels + 4 cho kênh mask).

dim (*int*, mặc định là *5120*) : Số lượng kênh trong transformer.

ffn_dim (*int*, mặc định là *13824*) : Kích thước chiều trung gian trong mạng feed-forward.

freq_dim (*int*, mặc định là *256*) : Kích thước cho các nhúng thời gian hình sin.

text_dim (*int*, mặc định là *4096*) : Kích thước chiều đầu vào cho nhúng văn bản.

out_dim (*int*, mặc định là *16*) : Số lượng kênh trong đầu ra.

num_heads (*int*, mặc định là *40*) : Số lượng đầu chú ý.

num_layers (*int*, mặc định là *40*) : Số lượng lớp khối transformer cần sử dụng.

cross_attn_norm (*bool*, mặc định là *True*) : Bật chuẩn hóa cross-attention.

eps (*float*, mặc định là *1e-6*) : Giá trị epsilon cho các lớp chuẩn hóa.

use_img_emb (*bool*, mặc định là *True*) : Có sử dụng nhúng hình ảnh CLIP hay không.

refer_offset_t (*int*, mặc định là *1*) : RoPE offset cho chiều thời gian của tham chiếu.

refer_offset_h (*int*, mặc định là *0*) : Độ lệch RoPE cho chiều cao của tham chiếu.

refer_offset_w (*int*, mặc định là *-1*) : Độ dịch RoPE cho chiều rộng của tham chiếu. -1 có nghĩa là sử dụng kích thước lưới sinh.

refer_stride (*int*, mặc định là *1*) : Bước nhảy (stride) cho việc áp dụng RoPE trên tham chiếu.

Một mô hình Transformer cho dữ liệu dạng video được sử dụng trong mô hình Wan-Animate-2.

Wan-Animate-2 sử dụng cơ chế chú ý trong ngữ cảnh (in-context attention) với bộ đệm KV: một video tham chiếu trước tiên được mã hóa (`kv_cache_mode="extract"`) để nạp vào [*WanAnimate2KVCache*], sau đó mỗi bước khử nhiễu (`kv_cache_mode="cached"`) sẽ chú ý đồng thời lên các token sinh ra và K/V tham chiếu đã được đệm thông qua `BlockMask` linh hoạt. Do đó, chú ý tự (self-attention) của quá trình sinh chỉ chạy trên backend chú ý `flex`; mọi chú ý khác trong mô hình đều hoạt động trên bất kỳ backend nào.

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

```python
forward(hidden_states: list[torch.Tensor], timestep: Tensor, encoder_hidden_states: list[torch.Tensor], condition_latents: list[torch.Tensor], 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)
```

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

**Tham số:**

hidden_states (`list[torch.Tensor]`) : Latents cho lượt này — latents tham chiếu khi `kv_cache_mode="extract"`, latents sinh nhiễu khi `kv_cache_mode="cached"`.

timestep (`torch.Tensor`) : Bước thời gian khử nhiễu. Bị bỏ qua khi `kv_cache_mode="extract"`, chế độ này sử dụng bước thời gian cố định là 1.

encoder_hidden_states (`list[torch.Tensor]`) : Nhúng văn bản cho lượt này.

condition_latents (`list[torch.Tensor]`) : Các latents điều kiện được nối vào `hidden_states` trước khi thực hiện patch embedding.

kv_cache (`WanAnimate2KVCache`) : Được ghi dưới `kv_cache_mode="extract"`, được đọc dưới `"cached"`.

kv_cache_mode (`str`) : `"extract"` chạy bước tham chiếu và điền vào `kv_cache`; `"cached"` chạy một bước khử nhiễu đối với các token tham chiếu đã được lưu trong bộ nhớ đệm.

seq_len (`int`) : Số lượng token mà mỗi mẫu phải giữ lại sau patch embedding.

encoder_hidden_states_image (`torch.Tensor`, *tùy chọn*) : các embedding hình ảnh CLIP, được sử dụng khi mô hình được cấu hình với `use_img_emb`.

offset_grid_sizes (`torch.Tensor`, *tùy chọn*) : Lưới patch của các latents tham chiếu, được dùng để giải quyết bất kỳ `refer_offset_*` nào được đặt thành -1. Bắt buộc khi `kv_cache_mode="extract"`; khi `"cached"`, `reference_grid_sizes` mô tả cùng một lưới và được dùng thay thế.

reference_grid_sizes (`torch.Tensor`, *tùy chọn*) : Lưới patch của các latent tham chiếu, được sử dụng cho các rotary embeddings tham chiếu. Bắt buộc khi `kv_cache_mode="cached"`.

origin_len (`int`, *optional*) : Số khung của video đầy đủ, mà mặt nạ khối ngữ cảnh được xây dựng trên đó. Bắt buộc khi `kv_cache_mode="cached"`.

origin_area (`list[int]`, *tuỳ chọn*) : Kích thước không gian `[height, width]` của video đầy đủ, mà mặt nạ khối ngữ cảnh được xây dựng trên đó. Bắt buộc khi `kv_cache_mode="cached"`.

is_uncondtion (`bool`, *tùy chọn*) : Xác định xem đây có phải là nhánh không điều kiện của classifier-free guidance hay không.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một `~models.transformer_2d.Transformer2DModelOutput` thay vì một tuple thông thường hay không.

**Trả về:** [Transformer2DModelOutput](/docs/diffusers/main/vi/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) hoặc `tuple(list[torch.Tensor])`

Mẫu dự đoán cho mỗi latent đầu vào, chưa được unpatchify; một tuple thông thường nếu `return_dict` là `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)
```

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

**Tham số:**

sample (`torch.Tensor` có shape `(batch_size, num_channels, height, width)` hoặc `(batch size, num_vector_embeds - 1, num_latent_pixels)` nếu [Transformer2DModel](/docs/diffusers/main/vi/api/models/transformer2d#diffusers.Transformer2DModel) là discrete) : Đầu ra của hidden states được điều kiện bởi đầu vào `encoder_hidden_states`. Nếu là discrete, trả về các phân phối xác suất cho các latent pixels chưa bị nhiễu.

Đầu ra của [Transformer2DModel](/docs/diffusers/main/vi/api/models/transformer2d#diffusers.Transformer2DModel).