Hugging Face's logo

Diffusers documentation

AnyFlowFARTransformer3DModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

AnyFlowFARTransformer3DModel

Transformer 3D kausal (FAR) yang digunakan oleh AnyFlowFARPipeline — varian FAR dari AnyFlow. Lihat halaman AnyFlowFARPipeline untuk paper, penulis, dan checkpoint yang dirilis. Ini memperluas backbone Wan2.1 v0.35.1 dengan tiga tambahan:

  1. Mask blok kausal FAR melalui torch.nn.attention.flex_attention, mendukung generasi autoregresif per chunk seperti yang diperkenalkan dalam FAR.
  2. Embedding patch bingkai terkompresi (far_patch_embedding) untuk bingkai konteks (bingkai yang sudah dihasilkan), diinisialisasi dari patch_embedding resolusi penuh pada saat konstruksi melalui interpolasi trilinear.
  3. Embedding peta aliran dua langkah waktu (sama seperti AnyFlowTransformer3DModel) — setiap panggilan forward dikondisikan pada kedua langkah waktu sumber t dan langkah waktu target r.

Jadwal chunk default (chunk_partition) disimpan dalam konfigurasi model; checkpoint NVIDIA AnyFlow-FAR yang dirilis menggunakan [1, 3, 3, 3, 3, 3, 3, 2] untuk pengaturan 81-frame kanonik. forward menerima override chunk_partition per pemanggilan, sehingga checkpoint yang sama juga dapat menangani konfigurasi num_frames lainnya tanpa pelatihan ulang.

from diffusers import AnyFlowFARTransformer3DModel

# Causal AnyFlow checkpoint (FAR):
transformer = AnyFlowFARTransformer3DModel.from_pretrained(
    "nvidia/AnyFlow-FAR-Wan2.1-1.3B-Diffusers", subfolder="transformer"
)

AnyFlowFARTransformer3DModel

kelas diffusers.AnyFlowFARTransformer3DModel

< >

( patch_size: typing.Tuple[int] = (1, 2, 2)compressed_patch_size: typing.Tuple[int] = (1, 4, 4)full_chunk_limit: int = 3num_attention_heads: int = 40attention_head_dim: int = 128in_channels: int = 16out_channels: int = 16text_dim: int = 4096freq_dim: int = 256ffn_dim: int = 13824num_layers: int = 40cross_attn_norm: bool = Trueeps: float = 1e-06image_dim: typing.Optional[int] = Nonerope_max_seq_len: int = 1024gate_value: float = 0.25deltatime_type: str = 'r'chunk_partition: typing.Tuple[int, ...] = (1, 3, 3, 3, 3, 3, 3, 2) )

Parameter

  • patch_size (Tuple[int], defaultnya (1, 2, 2)) — Dimensi patch 3D untuk potongan resolusi penuh.
  • compressed_patch_size (Tuple[int], defaultnya (1, 4, 4)) — Dimensi patch yang lebih besar untuk chunk FAR-compressed (konteks).
  • full_chunk_limit (int, defaultnya 3) — Jumlah maksimum chunk resolusi penuh sebelum chunk sebelumnya diturunkan menjadi konteks FAR terkompresi. Checkpoint yang dirilis menggunakan 3.
  • num_attention_heads (int, defaultnya 40) — Jumlah kepala perhatian (attention heads).
  • attention_head_dim (int, defaultnya 128) — Jumlah channel di setiap head.
  • in_channels (int, defaultnya 16) — Jumlah channel pada input latent.
  • out_channels (int, defaultnya 16) — Jumlah channel pada latent output.
  • text_dim (int, defaultnya 4096) — Dimensi input untuk embedding teks (UMT5).
  • freq_dim (int, defaultnya 256) — Dimensi untuk embedding waktu sinusoidal.
  • ffn_dim (int, defaultnya 13824) — Dimensi perantara dalam jaringan feed-forward.
  • num_layers (int, defaultnya 40) — Jumlah blok transformer.
  • cross_attn_norm (bool, defaultnya True) — Aktifkan normalisasi cross-attention.
  • eps (float, defaultnya 1e-6) — Epsilon untuk lapisan normalisasi.
  • image_dim (Optional[int], opsional, default None) — Dimensi embedding gambar untuk kondisioning I2V.
  • rope_max_seq_len (int, defaultnya 1024) — Panjang maksimum urutan yang digunakan untuk prahitung frekuensi posisi rotasi.
  • gate_value (float, defaultnya 0.25) — Gerbang pencampuran antara embedding timestep sumber dan embedding timestep delta.
  • deltatime_type (str, defaultnya ‘r’) — Bisa "r" (delta adalah timestep target) atau "t-r" (delta adalah interval absolut).
  • chunk_partition (Tuple[int, …], default (1, 3, 3, 3, 3, 3, 3, 2)) — Jumlah frame per chunk default yang digunakan oleh pipeline. Checkpoint NVIDIA AnyFlow-FAR yang dirilis menargetkan num_frames=81 (21 frame laten pada VAE temporal stride 4) yang dipecah menjadi 1 + 3*6 + 2. Nilai num_frames yang berbeda memerlukan override chunk_partition yang sesuai dan diteruskan ke AnyFlowFARPipeline.call() (dan juga ke forward).

Transformer 3D Kausal (FAR) untuk pengambilan sampel peta aliran AnyFlow dengan generasi autoregresif per chunk.

Memperluas tulang punggung Wan2.1 v0.35.1 dengan:

  • Mask blok kausal FAR melalui torch.nn.attention.flex_attention, mendukung generasi autoregresif per chunk (FAR).
  • Embedding patch bingkai terkompresi far_patch_embedding untuk bingkai konteks (yang sudah dihasilkan), diinisialisasi dari patch_embedding melalui interpolasi trilinear sehingga model yang baru dibangun sudah berada pada titik awal yang wajar bahkan sebelum fine-tuning LoRA.
  • Embedding peta aliran dua-langkah waktu untuk pengambilan sampel langkah apa pun (sama seperti AnyFlowTransformer3DModel).

Gunakan AnyFlowTransformer3DModel untuk T2V bidireksional biasa — varian tersebut melewati masking kausal FAR dan far_patch_embedding serta berukuran ~5–10% lebih kecil.

build_attention_mask

< >

( chunk_partition: typing.List[int]height: intwidth: inthas_clean_context: bool = Falsedevice: typing.Optional[torch.device] = Nonemode: str = 'train' ) → ~torch.nn.attention.flex_attention.BlockMask

Parameter

  • chunk_partition — jumlah frame per chunk (harus berjumlah sama dengan jumlah frame laten).
  • height, width — dimensi spasial laten.
  • has_clean_context — True ketika clean_hidden_states akan diteruskan melalui forward (pelatihan V2V/I2V); hanya keberadaan flag ini yang memengaruhi tata letak mask.
  • device — perangkat untuk BlockMask yang dihasilkan. Mask tidak dipindahkan secara otomatis oleh device_map="auto"; bangun di perangkat yang sama tempat input transformer akan berada.
  • mode — "train" (cocok dengan _forward_train) atau "cache" (cocok dengan _forward_cache). Jalur autoregressive _forward_inference melakukan perhatian melalui KV cache dan tidak memiliki mode di sini.

Mengembalikan

~torch.nn.attention.flex_attention.BlockMask

causal mask yang mencakup layout FAR, dipadatkan menjadi kelipatan 128 di sepanjang dimensi sekuens (persyaratan ukuran blok BlockMask).

Membuang

ValueError

  • ValueError — jika mode bukan "train" maupun "cache".

Bangun prapembuatan ~torch.nn.attention.flex_attention.BlockMask kausal di luar forward.

Lewatkan hasil melalui kwarg attention_mask dari forward agar seluruh transformer kompatibel dengan torch.compile(fullgraph=True). Tanpa mask yang sudah dibangun sebelumnya, forward akan kembali ke konstruksi internal — jalur tersebut menggunakan flex_attention.create_block_mask(_compile=False) dan merusak grafik kompilasi.

forward

< >

( hidden_states: Tensortimestep: Tensorr_timestep: Tensorencoder_hidden_states: Tensorchunk_partition: typing.List[int]encoder_hidden_states_image: typing.Optional[torch.Tensor] = Noneclean_hidden_states: typing.Optional[torch.Tensor] = Noneclean_timestep: typing.Optional[torch.Tensor] = Nonekv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = Nonekv_cache_flag: typing.Optional[typing.Dict[str, typing.Any]] = Noneattention_mask: typing.Optional[torch.nn.attention.flex_attention.BlockMask] = Noneattention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = Nonereturn_dict: bool = True ) → [~models.transformer_2d.Transformer2DModelOutput], [AnyFlowFARTransformerOutput] or tuple

Parameter

  • hidden_states (torch.Tensor) — Input laten dengan bentuk (B, F, C, H, W).
  • timestep (torch.Tensor) — Timestep t peta aliran sumber (lebih berisau).
  • r_timestep (torch.Tensor) — Timestep r flow-map target (bersih).
  • encoder_hidden_states (torch.Tensor) — Embedding teks UMT5.
  • chunk_partition (List[int]) — Jumlah frame per chunk; totalnya harus sesuai dengan jumlah frame laten di hidden_states.
  • encoder_hidden_states_image (torch.Tensor, opsional) — Embedding gambar I2V; digabungkan sebelum token teks jika disediakan.
  • clean_hidden_states (torch.Tensor, opsional) — Frame kondisioning bersih (tanpa noise) yang digunakan oleh rollout pelatihan.
  • clean_timestep (torch.Tensor, opsional) — Timesteps untuk frame conditioning bersih dalam rollout pelatihan.
  • kv_cache (List[Dict[str, torch.Tensor]], opsional) — Cache KV per blok untuk inferensi autoregresif. None memilih jalur pelatihan.
  • kv_cache_flag (Dict[str, Any], opsional) — Metadata KV-cache (mis. flag is_cache_step dan jumlah token).
  • attention_mask (BlockMask, opsional) — Mask kausal yang sudah dibangun, biasanya dibuat melalui build_attention_mask. Diproses oleh jalur pelatihan dan prefill KV-cache; jalur inferensi autoregresif melakukan perhatian melalui KV cache dan tidak menggunakan mask penuh. Ketika None, jalur pelatihan / cache membangun mask secara internal; fallback tersebut tidak aman untuk kompilasi (fungsi dasar flex_attention.create_block_mask merusak graf di bawah fullgraph=True), jadi berikan mask yang sudah dibangun setiap kali membungkus forward dengan torch.compile.
  • attention_kwargs (dict, opsional) — Diteruskan ke prosesor perhatian.
  • return_dict (bool, opsional, default True) — Jika False, mengembalikan tuple posisional alih-alih dataclass output.

Mengembalikan

[~models.transformer_2d.Transformer2DModelOutput], [AnyFlowFARTransformerOutput] atau tuple

Ketika return_dict bernilai False, sebuah tuple polos dikembalikan. Sebaliknya, rollout pelatihan kausal (kv_cache is None) mengembalikan [~models.transformer_2d.Transformer2DModelOutput], sedangkan jalur prefill cache dan inferensi autoregresif mengembalikan [AnyFlowFARTransformerOutput].

Lewatan maju kausal FAR. Mendelegasikan ke salah satu dari tiga jalur internal:

  • kv_cache is None → rollout pelatihan kausal (mengembalikan Transformer2DModelOutput).
  • kv_cache is not None dan kv_cache_flag["is_cache_step"] → cache-prefill (mengembalikan AnyFlowFARTransformerOutput dengan sample=None).
  • Jika tidak → langkah inferensi autoregresif (mengembalikan AnyFlowFARTransformerOutput).

AnyFlowFARTransformerOutput

kelas diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput

< >

( sample: typing.Optional[torch.Tensor] = Nonekv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = None )

Parameter

  • sample (torch.Tensor atau None) — Target denoising yang diprediksi untuk chunk autoregressive. None untuk jalur cache-prefill, yang hanya menulis ke KV cache dan tidak menghasilkan sampel yang dapat digunakan.
  • kv_cache (list[dict[str, torch.Tensor]], opsional) — Status cache KV per blok yang digunakan oleh langkah autoregresif berikutnya.

Dataclass output untuk jalur forward kausal dari AnyFlowFARTransformer3DModel.

Update on GitHub

←AllegroTransformer3DModel AnyFlowTransformer3DModel→