Hugging Face's logo

Diffusers documentation

MiniMaxH3Transformer3DModel

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

MiniMaxH3Transformer3DModel

Um modelo Diffusion Transformer para geração conjunta de vídeo e áudio, introduzido em MiniMax-H3 pela MiniMax.

MiniMax-H3 executa uma única pilha de blocos sobre uma sequência 1-D empacotada que contém, de uma só vez, o condicionamento de texto, as linhas da imagem de condicionamento e do vídeo, as linhas de áudio e as linhas do vídeo de destino. A atenção é autoatenção completa sobre essa sequência, portanto não há atenção cruzada nem pesos de bloco por modalidade. O comportamento específico de cada modalidade vem apenas das duas projeções de patch de entrada, da tag de modalidade por linha que seleciona os parâmetros de modulação AdaLN e das duas cabeças de saída.

A construção do layout empacotado é responsabilidade do chamador, motivo pelo qual a assinatura do forward recebe o layout separado dos latentes: a grade de posições (t, h, w), as tags de modalidade por linha, os índices de timestep por linha e os três tensores de índice que endereçam as linhas de vídeo, áudio e texto. MiniMaxH3Blocks e MiniMaxH3Ref2VABlocks constroem tudo isso.

Um layout que carrega linhas de padding (tag -1) precisa de um backend de atenção mascarada, pois essas linhas são mantidas em seu próprio documento de atenção por uma máscara booleana; uma sequência sem padding não precisa de máscara e mantém todos os backends disponíveis.

Um repositório contém as partições de checkpoint liberadas, portanto, a subpasta é o que seleciona a tarefa: transformer/ para as tarefas de texto e keyframe, transformer_ref/ para a tarefa omni-reference.

import torch
from diffusers import MiniMaxH3Transformer3DModel

transformer = MiniMaxH3Transformer3DModel.from_pretrained(
    "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"

O checkpoint é de precisão mista: as duas projeções de entrada de patch, o MLP de timestep e as duas saídas são float32, enquanto a pilha de blocos é bfloat16. from_pretrained mantém esse layout por meio de _keep_in_fp32_modules, então passe dtype=torch.bfloat16 e deixe que ele posicione os módulos float32, em vez de converter o modelo com .to(torch.bfloat16) depois.

MiniMaxH3Transformer3DModel

classe diffusers.MiniMaxH3Transformer3DModel

< >

( num_attention_heads: int = 56attention_head_dim: int = 128hidden_size: int = 5376num_layers: int = 50num_refiner_layers: int = 2ffn_dim: int = 14336in_channels: int = 24audio_in_channels: int = 32patch_size: tuple = (1, 2, 2)text_dim: int = 5120freq_dim: int = 256time_embed_hidden_dim: int = 5376time_embed_dim: int = 2688rope_freq_dim: int = 16rope_theta: float = 10000.0norm_eps: float = 1e-05qk_norm_eps: float = 1e-05final_norm_eps: float = 1e-05 )

Parâmetros

  • num_attention_heads (int, padrão 56) — O número de cabeças a serem usadas para a atenção multi-cabeça.
  • attention_head_dim (int, padrão 128) — O número de canais em cada cabeça de atenção. Observe que num_attention_heads * attention_head_dim é maior que hidden_size no MiniMax-H3.
  • hidden_size (int, padrão 5376) — O número de canais da sequência empacotada (o fluxo residual).
  • num_layers (int, padrão 50) — O número de blocos de transformer.
  • num_refiner_layers (int, padrão 2) — O número de blocos de refinamento de tokens aplicados ao fluxo de texto projetado.
  • ffn_dim (int, padrão 14336) — A dimensão interna das camadas feed-forward SwiGLU.
  • in_channels (int, padrão 24) — O número de canais dos latentes do vídeo.
  • audio_in_channels (int, padrão 32) — O número de canais dos latentes de áudio.
  • patch_size (tuple[int, int, int], padrão (1, 2, 2)) — O patch (t, h, w) usado para empacotar os latentes do vídeo em linhas.
  • text_dim (int, padrão 5120) — O número de canais da condição de texto produzida pelo codificador de texto.
  • freq_dim (int, padrão 256) — A dimensão do embedding sinusoidal de timestep. Os timesteps são consumidos sem escala em [0, 1].
  • time_embed_hidden_dim (int, padrão 5376) — A dimensão interna do MLP de passo de tempo.
  • time_embed_dim (int, padrão 2688) — A dimensão de saída do MLP de timestep, ou seja, a entrada de cada projeção AdaLN.
  • rope_freq_dim (int, padrão 16) — O número de frequências rotativas por eixo. Os eixos (t, h, w) compartilham um buffer inv_freq deste comprimento e 2 * 3 * rope_freq_dim dos canais de attention_head_dim são rotacionados.
  • rope_theta (float, padrão 10000.0) — A base do agendamento de frequência rotativa a partir do qual o buffer rope.inv_freq é calculado.
  • norm_eps (float, padrão 1e-5) — Epsilon das normalizações pré-atenção e pré-feed-forward.
  • qk_norm_eps (float, padrão 1e-5) — Epsilon das normalizações de query/key por cabeça.
  • final_norm_eps (float, padrão 1e-5) — Epsilon da normalização da saída do refinador de tokens e de norm_out.

Um modelo Transformer para geração conjunta de vídeo + áudio, introduzido no MiniMax-H3.

MiniMax-H3 executa uma única pilha de blocos sobre uma sequência 1-D empacotada que contém a condição de texto, as linhas da imagem/vídeo de condicionamento, as linhas de áudio e as linhas do vídeo alvo. A atenção é autoatenção completa sobre essa sequência; não há atenção cruzada nem pesos de bloco por modalidade. O comportamento específico de cada modalidade vem apenas das duas projeções de patch de entrada, da tag de modalidade AdaLN por linha e dos dois cabeçalhos de saída.

O chamador é responsável por construir o layout empacotado: aplicar patchify aos latentes do vídeo, ordenar as linhas e produzir a grade de posições (t, h, w), as tags de modalidade por linha e os índices de timestep por linha. A sequência não possui padding — a implementação de referência faz padding até um múltiplo de 64 para o FlashAttention e separa o final com cu_seqlens = [0, used, S], o que esta portabilidade não utiliza —, portanto, a atenção é executada sem máscara sobre um único documento e todos os backends de atenção permanecem disponíveis.

O eixo de lote é um eixo de replicação pura: os argumentos estruturais (timestep, timestep_indices, token_tags, position_ids e os três tensores de índice) descrevem um único layout empacotado que todos os itens do lote compartilham, e cada item é um único documento de atenção.

forward

< >

( hidden_states: Tensoraudio_hidden_states: Tensorencoder_hidden_states: Tensortimestep: Tensortimestep_indices: Tensortoken_tags: Tensorposition_ids: Tensorvideo_indices: Tensoraudio_indices: Tensortext_indices: Tensorattention_kwargs: dict[str, typing.Any] | None = Nonereturn_dict: bool = True ) → MiniMaxH3TransformerOutput or tuple

Parâmetros

  • hidden_states (torch.Tensor de forma (batch_size, num_video_tokens, in_channels * prod(patch_size))) — Linhas latentes de vídeo em patches — linhas de condicionamento e linhas de alvo — ordenadas conforme aparecem na sequência empacotada, ou seja, correspondendo a video_indices.
  • audio_hidden_states (torch.Tensor de forma (batch_size, num_audio_tokens, audio_in_channels)) — Linhas latentes de áudio, ordenadas para corresponder a audio_indices.
  • encoder_hidden_states (torch.Tensor de forma (batch_size, num_text_tokens, text_dim)) — Condição de texto, ordenada para corresponder a text_indices.
  • timestep (torch.Tensor de forma (num_timesteps,)) — Os valores de timestep distintos presentes na sequência empacotada, em [0, 1] e sem escala. Uma única forward atende linhas em diferentes níveis de ruído (vídeo alvo, áudio alvo, linhas de condicionamento).
  • timestep_indices (torch.Tensor de forma (seq_len,)) — Para cada linha da sequência empacotada, o índice do seu timestep em timestep.
  • token_tags (torch.Tensor de forma (seq_len,)) — Para cada linha da sequência empacotada, sua modalidade: 0 vídeo, 1 texto, 2 áudio.
  • position_ids (torch.Tensor de forma (seq_len, 3)) — As coordenadas rotacionais (t, h, w) de cada linha da sequência empacotada.
  • video_indices (torch.Tensor de forma (num_video_tokens,)) — Posições das linhas de vídeo na sequência empacotada.
  • audio_indices (torch.Tensor de forma (num_audio_tokens,)) — Posições das linhas de áudio na sequência empacotada.
  • text_indices (torch.Tensor de forma (num_text_tokens,)) — Posições das linhas de texto na sequência empacotada.
  • attention_kwargs (dict, opcional) — Um dicionário de kwargs que, se especificado, pode conter uma entrada scale que é aplicada às camadas LoRA.
  • return_dict (bool, padrão True) — Se deve retornar um MiniMaxH3TransformerOutput em vez de uma tupla simples.

Retorna

MiniMaxH3TransformerOutput ou tuple

A velocidade do vídeo de forma (batch_size, num_video_tokens, in_channels * prod(patch_size)) e a velocidade do áudio de forma (batch_size, num_audio_tokens, audio_in_channels), na ordem das linhas de video_indices e audio_indices.

MiniMaxH3TransformerOutput

classe diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput

< >

( sample: Tensoraudio_sample: typing.Optional[torch.Tensor] = None )

Parâmetros

  • sample (torch.Tensor de forma (batch_size, num_video_tokens, in_channels * prod(patch_size))) — A predição de velocidade do vídeo para as linhas endereçadas por video_indices, na mesma ordem. As linhas de condicionamento são retornadas sem máscara — mascará-las antes do passo do scheduler é responsabilidade do chamador.
  • audio_sample (torch.Tensor de forma (batch_size, num_audio_tokens, audio_in_channels), padrão None) — A predição de velocidade do áudio para as linhas endereçadas por audio_indices, na mesma ordem. forward sempre preenche esse campo; ele só tem valor padrão None para que a saída possa ser reconstruída a partir de um dicionário simples de seus campos, que é a forma como os hooks de offload do accelerate movem um BaseOutput de volta para o dispositivo de entrada.

A saída de MiniMaxH3Transformer3DModel.

Update on GitHub

←LuminaNextDiT2DModel MiniMaxMusic3Transformer1DModel→