# AnyFlowFARTransformer3DModel

Transformer 3D kausal (FAR) yang digunakan oleh [`AnyFlowFARPipeline`](../pipelines/anyflow#diffusers.AnyFlowFARPipeline) — varian FAR dari [AnyFlow](https://huggingface.co/papers/2605.13724). Lihat halaman [`AnyFlowFARPipeline`](../pipelines/anyflow) 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](https://huggingface.co/papers/2503.19325).
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`](anyflow_transformer3d)) — 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.

```python
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]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L961)

**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__()](/docs/diffusers/main/id/api/pipelines/anyflow#diffusers.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](https://huggingface.co/papers/2503.19325)).
- **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]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L1232)

**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]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L1098)

**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]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L55)

**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`.