Diffusers documentation
MiniMax-H3-Image
MiniMax-H3-Image
MiniMax-H3-Imageは、MiniMax-H3をベースとしたMiniMaxの画像モデルで、テキストから画像を生成したり、参照画像を編集したりするために使用できます。チェックポイントはMiniMaxAI/MiniMax-H3-Imageで確認できます。
MiniMax-H3と同様に、Modular Diffusersブロックとしてのみ統合されています。MiniMaxH3ImageBlocksとそのMiniMaxH3ImageModularPipelineが統合のすべてです。
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 は、ブロックがコンポーネントを必要とするたびに、そのコンポーネントをアクセラレーター上に移動します。4736x3552 の画像の場合、ピーク時のメモリ使用量は約 65 GB になります。
テキストから画像へ:
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]参照画像の編集:
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 |
text_encoder | Qwen3VLForConditionalGeneration |
vae | AutoencoderKLMiniMaxH3Image |
tokenizer, processor | テキストエンコーダーのトークナイザーとQwen3VLProcessor |
scheduler | MiniMaxH3Scheduler |
テキストエンコーダーは、MiniMax-H3で使用されているものと同じです。リポジトリが自己完結型となるよう、チェックポイントには独自のコピーが含まれています。Hubはリポジトリ間で同一のファイルを重複排除するため、このコピーは追加のストレージを消費しません。
ワークフロー
ワークフローはimage入力に基づいて選択されます:
text2imageはpromptから生成します。image_conditionedは、promptと、imageとして渡される 1 つ以上の参照画像から生成します。プロンプトでは、それらを<Picture 1>、<Picture 2>のように順番に参照します。参照画像はそれぞれ元のサイズを保持します。短辺が 1024 ピクセルから 2048 ピクセルの範囲外の場合にのみリサイズされ、生成される画像のサイズにリサイズされることはありません。
プロンプトはチャットテンプレートなしでそのまま使用され、長く完全な説明が最も効果的です。編集プロンプトでは、通常、保持する対象を指定し、次に変更する点を示し、最後にターゲット画像を完全に記述します。
プロンプトの強化
MiniMax-H3-Image-PEはMiniMaxのプロンプト拡張モデルです。短いリクエストを、画像モデルが最も効果的に動作する詳細な記述に書き換え、アスペクト比を推奨します。diffusers/minimax-h3-image-pe-blocksのカスタムブロックは、これを独自のパイプラインとして実行します。xgrammarが必要で、GPUメモリは約18 GBです。
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
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
MiniMax-H3-Image用のModularPipeline: テキストから画像への生成(text2image)と参照画像による編集(image_conditioned)
MiniMax-H3-Image は、テキスト行、参照画像の行、生成画像の行（単一の潜在フレーム）からなる1つのパックされたシーケンス上で、オーディオなしで MiniMax-H3 トランスフォーマーを実行します。チェックポイントは2回蒸留されています。ガイダンスが重みに焼き込まれているため、グイダーも negative_prompt も guidance_scale もありません。また、トランスフォーマーの出力ヘッドを1ステップごとに1つずつ使用して、6ステップの固定グリッドでサンプリングを行うため、num_inference_steps もありません。
MiniMaxH3ImageBlocks
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’。
出力:
images (list):
生成された画像。