Diffusers documentation
MiniMaxH3Transformer3DModel
MiniMaxH3Transformer3DModel
MiniMax에서 MiniMax-H3를 통해 소개된, 비디오와 오디오를 함께 생성하는 Diffusion Transformer 모델입니다.
MiniMax-H3은 텍스트 조건부, 조건부 이미지 및 비디오 행, 오디오 행, 대상 비디오 행을 동시에 포함하는 하나의 패킹된 1차원 시퀀스 위에 단일 블록 스택을 실행합니다. 어텐션은 해당 시퀀스에 대한 완전한 셀프 어텐션(full self-attention)이므로 크로스 어텐션이나 모달리티별 블록 가중치가 없습니다. 모달리티별 동작은 두 개의 입력 패치 투영, AdaLN 변조 매개변수를 선택하는 행별 모달리티 태그, 그리고 두 개의 출력 헤드에서만 비롯됩니다.
packed layout를 구성하는 것은 호출자의 역할이며, 이 때문에 forward 시그니처는 latents와 별도로 layout을 받습니다: (t, h, w) 위치 그리드, 행별 modality 태그, 행별 timestep 인덱스, 그리고 video, audio, text 행을 참조하는 세 개의 인덱스 텐서입니다. MiniMaxH3Blocks와 MiniMaxH3Ref2VABlocks는 이 모든 것을 구성합니다.
패딩 행을 포함하는 레이아웃(태그 -1)은 해당 행들이 불리언 마스크에 의해 자체 어텐션 문서로 유지되므로 마스크드 어텐션 백엔드가 필요합니다. 패딩이 없는 시퀀스는 마스크가 필요 없으며 모든 백엔드를 사용할 수 있습니다.
하나의 저장소에 릴리스된 체크포인트 파티션이 모두 포함되어 있으므로, 태스크는 서브폴더로 선택합니다: 텍스트 및 키프레임 태스크에는 transformer/, omni-reference 태스크에는 transformer_ref/를 사용합니다.
import torch
from diffusers import MiniMaxH3Transformer3DModel
transformer = MiniMaxH3Transformer3DModel.from_pretrained(
"MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16
).to("cuda") # or "mps", "xpu", "cpu"체크포인트는 혼합 정밀도로 구성됩니다. 두 개의 입력 패치 투영, 타임스텝 MLP, 두 개의 출력 헤드는 float32이고, 블록 스택은 bfloat16입니다. from_pretrained는 _keep_in_fp32_modules를 통해 해당 레이아웃을 유지하므로, dtype=torch.bfloat16를 전달하고 float32 모듈의 배치에 맡기세요. 나중에 .to(torch.bfloat16)로 모델을 캐스팅하지 마세요.
MiniMaxH3Transformer3DModel
class diffusers.MiniMaxH3Transformer3DModel
< source >( 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[int, int, int] = (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 )
매개변수
- num_attention_heads (
int, 기본값56) — 멀티헤드 어텐션에 사용할 헤드의 수입니다. - attention_head_dim (
int, 기본값128) — 각 attention head의 채널 수입니다. MiniMax-H3에서는num_attention_heads * attention_head_dim이hidden_size보다 크다는 점에 유의하세요. - hidden_size (
int, 기본값5376) — 패킹된 시퀀스의 채널 수(잔차 스트림)입니다. - num_layers (
int, 기본값50) — Transformer 블록의 개수입니다. - num_refiner_layers (
int, 기본값2) — 투영된 텍스트 스트림에 적용되는 토크 리파이너 블록의 수입니다. - ffn_dim (
int, 기본값14336) — SwiGLU 피드포워드 레이어의 내부 차원입니다. - in_channels (
int, 기본값24) — 비디오 latents의 채널 수입니다. - audio_in_channels (
int, 기본값32) — 오디오 latents의 채널 수입니다. - patch_size (
tuple[int, int, int], 기본값(1, 2, 2)) — 비디오 잠재를 행으로 패킹하는 데 사용되는(t, h, w)패치입니다. - text_dim (
int, 기본값5120) — 텍스트 인코더가 생성하는 텍스트 조건의 채널 수입니다. - freq_dim (
int, 기본값256) — 사인 파형 타임스텝 임베딩의 차원입니다. 타임스텝은[0, 1]범위에서 스케일링되지 않은 상태로 사용됩니다. - time_embed_hidden_dim (
int, 기본값5376) — timestep MLP의 내부 차원입니다. - time_embed_dim (
int, 기본값2688) — timestep MLP의 출력 차원, 즉 모든 AdaLN 투영의 입력입니다. - rope_freq_dim (
int, 기본값16) — 축당 회전 주파수의 수입니다.(t, h, w)축은 이 길이의inv_freq버퍼를 공유하며,attention_head_dim채널 중2 * 3 * rope_freq_dim개가 회전됩니다. - rope_theta (
float, 기본값10000.0) —rope.inv_freq버퍼를 계산하는 데 사용되는 회전 주파수 스케줄의 기본값입니다. - norm_eps (
float, 기본값1e-5) — Attention 및 Feed-forward 이전 정규화(norm)의 Epsilon 값입니다. - qk_norm_eps (
float, 기본값1e-5) — 헤드별 query/key 정규화의 epsilon 값입니다. - final_norm_eps (
float, 기본값1e-5) — 토크린 리파이너 출력 정규화 및norm_out의 Epsilon 값입니다.
MiniMax-H3에서 소개된, 비디오와 오디오를 함께 생성하는 Transformer 모델입니다.
MiniMax-H3은 텍스트 조건, 조건부 이미지/비디오 행, 오디오 행 및 대상 비디오 행을 포함하는 하나의 패킹된 1차원 시퀀스 위에 단일 블록 스택을 실행합니다. 어텐션은 해당 시퀀스에 대한 완전한 셀프 어텐션이며, 크로스 어텐션이나 모달리티별 블록 가중치가 없습니다. 모달리티별 동작은 두 개의 입력 패치 투영, 행별 AdaLN 모달리티 태그, 두 개의 출력 헤드에서만 비롯됩니다.
호출자는 패킹된 레이아웃을 구성하는 책임을 집니다. 여기에는 비디오 잠재 변수를 패치화하고, 행을 정렬하며, (t, h, w) 위치 그리드, 행별 모달리티 태그 및 행별 타임스텝 인덱스를 생성하는 작업이 포함됩니다. 시퀀스에는 패딩이 없습니다. 참고 구현에서는 FlashAttention을 위해 64의 배수로 패딩을 추가하고 cu_seqlens = [0, used, S]로 꼬리를 분리하지만, 이 포트에서는 이를 사용할 필요가 없습니다. 따라서 어텐션은 하나의 문서에 대해 마스킹 없이 실행되며 모든 어텐션 백엔드가 사용 가능합니다.
배치 축은 순수한 복제 축입니다. 구조적 인자(timestep, timestep_indices, token_tags, position_ids 및 세 개의 인덱스 텐서)는 모든 배치 항목이 공유하는 하나의 패킹 레이아웃을 설명하며, 각 항목은 단일 어텐션 문서입니다.
forward
< source >( 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
매개변수
- hidden_states (
torch.Tensor, shape(batch_size, num_video_tokens, in_channels * prod(patch_size))) — 패치화된 비디오 잠재 행 — 조건부 행과 대상 행 — 패킹된 시퀀스에서 나타나는 순서대로 정렬되어 있으며, 즉video_indices와 일치합니다. - audio_hidden_states (
torch.Tensor, shape(batch_size, num_audio_tokens, audio_in_channels)) —audio_indices와 순서가 일치하도록 정렬된 오디오 잠재 행(latent rows)입니다. - encoder_hidden_states (
torch.Tensor, shape(batch_size, num_text_tokens, text_dim)) —text_indices와 일치하도록 정렬된 텍스트 조건부입니다. - timestep (
torch.Tensor, shape(num_timesteps,)) — 패킹된 시퀀스에 존재하는 서로 다른 timestep 값들입니다.[0, 1]범위로, 스케일링되지 않은 값입니다. 하나의 forward가 서로 다른 노이즈 레벨(타겟 비디오, 타겟 오디오, 조건부 행)의 행들을 처리합니다. - timestep_indices (
torch.Tensor, shape(seq_len,)) — 패킹된 시퀀스의 각 행에 대해,timestep에서의 해당 타임스텝 인덱스입니다. - token_tags (
torch.Tensor, shape(seq_len,)) — 패킹된 시퀀스의 각 행에 대해 해당 모달리티를 나타냅니다:0비디오,1텍스트,2오디오. - position_ids (
torch.Tensor, shape(seq_len, 3)) — 패킹된 시퀀스의 각 행에 대한(t, h, w)회전 좌표입니다. - video_indices (
torch.Tensor, shape(num_video_tokens,)) — 패킹된 시퀀스에서 비디오 행의 위치입니다. - audio_indices (
torch.Tensor, shape(num_audio_tokens,)) — 패킹된 시퀀스에서 오디오 행의 위치입니다. - text_indices (
torch.Tensor, shape(num_text_tokens,)) — 패킹된 시퀀스에서 텍스트 행의 위치입니다. - attention_kwargs (
dict, 선택 사항) — 지정된 경우, LoRA 레이어에 적용되는scale항목을 포함할 수 있는 kwargs 사전입니다. - return_dict (
bool, 기본값True) — 일반 튜플 대신MiniMaxH3TransformerOutput을 반환할지 여부.
반환값
MiniMaxH3TransformerOutput 또는 tuple
video_indices 및 audio_indices의 행 순서대로, 모양이 (batch_size, num_video_tokens, in_channels * prod(patch_size))인 비디오 속도 및 모양이 (batch_size, num_audio_tokens, audio_in_channels)인 오디오 속도입니다.
MiniMaxH3TransformerOutput
class diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput
< source >( sample: Tensoraudio_sample: typing.Optional[torch.Tensor] = None )
매개변수
- sample (
torch.Tensor, shape(batch_size, num_video_tokens, in_channels * prod(patch_size))) —video_indices로 지정된 행에 대한 비디오 속도 예측이며, 동일한 순서로 반환됩니다. 조건부 행은 마스킹되지 않은 상태로 반환되며, 스케줄러 단계 전에 이를 마스킹하는 것은 호출자의 책임입니다. - audio_sample (
torch.Tensor, shape(batch_size, num_audio_tokens, audio_in_channels), 기본값None) —audio_indices로 지정된 행에 대한 오디오 속도 예측 값이며, 동일한 순서를 따릅니다.forward는 항상 이 값을 채우며,None이 기본값인 이유는 해당 필드의 일반 dict에서 출력을 재구성할 수 있도록 하기 위해서입니다. 이는 accelerate offload hooks가BaseOutput을 입력 장치로 되돌리는 방식입니다.
MiniMaxH3Transformer3DModel의 출력입니다.