> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/mo-xing/minimax-h3-image.md).

# MiniMax-H3-Image：如何在本地运行

使用 Unsloth FP8 和 GGUF 量化版本，在本地通过 6 个步骤运行 MiniMax-H3-Image，进行文生图和图像编辑。

**MiniMax-H3-Image** 是 MiniMax 推出的开放权重 330 亿参数模型，支持文生图和使用最多 16 张参考图进行编辑。它适合较长且完整的提示词。该模型经过蒸馏， **仅需 6 步，无需 CFG**，在 **2048 × 2048** 画布上：使用 FP8 仓库时每张图约需 **5 秒** ；在 40 GB A100 上使用 UD-Q4\_K\_XL 时每张图约需 **18 秒** 。

{% columns %}
{% column width="50%" %}
这些量化版本采用 [Unsloth Dynamic](https://unsloth.ai/docs/basics/dynamic-3.0-ggufs)，可让重要层保持较高精度。可在 [Unsloth](https://unsloth.ai/docs/zh/desktop.md)、stable-diffusion.cpp 等工具中运行。

* MiniMax-H3-Image： [GGUF](https://huggingface.co/unsloth/MiniMax-H3-Image-GGUF) • [FP8](https://huggingface.co/unsloth/MiniMax-H3-Image-FP8)
* 原始模型： [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)

已在 NVIDIA A100（40 GB）和 RTX PRO 6000（96 GB）上，使用 Unsloth 开发版（版本高于 2026.11.4）进行测试。
{% endcolumn %}

{% column width="50%" %}

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FN17t739HDhs4Bs9VVAEL%2Fminimax-h3-image-out-bookshop.webp?alt=media" alt="Rainy bookshop window with an UNSLOTH BOOKS chalkboard and a sleeping cat"><figcaption><p>FP8 仓库（INT8），2048 × 2048，在 A100 上约需 5 秒</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FdhaLehHOWudDk9TmHJfW%2Fminimax-h3-image-out-valley.webp?alt=media" alt="Misty autumn valley with a wooden footbridge"><figcaption><p>FP8 仓库（INT8）</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FE5iZZZi5oMaVw4Jo3ViS%2Fminimax-h3-image-out-island.webp?alt=media" alt="Isometric floating island city"><figcaption><p>FP8 仓库（INT8）</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FQ8V3wLPL9YacqR4YD5LK%2Fminimax-h3-image-out-ramen.webp?alt=media" alt="Overhead photo of ramen"><figcaption><p>GGUF UD-Q4_K_XL</p></figcaption></figure></div>

### 内存需求 <a href="#memory-requirements" id="memory-requirements"></a>

搭配 32B Qwen3-VL 文本编码器（来自 MiniMax-H3）时，需要高端 GPU 或充足的系统 RAM。

| 配置方案                    | 图像模型                    | 文本编码器                         | VAE    | 下载总量        |
| ----------------------- | ----------------------- | ----------------------------- | ------ | ----------- |
| **FP8 仓库** （Unsloth 默认） | INT8-ConvRot，20.3 GB    | INT8 Qwen3-VL 32B，27.1 GB     | 2.3 GB | **约 50 GB** |
| **GGUF UD-Q4\_K\_XL**   | 13.6 GB                 | Q4\_K\_M Qwen3-VL 32B，18.2 GB | 2.3 GB | **约 34 GB** |
| **GGUF Q8\_0**          | 22.0 GB                 | Q4\_K\_M Qwen3-VL 32B，18.2 GB | 2.3 GB | **约 43 GB** |
| 提示词增强器（可选）              | Qwen3.5-9B UD-Q4\_K\_XL |                               |        | **6.9 GB**  |

| 您的硬件                          | 建议从                                                     |
| ----------------------------- | ------------------------------------------------------- |
| **至少配备 80 GB 显存的 NVIDIA GPU** | FP8 仓库，全程在 GPU 上运行。在 96 GB RTX PRO 6000 上测试：峰值占用 54 GB。 |
| **40 GB NVIDIA GPU**          | FP8 仓库。在配备 83 GB RAM 的 40 GB A100 上测试：部分内容从 RAM 流式加载。   |
| **24 GB NVIDIA GPU**          | GGUF **UD-Q4\_K\_XL**，或使用 FP8 仓库并配备 48 GB 以上系统 RAM      |
| **16 GB GPU**                 | GGUF **UD-Q4\_K\_XL** 或更小，并配备 48 GB 以上系统 RAM            |
| **Mac 或仅使用 CPU，RAM 至少 64 GB** | GGUF **UD-Q4\_K\_XL** （速度较慢）                            |

仅测试了 96 GB 和 40 GB 两种配置，其余为估算值。在 24 GB 配置下，UD-Q4\_K\_XL 优于 Q8\_0（后者会溢出到 RAM）。Mac 和 CPU 仅使用 GGUF。

#### FP8、INT8 和 GGUF <a href="#fp8-int8-and-gguf" id="fp8-int8-and-gguf"></a>

FP8 仓库包含两个 20.3 GB 的文件：INT8-ConvRot 和 FP8。 **Unsloth 默认加载 INT8-ConvRot** （搭配 INT8 文本编码器），因为它更接近 bf16（在 2048 × 2048 下，LPIPS 为 0.140，而 FP8 为 0.255）。选择器仍将其称为 **Fast FP8**。在显存充足的 GPU 上，它的速度约为 GGUF 的 3 倍。

GGUF 量化版本： **Q8\_0** 22.03 GB（最接近 bf16）， **UD-Q6\_K\_XL** 17.58 GB， **UD-Q4\_K\_XL** 13.61 GB（**推荐**), **UD-Q2\_K\_XL** 8.68 GB（内存紧张）。

#### 硬件说明 <a href="#hardware-notes" id="hardware-notes"></a>

这些功能需要 Unsloth 2026.11.5 或更高版本。

* **T4 和其他不支持 bf16 的 GPU：** FP8 仓库（INT8 图像模型和文本编码器）会以 fp16 渲染和编辑。在配备 51 GB RAM 的 15 GB Colab T4 上测试：数据块会从系统 RAM 流式加载（使用约 43 至 47 GB），GPU 显存占用最高约 14 GB。

  | 任务，6 步           | 每张图像所需时间   |
  | ---------------- | ---------- |
  | 文生图，1024 x 1024  | 约 28 秒     |
  | 文生图，2048 x 2048  | 约 83 秒     |
  | 图像编辑，1 张参考图，1024 | 2.5 至 3 分钟 |

  LoRA 可以加载和渲染，但加载时会流式读取完整的 66 GB 模型（在 T4 上约需 12 分钟）。 **顺序** 放置需要约 52.4 GB 可用系统 RAM；不足时，Unsloth 会拒绝运行并显示所需和可用内存数值。
* **Linux 上的 AMD** （Radeon 8060S，gfx1151）：使用 **bf16** 基础模型、重新加载、使用 LoRA 渲染和导出均可正常工作。

### 快速入门 <a href="#quickstart" id="quickstart"></a>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FUySaKhMrEM4BEdibJvbp%2Fminimax-h3-image-flow.webp?alt=media" alt="Animation: pick MiniMax-H3-Image (Fast FP8), type a prompt, click Generate and get an alpine valley at sunrise" width="375"><figcaption><p>加速版 Unsloth 工作流</p></figcaption></figure>

{% stepper %}
{% step %}

#### 安装 Unsloth <a href="#install-unsloth" id="install-unsloth"></a>

获取 [Unsloth 桌面应用](https://unsloth.ai/docs/zh/desktop.md) ，适用于 [macOS](https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/mac.md), [Windows](https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/windows-installation.md) 或 [Linux](https://unsloth.ai/docs/zh/kuai-su-kai-shi/install/linux.md).

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">下载 Unsloth</a>

也可以在终端中运行。适用于 macOS、Linux、WSL：

{% code collapsedlinecount="10" %}

```bash
curl -fsSL https://unsloth.ai/install.sh | sh
```

{% endcode %}

Windows PowerShell：

{% code collapsedlinecount="10" %}

```powershell
irm https://unsloth.ai/install.ps1 | iex
```

{% endcode %}

然后启动 Unsloth 并打开 `http://localhost:8888`:

{% code collapsedlinecount="10" %}

```bash
unsloth studio -H 0.0.0.0 -p 8888
```

{% endcode %}
{% endstep %}

{% step %}

#### 打开图像 <a href="#open-images" id="open-images"></a>

在侧边栏中选择 **图像** 。 **创建** 会默认打开。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FlQtHN8moCQiBVRksvUtk%2Fminimax-h3-image-images-page.png?alt=media" alt="The Unsloth Images page with the Create workflow open and no model loaded"><figcaption><p>图像页面</p></figcaption></figure>
{% endstep %}

{% step %}

#### 选择 MiniMax-H3-Image <a href="#pick-minimax-h3-image" id="pick-minimax-h3-image"></a>

点击 **选择图像模型**，搜索 `MiniMax-H3-Image` 并选择：

* **MiniMax-H3-Image (Fast FP8)**：FP8 仓库。适用于显存 24 GB 或以上的 NVIDIA GPU。
* **MiniMax-H3-Image-GGUF (Slow)**：选择一种量化版本。 **UD-Q4\_K\_XL** 为推荐选项。

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FHhCLEoV6z1L4Db8ily2v%2Fminimax-h3-image-picker-search.png?alt=media" alt="Model picker search results for MiniMax-H3-Image with the Fast FP8 and GGUF entries"><figcaption><p>搜索结果</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F3ZuWCPvHggmFB2WbdphS%2Fminimax-h3-image-gguf-quants.png?alt=media" alt="The GGUF entry expanded to show its quants, with UD-Q4_K_XL marked recommended"><figcaption><p>GGUF 量化版本</p></figcaption></figure></div>

首次加载时会下载模型、文本编码器和 VAE。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FqfYd6Ju8MCpA2vWphkeV%2Fminimax-h3-image-download.png?alt=media" alt="Download panel with the 27 GB INT8 text encoder" width="400"><figcaption><p>首次下载 FP8 仓库</p></figcaption></figure>
{% endstep %}

{% step %}

#### 编写提示词 <a href="#write-your-prompt" id="write-your-prompt"></a>

描述完整图像。Unsloth 会设置为 **6 步** （已锁定：该模型经过蒸馏，步数固定为 6）， **引导系数为 1** 以及 **2048 × 2048**.

**增强提示词** （默认开启，也是 MiniMax 参考工作流）会使用 Qwen3.5-9B 模型改写你的提示词。这是一个独立的 **6.9 GB** 下载，速度较慢：约 **3.5 分钟** 在 A100 上每张图像额外耗时。快速试用时请将其关闭。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FBJhHYOSYImp8McKcvGjM%2Fminimax-h3-image-enhancer.png?alt=media" alt="Enhance prompt switch with its 6.9 GB download button" width="350"><figcaption><p>下载前增强提示词</p></figcaption></figure>
{% endstep %}

{% step %}

#### 生成 <a href="#generate" id="generate"></a>

点击 **生成**. **配方** 会显示所有设置、精度和增强后的提示词。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fmqa9vZ88KIaOFN27Gl5n%2Fminimax-h3-image-result-lossless.webp?alt=media" alt="Ginger cat asleep on books in a rainy bookshop window"><figcaption><p>FP8 仓库（INT8）、短提示词、开启增强器、种子 42</p></figcaption></figure>

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FwwUefNK5OGmbIuwl2tfE%2Fminimax-h3-image-recipe-lossless.webp?alt=media" alt="Recipe card with the enhanced prompt, INT8 precision, 6 steps and seed 42"><figcaption><p>配方卡</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### 图像编辑 <a href="#image-editing" id="image-editing"></a>

选择 **编辑**，上传 **图片 1**，然后 **添加图片** 以添加更多（最多 16 张）。将它们命名为 `<Picture 1>`, `<Picture 2>` ，并说明要保留和更改的内容。输出会沿用图片 1 在 2048 画布上的形状；以下示例使用 **输出尺寸** **自定义** `1024 × 1024`、种子 7、关闭增强器：在 RTX PRO 6000（FP8 仓库）上每张耗时 3 到 4 秒。开启增强器时，在 A100 上编辑一张图约耗时 9 分钟。

{% hint style="info" %}
不要使用生成图片时相同的种子和尺寸来编辑该图片。这样编辑会从图片自身的噪声开始，导致结果过度锐化，并忽略指令。请更改种子（或保留随机设置）。
{% endhint %}

**一张图片：** “编辑 \<Picture 1>。将场景变成一个下雪的冬日清晨。保留桥梁、河流和山脉不变。”

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FdYqwblQlu0tXyHWZR02d%2Fminimax-h3-image-edit1.png?alt=media" alt="Edit with the autumn valley as Picture 1 and the snowy result"><figcaption><p>一张图片</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FCG9GfRXXtmBhCMLt7ko6%2Fminimax-h3-image-edit-winter.webp?alt=media" alt="The same valley, bridge and river on a snowy winter morning"><figcaption><p>结果</p></figcaption></figure></div>

**两张图片：** “将 \<Picture 2> 中的热气球放到 \<Picture 1> 山谷上方的天空中。保留桥梁、树木、河流和光线不变。”

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FJ0iVCIJ1aDg9ibKSM9nY%2Fminimax-h3-image-edit2.png?alt=media" alt="Edit with the valley and a balloon as Pictures 1 and 2"><figcaption><p>两张图片</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FnyY7SUigpABhfJK6q40y%2Fminimax-h3-image-edit-balloon.webp?alt=media" alt="The valley from Picture 1 with the hot-air balloon from Picture 2 in the sky"><figcaption><p>结果</p></figcaption></figure></div>

### 训练 LoRA <a href="#train-a-lora" id="train-a-lora"></a>

查看 [微调 MiniMax-H3-Image](https://unsloth.ai/docs/zh/mo-xing/minimax-h3-image/fine-tune-minimax-h3-image.md)

#### 前后对比 <a href="#before-and-after" id="before-and-after"></a>

种子 42，1024 × 1024，关闭增强器： `a trtcrd of a cat sitting on a throne holding a golden cup, "queen of cats"` 以及 `a trtcrd of an astronaut standing on the moon holding a lantern, "the explorer"`.

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fkg53StPeOhBWosYeBEkn%2Fminimax-h3-image-lora-cat-before.webp?alt=media" alt="Without the LoRA: photo-like cat on a throne"><figcaption><p>无 LoRA</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F5idj4QIy1DMxo4QWxs88%2Fminimax-h3-image-lora-cat-w06.webp?alt=media" alt="LoRA weight 0.6: illustrated cat"><figcaption><p>权重 0.6</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FoD4Irr8nLFeWdVOvHUMT%2Fminimax-h3-image-lora-cat-after.webp?alt=media" alt="LoRA weight 1.0: tarot card style cat"><figcaption><p>权重 1.0</p></figcaption></figure></div>

<div><figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FjEaC0aZLy24V1JEzLzdH%2Fminimax-h3-image-lora-astronaut-before.webp?alt=media" alt="Without the LoRA: astronaut photo"><figcaption><p>无 LoRA</p></figcaption></figure> <figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F7KTnboVty4ipiJY5X4OH%2Fminimax-h3-image-lora-astronaut-after.webp?alt=media" alt="LoRA weight 1.0: tarot card style astronaut"><figcaption><p>权重 1.0</p></figcaption></figure></div>

* 权重 **1.0** 会呈现完整风格； **0.6 到 0.8** 效果更含蓄。
* 即使不使用触发词，LoRA 也会对提示词产生轻微影响。对于其他任务，请降低权重或不加载它。
* 在 1024 × 1024（训练尺寸）下，风格效果最强；在 2048 × 2048 下则较弱。

[在微调指南中继续](https://unsloth.ai/docs/zh/mo-xing/minimax-h3-image/fine-tune-minimax-h3-image.md#before-and-after)

### 通过代码运行 <a href="#run-from-code" id="run-from-code"></a>

#### Unsloth API <a href="#unsloth-api" id="unsloth-api"></a>

在 Images 页面加载模型，然后调用兼容 OpenAI 的 `POST /v1/images/generations` 端点（若要按 `model` 加载，请改为开启 **按请求切换图像和视频模型** ，路径为 **Settings → API**）。在此创建 API 密钥（[Unsloth API](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/api.md)）；示例会读取 `UNSLOTH_API_KEY`.

使用 `openai` (`pip install openai`):

{% code collapsedlinecount="10" %}

```python
import base64
import os

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8888/v1", api_key=os.environ["UNSLOTH_API_KEY"])

result = client.images.generate(
    model="unsloth/MiniMax-H3-Image-FP8",
    prompt="A misty mountain valley at sunrise with a wooden footbridge over a calm river, autumn trees in red, orange and gold on both banks, and soft golden light breaking through the mist. Detailed landscape photograph.",
    size="2048x2048",
    response_format="b64_json",
    extra_body={"steps": 6, "guidance": 1.0, "seed": 42},
)

with open("valley.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
```

{% endcode %}

使用 `curl`:

{% code collapsedlinecount="10" %}

```bash
curl -s http://localhost:8888/v1/images/generations \
  -H "Authorization: Bearer $UNSLOTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "unsloth/MiniMax-H3-Image-FP8",
    "prompt": "Isometric 3D illustration of a tiny floating island city with pastel houses and terracotta roofs, a waterfall pouring off the edge into soft clouds, and small hot-air balloons drifting around it. Clean lines, soft shadows, calm pastel palette.",
    "size": "2048x2048",
    "response_format": "b64_json",
    "seed": 7
  }' \
  | python3 -c "import sys, json, base64; open('island.png', 'wb').write(base64.b64decode(json.load(sys.stdin)['data'][0]['b64_json']))"
```

{% endcode %}

`size` 表示 `WIDTHxHEIGHT` ，且宽高必须是 16 的倍数； `steps` 和 `guidance` 默认值分别为 6 和 1。API 不会运行增强器。在 RTX PRO 6000 上每张图约需 3 秒，在 A100 上约需 5 秒。

**通过 API 使用 LoRA** （Unsloth 2026.11.5 或更新版本）：请求会使用加载时合并的 LoRA，例如在 **部署到 Create**之后。使用不同 `loras` 列表的请求会被拒绝；如需更改，请重新加载。

#### 使用 stable-diffusion.cpp 运行 GGUF <a href="#gguf-with-stable-diffusion.cpp" id="gguf-with-stable-diffusion.cpp"></a>

使用 `sd-cli` 运行来自 [stable-diffusion.cpp](https://github.com/unslothai/stable-diffusion.cpp) （Unsloth 锁定的版本）的 GGUF。

**1. 获取 `sd-cli`** （Linux，CUDA 13）。 [发布页面](https://github.com/unslothai/stable-diffusion.cpp/releases/tag/master-982-0518b34-u27b9ddc) 还提供 CUDA 12、Vulkan、CPU、macOS 和 Windows 版本。

{% code collapsedlinecount="10" %}

```bash
curl -L -o sd.zip https://github.com/unslothai/stable-diffusion.cpp/releases/download/master-982-0518b34-u27b9ddc/sd-master-982-0518b34-u27b9ddc-bin-Linux-Ubuntu-22.04-x86_64-cuda13.zip
unzip -o sd.zip
mv sd-master-982-0518b34-u27b9ddc-bin-Linux-Ubuntu-22.04-x86_64-cuda13 sd
./sd/sd-cli --version
```

{% endcode %}

**2. 下载模型、文本编码器和 VAE** （约 34 GB）：

{% code collapsedlinecount="10" %}

```bash
pip install -U huggingface_hub
hf download unsloth/MiniMax-H3-Image-GGUF minimax_h3_image_pruned-UD-Q4_K_XL.gguf --local-dir models
hf download unsloth/MiniMax-H3-GGUF qwen3vl_32b_minimax_h3-Q4_K_M.gguf --local-dir models
hf download MiniMaxAI/MiniMax-H3-Image vae/diffusion_pytorch_model.safetensors --local-dir models
```

{% endcode %}

**3. 创建图像。** `--offload-to-cpu` 会将权重保留在 RAM 中，并在需要时将各部分移至 GPU（显存峰值为 19.4 GB，RAM 为 39 GB）。

{% code collapsedlinecount="10" %}

```bash
./sd/sd-cli \
  --diffusion-model models/minimax_h3_image_pruned-UD-Q4_K_XL.gguf \
  --llm models/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
  --vae models/vae/diffusion_pytorch_model.safetensors \
  -p "A misty mountain valley at sunrise with a wooden footbridge over a calm river, autumn trees in red, orange and gold on both banks, and soft golden light breaking through the mist. Detailed landscape photograph." \
  --steps 6 --cfg-scale 1.0 --sampling-method euler --sigmas minimax-h3-image --rng cpu \
  --offload-to-cpu \
  -W 2048 -H 2048 --seed 42 \
  -o valley-sdcpp.png
```

{% endcode %}

在 40 GB A100 上需 103 秒，在 RTX PRO 6000 上需 12 秒。

**4. 编辑图像。** 每个 `-r` 都表示下一个 `<Picture N>`; `sd-cli` 会将它们裁剪为 `-W` × `-H`，因此请匹配图片 1 的形状。无需视觉文件。在 RTX PRO 6000 上耗时 16 秒和 20 秒。

{% code collapsedlinecount="10" %}

```bash
./sd/sd-cli \
  --diffusion-model models/minimax_h3_image_pruned-UD-Q4_K_XL.gguf \
  --llm models/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
  --vae models/vae/diffusion_pytorch_model.safetensors \
  -r valley-sdcpp.png \
  -p "Edit <Picture 1>. Turn the scene into a snowy winter morning. Keep the bridge, the river and the mountains the same." \
  --steps 6 --cfg-scale 1.0 --sampling-method euler --sigmas minimax-h3-image --rng cpu \
  --offload-to-cpu \
  -W 1024 -H 1024 --seed 42 \
  -o valley-sdcpp-winter.png
```

{% endcode %}

两张图片（`balloon.png` 是一张气球照片）：

{% code collapsedlinecount="10" %}

```bash
./sd/sd-cli \
  --diffusion-model models/minimax_h3_image_pruned-UD-Q4_K_XL.gguf \
  --llm models/qwen3vl_32b_minimax_h3-Q4_K_M.gguf \
  --vae models/vae/diffusion_pytorch_model.safetensors \
  -r valley-sdcpp.png -r balloon.png \
  -p "Put the hot-air balloon from <Picture 2> in the sky above the valley in <Picture 1>. Keep the bridge, the trees, the river and the light the same." \
  --steps 6 --cfg-scale 1.0 --sampling-method euler --sigmas minimax-h3-image --rng cpu \
  --offload-to-cpu \
  -W 1024 -H 1024 --seed 42 \
  -o valley-sdcpp-balloon.png
```

{% endcode %}

在 Mac 或 CPU 上，请使用应用中的 GGUF，或使用 `Darwin-macOS-arm64` / CPU `sd-cli` 构建版本，并确保内存足以容纳图像模型和 18.2 GB 的文本编码器（我们尚未测试）。

### 推荐设置 <a href="#recommended-settings" id="recommended-settings"></a>

| 设置             | Unsloth（FP8 或 GGUF）                     | stable-diffusion.cpp                                          |
| -------------- | --------------------------------------- | ------------------------------------------------------------- |
| **步数**         | **6** （已锁定）                             | `--steps 6`                                                   |
| **引导强度 / CFG** | **1**                                   | `--cfg-scale 1.0`                                             |
| **采样器 / 调度器**  | 由 Unsloth 设置                            | `--sampling-method euler --sigmas minimax-h3-image --rng cpu` |
| **负面提示词**      | 留空                                      | 留空                                                            |
| **尺寸**         | `2048×2048` 作为起始尺寸（ **模型尺寸** 列表中还有更多选项） | `-W 2048 -H 2048`                                             |
| **种子**         | 任意数字，可用于复现结果                            | `--seed 42`                                                   |

在约 4 MP 及以上尺寸时效果最佳。 **模型尺寸** 列表列出了原生尺寸，例如 `2368×1760` （4:3）和 `2720×1536` （16:9），还包括 16 MP 尺寸，例如 `4096×4096` （内存和耗时约为 4 倍）。

### 故障排除 <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>模型选择器中没有 MiniMax-H3-Image</summary>

[更新 Unsloth](https://unsloth.ai/docs/get-started/install/updating) 并重启。如果已加载模型，选择器会打开到 **本地设备**：点击 **推荐**。Mac 和 CPU 设备仅会列出 GGUF。

</details>

<details>

<summary>生成需要几分钟</summary>

关闭 **优化提示词** 。此外，在 NVIDIA 上，GGUF 的速度比 FP8 仓库慢约 3 倍。

</details>

<details>

<summary>API 忽略了我指定的模型</summary>

在 Images 页面加载 MiniMax-H3-Image，或开启 **按请求切换图像和视频模型** （位于） **设置 → API**.

</details>

<details>

<summary>sd-cli 提示缺少 libcudart.so.12 或 libcudart.so.13</summary>

使用 `cuda13` 压缩包（含 CUDA 13）， `cuda12` 压缩包（含 CUDA 12），或 Vulkan 构建版本。

</details>

另请参阅 [如何在本地运行图像扩散模型](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/diffusion-image.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://unsloth.ai/docs/zh/mo-xing/minimax-h3-image.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
