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

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

Fuente

Parámetros:

patch_size (Tuple[int], por defecto (1, 2, 2)) : dimensiones de parche 3D para fragmentos de resolución completa.

compressed_patch_size (Tuple[int], por defecto (1, 4, 4)) : Dimensiones de parche más grandes para los fragmentos (contexto) comprimidos con FAR.

full_chunk_limit (int, por defecto 3) : Número máximo de fragmentos de resolución completa antes de que los fragmentos anteriores se degraden a contexto FAR comprimido. Los puntos de control publicados usan 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 las incrustaciones 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 la atención cruzada.

eps (float, por defecto 1e-6) : Epsilon para las capas de normalización.

image_dim (Optional[int], opcional, valor predeterminado None) : Dimensión del incrustado de imagen para el condicionamiento de 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 de paso de origen y paso delta.

deltatime_type (str, por defecto 'r') : Ya sea "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úmero de fotogramas por bloque utilizado 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 sobrecarga coincidente de chunk_partition pasada a AnyFlowFARPipeline.call() (y de forma similar a forward).

Causal (FAR) 3D Transformer 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).
• Embedding 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[[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')

Fuente

Parámetros:

chunk_partition : número de fotogramas por bloque (deben sumar el número de fotogramas latentes).

height, width : dimensiones espaciales latentes.

has_clean_context : True cuando clean_hidden_states se transmitirá 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 transformador.

mode : "train" (coincide con _forward_train) o "cache" (coincide con _forward_cache). La ruta 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).

Excepciones: 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[[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)

Fuente

Parámetros:

hidden_states (torch.Tensor) : Entrada latente de forma (B, F, C, H, W).

timestep (torch.Tensor) : Paso temporal t del mapa de flujo de origen (más ruidoso).

r_timestep (torch.Tensor) : Paso temporal r del mapa de flujo objetivo (más limpio).

encoder_hidden_states (torch.Tensor) : Embeddings 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) : incrustación de imagen I2V; se concatena antes de los tokens de texto cuando se proporciona.

clean_hidden_states (torch.Tensor, opcional) : Marcos 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. Se utiliza en 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 es 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 se debe pasar una máscara predefinida siempre que se 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[[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)

Fuente

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.

Clase de datos de salida para las rutas de propagación causal de AnyFlowFARTransformer3DModel.