diffusers/main/id/api/models/anyflow_far_transformer3d.md

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 standar. 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[[diffusers.AnyFlowFARTransformer3DModel]]

diffusers.AnyFlowFARTransformer3DModel[[diffusers.AnyFlowFARTransformer3DModel]]

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

Sumber

Parameter:

patch_size (Tuple[int], defaultnya (1, 2, 2)) : dimensi patch 3D untuk chunk resolusi penuh.

compressed_patch_size (Tuple[int], defaultnya (1, 4, 4)) : Dimensi patch yang lebih besar untuk chunk (konteks) yang dikompresi FAR.

full_chunk_limit (int, defaultnya 3) : Jumlah maksimum chunk resolusi penuh sebelum chunk sebelumnya diturunkan ke konteks FAR terkompresi. Checkpoint yang dirilis menggunakan 3.

num_attention_heads (int, defaultnya 40) : Jumlah kepala perhatian.

attention_head_dim (int, defaultnya 128) : Jumlah channel di setiap head.

in_channels (int, defaultnya 16) : Jumlah channel pada latent input.

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 penanaman 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, defaultnya None) : Dimensi embedding gambar untuk kondisioning I2V.

rope_max_seq_len (int, defaultnya 1024) : Panjang maksimum sekuens yang digunakan untuk pramenghitung frekuensi posisi rotasi.

gate_value (float, defaultnya 0.25) : Gerbang pencampuran antara embedding source-timestep dan delta-timestep.

deltatime_type (str, defaultnya 'r') : Sama dengan "r" (delta adalah target timestep) atau "t-r" (delta adalah interval absolut).

chunk_partition (Tuple[int, ...], defaultnya (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 dibagi 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).

Causal (FAR) 3D Transformer untuk sampling flow-map 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 ukurannya lebih kecil sekitar 5–10%.

build_attention_mask[[diffusers.AnyFlowFARTransformer3DModel.build_attention_mask]]

build_attention_mask(chunk_partition: typing.List[int], height: int, width: int, has_clean_context: bool = False, device: typing.Optional[torch.device] = None, mode: str = 'train')

Sumber

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 _forward_inference autoregresif memperhatikan 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).

Mengangkat: 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[[diffusers.AnyFlowFARTransformer3DModel.forward]]

forward(hidden_states: Tensor, timestep: Tensor, r_timestep: Tensor, encoder_hidden_states: Tensor, chunk_partition: typing.List[int], encoder_hidden_states_image: typing.Optional[torch.Tensor] = None, clean_hidden_states: typing.Optional[torch.Tensor] = None, clean_timestep: typing.Optional[torch.Tensor] = None, kv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = None, kv_cache_flag: typing.Optional[typing.Dict[str, typing.Any]] = None, attention_mask: typing.Optional[torch.nn.attention.flex_attention.BlockMask] = None, attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None, return_dict: bool = True)

Sumber

Parameter:

hidden_states (torch.Tensor) : Input laten dengan bentuk (B, F, C, H, W).

timestep (torch.Tensor) : Langkah waktu (timestep) peta aliran sumber (lebih berisik) t.

r_timestep (torch.Tensor) : Langkah waktu (timestep) peta aliran (flow-map) target (bersih) r.

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) : Bingkai 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) : KV cache 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, defaultnya True) : Jika False, mengembalikan tuple posisi 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[[diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput]]

diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput[[diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput]]

diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput(sample: typing.Optional[torch.Tensor] = None, kv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = None)

Sumber

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.