# MiniMax-H3-Image

MiniMax-H3-Image 是 MiniMax 基于 [MiniMax-H3](./minimax_h3) 开发的图像模型，用于文本生成图像和参考图像编辑。您可以在 [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image) 找到该检查点。

与 MiniMax-H3 类似，它仅以 [Modular Diffusers](../../modular_diffusers/overview) 块的形式集成：[MiniMaxH3ImageBlocks](/docs/diffusers/v0.43.0/zh/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) 及其 [MiniMaxH3ImageModularPipeline](/docs/diffusers/v0.43.0/zh/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)
```

在 bfloat16 精度下，transformer 和文本编码器各占用约 62 GB，无法同时放入 80 GB 的 GPU，因此示例使用了自动卸载：当某个 block 需要时，[ComponentsManager](/docs/diffusers/v0.43.0/zh/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/v0.43.0/zh/api/models/minimax_h3_image_transformer2d#diffusers.MiniMaxH3ImageTransformer2DModel) |
| `text_encoder` | `Qwen3VLForConditionalGeneration` |
| `vae` | [AutoencoderKLMiniMaxH3Image](/docs/diffusers/v0.43.0/zh/api/models/autoencoderkl_minimax_h3_image#diffusers.AutoencoderKLMiniMaxH3Image) |
| `tokenizer`, `processor` | 文本编码器的分词器和一个 `Qwen3VLProcessor` |
| `scheduler` | [MiniMaxH3Scheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/minimax_h3#diffusers.MiniMaxH3Scheduler) |

文本编码器与 [MiniMax-H3](./minimax_h3) 所使用的相同。检查点保留了自己的副本，以确保仓库的自包含性；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`，并且大约需要 18 GB 的 GPU 内存。

```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` 传入，以扩展编辑指令。然后，将 `prompt` 传入图像流水线，并使用与 `aspect_ratio` 匹配的 `height` 和 `width`。

## 图像大小

`height` 和 `width` 指定返回图像的尺寸，默认值为 2048。该模型以 400 万像素或更高的分辨率生成图像：如果请求的尺寸较小，系统会在具有相同宽高比的更大画布上生成图像，然后再缩放回请求的尺寸，因此 1024x1024 的请求与 2048x2028 的请求成本相同。`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 每步有一个输出头，因此没有 `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/v0.43.0/src/diffusers/modular_pipelines/minimax_h3_image/modular_pipeline.py#L27)

用于 MiniMax-H3-Image 的 ModularPipeline：文本生成图像（`text2image`）和参考图像编辑（`image_conditioned`）。

MiniMax-H3-Image 在一条打包序列上运行 MiniMax-H3 变换器，该序列包含文本行、参考图像的行以及生成图像的行（即单个潜在帧），且不处理音频。该检查点经过两次蒸馏：引导已融入权重中，因此没有引导器，也没有 `negative_prompt` 和 `guidance_scale`；它在六步的固定网格上进行采样，每一步对应变换器的一个输出头，因此也没有 `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]): 检查点中逐步输出头进行蒸馏所使用的采样网格。

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`, *可选*): 参考图像的条件潜变量。其形状为 where，每个参考图像的几何信息均来源于此。 latents (`Tensor`): 形状为 `(1, latent_channels, latent_height, latent_width)` 的预生成噪声，用于替代随机抽取。 reference_noise (`list`, *可选*): 参考图像的预生成噪声，每个张量的形状对应 `reference_latents` 中的每个条目，用于替代随机抽取。 **denoiser_input_fields (`None`, *可选*): Transformer 按名称读取的打包序列的结构描述：`token_tags`、`position_ids` 以及两个行索引张量。 output_type (`str`, *可选*, 默认为 pil): 输出格式：'pil'、'np'、'pt'。

输出：图像（`list`）：生成的图像。