# MiniMaxH3Transformer3DModel MiniMax에서 [MiniMax-H3](https://huggingface.co/MiniMaxAI/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](/docs/diffusers/main/ko/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks)와 `MiniMaxH3Ref2VABlocks`는 이 모든 것을 구성합니다. 패딩 행을 포함하는 레이아웃(태그 `-1`)은 해당 행들이 불리언 마스크에 의해 자체 어텐션 문서로 유지되므로 마스크드 어텐션 백엔드가 필요합니다. 패딩이 없는 시퀀스는 마스크가 필요 없으며 모든 백엔드를 사용할 수 있습니다. 하나의 저장소에 릴리스된 체크포인트 파티션이 모두 포함되어 있으므로, 태스크는 서브폴더로 선택합니다: 텍스트 및 키프레임 태스크에는 `transformer/`, omni-reference 태스크에는 `transformer_ref/`를 사용합니다. ```python 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[[diffusers.MiniMaxH3Transformer3DModel]] #### diffusers.MiniMaxH3Transformer3DModel[[diffusers.MiniMaxH3Transformer3DModel]] ```python diffusers.MiniMaxH3Transformer3DModel(num_attention_heads: int = 56, attention_head_dim: int = 128, hidden_size: int = 5376, num_layers: int = 50, num_refiner_layers: int = 2, ffn_dim: int = 14336, in_channels: int = 24, audio_in_channels: int = 32, patch_size: tuple = (1, 2, 2), text_dim: int = 5120, freq_dim: int = 256, time_embed_hidden_dim: int = 5376, time_embed_dim: int = 2688, rope_freq_dim: int = 16, rope_theta: float = 10000.0, norm_eps: float = 1e-05, qk_norm_eps: float = 1e-05, final_norm_eps: float = 1e-05) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_minimax_h3.py#L379) **매개변수:** num_attention_heads (`int`, 기본값 `56`) : multi-head attention에 사용할 헤드 수입니다. 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)`) : 비디오 latents를 행으로 패킹하는 데 사용되는 `(t, h, w)` 패치입니다. text_dim (`int`, 기본값 `5120`) : 텍스트 인코더가 생성하는 텍스트 조건의 채널 수입니다. freq_dim (`int`, 기본값 `256`) : 사인oidal 타임스텝 임베딩의 차원입니다. 타임스텝은 `[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`) : pre-attention 및 pre-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[[diffusers.MiniMaxH3Transformer3DModel.forward]] ```python forward(hidden_states: Tensor, audio_hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, timestep_indices: Tensor, token_tags: Tensor, position_ids: Tensor, video_indices: Tensor, audio_indices: Tensor, text_indices: Tensor, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_minimax_h3.py#L605) **매개변수:** 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 행입니다. encoder_hidden_states (`torch.Tensor`, shape `(batch_size, num_text_tokens, text_dim)`) : `text_indices`와 순서가 일치하도록 정렬된 텍스트 조건부입니다. timestep (`torch.Tensor`, shape `(num_timesteps,)`) : 패킹된 시퀀스에 존재하는 *서로 다른* 타임스텝 값들입니다. `[0, 1]` 범위로, 스케일링되지 않은 값입니다. 하나의 포워드가 서로 다른 노이즈 레벨(타겟 비디오, 타겟 오디오, 조건부 행)의 행들을 처리합니다. timestep_indices (`torch.Tensor`, shape `(seq_len,)`) : packed sequence의 각 행에 대해, `timestep`에서의 해당 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,)`) : packed sequence에서 비디오 행의 위치. audio_indices (`torch.Tensor`, shape `(num_audio_tokens,)`) : packed sequence에서 오디오 행의 위치. text_indices (`torch.Tensor`, shape `(num_text_tokens,)`) : packed sequence에서 텍스트 행의 위치. attention_kwargs (`dict`, *선택 사항*) : 지정된 경우, LoRA 레이어에 적용되는 `scale` 항목을 포함할 수 있는 kwargs 사전입니다. return_dict (`bool`, 기본값 `True`) : 일반 튜플 대신 `MiniMaxH3TransformerOutput`를 반환할지 여부. **반환값:** `MiniMaxH3TransformerOutput` 또는 `tuple` `video_indices`와 `audio_indices`의 행 순서대로, shape가 `(batch_size, num_video_tokens, in_channels * prod(patch_size))`인 video velocity와 shape가 `(batch_size, num_audio_tokens, audio_in_channels)`인 audio velocity입니다. ## MiniMaxH3TransformerOutput[[diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput]] #### diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput[[diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput]] ```python diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput(sample: Tensor, audio_sample: typing.Optional[torch.Tensor] = None) ``` [소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_minimax_h3.py#L42) **매개변수:** 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`는 항상 이 값을 채우며, 필드의 일반 dict에서 출력을 재구성할 수 있도록 기본값만 `None`으로 설정되어 있습니다. 이는 accelerate offload 훅이 `BaseOutput`을 입력 장치로 되돌리는 방식입니다. [MiniMaxH3Transformer3DModel](/docs/diffusers/main/ko/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel)의 출력입니다.