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.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

AnyFlowFARTransformer3DModel

El Transformer 3D causal (FAR) utilizado por AnyFlowFARPipeline — la variante FAR de AnyFlow. Consulte la página de AnyFlowFARPipeline para ver el paper, los autores y los checkpoints publicados. Extiende el backbone de Wan2.1 v0.35.1 con tres adiciones:

  1. Máscara de bloques causal de FAR mediante torch.nn.attention.flex_attention, que admite la generación autoregresiva por fragmentos tal como se introdujo en FAR.
  2. Incrustado de parches de fotogramas comprimidos (far_patch_embedding) para los fotogramas de contexto (ya generados), inicializado en caliente a partir del patch_embedding de resolución completa en el momento de la construcción mediante interpolación trilineal.
  3. Incrustado de flujo-mapa de doble paso temporal (igual que AnyFlowTransformer3DModel) — cada llamada de adelante se condiciona tanto en el paso temporal de origen t como en el paso temporal de destino r.

El programa de bloques predeterminado (chunk_partition) se almacena en la configuración del modelo; los puntos de control de NVIDIA AnyFlow-FAR publicados utilizan [1, 3, 3, 3, 3, 3, 3, 2] para la configuración canónica de 81 fotogramas. forward acepta una sobrescritura de chunk_partition por llamada, por lo que el mismo punto de control también maneja otras configuraciones de num_frames sin necesidad de volver a entrenar.

from diffusers import AnyFlowFARTransformer3DModel

# Causal AnyFlow checkpoint (FAR):
transformer = AnyFlowFARTransformer3DModel.from_pretrained(
    "nvidia/AnyFlow-FAR-Wan2.1-1.3B-Diffusers", subfolder="transformer"
)

AnyFlowFARTransformer3DModel

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

Parámetros

  • patch_size (Tuple[int], por defecto (1, 2, 2)) — Dimensiones del parche 3D para fragmentos a resolución completa.
  • compressed_patch_size (Tuple[int], por defecto (1, 4, 4)) — Dimensiones de parche más grandes para los fragmentos comprimidos FAR (contexto).
  • full_chunk_limit (int, por defecto 3) — Número máximo de fragmentos a resolución completa antes de que los fragmentos anteriores se degraden a contexto FAR comprimido. Los puntos de control publicados utilizan 3.
  • num_attention_heads (int, por defecto 40) — Número de cabezas de atención.
  • attention_head_dim (int, por defecto 128) — El número de canales en cada cabeza.
  • in_channels (int, por defecto 16) — El número de canales en el latente de entrada.
  • out_channels (int, por defecto 16) — El número de canales en el latente de salida.
  • text_dim (int, por defecto 4096) — Dimensión de entrada para los embeddings de texto (UMT5).
  • freq_dim (int, por defecto 256) — Dimensión para las incrustaciones sinusoidales de tiempo.
  • ffn_dim (int, por defecto 13824) — Dimensión intermedia en la red feed-forward.
  • num_layers (int, por defecto 40) — Número de bloques de transformer.
  • cross_attn_norm (bool, por defecto True) — Habilita la normalización de atención cruzada.
  • eps (float, por defecto 1e-6) — Epsilon para las capas de normalización.
  • image_dim (Optional[int], opcional, por defecto None) — Dimensión de la incrustación de imagen para el condicionamiento I2V.
  • rope_max_seq_len (int, por defecto 1024) — Longitud máxima de secuencia utilizada para precalcular las frecuencias de posición rotativa.
  • gate_value (float, por defecto 0.25) — Puerta de mezcla entre las incrustaciones del paso de tiempo de origen y las del paso de tiempo delta.
  • deltatime_type (str, por defecto ‘r’) — O bien "r" (delta es el paso de tiempo objetivo) o "t-r" (delta es el intervalo absoluto).
  • chunk_partition (Tuple[int, …], por defecto (1, 3, 3, 3, 3, 3, 3, 2)) — Números de fotogramas por bloque utilizados por defecto en el pipeline. Los puntos de control NVIDIA AnyFlow-FAR publicados apuntan a num_frames=81 (21 fotogramas latentes con un paso temporal de VAE de 4) divididos como 1 + 3*6 + 2. Un num_frames diferente requiere una coincidencia de chunk_partition pasada a AnyFlowFARPipeline.call() (y de igual manera a forward).

Transformador 3D causal (FAR) para el muestreo de mapas de flujo de AnyFlow con generación autoregresiva por bloques.

Extiende el backbone de Wan2.1 v0.35.1 con:

  • Máscara de bloque causal FAR mediante torch.nn.attention.flex_attention, con soporte para generación autoregresiva por bloques (FAR).
  • Incrustado de parches de fotogramas comprimidos far_patch_embedding para los fotogramas de contexto (ya generados), inicializado a partir de patch_embedding mediante interpolación trilineal, de modo que un modelo recién construido ya parte de un punto de partida razonable incluso antes del ajuste fino con LoRA.
  • Incrustado de flujo-mapa de doble paso de tiempo para muestreo de cualquier paso (igual que AnyFlowTransformer3DModel).

Usa AnyFlowTransformer3DModel en su lugar para T2V bidireccional simple: esa variante omite el enmascaramiento causal de FAR y far_patch_embedding, y es un 5–10 % más pequeña.

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

Parámetros

  • chunk_partition — número de fotogramas por chunk (debe sumar el número total de fotogramas latentes).
  • height, width — dimensiones espaciales latentes.
  • has_clean_context — True cuando clean_hidden_states se pasará a través de forward (entrenamiento V2V/I2V); solo esta bandera de presencia afecta al diseño de la máscara.
  • device — dispositivo para el BlockMask resultante. La máscara no se mueve automáticamente con device_map="auto"; créala en el mismo dispositivo donde estarán las entradas del transformer.
  • mode — "train" (corresponde a _forward_train) o "cache" (corresponde a _forward_cache). La ruta de inferencia autoregresiva _forward_inference atiende a través de la caché KV y no tiene modo aquí.

Devuelve

~torch.nn.attention.flex_attention.BlockMask

máscara causal que abarca el diseño FAR, rellena hasta un múltiplo de 128 a lo largo de la dimensión de secuencia (el requisito de tamaño de bloque de BlockMask).

Lanza

ValueError

  • ValueError — si mode no es ni "train" ni "cache".

Construya previamente la ~torch.nn.attention.flex_attention.BlockMask causal fuera de forward.

Pase el resultado a través del argumento attention_mask de forward para hacer que todo el transformador sea compatible con torch.compile(fullgraph=True). Sin una máscara preestablecida, forward recurre a construirla internamente; esa ruta utiliza flex_attention.create_block_mask(_compile=False) y rompe el grafo de compilación.

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

Parámetros

  • hidden_states (torch.Tensor) — Entrada latente de forma (B, F, C, H, W).
  • timestep (torch.Tensor) — Paso de tiempo t del mapa de flujo de origen (más ruidoso).
  • r_timestep (torch.Tensor) — Paso de tiempo r del mapa de flujo objetivo (más limpio).
  • encoder_hidden_states (torch.Tensor) — Incrustaciones de texto de UMT5.
  • chunk_partition (List[int]) — Número de fotogramas por bloque; el total debe coincidir con el número de fotogramas latentes en hidden_states.
  • encoder_hidden_states_image (torch.Tensor, opcional) — Incrustado de imagen I2V; se concatena antes de los tokens de texto cuando se proporciona.
  • clean_hidden_states (torch.Tensor, opcional) — Fotogramas de condicionamiento limpios (sin ruido) utilizados por el despliegue de entrenamiento.
  • clean_timestep (torch.Tensor, opcional) — Pasos de tiempo para los fotogramas de condicionamiento limpios en el despliegue de entrenamiento.
  • kv_cache (List[Dict[str, torch.Tensor]], opcional) — Caché KV por bloque para inferencia autoregresiva. None selecciona la ruta de entrenamiento.
  • kv_cache_flag (Dict[str, Any], opcional) — Metadatos de la caché KV (p. ej., la bandera is_cache_step y los recuentos de tokens).
  • attention_mask (BlockMask, opcional) — Máscara causal predefinida, generalmente construida mediante build_attention_mask. La consumen las rutas de entrenamiento y de prellenado de la caché KV; la ruta de inferencia autoregresiva atiende a través de la caché KV y no utiliza una máscara completa. Cuando None, las rutas de entrenamiento / caché construyen la máscara internamente; esa alternativa no es segura para la compilación (la función subyacente flex_attention.create_block_mask rompe el grafo bajo fullgraph=True), por lo que pase una máscara predefinida siempre que envuelva forward en torch.compile.
  • attention_kwargs (dict, opcional) — Se reenvía a los procesadores de atención.
  • return_dict (bool, opcional, valor predeterminado True) — Si es False, devuelve tuplas posicionales en lugar de una dataclass de salida.

Devuelve

[~models.transformer_2d.Transformer2DModelOutput], [AnyFlowFARTransformerOutput] o tuple

Cuando return_dict es False, se devuelve una tuple simple. En caso contrario, el despliegue de entrenamiento causal (kv_cache is None) devuelve un [~models.transformer_2d.Transformer2DModelOutput], mientras que las rutas de prellenado de caché e inferencia autoregresiva devuelven un [AnyFlowFARTransformerOutput].

Paso de propagación hacia adelante causal de FAR. Se despacha a una de tres rutas internas:

  • kv_cache is None → despliegue de entrenamiento causal (devuelve Transformer2DModelOutput).
  • kv_cache is not None y kv_cache_flag["is_cache_step"] → cache-prefill (devuelve AnyFlowFARTransformerOutput con sample=None).
  • En caso contrario → paso de inferencia autoregresivo (devuelve AnyFlowFARTransformerOutput).

AnyFlowFARTransformerOutput

clase diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput

< >

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

Parámetros

  • sample (torch.Tensor o None) — Objetivo de desruido predicho para el fragmento autoregresivo. None para la ruta de prellenado de caché, que solo escribe la caché KV y no produce ninguna muestra utilizable.
  • kv_cache (list[dict[str, torch.Tensor]], opcional) — Estado de la caché KV por bloque utilizado por los pasos autoregresivos posteriores.

Dataclass de salida para las rutas de propagación causal de AnyFlowFARTransformer3DModel.

Update on GitHub

←AllegroTransformer3DModel AnyFlowTransformer3DModel→