# WanAnimate2Transformer3DModel

Alibaba Wan Team による [Wan-Animate-2](https://github.com/Wan-Video/Wan2.2) で使用される、3D ビデオ類似データ向けの Diffusion Transformer モデルです。インコンテキスト参照メカニズムを通じて、駆動ビデオの動きでキャラクター画像をアニメーション化します。各セグメントはまず参照パス (`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/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*) : クロスアテンションの正規化を有効にします。

eps (*float*、デフォルトは *1e-6*) : 正規化レイヤー用のエプシロン値。

use_img_emb (*bool*、デフォルトは *True*) : CLIP の画像埋め込みを使用するかどうか。

refer_offset_t (*int*、デフォルトは *1*) : 参照の時間次元に対する RoPE オフセット。

refer_offset_h (*int*、デフォルトは *0*) : 参照の高さ次元に対する RoPE オフセット。

refer_offset_w (*int*、デフォルトは *-1*) : 参照の幅次元に対する RoPE オフセットです。-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 に対して、フレキシブルな `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`) : デノイジングのタイムステップ。`kv_cache_mode="extract"` の場合は無視され、固定のタイムステップ 1 が使用されます。

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"` は参照パスを実行して `kv_cache` を設定し、`"cached"` はキャッシュされた参照トークンに対してデノイジングステップを実行します。

seq_len (`int`) : パッチ埋め込み後に各サンプルが保持すべきトークン数。

encoder_hidden_states_image (`torch.Tensor`, *任意*) : モデルが`use_img_emb`で設定されている場合に使用されるCLIPの画像埋め込み。

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`, *任意*) : 完全な動画のフレーム数。インコンテキストブロックマスクはこの範囲で構築されます。`kv_cache_mode="cached"` の場合は必須です。

origin_area (`list[int]`、*任意*) : 完全な動画の空間サイズ `[height, width]`。インコンテキストブロックマスクはこのサイズに基づいて構築されます。`kv_cache_mode="cached"` の場合は必須です。

is_uncondtion (`bool`, *任意*) : classifier-free guidance の無条件ブランチであるかどうかを示します。

return_dict (`bool`、*任意*、デフォルトは`True`) : 通常のタプルではなく`~models.transformer_2d.Transformer2DModelOutput`を返すかどうか。

**戻り値:** [Transformer2DModelOutput](/docs/diffusers/main/ja/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/ja/api/models/transformer2d#diffusers.Transformer2DModel) が離散型の場合 `(batch size, num_vector_embeds - 1, num_latent_pixels)`) : `encoder_hidden_states` 入力を条件とする隠れ状態の出力です。離散型の場合、ノイズ除去されていない潜在ピクセルの確率分布を返します。

[Transformer2DModel](/docs/diffusers/main/ja/api/models/transformer2d#diffusers.Transformer2DModel)の出力です。