# WanAnimate2Transformer3DModel

Модель Diffusion Transformer для 3D-видеоподобных данных, используемая в [Wan-Animate-2](https://github.com/Wan-Video/Wan2.2) от команды Alibaba Wan. Она анимирует изображение персонажа с помощью движения из управляющего видео посредством механизма контекстной ссылки: каждый сегмент сначала выполняет проход ссылки (`kv_cache_mode="extract"`), кэшируя справочные K/V для каждого слоя, после чего проходы денойзинга (`kv_cache_mode="cached"`) совместно обращаются к токенам генерации и кэшированным справочным токенам через гибкую `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/v0.43.0/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*) : Количество каналов в трансформере.

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-6*) : Значение эпсилона для слоёв нормализации.

use_img_emb (*bool*, по умолчанию *True*) : Использовать ли CLIP image embedding.

refer_offset_t (*int*, по умолчанию *1*) : смещение RoPE для временного измерения эталонного сигнала.

refer_offset_h (*int*, по умолчанию *0*) : смещение RoPE для измерения высоты эталонного изображения.

refer_offset_w (*int*, по умолчанию *-1*) : смещение RoPE для ширины эталонного изображения. Значение -1 означает использование размера сетки генерации.

refer_stride (*int*, по умолчанию *1*) : Шаг применения RoPE к эталонному представлению.

Модель Transformer для видео-подобных данных, используемая в модели Wan-Animate-2.

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_wan_animate_2.py#L766)

**Параметры:**

hidden_states (`list[torch.Tensor]`) : Латенты для этого прохода — эталонные латенты, если `kv_cache_mode="extract"`, латенты шумной генерации, если `kv_cache_mode="cached"`.

timestep (`torch.Tensor`) : Шаг денойзинга. Игнорируется при `kv_cache_mode="extract"`, который использует фиксированный шаг 1.

encoder_hidden_states (`list[torch.Tensor]`) : Текстовые эмбеддинги для этого прохода.

condition_latents (`list[torch.Tensor]`) : Условные латенты, конкатенированные с `hidden_states` перед patch-эмбеддингом.

kv_cache (`WanAnimate2KVCache`) : записывается при `kv_cache_mode="extract"`, читается при `"cached"`.

kv_cache_mode (`str`) : `"extract"` выполняет проход по эталонным данным и заполняет `kv_cache`; `"cached"` выполняет шаг денойзинга по кэшированным эталонным токенам.

seq_len (`int`) : Количество токенов, которое каждый образец должен содержать после встраивания патчей.

encoder_hidden_states_image (`torch.Tensor`, *необязательный*) : эмбеддинги изображений CLIP, используются, когда модель настроена с `use_img_emb`.

offset_grid_sizes (`torch.Tensor`, *необязательный*) : Сетка патчей для опорных латентов, используется для разрешения значений `refer_offset_*`, равных -1. Обязателен при `kv_cache_mode="extract"`; при `"cached"` вместо него используется `reference_grid_sizes`, описывающий ту же сетку.

reference_grid_sizes (`torch.Tensor`, *необязательный*) : Сетка патчей для опорных латентов, используемая для опорных вращательных эмбеддингов. Обязателен при `kv_cache_mode="cached"`.

origin_len (`int`, *optional*) : Количество кадров полного видео, на основе которого строится маска блока в контексте. Обязательно при `kv_cache_mode="cached"`.

origin_area (`list[int]`, *optional*) : Пространственный размер `[height, width]` полного видео, на котором строится маска блока в контексте. Обязательно при `kv_cache_mode="cached"`.

is_uncondtion (`bool`, *необязательный*) : Указывает, является ли это безусловной ветвью классификатора без направляющих (classifier-free guidance).

return_dict (`bool`, *необязательный*, по умолчанию `True`) : Возвращать ли `~models.transformer_2d.Transformer2DModelOutput` вместо обычного кортежа.

**Возвращает:** [Transformer2DModelOutput](/docs/diffusers/v0.43.0/ru/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/v0.43.0/src/diffusers/models/modeling_outputs.py#L21)

**Параметры:**

sample (`torch.Tensor` формы `(batch_size, num_channels, height, width)` или `(batch size, num_vector_embeds - 1, num_latent_pixels)`, если [Transformer2DModel](/docs/diffusers/v0.43.0/ru/api/models/transformer2d#diffusers.Transformer2DModel) дискретный): выходные скрытые состояния, обусловленные входом `encoder_hidden_states`. Если модель дискретная, возвращает распределения вероятностей для ненашумленных латентных пикселей.

Вывод [Transformer2DModel](/docs/diffusers/v0.43.0/ru/api/models/transformer2d#diffusers.Transformer2DModel).