MiniMax-H3-Image
MiniMax-H3-Image 是 MiniMax H3 家族中的图像生成模型,以开放权重形式发布。生成与编辑共用同一个模型权重:模型既能根据文本生成图像,也能根据一张或多张参考图完成图像编辑,二者由同一个 33.1B 的扩散 Transformer 承担。它可以在任意画幅比例下直接生成约 1600 万像素的图像(从 4096×4096 到 6272×2688),无需超分;模型被蒸馏到 6 步采样,且不需要无分类器引导(CFG)。该扩散 Transformer 采用 H3 架构并去掉了音频分支,文本编码器与 MiniMax-H3 完全一致。
安装
在使用本模型进行推理和训练之前,请先安装 DiffSynth-Studio。
git clone https://github.com/modelscope/DiffSynth-Studio.git
cd DiffSynth-Studio
pip install -e .
更多安装方式请参考安装依赖。
快速开始
运行以下代码即可先用文本生成一张图像,再对刚生成的图像做一次编辑。该脚本把全部组件都放在显卡上,总共需要约 135 GB 显存(文本编码器 66.7 GB、Transformer 66.3 GB、图像 VAE 2.3 GB);显存不够时请使用低显存示例,它把文本编码器与 VAE 按磁盘流式加载、把 Transformer 以 int8 存放在主机内存。面向 24GB 消费级显卡与数据中心部署,参见不同硬件上的推理方案。
import torch
from diffsynth.pipelines.minimax_h3_image import MiniMaxH3ImagePipeline, ModelConfig
from diffsynth.core.quant import QuantizeConfig
from PIL import Image
pipe = MiniMaxH3ImagePipeline.from_pretrained(
torch_dtype=torch.bfloat16,
device="cuda",
model_configs=[
ModelConfig(model_id="MiniMax/MiniMax-H3", origin_file_pattern="FL2VA/text_encoder/model*.safetensors"),
ModelConfig(model_id="MiniMax/MiniMax-H3-Image", origin_file_pattern="transformer/model*.safetensors"),
ModelConfig(model_id="MiniMax/MiniMax-H3-Image", origin_file_pattern="pdd_fused_heads.safetensors"),
ModelConfig(model_id="MiniMax/MiniMax-H3-Image", origin_file_pattern="vae/diffusion_pytorch_model.safetensors"),
],
processor_config=ModelConfig(model_id="MiniMax/MiniMax-H3-Image", origin_file_pattern="processor/"),
vram_limit=torch.cuda.mem_get_info("cuda")[1] / (1024 ** 3) - 2,
)
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, "
"warm afternoon light raking across the grain of the wood."
)
image = pipe(prompt=prompt, height=4096, width=4096, seed=42)
image.save("MiniMax-H3-Image.jpg")
prompt = "Change the color of the tomato in <Picture 1> to green."
image = pipe(
prompt=prompt, height=4096, width=4096, seed=43,
edit_image=[Image.open("MiniMax-H3-Image.jpg")],
)
image.save("MiniMax-H3-Image-Edit.jpg")
模型总览
| 模型 ID | 推理 | 低显存推理 | 全量训练 | 全量训练后验证 | LoRA 训练 | LoRA 训练后验证 |
|---|---|---|---|---|---|---|
| MiniMax/MiniMax-H3-Image | code | code | code | code | code | code |
| DiffSynth-Studio/MiniMax-H3-Image-EntroPack (AdaLN-pruned) | code | code | code | code | code | code |
| DiffSynth-Studio/MiniMax-H3-Image-EntroPack (EntroPack) | code | code | - | - | code | code |
| Comfy-Org/MiniMax-H3-Image (pruned) | code | code | code | code | code | code |
| Comfy-Org/MiniMax-H3-Image (int8 pruned) | code | code | - | - | code | code |
模型推理
MiniMax-H3-Image 有两种工作模式:文生图,以及基于参考图的图像编辑。二者都通过 MiniMaxH3ImagePipeline 完成,由 edit_image 参数选择具体模式,因此同一份脚本即可覆盖两种用法。提示词会被原样使用,不套用对话模板,建议使用较长且完整的描述。
文生图
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, "
"warm afternoon light raking across the grain of the wood."
)
image = pipe(prompt=prompt, height=4096, width=4096, seed=42)
image.save("MiniMax-H3-Image.jpg")
height 与 width 是返回图像的尺寸,默认 2048。模型在 400 万像素及以上生成效果最好:当请求尺寸小于 min_generation_area(默认 2048×2048 像素面积)时,模型会按相同画幅比例在更大的画布上生成,再缩放回请求尺寸,因此 1024×1024 的请求与 2048×2048 的请求开销相同;把 min_generation_area 设为 1024 可关闭该行为。无论哪种情况,画布边长都会对齐到 32 的倍数。
模型的有效工作区间约为 400 万到 2000 万像素,通常在 1600 万像素附近效果最佳:
| 画幅比例 | 尺寸(宽 x 高) |
|---|---|
| 1:1 | 4096x4096 |
| 4:3 / 3:4 | 4736x3552 / 3552x4736 |
| 3:2 / 2:3 | 5024x3360 / 3360x5024 |
| 16:9 / 9:16 | 5472x3072 / 3072x5472 |
| 21:9 | 6272x2688 |
图像编辑
from PIL import Image
prompt = "Change the color of the tomato in <Picture 1> to green."
image = pipe(
prompt=prompt, height=4096, width=4096, seed=43,
edit_image=[Image.open("MiniMax-H3-Image.jpg")],
)
image.save("MiniMax-H3-Image-Edit.jpg")
提示词按顺序用 <Picture 1>、<Picture 2> 等指代参考图,最多支持 16 张参考图。参考图保持自身尺寸:仅当短边不在 1024 到 2048 像素之间时才会缩放,且绝不会被缩放到生成图像的尺寸。编辑提示词通常先说明要保留的内容,再说明要修改的内容,最后完整描述目标图像。
采样
模型在固定的 sigma 网格上进行 6 步采样,Transformer 每一步对应一个独立输出头:
distilled=True(默认)时num_inference_steps必须是 6。图像 VAE 以重叠分块(256 像素、至少 64 像素重叠)编解码并线性混合。分块是官方输出的组成部分,因此
tiling=True(默认)可以复现参考结果;tiling=False会整图解码,显存占用高得多。支持
cfg_scale与negative_prompt。该模型经过引导蒸馏,默认值(cfg_scale=1.0、空的negative_prompt)即复现官方行为;cfg_scale大于 1 会额外执行一次无条件分支,并按uncond + cfg_scale * (cond - uncond)合并,仅用于实验——蒸馏权重并未针对这种用法训练。distilled=False配合num_inference_steps=N会切换到普通 flow-match 采样;此时 Transformer 的 6 个输出头按噪声水平就近选择,而不是按步序号。
在单张 H20(96 GB)上实测:快速开始的脚本把文本编码器、Transformer 与 VAE 全部驻留在显卡上,共需约 135 GB 显存,因此单张 96 GB 显卡放不下;低显存示例把文本编码器与 VAE 改为磁盘流式、把 Transformer 与每步输出头以 int8 存放在主机内存,生成一张 4096×4096 图像再对其做一次编辑,含模型加载共约 4.5 分钟,显存峰值约 38 GiB。
不同硬件上的推理方案
MiniMax-H3-Image 的模型参数量非常大,针对不同的硬件条件,我们提供了多种推理方案。
消费级 NVIDIA GPU RTX 4090
以 RTX 4090 为例,GPU 显存只有 24G,因此需要对模型进行量化压缩,我们推荐使用 DiffSynth + EntroPack 进行推理。
安装 Python 环境:
pip install diffsynth==2.2.2
pip install cupy-cuda12x # or cupy-cuda13x
方案一:24GB 显存 + 32GB 内存
开启 INT8 量化 + ConvRot 提升精度,DiT 部分开启动态 CPU Offload,Text Encoder 部分开启 Disk Offload 流式加载和推理,图像生成质量几乎无损。
import torch
from diffsynth.pipelines.minimax_h3_image import MiniMaxH3ImagePipeline, ModelConfig
quant_vram_config = {
"offload_dtype": torch.bfloat16,
"offload_device": "cpu",
"onload_dtype": torch.bfloat16,
"onload_device": "cpu",
"preparing_dtype": torch.bfloat16,
"preparing_device": "cuda",
"computation_dtype": torch.bfloat16,
"computation_device": "cuda",
}
offload_vram_config = {
# 如果有更多内存,可以设置 offload_vram_config = quant_vram_config
"offload_dtype": "disk",
"offload_device": "disk",
"onload_dtype": "disk",
"onload_device": "disk",
"preparing_dtype": torch.bfloat16,
"preparing_device": "cuda",
"computation_dtype": torch.bfloat16,
"computation_device": "cuda",
}
pipe = MiniMaxH3ImagePipeline.from_pretrained(
torch_dtype=torch.bfloat16,
device="cuda",
model_configs=[
ModelConfig(
model_id="DiffSynth-Studio/MiniMax-H3-Image-EntroPack",
origin_file_pattern="models/dit_8bit_int8.safetensors",
origin_config_file="models/dit_8bit_int8.json",
**quant_vram_config,
),
ModelConfig(
model_id="DiffSynth-Studio/EntroPackPreQuants",
origin_file_pattern="models/MiniMax-H3/text_encoder_int8_convrot.safetensors",
origin_config_file="models/MiniMax-H3/text_encoder_int8_convrot.json",
**offload_vram_config,
),
ModelConfig(
model_id="MiniMax/MiniMax-H3-Image",
origin_file_pattern="pdd_fused_heads.safetensors",
**quant_vram_config,
),
ModelConfig(
model_id="DiffSynth-Studio/MiniMax-H3-Image-EntroPack",
origin_file_pattern="models/vae_int8.safetensors",
**quant_vram_config,
),
],
processor_config=ModelConfig(model_id="MiniMax/MiniMax-H3-Image", origin_file_pattern="processor/"),
vram_limit=20,
)
prompt = "A cat is sitting on the table. A book is on the table."
image = pipe(prompt=prompt, height=4096, width=4096, seed=42)
image.save("MiniMax-H3-Image-Pruned-EntroPack.jpg")
方案二:24GB 显存 + 8GB 内存
以 8.5bit、5bit 和 2.9bit 混合量化到 3bit 的平均精度,无任何 Offload,生成大量图片时速度最快。
import torch
from diffsynth.pipelines.minimax_h3_image import MiniMaxH3ImagePipeline, ModelConfig
pipe = MiniMaxH3ImagePipeline.from_pretrained(
torch_dtype=torch.bfloat16,
device="cuda",
model_configs=[
ModelConfig(
model_id="DiffSynth-Studio/MiniMax-H3-Image-EntroPack",
origin_file_pattern="models/dit_extreme_3bpp.safetensors",
origin_config_file="models/dit_extreme_3bpp.json",
),
ModelConfig(
model_id="DiffSynth-Studio/EntroPackPreQuants",
origin_file_pattern="models/MiniMax-H3/text_encoder_3bpp.safetensors",
origin_config_file="models/MiniMax-H3/text_encoder_3bpp.json",
),
ModelConfig(
model_id="MiniMax/MiniMax-H3-Image",
origin_file_pattern="pdd_fused_heads.safetensors",
),
ModelConfig(
model_id="DiffSynth-Studio/MiniMax-H3-Image-EntroPack",
origin_file_pattern="models/vae_int8.safetensors",
),
],
processor_config=ModelConfig(model_id="MiniMax/MiniMax-H3-Image", origin_file_pattern="processor/"),
)
prompt = "A cat is sitting on the table. A book is on the table."
image = pipe(prompt=prompt, height=4096, width=4096, seed=42)
image.save("MiniMax-H3-Image-Pruned-EntroPack.jpg")
NVIDIA GPU H20
H20 是目前广泛用于数据中心服务器上的低成本推理 GPU,使用 DiffSynth + EntroPack,首先使用 DiffSynth 中的自定义注意力算子,启用 Sage Attention 中量化后的注意力算子(以下代码需要在 import diffsynth 之前执行)。
import os
os.environ["DIFFSYNTH_ATTENTION_IMPLEMENTATION"] = "sage_attention_h20_fast"
from sageattention import sageattn_qk_int8_pv_fp8_cuda_sm90
from diffsynth.core.attention.common import rearrange_out, rearrange_qkv
from diffsynth.core.attention.registry import register_attention_implementation
def sage_attention_h20_fast(q, k, v, q_pattern="b n s d", k_pattern="b n s d", v_pattern="b n s d", out_pattern="b n s d", dims=None, scale=None):
required_in_pattern, required_out_pattern = "b s n d", "b s n d"
q, k, v = rearrange_qkv(q, k, v, q_pattern, k_pattern, v_pattern, required_in_pattern, dims)
q, k, v = q.contiguous(), k.contiguous(), v.contiguous()
out = sageattn_qk_int8_pv_fp8_cuda_sm90(
q, k, v,
tensor_layout="NHD",
qk_quant_gran="per_warp",
pv_accum_dtype="fp32+fp32",
smooth_k=False,
is_causal=False,
sm_scale=scale,
)
out = rearrange_out(out, out_pattern, required_out_pattern, dims)
return out
register_attention_implementation(
"sage_attention_h20_fast",
sage_attention_h20_fast,
supports_causal=False,
supports_window=False,
supports_mask=False,
)
启用 INT8 量化 + ConvRot 提升精度 + 编译加速,开始模型推理:
import torch
from diffsynth.pipelines.minimax_h3_image import MiniMaxH3ImagePipeline, ModelConfig
pipe = MiniMaxH3ImagePipeline.from_pretrained(
torch_dtype=torch.bfloat16,
device="cuda",
model_configs=[
ModelConfig(
model_id="DiffSynth-Studio/MiniMax-H3-Image-EntroPack",
origin_file_pattern="models/dit_8bit_int8.safetensors",
origin_config_file="models/dit_8bit_int8.json",
),
ModelConfig(
model_id="DiffSynth-Studio/EntroPackPreQuants",
origin_file_pattern="models/MiniMax-H3/text_encoder_int8_convrot.safetensors",
origin_config_file="models/MiniMax-H3/text_encoder_int8_convrot.json",
),
ModelConfig(
model_id="MiniMax/MiniMax-H3-Image",
origin_file_pattern="pdd_fused_heads.safetensors",
),
ModelConfig(
model_id="DiffSynth-Studio/MiniMax-H3-Image-EntroPack",
origin_file_pattern="models/vae_int8.safetensors",
),
],
processor_config=ModelConfig(model_id="MiniMax/MiniMax-H3-Image", origin_file_pattern="processor/"),
)
pipe.compile_pipeline()
prompt = "A cat is sitting on the table. A book is on the table."
image = pipe(prompt=prompt, height=4096, width=4096, seed=42)
image.save("MiniMax-H3-Image-Pruned-EntroPack.jpg")
这个推理方案需要约 50GB 显存,首次推理有减速效果,其后每次推理都会加速,适合部署线上推理服务。
模型训练
MiniMax-H3-Image 支持全量微调与 LoRA 微调。33.1B 的 Transformer 在 bf16 下占 66.3 GB,文本编码器另占 66.7 GB,因此两种训练配方都采用两阶段拆分流程:第一阶段(--task "sft:data_process")对数据集做预处理并缓存文本嵌入与 VAE latent,此时 Transformer 卸载到磁盘;第二阶段(--task "sft:train")在缓存数据集上训练,文本编码器与 VAE 卸载到磁盘。--lora_target_modules 留空,由框架自行决定 LoRA 加在哪些模块上;对该 Transformer 而言,它会覆盖各 block 堆栈的注意力与前馈投影,以及每个 block 的 AdaLN 投影,秩为 32。
训练数据是一个图片目录加一份 metadata.csv,其中记录图片文件名与提示词:
image,prompt
1.jpg,"a professional photo of a cute white and brown dog sitting on a wall under cherry blossoms"
modelscope download --dataset DiffSynth-Studio/diffsynth_example_dataset --include "minimax_h3_image/MiniMax-H3-Image/*" --local_dir ./data/diffsynth_example_dataset
# 第一阶段:缓存确定性的预处理结果。
accelerate launch examples/minimax_h3_image/model_training/train.py \
--dataset_base_path ./data/diffsynth_example_dataset/minimax_h3_image/MiniMax-H3-Image \
--dataset_metadata_path ./data/diffsynth_example_dataset/minimax_h3_image/MiniMax-H3-Image/metadata.csv \
--data_file_keys "image" \
--max_pixels 1048576 \
--dataset_repeat 1 \
--model_id_with_origin_paths "MiniMax/MiniMax-H3:FL2VA/text_encoder/model*.safetensors,MiniMax/MiniMax-H3-Image:transformer/model*.safetensors,MiniMax/MiniMax-H3-Image:pdd_fused_heads.safetensors,MiniMax/MiniMax-H3-Image:vae/diffusion_pytorch_model.safetensors" \
--learning_rate 1e-4 \
--num_epochs 1 \
--remove_prefix_in_ckpt "pipe.dit." \
--output_path "./models/train/MiniMax-H3-Image-split-cache" \
--lora_base_model "dit" \
--lora_target_modules "" \
--lora_rank 32 \
--use_gradient_checkpointing \
--task "sft:data_process" \
--offload_models "MiniMax/MiniMax-H3-Image:transformer/model*.safetensors,MiniMax/MiniMax-H3-Image:pdd_fused_heads.safetensors"
# 第二阶段:在缓存数据集上训练 LoRA。
accelerate launch examples/minimax_h3_image/model_training/train.py \
--dataset_base_path "./models/train/MiniMax-H3-Image-split-cache" \
--data_file_keys "image" \
--max_pixels 1048576 \
--dataset_repeat 50 \
--model_id_with_origin_paths "MiniMax/MiniMax-H3:FL2VA/text_encoder/model*.safetensors,MiniMax/MiniMax-H3-Image:transformer/model*.safetensors,MiniMax/MiniMax-H3-Image:pdd_fused_heads.safetensors,MiniMax/MiniMax-H3-Image:vae/diffusion_pytorch_model.safetensors" \
--learning_rate 1e-4 \
--num_epochs 5 \
--remove_prefix_in_ckpt "pipe.dit." \
--output_path "./models/train/MiniMax-H3-Image-split-lora" \
--lora_base_model "dit" \
--lora_target_modules "" \
--lora_rank 32 \
--use_gradient_checkpointing \
--task "sft:train" \
--offload_models "MiniMax/MiniMax-H3:FL2VA/text_encoder/model*.safetensors,MiniMax/MiniMax-H3-Image:vae/diffusion_pytorch_model.safetensors"
编辑训练以注释形式附在 LoRA 与全量脚本的末尾:取消注释并删掉上方的文生图两阶段即可。它使用 minimax_h3_image/MiniMax-H3-Image-Edit 数据集,其 metadata.csv 多出一列 edit_image 记录参考图路径,edit_image 同时出现在 --data_file_keys 与 --extra_inputs 中,参考图会与目标图一同被缓存。
正是两阶段拆分让训练能够放进单张显卡:整个流程中 Transformer、文本编码器与 VAE 从不同时驻留。训练脚本使用 --max_pixels 1048576,把每个样本缩放到约 100 万像素;验证脚本则以与低显存示例相同的卸载配置加载训练产物。推荐训练脚本见上文「模型总览」表格。关于如何编写模型训练脚本,请参考模型训练。