# AnyFlowFARTransformer3DModel

[`AnyFlowFARPipeline`](../pipelines/anyflow#diffusers.AnyFlowFARPipeline) tarafından kullanılan nedensel (FAR) 3D Transformer — [AnyFlow](https://huggingface.co/papers/2605.13724)'nun FAR varyantı. Makale, yazarlar ve yayınlanan checkpoint'ler için [`AnyFlowFARPipeline`](../pipelines/anyflow) sayfasına bakın. v0.35.1 Wan2.1 omurgasını üç ekleme ile genişletir:

1. [FAR](https://huggingface.co/papers/2503.19325)'da tanıtılan parça bazlı otoregresif üretimi destekleyen, `torch.nn.attention.flex_attention` üzerinden uygulanan **FAR nedensel blok maskesi**.
2. Bağlam (zaten üretilmiş) kareleri için **sıkıştırılmış kare yama gömme** (`far_patch_embedding`), inşaat sırasında tam çözünürlüklü `patch_embedding`'den üç doğrusal interpolasyon yoluyla başlatılır.
3. **Çift zaman adımı akış haritası gömümü** ([`AnyFlowTransformer3DModel`](anyflow_transformer3d) ile aynı) — her ileri çağrı, hem kaynak zaman adımına ``t`` hem de hedef zaman adımına ``r`` koşullanır.

Varsayılan parça zamanlaması (`chunk_partition`) model yapılandırmasında saklanır; yayımlanan NVIDIA AnyFlow-FAR denetim noktaları, standart 81 kare ayarında `[1, 3, 3, 3, 3, 3, 3, 2]` kullanır. `forward`, çağrı başına `chunk_partition` geçersiz kılma işlevini kabul eder, böylece aynı denetim noktası yeniden eğitim gerektirmeden diğer `num_frames` yapılandırmalarını da işler.

```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))
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L961)

**Parametreler:**

patch_size (*Tuple[int]*, varsayılan *(1, 2, 2)*) : Tam çözünürlüklü parçalar için 3B yama boyutları.

compressed_patch_size (*Tuple[int]*, varsayılan *(1, 4, 4)*) : FAR-sıkıştırılmış (bağlam) parçaları için daha büyük yama boyutları.

full_chunk_limit (*int*, varsayılan *3*) : Daha önceki parçaların sıkıştırılmış FAR bağlamına düşürülmeden önce işlenecek tam çözünürlüklü parça sayısı üst sınırı. Yayınlanan denetim noktaları `3` kullanır.

num_attention_heads (*int*, varsayılan *40*) : Dikkat başlarının sayısı.

attention_head_dim (*int*, varsayılan *128*) : Her baştaki kanal sayısı.

in_channels (*int*, varsayılan *16*) : Girdi latentindeki kanal sayısı.

out_channels (*int*, varsayılan *16*) : Çıktı latentindeki kanal sayısı.

text_dim (*int*, varsayılan *4096*) : Metin gömme (UMT5) için giriş boyutu.

freq_dim (*int*, varsayılan *256*) : Sinüzoidal zaman gömme boyutu.

ffn_dim (*int*, varsayılan *13824*) : İleri beslemeli ağdaki ara boyut.

num_layers (*int*, varsayılan *40*) : Transformer bloklarının sayısı.

cross_attn_norm (*bool*, varsayılan *True*) : Çapraz dikkat normalizasyonunu etkinleştirir.

eps (*float*, varsayılan *1e-6*) : Normalizasyon katmanları için epsilon.

image_dim (*Optional[int]*, *opsiyonel*, varsayılan *None*) : I2V koşullandırma için gömme boyutu.

rope_max_seq_len (*int*, varsayılan *1024*) : Döner konum frekanslarını önceden hesaplamak için kullanılan maksimum dizi uzunluğu.

gate_value (*float*, varsayılan *0.25*) : Kaynak zaman adımı ve delta zaman adımı gömme değerleri arasındaki karıştırma kapısı.

deltatime_type (*str*, varsayılan *'r'*) : `"r"` (delta hedef zaman adımıdır) veya `"t-r"` (delta mutlak aralıktır).

chunk_partition (*Tuple[int, ...]*, varsayılan *(1, 3, 3, 3, 3, 3, 3, 2)*) : Hattın kullandığı varsayılan parça başına kare sayıları. Yayınlanan NVIDIA AnyFlow-FAR kontrol noktaları `num_frames=81` hedefler (VAE zaman adımlı 4 ile 21 latent kare) ve `1 + 3*6 + 2` olarak bölünür. Farklı bir `num_frames` değeri, [AnyFlowFARPipeline.__call__()](/docs/diffusers/main/tr/api/pipelines/anyflow#diffusers.AnyFlowFARPipeline.__call__) (ve benzer şekilde `forward`) fonksiyonuna iletilen eşleşen bir `chunk_partition` geçersiz kılmasını gerektirir.

Causal (FAR) AnyFlow akış haritası örneklemesi için parça bazlı otoregresif üretim ile 3D Transformer.

v0.35.1 Wan2.1 omurgasını şu özelliklerle genişletir:

- `torch.nn.attention.flex_attention` ile **FAR nedensel blok maskesi**, parça bazlı otoregresif üretimi ([FAR](https://huggingface.co/papers/2503.19325)) destekler.
- Bağlam (zaten oluşturulmuş) kareleri için `far_patch_embedding` ile **sıkıştırılmış kare yama gömme**, yeni oluşturulmuş bir modelin LoRA ince ayarı yapılmadan bile makul bir başlangıç noktasında olmasını sağlamak için üç doğrusal interpolasyon yoluyla `patch_embedding`'den başlatılır.
- Herhangi bir adımda örneklemeye yönelik **Çift zaman adımlı akış haritası gömümü** (`AnyFlowTransformer3DModel` ile aynı).

Düz çift yönlü T2V için bunun yerine `AnyFlowTransformer3DModel` kullanın — bu varyant FAR nedensel maskelemeyi ve `far_patch_embedding` bileşenini atlar ve yaklaşık %5–10 daha küçüktür.

#### 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')
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L1232)

**Parametreler:**

chunk_partition : parça başına kare sayıları (latent kare sayısına eşit toplamda olmalıdır).

height, width : latent uzamsal boyutları.

has_clean_context : `clean_hidden_states`, `forward` üzerinden aktarılacaksa (V2V/I2V eğitimi) `True`; maske yerleşimini yalnızca bu varlık bayrağı etkiler.

device : Sonuç olarak oluşturulan `BlockMask` için cihaz. `device_map="auto"` tarafından mask otomatik olarak taşınmaz; maski, dönüştürücünün girdilerinin bulunacağı aynı cihazda oluşturun.

mode : `"train"` (`_forward_train` ile eşleşir) veya `"cache"` (`_forward_cache` ile eşleşir). Otoregresif `_forward_inference` yolu KV önbelleği üzerinden dikkat uygular ve burada bir moda sahip değildir.

**Dönüş:** `~torch.nn.attention.flex_attention.BlockMask`

FAR yerleşimini kapsayan, sıralama boyutu boyunca 128'in katına yastıklanmış nedensel maske (BlockMask blok boyutu gereksinimi).

**Yükselen:** `ValueError`

- `ValueError` -- `mode` ne `"train"` ne de `"cache"` ise.

Nedensel `~torch.nn.attention.flex_attention.BlockMask` nesnesini `forward` dışında önceden oluşturun.

Sonucu, tüm transformer'ın `torch.compile(fullgraph=True)` ile uyumlu hale gelmesi için `forward`'in `attention_mask` kwarg'ı üzerinden iletin. Ön oluşturulmuş bir maske olmadan `forward`, bunu içsel olarak oluşturmak için geri düşer — bu yol `flex_attention.create_block_mask(_compile=False)` kullanır ve derleme grafiğini bozar.

#### 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)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L1098)

**Parametreler:**

hidden_states (*torch.Tensor*) : `(B, F, C, H, W)` biçiminde gizli girdi.

timestep (*torch.Tensor*) : Kaynak (daha gürültülü) akış haritası zaman adımı *t*.

r_timestep (*torch.Tensor*) : Hedef (daha temiz) akış haritası zaman adımı *r*.

encoder_hidden_states (*torch.Tensor*) : UMT5 metin gömüleri.

chunk_partition (*List[int]*) : Parça başına kare sayıları; toplam, `hidden_states` içindeki gizli kare sayısıyla eşleşmelidir.

encoder_hidden_states_image (*torch.Tensor*, *opsiyonel*) : I2V gömülü görseli; sağlandığında metin jetonlarından önce birleştirilir.

clean_hidden_states (*torch.Tensor*, *opsiyonel*) : Eğitim rollout'unda kullanılan temiz (gürültüsüz) koşullandırma kareleri.

clean_timestep (*torch.Tensor*, *opsiyonel*) : Eğitim rollout'undaki temiz koşullandırma kareleri için zaman adımları.

kv_cache (*List[Dict[str, torch.Tensor]]*, *opsiyonel*) : Otoregresif çıkarım için blok başına KV önbelleği. *None* eğitim yolunu seçer.

kv_cache_flag (*Dict[str, Any]*, *isteğe bağlı*) : KV-cache meta verileri (ör. `is_cache_step` bayrağı ve token sayıları).

attention_mask (*BlockMask*, *opsiyonel*) : Genellikle `build_attention_mask` üzerinden oluşturulan, önceden derlenmiş nedensel maske. Eğitim ve KV önbellek ön doldurma yolları tarafından tüketilir; otoregresif çıkarım yolu KV önbelleği üzerinden dikkat uygular ve tam bir maske kullanmaz. `None` olduğunda, eğitim / önbellek yolları maskenin içsel olarak oluşturulmasını sağlar; bu yedek çözüm derleme güvenliği açısından uygun değildir (alttaki `flex_attention.create_block_mask`, `fullgraph=True` altında grafiği bozar), bu nedenle `forward`'ı `torch.compile` ile sarmalarken her zaman önceden derlenmiş bir maske geçirin.

attention_kwargs (*dict*, *opsiyonel*) : Dikkat işleyicilerine (attention processors) iletilir.

return_dict (*bool*, *opsiyonel*, varsayılan *True*) : *False* ise, çıktı veri sınıfı yerine konumsal demetler döndürülür.

**Dönüş:** [*~models.transformer_2d.Transformer2DModelOutput*], [*AnyFlowFARTransformerOutput*] veya *tuple*

*return_dict* *False* olduğunda, düz bir *tuple* döndürülür. Aksi halde, nedensel eğitim rollout'u (*kv_cache is None*) bir [*~models.transformer_2d.Transformer2DModelOutput*] döndürürken, önbellek ön-doldurma ve otoregresif çıkarım yolları bir [*AnyFlowFARTransformerOutput*] döndürür.

FAR nedensel ileri geçişi. Üç iç yoldan birine yönlendirir:

- `kv_cache is None` → nedensel eğitim dağıtımı (`Transformer2DModelOutput` döndürür).
- `kv_cache is not None` ve `kv_cache_flag["is_cache_step"]` → cache-prefill (`sample=None` ile `AnyFlowFARTransformerOutput` döndürür).
- Aksi halde → otoregresif çıkarım adımı (`AnyFlowFARTransformerOutput` döndürür).

## 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)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L55)

**Parametreler:**

sample (*torch.Tensor* veya *None*) : Otoregresif parça için tahmin edilen gürültü azaltma hedefi. Sadece KV önbelleğini yazan ve kullanılabilir bir örnek üretmeyen önbellek ön-doldurma yolu için `None`.

kv_cache (*list[dict[str, torch.Tensor]]*, *opsiyonel*) : Sonraki otoregresif adımlar tarafından kullanılan blok başına KV önbellek durumu.

`AnyFlowFARTransformer3DModel`'in nedensel ileri yolları için çıktı veri sınıfı.