# AnyFlowFARTransformer3DModel

Le Transformer 3D causal (FAR) utilisé par [`AnyFlowFARPipeline`](../pipelines/anyflow#diffusers.AnyFlowFARPipeline) — la variante FAR de [AnyFlow](https://huggingface.co/papers/2605.13724). Consultez la page [`AnyFlowFARPipeline`](../pipelines/anyflow) pour le papier, les auteurs et les points de contrôle publiés. Il étend le socle Wan2.1 v0.35.1 avec trois ajouts :

1. **masque de bloc causal FAR** via `torch.nn.attention.flex_attention`, prenant en charge la génération autorégressive par morceaux telle qu'introduite dans [FAR](https://huggingface.co/papers/2503.19325).
2. **Embedding de patch à trames compressées** (`far_patch_embedding`) pour les trames de contexte (déjà générées), initialisées à partir de l'`patch_embedding` pleine résolution au moment de la construction, par interpolation trilinéaire.
3. **Embedding de carte de flux à double pas de temps** (identique à [`AnyFlowTransformer3DModel`](anyflow_transformer3d)) — chaque appel de propagation conditionne sur le pas de temps source ``t`` et le pas de temps cible ``r``.

L’ordonnancement de blocs par défaut (`chunk_partition`) est stocké dans la configuration du modèle ; les points de contrôle NVIDIA AnyFlow-FAR publiés utilisent `[1, 3, 3, 3, 3, 3, 3, 2]` pour la configuration canonique de 81 images. `forward` accepte une surcharge `chunk_partition` par appel, de sorte que le même point de contrôle gère également d’autres configurations `num_frames` sans réentraînement.

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

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

**Paramètres :**

patch_size (*Tuple[int]*, par défaut *(1, 2, 2)*) : dimensions des patches 3D pour les blocs à résolution complète.

compressed_patch_size (*Tuple[int]*, par défaut *(1, 4, 4)*) : Dimensions de patch plus grandes pour les segments (contexte) compressés FAR.

full_chunk_limit (*int*, par défaut *3*) : Nombre maximal de blocs en résolution complète avant que les blocs antérieurs ne soient rétrogradés en contexte FAR compressé. Les points de contrôle publiés utilisent `3`.

num_attention_heads (*int*, par défaut *40*) : Nombre de têtes d'attention.

attention_head_dim (*int*, par défaut *128*) : Le nombre de canaux dans chaque tête.

in_channels (*int*, par défaut *16*) : Le nombre de canaux dans le latent d'entrée.

out_channels (*int*, par défaut *16*) : Le nombre de canaux dans le latent de sortie.

text_dim (*int*, par défaut *4096*) : Dimension d'entrée pour les embeddings de texte (UMT5).

freq_dim (*int*, par défaut *256*) : Dimension pour les embeddings temporels sinusoïdaux.

ffn_dim (*int*, par défaut *13824*) : Dimension intermédiaire du réseau feed-forward.

num_layers (*int*, par défaut *40*) : Nombre de blocs transformer.

cross_attn_norm (*bool*, par défaut *True*) : Active la normalisation de l'attention croisée.

eps (*float*, par défaut *1e-6*) : Epsilon pour les couches de normalisation.

image_dim (*Optional[int]*, *facultatif*, par défaut *None*) : Dimension de l'intégration d'image pour le conditionnement I2V.

rope_max_seq_len (*int*, par défaut *1024*) : Longueur maximale de séquence utilisée pour précalculer les fréquences de position rotative.

gate_value (*float*, par défaut *0.25*) : Porte de mélange entre les embeddings de pas source et de pas delta.

deltatime_type (*str*, par défaut *'r'*) : Soit `"r"` (delta est l'étape temporelle cible) soit `"t-r"` (delta est l'intervalle absolu).

chunk_partition (*Tuple[int, ...]*, par défaut *(1, 3, 3, 3, 3, 3, 3, 2)*) : Nombre de frames par chunk utilisé par défaut par le pipeline. Les points de contrôle NVIDIA AnyFlow-FAR publiés ciblent `num_frames=81` (21 frames latentes avec un pas temporel VAE de 4), répartis en `1 + 3*6 + 2`. Un `num_frames` différent nécessite une surcharge correspondante de `chunk_partition` passée à [AnyFlowFARPipeline.__call__()](/docs/diffusers/v0.43.0/fr/api/pipelines/anyflow#diffusers.AnyFlowFARPipeline.__call__) (et de même à `forward`).

Causal (FAR) 3D Transformer pour l'échantillonnage de cartes de flux AnyFlow avec génération auto-régressive par blocs.

Étend le socle Wan2.1 v0.35.1 avec :

- **masque de bloc causal FAR** via `torch.nn.attention.flex_attention`, prenant en charge la génération autorégressive par morceaux ([FAR](https://huggingface.co/papers/2503.19325)).
- **Embedding de patch à trames compressées** `far_patch_embedding` pour les trames de contexte (déjà générées), initialisé à partir de `patch_embedding` par interpolation trilinéaire, afin qu'un modèle nouvellement construit se trouve déjà à un point de départ raisonnable, même avant l'ajustement fin LoRA.
- **Embedding de carte de flux à double pas de temps** pour l'échantillonnage à pas arbitraire (identique à `AnyFlowTransformer3DModel`).

Utilisez `AnyFlowTransformer3DModel` à la place pour un T2V bidirectionnel simple — cette variante ignore le masquage causal FAR et `far_patch_embedding` et est environ 5 à 10 % plus petite.

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

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L1237)

**Paramètres :**

chunk_partition : nombre de trames par bloc (la somme doit correspondre au nombre de trames latentes).

height, width : dimensions spatiales latentes.

has_clean_context : `True` lorsque `clean_hidden_states` sera transmis à travers `forward` (entraînement V2V/I2V) ; seule cette présence affecte la disposition du masque.

device : appareil pour le `BlockMask` résultant. Le masque n'est pas déplacé automatiquement par `device_map="auto"` ; construisez-le sur le même appareil que celui sur lequel résideront les entrées du transformeur.

mode : `"train"` (correspond à `_forward_train`) ou `"cache"` (correspond à `_forward_cache`). Le chemin autorégressif `_forward_inference` effectue l'attention à travers le cache KV et n'a pas de mode ici.

**Retourne :** `~torch.nn.attention.flex_attention.BlockMask`

masque causal couvrant la disposition FAR, rembourré jusqu'à un multiple de 128 le long de la dimension de séquence (exigence de taille de bloc de BlockMask).

**Levée :** `ValueError`

- `ValueError` -- si `mode` n'est ni `"train"` ni `"cache"`.

Préconstruisez le `~torch.nn.attention.flex_attention.BlockMask` causal en dehors de `forward`.

Transmettez le résultat via le mot-clé `attention_mask` de `forward` pour rendre l'ensemble du transformateur compatible avec `torch.compile(fullgraph=True)`. En l'absence d'un masque préconstruit, `forward` se rabat sur sa construction interne — ce chemin utilise `flex_attention.create_block_mask(_compile=False)` et brise le graphe de compilation.

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

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

**Paramètres :**

hidden_states (*torch.Tensor*) : Entrée latente de forme `(B, F, C, H, W)`.

timestep (*torch.Tensor*) : Pas de temps *t* de la carte de flux source (plus bruitée).

r_timestep (*torch.Tensor*) : Pas de temps *r* de la carte de flux cible (plus propre).

encoder_hidden_states (*torch.Tensor*) : embeddings de texte UMT5.

chunk_partition (*List[int]*) : Nombre de trames par bloc ; le total doit correspondre au nombre de trames latentes dans `hidden_states`.

encoder_hidden_states_image (*torch.Tensor*, *facultatif*) : embedding d'image I2V ; concaténé avant les jetons de texte s'il est fourni.

clean_hidden_states (*torch.Tensor*, *facultatif*) : Images de conditionnement propres (sans bruit) utilisées par le déroulement de l'entraînement.

clean_timestep (*torch.Tensor*, *facultatif*) : Timesteps des images de conditionnement propres dans le déroulement de l'entraînement.

kv_cache (*List[Dict[str, torch.Tensor]]*, *facultatif*) : Cache KV par bloc pour l'inférence autorégressive. *None* sélectionne le chemin d'entraînement.

kv_cache_flag (*Dict[str, Any]*, *facultatif*) : métadonnées du cache KV (par exemple, l'indicateur `is_cache_step` et les nombres de jetons).

attention_mask (*BlockMask*, *facultatif*) : masque causal préconstruit, généralement créé via `build_attention_mask`. Utilisé par les chemins d’entraînement et de préremplissage du cache KV ; le chemin d’inférence autorégressive effectue l’attention à travers le cache KV et n’utilise pas de masque complet. Lorsque `None`, les chemins d’entraînement / de cache construisent le masque en interne ; ce repli n’est pas sûr pour la compilation (la fonction sous-jacente `flex_attention.create_block_mask` casse le graphe sous `fullgraph=True`), il est donc recommandé de passer un masque préconstruit lorsque `forward` est enveloppé dans `torch.compile`.

attention_kwargs (*dict*, *facultatif*) : Transmis aux processeurs d'attention.

return_dict (*bool*, *facultatif*, par défaut *True*) : Si *False*, renvoie des tuples positionnels au lieu d'une dataclass de sortie.

**Retourne :** [*~models.transformer_2d.Transformer2DModelOutput*], [*AnyFlowFARTransformerOutput*] ou *tuple*

Lorsque *return_dict* est *False*, un simple *tuple* est renvoyé. Sinon, le déroulement d'entraînement causal (*kv_cache is None*) renvoie un [*~models.transformer_2d.Transformer2DModelOutput*], tandis que les chemins de préremplissage du cache et d'inférence autorégressive renvoient un [*AnyFlowFARTransformerOutput*].

Passage avant causal FAR. Aiguille vers l'un des trois chemins internes :

- `kv_cache is None` → déroulement d’entraînement causal (renvoie `Transformer2DModelOutput`).
- `kv_cache is not None` et `kv_cache_flag["is_cache_step"]` → cache-prefill (renvoie `AnyFlowFARTransformerOutput` avec `sample=None`).
- Sinon → étape d'inférence autorégressive (renvoie `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)
```

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

**Paramètres :**

sample (*torch.Tensor* ou *None*) : Cible de débruitage prédite pour le bloc autorégressif. `None` pour le chemin de préremplissage du cache, qui n'écrit que le cache KV et ne produit aucun échantillon utilisable.

kv_cache (*list[dict[str, torch.Tensor]]*, *facultatif*) : État du cache KV par bloc utilisé par les étapes autorégressives suivantes.

Classe de données de sortie des chemins avant causaux de `AnyFlowFARTransformer3DModel`.