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

AnyFlowFARTransformer3DModel

O Transformer 3D causal (FAR) usado por AnyFlowFARPipeline — a variante FAR do AnyFlow. Consulte a página do AnyFlowFARPipeline para o paper, os autores e os checkpoints liberados. Ele estende o backbone Wan2.1 da v0.35.1 com três adições:

1. máscara de bloco causal FAR via torch.nn.attention.flex_attention, com suporte à geração autoregressiva por blocos, conforme introduzido em FAR.
2. Embedding de patch de quadro comprimido (far_patch_embedding) para quadros de contexto (já gerados), inicializado a partir do patch_embedding de resolução completa no momento da construção, por meio de interpolação trilinear.
3. Embedding de fluxo-mapa com dois passos de tempo (igual ao AnyFlowTransformer3DModel) — cada chamada de forward é condicionada tanto no passo de tempo de origem t quanto no passo de tempo de destino r.

O cronograma de blocos padrão (chunk_partition) é armazenado na configuração do modelo; os checkpoints NVIDIA AnyFlow-FAR publicados usam [1, 3, 3, 3, 3, 3, 3, 2] para a configuração canônica de 81 quadros. forward aceita uma substituição de chunk_partition por chamada, de modo que o mesmo checkpoint também lida com outras configurações de num_frames sem necessidade de re-treinamento.

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

Fonte

Parâmetros:

patch_size (Tuple[int], padrão (1, 2, 2)) : dimensões do patch 3D para blocos em resolução completa.

compressed_patch_size (Tuple[int], padrão (1, 4, 4)) : Dimensões de patch maiores para os blocos (contexto) comprimidos pelo FAR.

full_chunk_limit (int, padrão 3) : Número máximo de blocos em resolução completa antes que blocos anteriores sejam rebaixados para o contexto FAR comprimido. Os checkpoints liberados usam 3.

num_attention_heads (int, padrão 40) : Número de cabeças de atenção.

attention_head_dim (int, padrão 128) : O número de canais em cada head.

in_channels (int, padrão 16) : O número de canais no latente de entrada.

out_channels (int, padrão 16) : O número de canais no latente de saída.

text_dim (int, padrão 4096) : Dimensão de entrada para embeddings de texto (UMT5).

freq_dim (int, padrão 256) : Dimensão para embeddings de tempo sinusoidais.

ffn_dim (int, padrão 13824) : Dimensão intermediária na rede feed-forward.

num_layers (int, padrão 40) : Número de blocos de transformer.

cross_attn_norm (bool, padrão True) : Ativa a normalização de atenção cruzada.

eps (float, padrão 1e-6) : Epsilon para as camadas de normalização.

image_dim (Optional[int], opcional, padrão None) : Dimensão do embedding de imagem para condicionamento I2V.

rope_max_seq_len (int, padrão 1024) : Comprimento máximo da sequência usado para pré-computar as frequências de posição rotativa.

gate_value (float, padrão 0.25) : Porta de mistura entre os embeddings de timestep de origem e timestep delta.

deltatime_type (str, padrão 'r') : Ou "r" (delta é o passo de tempo alvo) ou "t-r" (delta é o intervalo absoluto).

chunk_partition (Tuple[int, ...], padrão (1, 3, 3, 3, 3, 3, 3, 2)) : Contagem padrão de quadros por bloco usada pelo pipeline. Os checkpoints NVIDIA AnyFlow-FAR liberados visam num_frames=81 (21 quadros latentes com passo temporal do VAE 4) divididos como 1 + 3*6 + 2. Um num_frames diferente requer uma substituição correspondente de chunk_partition passada para AnyFlowFARPipeline.call() (e da mesma forma para forward).

Causal (FAR) 3D Transformer para amostragem de mapas de fluxo do AnyFlow com geração autoregressiva por blocos.

Estende o backbone Wan2.1 v0.35.1 com:

• máscara de bloco causal FAR via torch.nn.attention.flex_attention, com suporte à geração autoregressiva por blocos (FAR).
• Embedding de patches de frames comprimidos far_patch_embedding para frames de contexto (já gerados), inicializado a partir de patch_embedding via interpolação trilinear, de modo que um modelo recém-construído já esteja em um ponto de partida razoável mesmo antes do fine-tuning com LoRA.
• Embedding de fluxo-mapa com dois passos de tempo para amostragem em qualquer passo (igual a AnyFlowTransformer3DModel).

Use AnyFlowTransformer3DModel em vez disso para T2V bidirecional puro — essa variante ignora a máscara causal FAR e far_patch_embedding e é ~5–10% menor.

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

Fonte

Parâmetros:

chunk_partition : contagens de quadros por bloco (devem somar o número de quadros latentes).

height, width : dimensões espaciais latentes.

has_clean_context : True quando clean_hidden_states será passado por forward (treinamento de V2V/I2V); apenas essa flag de presença afeta o layout da máscara.

device : dispositivo para o BlockMask resultante. A máscara não é movida automaticamente por device_map="auto"; construa-a no mesmo dispositivo em que as entradas do transformer ficarão.

mode : "train" (corresponde a _forward_train) ou "cache" (corresponde a _forward_cache). O caminho autoregressivo _forward_inference atende através do cache KV e não possui modo aqui.

Retorna: ~torch.nn.attention.flex_attention.BlockMask

máscara causal abrangendo o layout FAR, preenchida até um múltiplo de 128 ao longo da dimensão da sequência (o requisito de tamanho de bloco do BlockMask).

Exceções: ValueError

• ValueError -- se mode não for nem "train" nem "cache".

Pré-construa a ~torch.nn.attention.flex_attention.BlockMask causal fora do forward.

Passe o resultado via o kwarg attention_mask de forward para tornar o transformer inteiro compatível com torch.compile(fullgraph=True). Sem uma máscara pré-construída, forward recorre à construção interna dela — esse caminho usa flex_attention.create_block_mask(_compile=False) e quebra o grafo de compilação.

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)

Fonte

Parâmetros:

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

timestep (torch.Tensor) : Passo de tempo t do fluxo-mapa de origem (mais ruidoso).

r_timestep (torch.Tensor) : Timestep r do mapa de fluxo (cleaner) alvo.

encoder_hidden_states (torch.Tensor) : embeddings de texto do UMT5.

chunk_partition (List[int]) : Contagens de quadros por bloco; o total deve corresponder ao número de quadros latentes em hidden_states.

encoder_hidden_states_image (torch.Tensor, opcional) : incorporação de imagem I2V; concatenada antes dos tokens de texto quando fornecida.

clean_hidden_states (torch.Tensor, opcional) : Quadros de condicionamento limpos (sem ruído) usados pelo rollout de treinamento.

clean_timestep (torch.Tensor, opcional) : Passos de tempo para os quadros de condicionamento limpos no rollout de treinamento.

kv_cache (List[Dict[str, torch.Tensor]], opcional) : Cache de KV por bloco para inferência autoregressiva. None seleciona o caminho de treinamento.

kv_cache_flag (Dict[str, Any], opcional) : Metadados do KV-cache (por exemplo, a flag is_cache_step e as contagens de tokens).

attention_mask (BlockMask, opcional) : Máscara causal pré-construída, tipicamente criada via build_attention_mask. Consumida pelos caminhos de treinamento e de pré-preenchimento do KV-cache; o caminho de inferência autoregressiva atende através do KV cache e não utiliza uma máscara completa. Quando None, os caminhos de treinamento / cache constroem a máscara internamente; essa alternativa não é segura para compilação (a função subjacente flex_attention.create_block_mask quebra o grafo sob fullgraph=True), portanto, passe uma máscara pré-construída sempre que envolver forward em torch.compile.

attention_kwargs (dict, opcional) : Encaminhado para os processadores de atenção.

return_dict (bool, opcional, padrão True) : Se False, retorna tuplas posicionais em vez de uma dataclass de saída.

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

Quando return_dict é False, uma tuple simples é retornada. Caso contrário, o rollout de treinamento causal (kv_cache is None) retorna um [~models.transformer_2d.Transformer2DModelOutput], enquanto os caminhos de pré-preenchimento de cache e inferência autoregressiva retornam um [AnyFlowFARTransformerOutput].

Passada causal de FAR. Despacha para um dos três caminhos internos:

• kv_cache is None → rollout de treinamento causal (retorna Transformer2DModelOutput).
• kv_cache is not None e kv_cache_flag["is_cache_step"] → cache-prefill (retorna AnyFlowFARTransformerOutput com sample=None).
• Caso contrário → etapa de inferência autoregressiva (retorna 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)

Fonte

Parâmetros:

sample (torch.Tensor ou None) : Alvo de desruido previsto para o chunk autoregressivo. None para o caminho de pré-preenchimento do cache, que apenas grava o cache KV e não produz nenhuma amostra utilizável.

kv_cache (list[dict[str, torch.Tensor]], opcional) : Estado do cache KV por bloco usado pelas etapas autoregressivas subsequentes.

Dataclass de saída para os caminhos de encaminhamento causal do AnyFlowFARTransformer3DModel.