Diffusers documentation
WanAnimate2Transformer3DModel
WanAnimate2Transformer3DModel
Alibaba Wan Team による Wan-Animate-2 で使用される、3D ビデオ類似データ向けの Diffusion Transformer モデルです。インコンテキスト参照メカニズムを通じて、駆動ビデオの動きでキャラクター画像をアニメーション化します。各セグメントはまず参照パス (kv_cache_mode="extract") を実行して各レイヤーの参照 K/V をキャッシュし、その後、デノイジングパス (kv_cache_mode="cached") が生成トークンとキャッシュされた参照トークンの両方に、flex BlockMask を通じて同時にアテンションを適用します。
モデルは、以下のコードスニペットで読み込むことができます。
from diffusers import WanAnimate2Transformer3DModel
transformer = WanAnimate2Transformer3DModel.from_pretrained("Wan-AI/Wan2.2-Animate-2-14B-Diffusers", subfolder="transformer", dtype=torch.bfloat16)WanAnimate2Transformer3DModel
class diffusers.WanAnimate2Transformer3DModel
< source >( patch_size: tuple = (1, 2, 2)text_len: int = 512in_dim: int = 36dim: int = 5120ffn_dim: int = 13824freq_dim: int = 256text_dim: int = 4096out_dim: int = 16num_heads: int = 40num_layers: int = 40cross_attn_norm: bool = Trueeps: float = 1e-06use_img_emb: bool = Truerefer_offset_t: int = 1refer_offset_h: int = 0refer_offset_w: int = -1refer_stride: int = 1 )
パラメータ
- 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
< source >( hidden_states: list[torch.Tensor]timestep: Tensorencoder_hidden_states: list[torch.Tensor]condition_latents: list[torch.Tensor]kv_cache: WanAnimate2KVCachekv_cache_mode: strseq_len: intencoder_hidden_states_image: typing.Optional[torch.Tensor] = Noneoffset_grid_sizes: typing.Optional[torch.Tensor] = Nonereference_grid_sizes: typing.Optional[torch.Tensor] = Noneorigin_len: int | None = Noneorigin_area: list[int] | None = Noneis_uncondtion: bool = Falsereturn_dict: bool = True ) → Transformer2DModelOutput or tuple(list[torch.Tensor])
パラメータ
- hidden_states (
list[torch.Tensor]) — このパスの潜変数。kv_cache_mode="extract"の場合は参照潜変数、kv_cache_mode="cached"の場合はノイズ付き生成潜変数です。 - timestep (
torch.Tensor) — Denoising のタイムステップ。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を返すかどうか。プレーンなタプルを返す代わりに、~models.transformer_2d.Transformer2DModelOutputを返します。
戻り値
Transformer2DModelOutput または tuple(list[torch.Tensor])
入力潜在変数ごとの予測サンプル（アンパッチ化済み）。return_dict が False の場合は、プレーンなタプルです。
Transformer2DModelOutput
クラス diffusers.models.modeling_outputs.Transformer2DModelOutput
< source >( sample: torch.Tensor )
パラメータ
- sample (
torch.Tensor、形状(batch_size, num_channels, height, width)、または Transformer2DModel が離散型の場合(batch size, num_vector_embeds - 1, num_latent_pixels)) —encoder_hidden_states入力を条件とする隠れ状態の出力です。離散型の場合、ノイズ除去されていない潜在ピクセルの確率分布を返します。
Transformer2DModelの出力です。