# MiniMax-H3-Image

MiniMax-H3-Image는 [MiniMax-H3](./minimax_h3)를 기반으로 한 MiniMax의 이미지 모델로, 텍스트 기반 이미지 생성 및 참조 이미지 편집에 사용됩니다. 체크포인트는 [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)에서 찾을 수 있습니다.

MiniMax-H3와 마찬가지로, [Modular Diffusers](../../modular_diffusers/overview) 블록으로만 통합됩니다: [MiniMaxH3ImageBlocks](/docs/diffusers/v0.43.0/ko/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks)와 해당 [MiniMaxH3ImageModularPipeline](/docs/diffusers/v0.43.0/ko/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageModularPipeline)이 전체 통합을 구성합니다.

```py
import torch
from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
```

transformer와 text encoder는 bfloat16에서 각각 약 62 GB로, 80 GB GPU에 함께 올라가지 않으므로 예제에서는 auto offloading을 사용합니다. [ComponentsManager](/docs/diffusers/v0.43.0/ko/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager)는 블록이 해당 구성 요소를 필요로 할 때 이를 accelerator로 이동합니다. 4736x3552 이미지의 경우 피크 메모리가 약 65 GB까지 올라갑니다.

텍스트-이미지:

```py
prompt = (
    "An overhead photograph of a rustic farm-to-table spread on a weathered wooden table: a round loaf of sourdough "
    "on burlap, wedges of cheese on a dark board, a copper bowl of vegetables, vine tomatoes, olives and walnuts."
)
image = pipe(
    prompt=prompt, height=3552, width=4736, generator=torch.Generator().manual_seed(42), output="images"
)[0]
```

참조 이미지 편집:

```py
from diffusers.utils import load_image

reference = load_image("https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/resolve/main/examples/reference1.png")
image = pipe(
    prompt="Keep everything in <Picture 1> as it is, but remove the headphones and have the two hosts fist bump.",
    image=reference,
    height=4096,
    width=4096,
    generator=torch.Generator().manual_seed(1234),
    output="images",
)[0]
```

## 구성 요소

| 컴포넌트 | 클래스 |
|---|---|
| `transformer` | [MiniMaxH3ImageTransformer2DModel](/docs/diffusers/v0.43.0/ko/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/v0.43.0/ko/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | 텍스트 인코더의 토크나이저와 `Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/v0.43.0/ko/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

텍스트 인코더는 [MiniMax-H3](./minimax_h3)에서 사용하는 것과 동일합니다. 저장소가 자체적으로 완결되도록 체크포인트에는 해당 인코더의 사본이 포함됩니다. Hub는 저장소 간에 동일한 파일을 중복 제거하므로, 이 사본은 Hub에서 추가 저장 공간을 차지하지 않습니다.

## 워크플로

워크플로우는 `image` 입력에서 선택됩니다:

- **`text2image`**는 `prompt`로부터 생성합니다.
- **`image_conditioned`**는 `prompt`와 `image`로 전달된 하나 이상의 참조 이미지로부터 생성합니다. 프롬프트는 참조 이미지를 순서대로 `<Picture 1>`, `<Picture 2>` 등으로 지칭합니다. 참조 이미지는 자체 크기를 유지하며, 짧은 변의 길이가 1024~2048픽셀 범위를 벗어난 경우에만 리사이즈되고, 생성된 이미지의 크기로 리사이즈되지 않습니다.

프롬프트는 채팅 템플릿 없이 그대로 사용되며, 길고 완전한 설명이 가장 효과적입니다. 편집 프롬프트는 일반적으로 유지할 요소를 명시한 후 변경할 요소를 명시하고, 마지막으로 대상 이미지를 완전히 설명하는 구조를 가집니다.

## 프롬프트 향상

[MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE)는 MiniMax의 프롬프트 확장 모델입니다. 짧은 요청을 이미지 모델이 가장 잘 처리할 수 있는 수준의 상세한 설명으로 재작성하고, 권장 종횡비를 제안합니다. [diffusers/minimax-h3-image-pe-blocks](https://huggingface.co/diffusers/minimax-h3-image-pe-blocks) 커스텀 블록은 이를 자체 파이프라인으로 실행합니다. `xgrammar`가 필요하며, GPU 메모리 약 18 GB가 필요합니다.

```py
import torch
from diffusers import ModularPipeline

enhancer = ModularPipeline.from_pretrained("diffusers/minimax-h3-image-pe-blocks", trust_remote_code=True)
enhancer.load_components(dtype=torch.bfloat16, device_map="cuda")

state = enhancer(prompt="a cozy cabin in the snow")
prompt, aspect_ratio = state.get("prompt"), state.get("aspect_ratio")
```

편집 지시문을 확장하려면 참조 이미지를 `image`로 전달하세요. 그런 다음 `aspect_ratio`와 일치하는 `height`와 `width`를 지정하여 `prompt`를 이미지 파이프라인에 전달하세요.

## 이미지 크기

`height`와 `width`는 반환되는 이미지의 크기를 나타내며 기본값은 2048입니다. 모델은 4 메가픽셀 이상으로 생성합니다. 요청된 크기가 더 작으면 동일한 종횡비인 더 큰 캔버스에서 생성한 뒤 원래 크기로 다시 조정되므로, 1024x1024 요청은 2048x2048 요청과 동일한 비용이 발생합니다. `min_generation_area`는 픽셀 단위로 해당 임계값을 설정합니다. 요청한 크기로 항상 생성하려면 `1024`를 전달하세요. 어느 경우든 캔버스의 각 변은 32의 배수로 반올림됩니다.

MiniMax는 1:1 비율에 4096x4096, 4:3 비율에 4736x3552, 3:2 비율에 5024x3360, 16:9 비율에 5472x3072, 21:9 비율에 6272x2688을 권장하며, 세로 형식의 경우 동일한 크기의 높이와 너비를 서로 바꾸어 사용하도록 권장합니다.

## 샘플링

- 체크포인트는 `sample_sigmas`에 대해 6단계로 샘플링하며, 트랜스포머에는 단계마다 하나의 출력 헤드가 있으므로 `num_inference_steps`가 없습니다.
- 모델은 guidance-distilled이므로 guider, `negative_prompt` 또는 `guidance_scale`이 없습니다.

## MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]]

#### diffusers.MiniMaxH3ImageModularPipeline[[diffusers.MiniMaxH3ImageModularPipeline]]

```python
diffusers.MiniMaxH3ImageModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3_image/modular_pipeline.py#L27)

MiniMax-H3-Image용 ModularPipeline: 텍스트-이미지 생성(`text2image`) 및 참조 이미지 편집(`image_conditioned`).

MiniMax-H3-Image는 오디오 없이 텍스트 행, 참조 이미지 행, 생성된 이미지 행(단일 latent 프레임)으로 구성된 하나의 packed sequence 위에서 MiniMax-H3 transformer를 실행합니다. 이 체크포인트는 두 번 증류(distilled)되었습니다. 가이던스가 가중치에 이미 반영되어 있어 guider, `negative_prompt`, `guidance_scale`이 없으며, transformer의 출력 헤드 하나당 한 단계씩 고정된 6단계 그리드에서 샘플링하므로 `num_inference_steps`도 없습니다.

```py
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3-Image")
pipe.load_components(dtype=torch.bfloat16)
```

## MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]]

#### diffusers.MiniMaxH3ImageBlocks[[diffusers.MiniMaxH3ImageBlocks]]

```python
diffusers.MiniMaxH3ImageBlocks()
```

[소스](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_h3_image/modular_blocks_minimax_h3_image.py#L371)

MiniMax-H3-Image의 모듈형 파이프라인 블록: `text2image` 및 `image`가 전달될 때의 참조 이미지 편집(`image_conditioned`).

지원되는 워크플로:
- `text2image`: `prompt` 필수
- `image_conditioned`: `prompt`, `image` 필수

구성 요소: image_processor (`VaeImageProcessor`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3Image`) scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3ImageTransformer2DModel`)

Configs: reference_min_short_edge (기본값: 1024) reference_max_short_edge (기본값: 2048) vision_min_short_edge (기본값: 1024) vision_max_short_edge (기본값: 1024) sample_sigmas (기본값: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): 체크포인트의 단계별 출력 헤드가 증류(distilled)된 샘플링 그리드입니다.

Inputs: image (`Image | list`, *선택 사항*): 편집의 참조 이미지 또는 이미지 목록입니다. 프롬프트는 순서대로 `<Picture 1>`, `<Picture 2>`, ... 로 참조합니다. prompt (`str`): 생성을 안내하는 프롬프트, 단일 문자열입니다. vision_images (`list`, *선택 사항*): 텍스트 인코더를 위해 리사이즈된 참조 이미지입니다. reference_images (`list`, *선택 사항*): VAE를 위해 리사이즈된 참조 이미지입니다. generator (`Generator`, *선택 사항*): 요청의 생성기입니다. 각 참조에 대해 후验 샘플 하나씩이 여기서 추출됩니다. height (`int`): 반환되는 이미지의 픽셀 단위 높이입니다. width (`int`): 반환되는 이미지의 픽셀 단위 너비입니다. min_generation_area (`int`, *선택 사항*, 기본값 4194304): 이미지가 생성되는 최소 픽셀 단위 면적입니다. 더 작은 `height x width`는 이 면적으로 확대된 캔버스에서 생성된 후 디코딩 후 `height x width`로 다시 리사이즈됩니다. 요청한 크도로 항상 생성하려면 1024를 전달하세요. reference_latents (`list`, *선택 사항*): 참조 이미지의 조건부 잠재 변수입니다. 각 참조의 기하학적 구조가 여기서 유래합니다. latents (`Tensor`): `(1, latent_channels, latent_height, latent_width)` 형태의 사전 생성된 노이즈로, 추출 대신 사용됩니다. reference_noise (`list`, *선택 사항*): 참조 이미지의 사전 생성된 노이즈로, `reference_latents`의 각 항목의 형태를 가진 텐서 하나씩이며, 추출 대신 사용됩니다. **denoiser_input_fields (`None`, *선택 사항*): 트랜스포머가 이름으로 읽는 패킹된 시퀀스의 구조적 설명: `token_tags`, `position_ids` 및 두 행 인덱스 텐서. output_type (`str`, *선택 사항*, 기본값 pil): 출력 형식: 'pil', 'np', 'pt'.

출력: 이미지 (`list`): 생성된 이미지.