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

AnyFlowFARTransformer3DModel

Le Transformer 3D causal (FAR) utilisé par AnyFlowFARPipeline — la variante FAR de AnyFlow. Consultez la page AnyFlowFARPipeline 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.
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) — 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.

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

Source

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() (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).
• 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]]

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

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

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

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

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

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.