# 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/main/ja/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks)とその[MiniMaxH3ImageModularPipeline](/docs/diffusers/main/ja/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 とテキストエンコーダーは bfloat16 でそれぞれ約 62 GB であり、80 GB の GPU に同時に収まりません。そのため、例では自動オフロードを使用しています。[ComponentsManager](/docs/diffusers/main/ja/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) は、ブロックがコンポーネントを必要とするたびに、そのコンポーネントをアクセラレーター上に移動します。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/main/ja/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/main/ja/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | テキストエンコーダーのトークナイザーと`Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/main/ja/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

テキストエンコーダーは、[MiniMax-H3](./minimax_h3)で使用されているものと同じです。リポジトリが自己完結型となるよう、チェックポイントには独自のコピーが含まれています。Hubはリポジトリ間で同一のファイルを重複排除するため、このコピーは追加のストレージを消費しません。

## ワークフロー

ワークフローは`image`入力に基づいて選択されます:

- **`text2image`** は `prompt` から生成します。
- **`image_conditioned`** は、`prompt` と、`image` として渡される 1 つ以上の参照画像から生成します。プロンプトでは、それらを `<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` カスタムブロックは、これを独自のパイプラインとして実行します。`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ステップにわたってサンプリングを行い、transformerにはステップごとに1つの出力ヘッドがあるため、`num_inference_steps`は存在しません。
- モデルはガイダンス蒸留されているため、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/main/src/diffusers/modular_pipelines/minimax_h3_image/modular_pipeline.py#L27)

MiniMax-H3-Image用のModularPipeline: テキストから画像への生成(`text2image`)と、参照画像を用いた編集(`image_conditioned`)。

MiniMax-H3-Image は、テキスト行、参照画像の行、生成画像の行（単一の潜在フレーム）からなる1つのパックされたシーケンス上で、オーディオなしで MiniMax-H3 トランスフォーマーを実行します。チェックポイントは2回蒸留されています。ガイダンスが重みに焼き込まれているため、グイダーも `negative_prompt` も `guidance_scale` も存在しません。また、トランスフォーマーの出力ヘッドを1ステップごとに1つずつ使用して、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/main/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]): チェックポイントのステップごとの出力ヘッドが蒸留されたサンプリンググリッドです。

Inputs: image (`Image | list`, *任意*): 編集の参照画像、またはそのリスト。プロンプトはこれらを `<Picture 1>`、`<Picture 2>`、... の順で参照します。 prompt (`str`): 生成をガイドするためのプロンプト。単一の文字列です。 vision_images (`list`, *任意*): テキストエンコーダー用にリサイズされた参照画像。 reference_images (`list`, *任意*): VAE用にリサイズされた参照画像。 generator (`Generator`, *任意*): リクエストのジェネレーター。参照画像ごとに1つの事後サンプルがこれから抽出されます。 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` の各エントリの形状を持つテンソルが1つずつ、抽選の代わりに使用されます。 **denoiser_input_fields (`None`, *任意*): トランスフォーマーが名前によって読み取るパックされたシーケンスの構造記述: `token_tags`、`position_ids` および2つの行インデックステンソル。 output_type (`str`, *任意*, デフォルトは pil): 出力形式: 'pil'、'np'、'pt'。

出力: 画像 (`list`): 生成された画像。