Hugging Face's logo

Diffusers documentation

AnyFlowFARTransformer3DModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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 l’architecture de base 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é à 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

classe diffusers.AnyFlowFARTransformer3DModel

< >

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

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 blocs compressés FAR (contexte).
  • full_chunk_limit (int, par défaut 3) — Nombre maximal de chunks en résolution complète avant que les chunks 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 des embeddings temporels sinusoïdaux.
  • ffn_dim (int, par défaut 13824) — Dimension intermédiaire du réseau de propagation avant.
  • num_layers (int, par défaut 40) — Nombre de blocs de 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 rotatives.
  • gate_value (float, par défaut 0.25) — Porte de mélange entre les embeddings du pas de temps source et du pas de temps delta.
  • deltatime_type (str, par défaut ‘r’) — Soit "r" (delta est l'étape cible) ou "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 checkpoints 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 transmise à AnyFlowFARPipeline.call() (et de même à forward).

Transformateur 3D causal (FAR) pour l'échantillonnage de la carte de flux d'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, de sorte 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

< >

( chunk_partition: typing.List[int]height: intwidth: inthas_clean_context: bool = Falsedevice: typing.Optional[torch.device] = Nonemode: str = 'train' ) → ~torch.nn.attention.flex_attention.BlockMask

Paramètres

  • chunk_partition — nombre de frames par chunk (la somme doit correspondre au nombre de frames latentes).
  • height, width — dimensions spatiales latentes.
  • has_clean_context — True lorsque clean_hidden_states sera transmis à travers forward (entraînement V2V/I2V) ; seul ce drapeau de 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 d’inférence 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).

Lève

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 casse le graphe de compilation.

forward

< >

( hidden_states: Tensortimestep: Tensorr_timestep: Tensorencoder_hidden_states: Tensorchunk_partition: typing.List[int]encoder_hidden_states_image: typing.Optional[torch.Tensor] = Noneclean_hidden_states: typing.Optional[torch.Tensor] = Noneclean_timestep: typing.Optional[torch.Tensor] = Nonekv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = Nonekv_cache_flag: typing.Optional[typing.Dict[str, typing.Any]] = Noneattention_mask: typing.Optional[torch.nn.attention.flex_attention.BlockMask] = Noneattention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = Nonereturn_dict: bool = True ) → [~models.transformer_2d.Transformer2DModelOutput], [AnyFlowFARTransformerOutput] or tuple

Paramètres

  • hidden_states (torch.Tensor) — Entrée latente de forme (B, F, C, H, W).
  • timestep (torch.Tensor) — Timestep 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 frames par chunk ; le total doit correspondre au nombre de frames latentes dans hidden_states.
  • encoder_hidden_states_image (torch.Tensor, facultatif) — Embedding d’image I2V ; concaténé avant les jetons de texte lorsqu’il est fourni.
  • clean_hidden_states (torch.Tensor, optionnel) — Images de conditionnement propres (sans bruit) utilisées par le déroulement de l’entraînement.
  • clean_timestep (torch.Tensor, optionnel) — Pas de temps pour les images de conditionnement propres dans le déroulement de l'entraînement.
  • kv_cache (List[Dict[str, torch.Tensor]], optionnel) — 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 compteurs 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 ; cette solution de repli n’est pas sûre 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

classe diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput

< >

( sample: typing.Optional[torch.Tensor] = Nonekv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = None )

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]], optionnel) — É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.

Update on GitHub

←AllegroTransformer3DModel AnyFlowTransformer3DModel→