# MiniMaxH3ImageTransformer2DModel

MiniMax에서 [MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)를 통해 소개한 이미지 생성 및 편집용 Diffusion Transformer 모델입니다.

[MiniMaxH3Transformer3DModel](/docs/diffusers/v0.43.0/ko/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel)에서 오디오 스트림을 제거한 모델입니다. 텍스트 조건부, 참조 이미지의 행, 생성된 이미지의 행을 포함하는 **하나의 패킹된 1차원 시퀀스**를 처리하는 단일 블록 스택으로 구성됩니다. 패킹된 레이아웃을 구성하는 것은 호출자의 책임이며, 이 때문에 forward 시그니처는 레이턴트와 별도로 레이아웃을 인수로 받습니다. `(t, h, w)` 위치 그리드, 행별 모달리티 태그, 행별 타임스텝 인덱스, 그리고 이미지 및 텍스트 행을 참조하는 두 인덱스 텐서입니다. [MiniMaxH3ImageBlocks](/docs/diffusers/v0.43.0/ko/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks)가 이 모든 것을 구성합니다.

체크포인트는 각 단계마다 하나의 출력 헤드를 유지하는 Parallel Decoding Distillation(PDD)을 통해 6개의 샘플링 단계로 증류됩니다. 따라서 `forward`는 현재 실행 중인 단계인 `pdd_step_index`를 인수로 받아 해당 단계의 헤드로 투영합니다.

```python
import torch
from diffusers import MiniMaxH3ImageTransformer2DModel

transformer = MiniMaxH3ImageTransformer2DModel.from_pretrained(
    "MiniMaxAI/MiniMax-H3-Image", subfolder="transformer_diffusers", 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)`로 모델을 캐스팅하지 마십시오.

## MiniMaxH3ImageTransformer2DModel[[diffusers.MiniMaxH3ImageTransformer2DModel]]

#### diffusers.MiniMaxH3ImageTransformer2DModel[[diffusers.MiniMaxH3ImageTransformer2DModel]]

```python
diffusers.MiniMaxH3ImageTransformer2DModel(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, patch_size: tuple[int, int, int] = (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, num_pdd_heads: int = 6)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_minimax_h3_image.py#L365)

**매개변수:**

num_attention_heads (`int`, 기본값 `56`) : multi-head attention에 사용할 헤드 수입니다.

attention_head_dim (`int`, 기본값 `128`) : 각 attention head의 채널 수. `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의 채널 수입니다.

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 값입니다.

num_pdd_heads (`int`, 기본값 `6`) : 체크포인트가 증류된 샘플링 단계 수입니다. 각 단계에는 고유한 출력 헤드가 있습니다.

MiniMax-H3-Image에서 소개된 이미지 생성 및 편집용 Transformer 모델입니다.

MiniMax-H3 트랜스포머에서 오디오 스트림을 제거한 모델입니다. 텍스트 조건, 참조 이미지의 행, 생성된 이미지의 행을 포함하는 **하나의 패킹된 1차원 시퀀스**를 단일 블록 스택으로 처리합니다. 어텐션은 해당 시퀀스에 대한 완전한 셀프 어텐션이며, 크로스 어텐션은 없습니다. 체크포인트는 Parallel Decoding Distillation(PDD)을 통해 고정된 샘플링 단계 수로 증류되며, 각 단계마다 하나의 출력 헤드를 유지하므로 `forward`는 현재 실행 중인 단계의 인덱스를 인자로 받습니다.

호출자는 패킹된 레이아웃을 구성하는 책임을 집니다. 구체적으로, latents를 patchify하고, 행을 정렬하며, `(t, h, w)` 위치 그리드, 행별 modality 태그, 행별 timestep 인덱스를 생성해야 합니다. 시퀀스에 패딩이 없으므로 주의 메커니즘은 하나의 문서 전체에 대해 마스킹 없이 실행되며, 모든 attention 백엔드가 사용 가능합니다.

배치 축은 순수한 복제 축입니다. 구조적 인자(`timestep`, `timestep_indices`, `token_tags`, `position_ids` 및 두 개의 인덱스 텐서)는 모든 배치 항목이 공유하는 하나의 패킹 레이아웃을 설명합니다.

#### forward[[diffusers.MiniMaxH3ImageTransformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, timestep_indices: Tensor, token_tags: Tensor, position_ids: Tensor, image_indices: Tensor, text_indices: Tensor, pdd_step_index: int, return_dict: bool = True)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_minimax_h3_image.py#L545)

**매개변수:**

hidden_states (`torch.Tensor`, shape `(batch_size, num_image_tokens, in_channels * prod(patch_size))`) : 패치화된 잠재 행 — 참조 이미지의 행과 생성된 이미지의 행 — 패킹된 시퀀스에 나타나는 순서대로 정렬되어 있으며, 즉 `image_indices`와 일치합니다.

encoder_hidden_states (`torch.Tensor`, shape `(batch_size, num_text_tokens, text_dim)`) : `text_indices`와 순서가 일치하도록 정렬된 텍스트 조건부입니다.

timestep (`torch.Tensor`, shape `(num_timesteps,)`) : packed sequence에 존재하는 *distinct* timestep 값들입니다. `[0, 1]` 범위로, 스케일링되지 않은 값입니다. 하나의 forward가 서로 다른 노이즈 레벨의 행(생성된 행, 참조 행)을 처리합니다.

timestep_indices (`torch.Tensor`, shape `(seq_len,)`) : packed sequence의 각 행에 대해, `timestep`에서의 해당 timestep 인덱스.

token_tags (`torch.Tensor`, shape `(seq_len,)`) : 패킹된 시퀀스의 각 행에 대해 해당 모달리티: `0` 이미지, `1` 텍스트.

position_ids (`torch.Tensor`, shape `(seq_len, 3)`) : 패킹된 시퀀스의 각 행에 대한 `(t, h, w)` 회전 좌표.

image_indices (`torch.Tensor`, shape `(num_image_tokens,)`) : packed sequence에서 이미지 행의 위치.

text_indices (`torch.Tensor`, shape `(num_text_tokens,)`) : packed sequence에서 텍스트 행의 위치.

pdd_step_index (`int`) : 출력 헤드를 선택하는 샘플링 단계입니다.

return_dict (`bool`, 기본값 `True`) : 일반 튜플 대신 [Transformer2DModelOutput](/docs/diffusers/v0.43.0/ko/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput)를 반환할지 여부.

**반환값:** [Transformer2DModelOutput](/docs/diffusers/v0.43.0/ko/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) 또는 `tuple`

`image_indices`의 행 순서대로, 각 이미지 행의 속도입니다. 모양은 `(batch_size, num_image_tokens, in_channels * prod(patch_size))`입니다.