Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: fix MiniMax-H3-Image downloads, explicit FP8/INT8 and 16 MP sizes (#17563)

oobabooga20686a0d92ff
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index fbde3601429..38852440220 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -4560,6 +4560,10 @@ class DiffusionBackend:
base_repo = nvfp4_gated_base(family_name)
if not dense_quant_supported_kind(model_kind):
reason = dense_quant_unsupported_kind_reason(model_kind)
+ elif family_name == MINIMAX_H3_IMAGE_FAMILY_NAME and model_kind == "pipeline":
+ # Own loader, no torch.compile: the torchao gates below do not apply.
+ from .diffusion_minimax_h3_image import explicit_scheme_refusal
+ reason = explicit_scheme_refusal(pinned, target.device)
elif getattr(fam, "denoiser_attr", "transformer") != "transformer":
# Refuse from the family table, before eviction and download.
reason = (
@@ -6330,6 +6334,91 @@ class DiffusionBackend:
logger = logger,
)
+ @staticmethod
+ def _h3_image_te_plan_files(
+ text_encoder_quant: Optional[str],
+ hf_token: Optional[str],
+ failures_out: Optional[list] = None,
+ ) -> dict[str, tuple[str, list[tuple[str, int]]]]:
+ """H3-Image encoder files (hosted int8 + H3 config, or H3 bf16), never the bundled copy."""
+ from huggingface_hub import HfApi
+
+ from .diffusion_minimax_h3_image import H3_IMAGE_TEXT_ENCODER_REPO, h3_image_te_scheme
+ from .video_minimax_h3_te import h3_te_quant_filename, h3_te_quant_source
+
+ scheme = h3_image_te_scheme(text_encoder_quant)
+ if scheme:
+ wanted = {
+ "text_encoder": (
+ h3_te_quant_source(scheme),
+ lambda name: name == h3_te_quant_filename(scheme),
+ ),
+ "text_encoder_config": (
+ H3_IMAGE_TEXT_ENCODER_REPO,
+ lambda name: name == "text_encoder/config.json",
+ ),
+ }
+ else:
+ wanted = {
+ "text_encoder": (
+ H3_IMAGE_TEXT_ENCODER_REPO,
+ lambda name: name.startswith("text_encoder/"),
+ )
+ }
+ planned: dict[str, tuple[str, list[tuple[str, int]]]] = {}
+ for component, (repo, keep) in wanted.items():
+ try:
+ info = hub_reachability.model_info(
+ HfApi(token = hf_token or None),
+ repo,
+ files_metadata = True,
+ skip_when_unreachable = False,
+ )
+ files = [
+ (s.rfilename, int(s.size))
+ for s in getattr(info, "siblings", None) or ()
+ if keep(s.rfilename) and getattr(s, "size", None) is not None
+ ]
+ if not files:
+ raise FileNotFoundError(f"{repo} lists no MiniMax-H3-Image {component}")
+ except Exception as exc: # noqa: BLE001 -- unlisted: the load fetches it inline
+ logger.warning("diffusion.h3_image_te_plan_failed: %s", exc)
+ if failures_out is not None:
+ failures_out.append(exc)
+ files = []
+ planned[component] = (repo, files)
+ return planned
+
+ def _h3_image_planned_dit_scheme(
+ self,
+ fam: Any,
+ transformer_quant: Optional[str],
+ gpu_ordinal: Optional[int],
+ failures_out: Optional[list] = None,
+ text_encoder_quant: Optional[str] = None,
+ ) -> Optional[str]:
+ """Hosted DiT scheme the H3-Image load would take, or None for bf16 shards."""
+ try:
+ from .diffusion_minimax_h3_image import QUANT_SCHEMES, planned_dit_scheme
+ with diffusion_device_scope(gpu_ordinal):
+ target = self._target_for_ordinal(fam, gpu_ordinal)
+ scheme = planned_dit_scheme(
+ transformer_quant,
+ target.device,
+ text_encoder_quant,
+ reclaimable_host_gb = pipeline_host_mib(
+ getattr(getattr(self, "_state", None), "pipe", None)
+ )
+ * 2**20
+ / 1e9,
+ )
+ return scheme if scheme in QUANT_SCHEMES else None
+ except Exception as exc: # noqa: BLE001 -- unplannable: stage the bf16 shards, as before
+ logger.warning("diffusion.h3_image_dit_plan_failed: %s", exc)
+ if failures_out is not None:
+ failures_out.append(exc)
+ return None
+
@staticmethod
def _te_prequant_plan_files(
fam: Any,
@@ -7234,8 +7323,16 @@ class DiffusionBackend:
te_quant_planned, _ = resolve_te_quant_request(
"none" if te_bf16_auto else text_encoder_quant, getattr(fam, "te_quant_auto", None)
)
+ h3_image = (
+ kind == "pipeline"
+ and getattr(fam, "name", None) == MINIMAX_H3_IMAGE_FAMILY_NAME
+ and not Path(repo_id).expanduser().exists()
+ )
+ plan_failures: list = []
te_files = (
- {
+ self._h3_image_te_plan_files(text_encoder_quant, hf_token, plan_failures)
+ if h3_image
+ else {
c: v
for c, v in self._te_prequant_plan_files(
fam,
@@ -7258,7 +7355,15 @@ class DiffusionBackend:
)
# Settled before the listing: only a checkpoint that resolves on the Hub may drop the released shards.
pipeline_planned = (
- self._pipeline_planned_denoiser_scheme(
+ self._h3_image_planned_dit_scheme(
+ fam,
+ load_kwargs.get("transformer_quant"),
+ load_kwargs.get("gpu_ordinal"),
+ plan_failures,
+ text_encoder_quant,
+ )
+ if h3_image and allow_device_probe
+ else self._pipeline_planned_denoiser_scheme(
fam,
base = base,
kind = kind,
@@ -7276,8 +7381,6 @@ class DiffusionBackend:
if allow_device_probe
else None
)
- # Declared before the prequant lookup so a repo missing both artifacts marks the plan partial; the dense shards are already dropped.
- plan_failures: list = []
dit_prequant = (
self._dit_prequant_plan_source(
fam,
@@ -11796,12 +11899,12 @@ class DiffusionBackend:
from .diffusion_minimax_h3_image import (
PLACE_RESIDENT,
PLACE_SEQUENTIAL,
+ h3_image_te_scheme,
load_minimax_h3_image_pipeline,
)
# Unset = Studio's hosted int8 encoder (the bf16 one is 66.7 GB); only an explicit dense ask keeps bf16.
- requested_te = str(text_encoder_quant or "").strip().lower()
- te_scheme = None if requested_te in ("none", "off", "bf16", "dense", "bfloat16") else "int8"
+ te_scheme = h3_image_te_scheme(text_encoder_quant)
pipe = load_minimax_h3_image_pipeline(
fetch_base,
dtype = target.dtype,
@@ -16767,6 +16870,9 @@ def _explicit_pipeline_components(fam: Any) -> Optional[tuple[str, ...]]:
return ANIMA_COMPONENTS
if name in (KREA2_FAMILY_NAME, MOSS_IMAGE_FAMILY_NAME):
return ("scheduler", "text_encoder", "tokenizer", "transformer", "vae")
+ if name == MINIMAX_H3_IMAGE_FAMILY_NAME:
+ # Encoder comes from download_plan's te_files, never the bundled text_encoder/.
+ return ("processor", "tokenizer", "transformer", "vae")
if name == IDEOGRAM4_FAMILY_NAME:
return (
"scheduler",
diff --git a/studio/backend/core/inference/diffusion_conditioning.py b/studio/backend/core/inference/diffusion_conditioning.py
index 820f2c14c41..08b566ceb62 100644
--- a/studio/backend/core/inference/diffusion_conditioning.py
+++ b/studio/backend/core/inference/diffusion_conditioning.py
@@ -15,6 +15,8 @@ LOCALIZED_EDIT_MODES = ("annotate", "paint", "mask")
MAX_CONDITION_SOURCE_PIXELS = 64_000_000
MIN_OUTPUT_SIDE = 256
+# Largest family max_output_side; per-family bounds live in check_output_size.
+MAX_REQUEST_SIDE = 6272
# Upstream QwenImage21Pipeline's own ``output_resolution`` default.
DEFAULT_REFERENCE_RESOLUTION = 1024
diff --git a/studio/backend/core/inference/diffusion_minimax_h3_image.py b/studio/backend/core/inference/diffusion_minimax_h3_image.py
index 87a8157c22f..367e1654bd9 100644
--- a/studio/backend/core/inference/diffusion_minimax_h3_image.py
+++ b/studio/backend/core/inference/diffusion_minimax_h3_image.py
@@ -106,6 +106,16 @@ PDD_HEADS_FILE = "pdd_fused_heads.safetensors"
PDD_CONFIG_FILE = "pdd_config.json"
DIFFUSERS_TRANSFORMER_SUBFOLDER = "transformer_diffusers"
DIFFUSERS_VAE_SUBFOLDER = "vae_diffusers"
+# Never the *_diffusers/ copy or the bundled text encoder.
+H3_IMAGE_BASE_PATTERNS = (
+ "model_index.json",
+ PDD_CONFIG_FILE,
+ "transformer/config.json",
+ "vae/*",
+ "tokenizer/*",
+ "processor/*",
+)
+H3_IMAGE_DENSE_DIT_PATTERNS = (PDD_HEADS_FILE, "transformer/*")
# "0" keeps the dense AdaLN projections (diagnostic: the table is the default and exact to the dense math).
ADALN_TABLE_ENV = "UNSLOTH_H3_IMAGE_ADALN_TABLE"
@@ -1690,6 +1700,13 @@ def _hub_files(
return Path(root)
+def _native_layout(root: Path, native: str, converted: str) -> bool:
+ """True to read ``root/native``: whenever it is there, else only when no converted copy is."""
+ return (root / native / "config.json").is_file() or not (
+ root / converted / "config.json"
+ ).is_file()
+
+
def _read_json(path: Path) -> dict:
with open(path, "r", encoding = "utf-8") as f:
return json.load(f)
@@ -1856,9 +1873,13 @@ def resolve_dit_scheme(
vram_gb: Optional[float],
width: int = 2048,
height: int = 2048,
+ host_gb: Optional[float] = None,
+ te_gb: Optional[float] = None,
+ inflight: int = 1,
) -> tuple[Optional[str], str]:
"""(scheme or None for bf16, reason). Auto: bf16 when the table-form bf16 DiT fits the card beside its working
- set, else int8. fp8 needs SM 8.9+ (falls back to int8 elsewhere)."""
+ set, else int8. With ``te_gb``, bf16 must also stay resident beside the encoder (48 GB cards go int8).
+ fp8 needs SM 8.9+ (else int8)."""
import torch
req = (requested or "auto").strip().lower()
@@ -1885,7 +1906,30 @@ def resolve_dit_scheme(
return "int8", "int8 requested"
need = H3_IMAGE_DIT_TABLE_BF16_GB + activation_gb(width, height) + 1.5
if vram_gb is not None and vram_gb >= need:
- return None, f"auto: bf16 DiT ({H3_IMAGE_DIT_TABLE_BF16_GB} GB) fits {vram_gb:.1f} GB"
+ if te_gb is None:
+ return None, f"auto: bf16 DiT ({H3_IMAGE_DIT_TABLE_BF16_GB} GB) fits {vram_gb:.1f} GB"
+ try:
+ placement = plan_placement(
+ vram_gb = vram_gb,
+ host_gb = host_gb,
+ dit_gb = dit_gb_for(None, adaln_table_enabled()),
+ te_gb = te_gb,
+ width = width,
+ height = height,
+ inflight = inflight,
+ ).placement
+ except RuntimeError: # no bf16 placement fits this host at all
+ placement = None
+ if placement in (PLACE_RESIDENT, PLACE_DIT_RESIDENT):
+ return (
+ None,
+ f"auto: bf16 DiT ({H3_IMAGE_DIT_TABLE_BF16_GB} GB) stays on {vram_gb:.1f} GB",
+ )
+ return (
+ "int8",
+ f"auto: beside the {te_gb:.1f} GB encoder the bf16 DiT would not stay on {vram_gb:.1f} GB "
+ f"({placement or 'no placement fits'}), int8 ConvRot",
+ )
return (
"int8",
f"auto: bf16 DiT would not fit {vram_gb if vram_gb is not None else 0:.1f} GB, int8 ConvRot",
@@ -1915,6 +1959,64 @@ def device_budgets(device: Any) -> tuple[Optional[float], Optional[float]]:
return vram, host
+def explicit_scheme_refusal(scheme: str, device: Any) -> Optional[str]:
+ """Why an explicit ``scheme`` cannot run as asked (resolve_dit_scheme would silently downgrade), or None."""
+ import torch
+
+ from .diffusion_precision import torchao_quantize_importable
+
+ if scheme not in QUANT_SCHEMES:
+ return (
+ f"MiniMax-H3-Image runs {' or '.join(QUANT_SCHEMES)} transformer weights, not {scheme}"
+ )
+ if not torchao_quantize_importable():
+ return (
+ "torchao is not importable on this install, and MiniMax-H3-Image's int8 and fp8 weights "
+ "need it"
+ )
+ dev = torch.device(device)
+ if scheme == "fp8" and dev.type == "cuda" and torch.cuda.is_available():
+ cap = tuple(torch.cuda.get_device_capability(dev))
+ if cap < (8, 9):
+ return f"fp8 needs compute capability 8.9 or newer, and this card is {cap[0]}.{cap[1]}; int8 runs here"
+ return None
+
+
+# Encoder requests that keep the bf16 encoder; any other value, unset included, takes the hosted int8 one.
+DENSE_TE_REQUESTS = frozenset({"none", "off", "bf16", "dense", "bfloat16"})
+
+
+def h3_image_te_scheme(requested: Optional[str]) -> Optional[str]:
+ """The encoder a load takes for the raw ``text_encoder_quant`` request: "int8" (hosted) or None (bf16)."""
+ return None if str(requested or "").strip().lower() in DENSE_TE_REQUESTS else "int8"
+
+
+def planned_dit_scheme(
+ transformer_quant: Optional[str],
+ device: Any,
+ text_encoder_quant: Optional[str] = None,
+ reclaimable_host_gb: float = 0.0,
+) -> Optional[str]:
+ """DiT scheme for the download plan. The load evicts chat and the resident model first, so plan the whole card
+ plus ``reclaimable_host_gb``; budget env vars still win."""
+ import torch
+
+ dev = torch.device(device)
+ vram, host = device_budgets(dev)
+ if not os.environ.get(VRAM_BUDGET_ENV) and dev.type == "cuda" and torch.cuda.is_available():
+ vram = torch.cuda.mem_get_info(dev)[1] / 1e9
+ if host is not None and not os.environ.get(HOST_BUDGET_ENV):
+ host += max(0.0, float(reclaimable_host_gb))
+ return resolve_dit_scheme(
+ transformer_quant,
+ device = dev,
+ vram_gb = vram,
+ host_gb = host,
+ te_gb = te_gb_for(h3_image_te_scheme(text_encoder_quant)),
+ inflight = stream_inflight() if dev.type == "cuda" else 1,
+ )[0]
+
+
def build_transformer_skeleton(config: dict, *, table_grid: Optional[Sequence[float]]) -> Any:
"""Meta-device model (buffers real), with the AdaLN table structure installed when ``table_grid`` is set."""
from accelerate import init_empty_weights
@@ -2182,8 +2284,7 @@ def load_h3_image_transformer(
from safetensors import safe_open
check = check_cancelled or (lambda: None)
- converted_dir = root / DIFFUSERS_TRANSFORMER_SUBFOLDER
- native = not (converted_dir / "config.json").is_file()
+ native = _native_layout(root, "transformer", DIFFUSERS_TRANSFORMER_SUBFOLDER)
tdir = root / ("transformer" if native else DIFFUSERS_TRANSFORMER_SUBFOLDER)
raw_config = _read_json(tdir / "config.json")
if native:
@@ -2289,8 +2390,7 @@ def load_h3_image_vae(root: Path, *, dtype: Any = None) -> Any:
from accelerate import init_empty_weights
from safetensors import safe_open
- converted_dir = root / DIFFUSERS_VAE_SUBFOLDER
- native = not (converted_dir / "config.json").is_file()
+ native = _native_layout(root, "vae", DIFFUSERS_VAE_SUBFOLDER)
vdir = root / ("vae" if native else DIFFUSERS_VAE_SUBFOLDER)
raw = _read_json(vdir / "config.json")
config = (
@@ -2642,16 +2742,7 @@ def load_minimax_h3_image_pipeline(
dtype = dtype or torch.bfloat16
device = torch.device(device)
vram, host = device_budgets(device)
- patterns = [
- "model_index.json",
- PDD_CONFIG_FILE,
- "transformer/config.json",
- "vae/*",
- "tokenizer/*",
- "processor/*",
- f"{DIFFUSERS_TRANSFORMER_SUBFOLDER}/config.json",
- f"{DIFFUSERS_VAE_SUBFOLDER}/*",
- ]
+ patterns = list(H3_IMAGE_BASE_PATTERNS)
hub = {"hf_token": hf_token, "cache_dir": cache_dir, "local_files_only": local_files_only}
root = _hub_files(repo_id, patterns, **hub)
check()
@@ -2666,10 +2757,18 @@ def load_minimax_h3_image_pipeline(
):
te_repo = te_entry[2].get("pretrained_model_name_or_path")
te_repo = te_repo or H3_IMAGE_TEXT_ENCODER_REPO
+ te_scheme = "int8" if (text_encoder_quant or "").strip().lower() == "int8" else None
+ inflight = stream_inflight() if device.type == "cuda" else 1
scheme, scheme_reason = resolve_dit_scheme(
- transformer_quant, device = device, vram_gb = vram, width = plan_width, height = plan_height
+ transformer_quant,
+ device = device,
+ vram_gb = vram,
+ width = plan_width,
+ height = plan_height,
+ host_gb = host,
+ te_gb = te_gb_for(te_scheme) if text_encoder is None else _module_gb(text_encoder),
+ inflight = inflight,
)
- te_scheme = "int8" if (text_encoder_quant or "").strip().lower() == "int8" else None
table = adaln_table_enabled()
plan_args = {
"vram_gb": vram if device.type == "cuda" else None,
@@ -2678,7 +2777,7 @@ def load_minimax_h3_image_pipeline(
"width": plan_width,
"height": plan_height,
"forced": (os.environ.get(PLACEMENT_ENV) or "").strip().lower() or None,
- "inflight": stream_inflight() if device.type == "cuda" else 1,
+ "inflight": inflight,
}
plan = plan_placement(
te_gb = te_gb_for(te_scheme) if text_encoder is None else _module_gb(text_encoder),
@@ -2719,11 +2818,7 @@ def load_minimax_h3_image_pipeline(
"dense_conditioning_linears": densified,
}
if transformer is None:
- root = _hub_files(
- repo_id,
- [PDD_HEADS_FILE, "transformer/*", f"{DIFFUSERS_TRANSFORMER_SUBFOLDER}/*"],
- **hub,
- )
+ root = _hub_files(repo_id, H3_IMAGE_DENSE_DIT_PATTERNS, **hub)
transformer, stats = load_h3_image_transformer(
root,
dtype = dtype,
@@ -2776,7 +2871,12 @@ def load_minimax_h3_image_pipeline(
)
local_te = root / "text_encoder"
- if text_encoder is None and (local_te / "config.json").is_file():
+ # Local folders only: a Hub snapshot may hold the unplanned bundled bf16 copy.
+ if (
+ text_encoder is None
+ and os.path.isdir(str(repo_id))
+ and (local_te / "config.json").is_file()
+ ):
local_gb = sum(f.stat().st_size for f in local_te.glob("*.safetensors")) / 1e9
if local_gb > plan.te_gb + 1.0:
_encoder_fits(local_gb, "the text encoder in this model folder")
diff --git a/studio/backend/core/inference/generate_image_tool.py b/studio/backend/core/inference/generate_image_tool.py
index 454dc021295..82f9f548272 100644
--- a/studio/backend/core/inference/generate_image_tool.py
+++ b/studio/backend/core/inference/generate_image_tool.py
@@ -13,6 +13,8 @@ import shutil
import time
from typing import Any, Optional
+from .diffusion_conditioning import MAX_REQUEST_SIDE
+
logger = logging.getLogger(__name__)
GENERATE_IMAGE_TOOL_NAME = "generate_image"
@@ -45,7 +47,7 @@ _POLL_S = 0.25
_PROMPT_ECHO_CHARS = 300
_MIN_SIDE = 256
# DiffusionGenerateRequest's own ceiling.
-_TRANSPORT_MAX_SIDE = 2752
+_TRANSPORT_MAX_SIDE = MAX_REQUEST_SIDE
def _size_limits(status: dict) -> tuple[int, int, int, int]:
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 6a2ea1178e2..c096e05326b 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -26,6 +26,7 @@ from pydantic import (
)
from core.inference.audio_workflows import status_audio_workflows
+from core.inference.diffusion_conditioning import MAX_REQUEST_SIDE
from core.inference.llama_server_args import (
BATCH_MAX,
BATCH_MIN,
@@ -5307,17 +5308,16 @@ class DiffusionGenerateRequest(BaseModel):
negative_prompt: Optional[str] = Field(
None, description = "What to avoid (if the model supports it)"
)
- # Transport ceiling = the largest 2K preset side; the loaded family enforces its own bounds and grid.
width: int = Field(
1024,
ge = 256,
- le = 2752,
+ le = MAX_REQUEST_SIDE,
description = "Image width in pixels (multiple of 16; the loaded model may require more)",
)
height: int = Field(
1024,
ge = 256,
- le = 2752,
+ le = MAX_REQUEST_SIDE,
description = "Image height in pixels (multiple of 16; the loaded model may require more)",
)
steps: int = Field(
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 3ae30a5b9a1..e5e1e733ec8 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -55,6 +55,7 @@ from hub.utils.hf_tokens import (
from routes.provider_credentials import current_credential_write, require_ui_session
from storage import credential_secrets
+from core.inference.diffusion_conditioning import MAX_REQUEST_SIDE
from core.rag.config import (
default_gguf_repo,
effective_gguf_repo_for_embedding_model,
@@ -283,8 +284,8 @@ class ImageGenerationPresetParams(BaseModel):
model_config = ConfigDict(extra = "forbid")
negativePrompt: str = ""
- width: int = Field(default = 1024, ge = 256, le = 2752, multiple_of = 16)
- height: int = Field(default = 1024, ge = 256, le = 2752, multiple_of = 16)
+ width: int = Field(default = 1024, ge = 256, le = MAX_REQUEST_SIDE, multiple_of = 16)
+ height: int = Field(default = 1024, ge = 256, le = MAX_REQUEST_SIDE, multiple_of = 16)
steps: int = Field(default = 9, ge = 1, le = 100)
guidance: float = Field(default = 0, ge = 0, le = 20)
batchSize: int = Field(default = 1, ge = 1, le = 32)
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 86291a7e5f2..aea0b2ac083 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -8601,6 +8601,125 @@ def test_download_plan_pipeline_kind_is_one_entry(monkeypatch):
assert "text_encoder/model.fp16.safetensors" not in files
+_H3_IMAGE_SIBLINGS = [
+ _FakeSibling("model_index.json", 900),
+ _FakeSibling("pdd_config.json", 200),
+ _FakeSibling("pdd_fused_heads.safetensors", 12 * 10**6),
+ _FakeSibling("transformer/config.json", 900),
+ _FakeSibling("transformer/model-00001-of-00002.safetensors", 33 * GB),
+ _FakeSibling("transformer/model-00002-of-00002.safetensors", 33 * GB),
+ _FakeSibling("transformer_diffusers/config.json", 900),
+ _FakeSibling(
+ "transformer_diffusers/diffusion_pytorch_model-00001-of-00002.safetensors", 33 * GB
+ ),
+ _FakeSibling("text_encoder/config.json", 900),
+ _FakeSibling("text_encoder/model-00001-of-00002.safetensors", 33 * GB),
+ _FakeSibling("vae/config.json", 900),
+ _FakeSibling("vae/diffusion_pytorch_model.safetensors", 2 * GB),
+ _FakeSibling("vae_diffusers/diffusion_pytorch_model.safetensors", 2 * GB),
+ _FakeSibling("tokenizer/tokenizer.json", 11 * 10**6),
+ _FakeSibling("processor/preprocessor_config.json", 900),
+]
+_H3_TE_INT8 = "text_encoders/official/qwen3vl_32b_minimax_h3_int8_convrot.safetensors"
+
+
+_H3_ENCODER_REPOS = {
+ "unsloth/MiniMax-H3-FP8": [
+ _FakeSibling(_H3_TE_INT8, 27 * GB),
+ _FakeSibling("other.gguf", GB),
+ ],
+ "MiniMaxAI/MiniMax-H3": [
+ _FakeSibling("text_encoder/config.json", 900),
+ _FakeSibling("text_encoder/model-00001-of-00002.safetensors", 33 * GB),
+ _FakeSibling("transformer/model.safetensors", 70 * GB),
+ ],
+}
+
+
+def _h3_image_download_plan(monkeypatch, tmp_path, encoder_repos, te_request):
+ index = tmp_path / "model_index.json"
+ index.write_text(
+ json.dumps(
+ {
+ "_class_name": "MiniMaxH3ImagePipeline",
+ "processor": ["transformers", "Qwen3VLProcessor"],
+ "scheduler": None,
+ "text_encoder": [
+ "transformers",
+ "Qwen3VLForConditionalGeneration",
+ {
+ "pretrained_model_name_or_path": "MiniMaxAI/MiniMax-H3",
+ "subfolder": "text_encoder",
+ },
+ ],
+ "tokenizer": ["transformers", "Qwen2TokenizerFast"],
+ "transformer": ["diffusers", "MiniMaxH3DiTModel"],
+ "vae": ["diffusers", "AutoencoderKLMiniMaxH3"],
+ }
+ )
+ )
+ monkeypatch.setattr("huggingface_hub.hf_hub_download", lambda *a, **k: str(index))
+ _fake_hf_api(monkeypatch, {"MiniMaxAI/MiniMax-H3-Image": _H3_IMAGE_SIBLINGS, **encoder_repos})
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_h3_image_planned_dit_scheme",
+ lambda self, *a, **k: None,
+ raising = False,
+ )
+ return DiffusionBackend().download_plan(
+ "MiniMaxAI/MiniMax-H3-Image", model_kind = "pipeline", text_encoder_quant = te_request
+ )
+
+
[email protected]("te_request", [None, "none"])
+def test_download_plan_for_minimax_h3_image_stages_the_encoder_its_loader_opens(
+ monkeypatch, tmp_path, te_request
+):
+ """The plan never stages the bundled 66.7 GB text_encoder/ or the *_diffusers/ copy."""
+ plan = _h3_image_download_plan(monkeypatch, tmp_path, _H3_ENCODER_REPOS, te_request)
+ assert plan["plan_failed"] is False
+ by_repo = {e["repo_id"]: e["files"] for e in plan["entries"]}
+ image = by_repo["MiniMaxAI/MiniMax-H3-Image"]
+ assert not [f for f in image if f.startswith("text_encoder/") and f.endswith(".safetensors")]
+ assert not [f for f in image if "_diffusers/" in f]
+ assert "transformer/model-00001-of-00002.safetensors" in image
+ if te_request is None:
+ assert by_repo["unsloth/MiniMax-H3-FP8"] == [_H3_TE_INT8]
+ # int8 encoder is built from the H3 repo's config.
+ assert by_repo["MiniMaxAI/MiniMax-H3"] == ["text_encoder/config.json"]
+ else:
+ assert "unsloth/MiniMax-H3-FP8" not in by_repo
+ assert by_repo["MiniMaxAI/MiniMax-H3"] == [
+ "text_encoder/config.json",
+ "text_encoder/model-00001-of-00002.safetensors",
+ ]
+
+
+ "te_request, encoder_repos",
+ [
+ (
+ None,
+ {
+ "unsloth/MiniMax-H3-FP8": [_FakeSibling("other.gguf", GB)],
+ "MiniMaxAI/MiniMax-H3": [_FakeSibling("text_encoder/config.json", 900)],
+ },
+ ),
+ (None, {"unsloth/MiniMax-H3-FP8": _H3_ENCODER_REPOS["unsloth/MiniMax-H3-FP8"]}),
+ ("none", {}),
+ ],
+)
+def test_download_plan_for_minimax_h3_image_flags_an_encoder_it_could_not_list(
+ monkeypatch, tmp_path, te_request, encoder_repos
+):
+ """An unfound encoder must set plan_failed, not read as "nothing missing"."""
+ plan = _h3_image_download_plan(monkeypatch, tmp_path, encoder_repos, te_request)
+ assert plan["plan_failed"] is True
+ staged = [f for e in plan["entries"] for f in e["files"]]
+ assert not [f for f in staged if f.startswith("text_encoder/") and f.endswith(".safetensors")]
+ assert _H3_TE_INT8 not in staged or "text_encoder/config.json" not in staged
+
+
def test_download_plan_flags_a_mirrored_pipeline_as_the_checkpoint(monkeypatch):
# Gated pipelines stage from the mirror, so only the planner can flag the selected model.
gated = "black-forest-labs/FLUX.1-dev"
diff --git a/studio/backend/tests/test_diffusion_minimax_h3_image.py b/studio/backend/tests/test_diffusion_minimax_h3_image.py
index 361dfdae04f..43feea69ec1 100644
--- a/studio/backend/tests/test_diffusion_minimax_h3_image.py
+++ b/studio/backend/tests/test_diffusion_minimax_h3_image.py
@@ -557,6 +557,68 @@ def test_auto_scheme_is_bf16_only_when_it_fits(h3i, monkeypatch):
assert h3i.resolve_dit_scheme(None, device = "cuda", vram_gb = 95.0)[0] is None
+ "vram, host, scheme",
+ [
+ # 48 GB: bf16 beside the encoder would go sequential (refused under ~74 GB RAM).
+ (48.2, 72.0, "int8"),
+ (48.2, 128.0, "int8"),
+ (80.0, 64.0, None),
+ (190.0, 1500.0, None),
+ ],
+)
+def test_auto_takes_bf16_only_when_it_stays_on_the_card_beside_the_encoder(h3i, vram, host, scheme):
+ pytest.importorskip("torchao")
+ te = h3i.te_gb_for("int8")
+ got, reason = h3i.resolve_dit_scheme(None, device = "cuda", vram_gb = vram, host_gb = host, te_gb = te)
+ assert got == scheme, reason
+ assert h3i.resolve_dit_scheme(None, device = "cuda", vram_gb = vram)[0] is None
+
+
+def test_the_plan_sizes_the_encoder_the_request_takes(h3i, monkeypatch):
+ seen = []
+ monkeypatch.setattr(
+ h3i, "resolve_dit_scheme", lambda req, **kw: seen.append(kw["te_gb"]) or (None, "x")
+ )
+ h3i.planned_dit_scheme(None, "cpu")
+ h3i.planned_dit_scheme(None, "cpu", "none")
+ assert seen == [h3i.H3_IMAGE_TE_INT8_GB, h3i.H3_IMAGE_TE_BF16_GB]
+
+
+def test_the_plan_credits_host_memory_the_unload_frees(h3i, monkeypatch):
+ """Host RAM held by the resident model is credited back, since the load unloads it first."""
+ pytest.importorskip("torchao")
+ import torch
+
+ monkeypatch.delenv(h3i.VRAM_BUDGET_ENV, raising = False)
+ monkeypatch.delenv(h3i.HOST_BUDGET_ENV, raising = False)
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
+ monkeypatch.setattr(h3i, "device_budgets", lambda dev: (80.0, 20.0))
+ assert h3i.planned_dit_scheme(None, "cuda") == "int8"
+ assert h3i.planned_dit_scheme(None, "cuda", reclaimable_host_gb = 44.0) is None
+ monkeypatch.setenv(h3i.HOST_BUDGET_ENV, "20")
+ assert h3i.planned_dit_scheme(None, "cuda", reclaimable_host_gb = 44.0) == "int8"
+
+
+def test_the_backend_plan_passes_the_resident_pipeline_host_memory(h3i, monkeypatch):
+ import types
+
+ from core.inference import diffusion as dmod
+
+ seen = []
+ monkeypatch.setattr(
+ h3i, "planned_dit_scheme", lambda *a, **kw: seen.append(kw["reclaimable_host_gb"])
+ )
+ monkeypatch.setattr(dmod, "pipeline_host_mib", lambda pipe: 4096 if pipe == "resident" else 0)
+ backend = dmod.DiffusionBackend()
+ monkeypatch.setattr(
+ backend, "_target_for_ordinal", lambda fam, ordinal: types.SimpleNamespace(device = "cpu")
+ )
+ backend._state = types.SimpleNamespace(pipe = "resident")
+ backend._h3_image_planned_dit_scheme(None, None, None)
+ assert seen == [pytest.approx(4096 * 2**20 / 1e9)]
+
+
def test_streamer_runs_blocks_from_the_host(h3i):
import torch
@@ -1309,3 +1371,209 @@ def test_hosted_metadata_attention_is_recorded(h3i):
t = types.SimpleNamespace()
h3i.h3_image_prepare_prequant_model()(t, {"attention": "INT8"})
assert getattr(t, h3i.CHECKPOINT_ATTENTION_ATTR) == "int8"
+
+
+def test_a_hub_snapshot_never_loads_the_bundled_encoder_or_the_converted_copy(
+ h3i, release, tmp_path, monkeypatch
+):
+ """A Hub load skips the bundled encoder and *_diffusers/ copy, even if a snapshot already holds them."""
+ import copy
+
+ import transformers
+
+ root, _ref, te = release
+ snap = _release_copy(root, tmp_path / "snap", with_encoder = False)
+ te.save_pretrained(str(snap / "text_encoder"))
+ fetched = []
+ monkeypatch.setattr(
+ h3i, "_hub_files", lambda repo, patterns, **kw: fetched.extend(patterns) or snap
+ )
+ loaded = []
+ monkeypatch.setattr(
+ h3i,
+ "load_h3_image_text_encoder",
+ lambda scheme, **kw: loaded.append(scheme) or (copy.deepcopy(te), scheme),
+ )
+
+ def _no_local_encoder(*a, **k):
+ raise AssertionError(f"the bundled encoder was loaded: {a}")
+
+ monkeypatch.setattr(
+ transformers.Qwen3VLForConditionalGeneration, "from_pretrained", _no_local_encoder
+ )
+ pipe = h3i.load_minimax_h3_image_pipeline(
+ h3i.H3_IMAGE_BASE_REPO, device = "cpu", text_encoder_quant = "int8"
+ )
+ assert pipe._unsloth_h3_report.te_scheme == "int8"
+ assert loaded in ([], ["int8"])
+ assert not [p for p in fetched if "text_encoder" in p or "_diffusers" in p]
+ assert "transformer/*" in fetched
+ pipe.release()
+
+
+def test_a_local_folder_still_brings_its_own_encoder(h3i, release, tmp_path, monkeypatch):
+ import transformers
+
+ root, _ref, te = release
+ rel = _release_copy(root, tmp_path / "rel", with_encoder = False)
+ te.save_pretrained(str(rel / "text_encoder"))
+ monkeypatch.setattr(
+ h3i,
+ "load_h3_image_text_encoder",
+ lambda *a, **k: (_ for _ in ()).throw(AssertionError("the hosted encoder was fetched")),
+ )
+ sized = _bf16_sized(h3i, monkeypatch, transformers.Qwen3VLForConditionalGeneration)
+ pipe = h3i.load_minimax_h3_image_pipeline(str(rel), device = "cpu", text_encoder_quant = "int8")
+ assert pipe._unsloth_h3_report.te_scheme is None
+ assert sized[-1] == h3i.H3_IMAGE_TE_BF16_GB
+ pipe.release()
+
+
+ "native, converted, reads_native",
+ [(True, True, True), (True, False, True), (False, True, False), (False, False, True)],
+)
+def test_the_native_layout_wins_when_both_are_present(
+ h3i, tmp_path, native, converted, reads_native
+):
+ for name, present in (("transformer", native), ("transformer_diffusers", converted)):
+ if present:
+ (tmp_path / name).mkdir()
+ (tmp_path / name / "config.json").write_text("{}")
+ assert h3i._native_layout(tmp_path, "transformer", "transformer_diffusers") is reads_native
+
+
+ "request_value, scheme",
+ [
+ (None, "int8"),
+ ("", "int8"),
+ ("auto", "int8"),
+ ("int8", "int8"),
+ ("none", None),
+ ("Off", None),
+ ("bf16", None),
+ ],
+)
+def test_the_encoder_scheme_follows_the_raw_request(h3i, request_value, scheme):
+ assert h3i.h3_image_te_scheme(request_value) == scheme
+
+
+def test_explicit_dit_schemes_are_honored_or_refused(h3i, monkeypatch):
+ import torch
+
+ from core.inference import diffusion_precision
+
+ monkeypatch.setattr(diffusion_precision, "torchao_quantize_importable", lambda: True)
+ assert h3i.explicit_scheme_refusal("int8", "cpu") is None
+ assert h3i.explicit_scheme_refusal("fp8", "cpu") is None
+ assert "not nvfp4" in h3i.explicit_scheme_refusal("nvfp4", "cpu")
+ assert "not mxfp8" in h3i.explicit_scheme_refusal("mxfp8", "cpu")
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
+ monkeypatch.setattr(torch.cuda, "get_device_capability", lambda dev = None: (8, 0))
+ assert "8.9 or newer" in h3i.explicit_scheme_refusal("fp8", "cuda")
+ assert h3i.explicit_scheme_refusal("int8", "cuda") is None
+ monkeypatch.setattr(torch.cuda, "get_device_capability", lambda dev = None: (8, 9))
+ assert h3i.explicit_scheme_refusal("fp8", "cuda") is None
+
+
+def test_the_plan_scheme_plans_the_whole_card(h3i, monkeypatch):
+ """The plan uses the whole card (the load evicts chat first); a VRAM budget still wins."""
+ import torch
+
+ monkeypatch.delenv(h3i.VRAM_BUDGET_ENV, raising = False)
+ seen = []
+ monkeypatch.setattr(h3i, "device_budgets", lambda dev: (20.0, 500.0))
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
+ monkeypatch.setattr(torch.cuda, "mem_get_info", lambda dev = None: (20e9, 80e9))
+ monkeypatch.setattr(
+ h3i,
+ "resolve_dit_scheme",
+ lambda req, *, device, vram_gb, **kw: seen.append(vram_gb) or (None, "x"),
+ )
+ assert h3i.planned_dit_scheme(None, "cuda") is None
+ monkeypatch.setenv(h3i.VRAM_BUDGET_ENV, "24")
+ monkeypatch.setattr(h3i, "device_budgets", lambda dev: (24.0, 500.0))
+ h3i.planned_dit_scheme(None, "cuda")
+ assert seen == [pytest.approx(80.0), pytest.approx(24.0)]
+
+
[email protected]("scheme", ["int8", "fp8"])
+def test_the_preflight_passes_explicit_h3_schemes_without_a_compile(h3i, monkeypatch, scheme):
+ """int8 / fp8 bypass the torchao compile gate; other schemes are refused before eviction."""
+ from core.inference import diffusion as dmod
+ from core.inference.diffusion_device import resolve_diffusion_device_target
+ from core.inference.diffusion_families import detect_family_for_pick
+
+ from core.inference import diffusion_precision
+
+ fam = detect_family_for_pick("MiniMaxAI/MiniMax-H3-Image", None, None)
+ monkeypatch.setattr(dmod, "compile_eligible", lambda target, **kw: False)
+ monkeypatch.setattr(diffusion_precision, "torchao_quantize_importable", lambda: True)
+ backend = dmod.DiffusionBackend()
+ import dataclasses
+
+ target = dataclasses.replace(resolve_diffusion_device_target(), device = "cpu")
+ kwargs = {"model_kind": "pipeline", "te_mode": None, "memory_mode": None, "cpu_offload": False}
+ backend._assert_precision_for_target(fam, target, pinned = scheme, **kwargs)
+ with pytest.raises(RuntimeError, match = "MiniMax-H3-Image runs int8 or fp8"):
+ backend._assert_precision_for_target(fam, target, pinned = "mxfp8", **kwargs)
+
+
[email protected]("scheme", ["int8", "fp8"])
+def test_an_explicit_scheme_without_torchao_is_refused_not_run_as_bf16(h3i, monkeypatch, scheme):
+ """Without torchao an explicit int8 / fp8 is refused, not silently run as bf16."""
+ import dataclasses
+
+ from core.inference import diffusion as dmod
+ from core.inference import diffusion_precision
+ from core.inference.diffusion_device import resolve_diffusion_device_target
+ from core.inference.diffusion_families import detect_family_for_pick
+
+ monkeypatch.setattr(diffusion_precision, "torchao_quantize_importable", lambda: False)
+ assert "torchao is not importable" in h3i.explicit_scheme_refusal(scheme, "cpu")
+ fam = detect_family_for_pick("MiniMaxAI/MiniMax-H3-Image", None, None)
+ target = dataclasses.replace(resolve_diffusion_device_target(), device = "cpu")
+ with pytest.raises(RuntimeError, match = "torchao is not importable"):
+ dmod.DiffusionBackend()._assert_precision_for_target(
+ fam,
+ target,
+ model_kind = "pipeline",
+ pinned = scheme,
+ te_mode = None,
+ memory_mode = None,
+ cpu_offload = False,
+ )
+
+
+def test_a_dit_scheme_the_plan_cannot_settle_marks_the_plan_partial(h3i, monkeypatch):
+ from core.inference import diffusion as dmod
+ from core.inference.diffusion_families import detect_family_for_pick
+
+ def _broken(*a, **k):
+ raise RuntimeError("no device answer")
+
+ monkeypatch.setattr(h3i, "planned_dit_scheme", _broken)
+ fam = detect_family_for_pick("MiniMaxAI/MiniMax-H3-Image", None, None)
+ failures = []
+ assert dmod.DiffusionBackend()._h3_image_planned_dit_scheme(fam, None, None, failures) is None
+ assert [str(e) for e in failures] == ["no device answer"]
+ monkeypatch.setattr(h3i, "planned_dit_scheme", lambda *a, **k: "int8")
+ failures.clear()
+ assert dmod.DiffusionBackend()._h3_image_planned_dit_scheme(fam, None, None, failures) == "int8"
+ assert failures == []
+
+
+def test_the_request_ceiling_admits_every_family_side(h3i):
+ """The request used to cap sides at 2752, rejecting every 16 MP size."""
+ from pydantic import ValidationError
+
+ from core.inference.diffusion_conditioning import MAX_REQUEST_SIDE
+ from core.inference.diffusion_families import _FAMILIES
+ from models.inference import DiffusionGenerateRequest
+
+ assert MAX_REQUEST_SIDE == max(int(f.max_output_side) for f in _FAMILIES)
+ for width, height in h3i.H3_IMAGE_16MP_SIZES:
+ DiffusionGenerateRequest(prompt = "x", width = width, height = height)
+ with pytest.raises(ValidationError):
+ DiffusionGenerateRequest(prompt = "x", width = MAX_REQUEST_SIDE + 16, height = 1024)
diff --git a/studio/backend/tests/test_diffusion_routes.py b/studio/backend/tests/test_diffusion_routes.py
index 13742ce4b6a..205862f1bec 100644
--- a/studio/backend/tests/test_diffusion_routes.py
+++ b/studio/backend/tests/test_diffusion_routes.py
@@ -2954,8 +2954,12 @@ def test_generate_schema_bounds_for_unified_editing(client):
ten = _post_generate(client, prompt = "p", init_image = "QUJD", reference_images = ["QUJD"] * 10)
assert ten.status_code == 422
assert _post_generate(client, prompt = "p", workflow = "inpaint").status_code == 422
+ # The transport ceiling admits every family's largest side; the loaded family enforces its own.
+ from core.inference.diffusion_conditioning import MAX_REQUEST_SIDE
+
assert _post_generate(client, prompt = "p", width = 2752, height = 1536).status_code == 200
- assert _post_generate(client, prompt = "p", width = 2768).status_code == 422
+ assert _post_generate(client, prompt = "p", width = MAX_REQUEST_SIDE).status_code == 200
+ assert _post_generate(client, prompt = "p", width = MAX_REQUEST_SIDE + 16).status_code == 422
bad_mode = _post_generate(client, prompt = "p", localized_edit = {"mode": "lasso", "image": "QUJD"})
assert bad_mode.status_code == 422
diff --git a/studio/backend/tests/test_media_generation_preset_settings.py b/studio/backend/tests/test_media_generation_preset_settings.py
index 11394d39ac9..0ffeac4e0cd 100644
--- a/studio/backend/tests/test_media_generation_preset_settings.py
+++ b/studio/backend/tests/test_media_generation_preset_settings.py
@@ -417,6 +417,7 @@ def test_preset_bounds_match_the_generation_request(monkeypatch):
{"steps": 500},
{"guidance": 100},
{"width": 8192},
+ {"width": 6288},
{"height": 64},
{"width": 257},
{"height": 257},
@@ -428,7 +429,15 @@ def test_preset_bounds_match_the_generation_request(monkeypatch):
).status_code
== 422
), params
- for params in ({"steps": 100}, {"guidance": 20}, {"width": 2048}, {"height": 256}):
+ # MiniMax-H3-Image 16 MP sizes.
+ for params in (
+ {"steps": 100},
+ {"guidance": 20},
+ {"width": 2048},
+ {"height": 256},
+ {"width": 6272},
+ {"height": 4096},
+ ):
assert (
client.put(
"/api/settings/generation-presets/image/custom",