# MiniMax-H3-Image

MiniMax-H3-Image, MiniMax tarafından [MiniMax-H3](./minimax_h3) tabanlı olarak geliştirilen, metinden görüntüye üretim ve referans görüntü düzenleme için kullanılan bir görüntü modelidir. Kontrol noktasını [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image) adresinde bulabilirsiniz.

MiniMax-H3 gibi, yalnızca [Modular Diffusers](../../modular_diffusers/overview) blokları olarak entegre edilir: [MiniMaxH3ImageBlocks](/docs/diffusers/v0.43.0/tr/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) ve bunların [MiniMaxH3ImageModularPipeline](/docs/diffusers/v0.43.0/tr/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageModularPipeline)'ı tüm entegrasyonu oluşturur.

```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 ve metin kodlayıcı, bfloat16'da yaklaşık 62 GB boyutundadır ve birlikte 80 GB'lık bir GPU'ya sığmaz; bu nedenle örnekler otomatik boşaltma (auto offloading) kullanır: [ComponentsManager](/docs/diffusers/v0.43.0/tr/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager), bir bloğun bir bileşene ihtiyacı olduğunda o bileşeni hızlandırıcıya taşır. 4736x3552 boyutundaki bir görüntüde bellek kullanımı yaklaşık 65 GB'a ulaşır.

Metinden görüntüye:

```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]
```

Referans görüntüsünü düzenleme:

```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]
```

## Bileşenler

| Bileşen | Sınıf |
|---|---|
| `transformer` | [MiniMaxH3ImageTransformer2DModel](/docs/diffusers/v0.43.0/tr/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/v0.43.0/tr/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | Metin kodlayıcısının belirteçleyicisi ve bir `Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/v0.43.0/tr/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

Metin kodlayıcı, [MiniMax-H3](./minimax_h3)'ün kullandığıyla aynıdır. Kontrol noktası, repozitorinin kendi içinde tamamlanmış olması için kendi kopyasını saklar; Hub, repozitoriler arasında aynı dosyaları tekilleştirir, bu nedenle kopya orada ek depolama alanı işgal etmez.

## İş Akışları

İş akışı, `image` girdisinde seçilir:

- **`text2image`**, `prompt` üzerinden üretir.
- **`image_conditioned`**, `prompt` ve `image` olarak geçirilen bir veya daha fazla referans görüntüden üretim yapar. Prompt, bunlara sırasıyla `<Picture 1>`, `<Picture 2>` vb. şeklinde atıfta bulunur. Referanslar kendi boyutlarını korur: her biri yalnızca kısa kenarı 1024 ile 2048 piksel aralığının dışında olduğunda yeniden boyutlandırılır ve asla üretilen görüntünün boyutuna getirilmez.

İstem, sohbet şablonu olmadan olduğu gibi kullanılır ve uzun, eksiksiz açıklamalar en iyi sonucu verir. Bir düzenleme istemi genellikle korunacak öğeleri, ardından değiştirilecek öğeleri adlandırır ve ardından hedef görüntüyü eksiksiz olarak açıklar.

## İstemci iyileştirme

[MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE), MiniMax'ın prompt genişletme modelidir: kısa bir isteği, görsel modelin en iyi çalıştığı türden ayrıntılı bir açıklamaya dönüştürür ve bir en-boy oranı önerir. [diffusers/minimax-h3-image-pe-blocks](https://huggingface.co/diffusers/minimax-h3-image-pe-blocks) özel blokları, bunu kendi bağımsız bir hattı olarak çalıştırır. Bunlar `xgrammar` gerektirir ve yaklaşık 18 GB GPU belleği kullanır.

```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")
```

Bunun yerine düzenleme talimatını genişletmek için referans görselleri `image` olarak iletin. Ardından `prompt` değerini görsel hattına iletin; `height` ve `width` değerleri `aspect_ratio` ile eşleşmelidir.

## Görsel boyutu

`height` ve `width`, döndürülen görüntünün boyutunu belirtir ve varsayılan olarak 2048'dir. Model, 4 megapiksel veya daha yüksek çözünürlükte üretim yapar: daha küçük bir istek, aynı en-boy oranına sahip daha büyük bir tuval üzerinde üretilir ve ardından yeniden boyutlandırılır; bu nedenle 1024x1024'lik bir istek, 2048x2048'lik bir istekle aynı maliyete sahiptir. `min_generation_area`, bu eşiği piksel cinsinden belirler; istenen boyutta her zaman üretim yapmak için `1024` değerini iletin. Her durumda tuvalin kenarları 32'nin katlarına yuvarlanır.

MiniMax, 1:1 için 4096x4096, 4:3 için 4736x3552, 3:2 için 5024x3360, 16:9 için 5472x3072 ve 21:9 için 6272x2688 boyutlarını önermektedir; dikey formatlar için ise aynı boyutların yükseklik ve genişlik değerleri yer değiştirilerek kullanılması önerilir.

## Örnekleme

- Kontrol noktası, `sample_sigmas` üzerinde 6 adımda örnekler ve dönüştürücü (transformer) her adım için bir çıktı başlığına sahip olduğundan, `num_inference_steps` parametresi yoktur.
- Model rehberlik damıtılmıştır, bu nedenle bir rehber, `negative_prompt` veya `guidance_scale` yoktur.

## 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)
```

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

MiniMax-H3-Image için modüler bir ModularPipeline: metinden görüntüye (`text2image`) ve referans görüntü düzenleme (`image_conditioned`).

MiniMax-H3-Image, MiniMax-H3 dönüştürücüsünü ses olmadan, metin satırlarından, referans görüntülerin satırlarından ve üretilen görüntünün satırlarından oluşan tek bir paketlenmiş dizide çalıştırır; bu, tek bir gizli çerçevedir. Kontrol noktası iki kez damıtılmıştır: yönlendirme ağırlıklara gömülmüştür, bu nedenle yönlendirici, `negative_prompt` ve `guidance_scale` yoktur ve ayrıca, dönüştürücünün her adımı için bir çıktı kafası olan altı adımlık sabit bir ızgarada örneklemeler yaptığı için `num_inference_steps` de yoktur.

```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()
```

[Kaynak](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 için modüler pipeline blokları: `text2image` ve `image` geçirildiğinde referans görüntü düzenleme (`image_conditioned`).

Desteklenen iş akışları:
- `text2image`: `prompt` gerektirir
- `image_conditioned`: `prompt` ve `image` gerektirir

Bileşenler: image_processor (`VaeImageProcessor`) text_encoder (`Qwen3VLForConditionalGeneration`) tokenizer (`Qwen2Tokenizer`) processor (`Qwen3VLProcessor`) vae (`AutoencoderKLMiniMaxH3Image`) scheduler (`MiniMaxH3Scheduler`) transformer (`MiniMaxH3ImageTransformer2DModel`)

Yapılandırmalar: reference_min_short_edge (varsayılan: 1024) reference_max_short_edge (varsayılan: 2048) vision_min_short_edge (varsayılan: 1024) vision_max_short_edge (varsayılan: 1024) sample_sigmas (varsayılan: [1.0, 0.9675236940383911, 0.8875485062599182, 0.75, 0.5327739119529724, 0.23200887441635132, 0.0]): Kontrol noktasının adım başına çıktı başlıklarının damıtıldığı örneklemleme ızgarası.

Inputs: image (`Image | list`, *isteğe bağlı*): Düzenlemenin referans görseli veya bunların bir listesi. İstem, bunlara sırasıyla `<Picture 1>`, `<Picture 2>`, ... olarak atıfta bulunur. prompt (`str`): Üretimi yönlendirmek için tek bir dize olan istem. vision_images (`list`, *isteğe bağlı*): Metin kodlayıcı için yeniden boyutlandırılmış referans görseller. reference_images (`list`, *isteğe bağlı*): VAE için yeniden boyutlandırılmış referans görseller. generator (`Generator`, *isteğe bağlı*): İsteğin üreteci. Her referans için bir posterior örnek ondan çekilir. height (`int`): Dönen görselin piksel cinsinden yüksekliği. width (`int`): Dönen görselin piksel cinsinden genişliği. min_generation_area (`int`, *isteğe bağlı*, varsayılan 4194304): Bir görselin oluşturulduğu en küçük alan, piksel cinsinden. Daha küçük bir `height x width`, bu alana ölçeklendirilmiş bir tuval üzerinde oluşturulur ve kodlama sonrası `height x width` boyutuna yeniden ölçeklenir. Her zaman istenen boyutta üretmek için 1024 geçin. reference_latents (`list`, *isteğe bağlı*): Referans görsellerin koşullama latentleri. Şekilleri, her referansın geometrisinin geldiği yerdir. latents (`Tensor`): Çekim yerine kullanılan, `(1, latent_channels, latent_height, latent_width)` şeklindeki önceden üretilmiş gürültü. reference_noise (`list`, *isteğe bağlı*): Referans görseller için önceden üretilmiş gürültü, `reference_latents` girdilerinin her birinin şekline sahip bir tensör, çekimler yerine kullanılır. **denoiser_input_fields (`None`, *isteğe bağlı*): Dönüştürücünün adla okuduğu paketlenmiş dizinin yapısal açıklaması: `token_tags`, `position_ids` ve iki satır-dizin tensörü. output_type (`str`, *isteğe bağlı*, varsayılan pil): Çıktı biçimi: 'pil', 'np', 'pt'.

Çıktılar: görüntüler (`list`): Oluşturulan görüntüler.