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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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+@staticmethoddef _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: vfor 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_probeelse 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_COMPONENTSif 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.pyindex 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_000MIN_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 = 1024diff --git a/studio/backend/core/inference/diffusion_minimax_h3_image.py b/studio/backend/core/inference/diffusion_minimax_h3_image.pyindex 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 torchreq = (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.5if 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_opencheck = 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_weightsfrom 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.bfloat16device = 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 1scheme, 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 Nonetable = 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")) / 1e9if 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.pyindex 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 shutilimport timefrom 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_SIDEdef _size_limits(status: dict) -> tuple[int, int, int, int]:diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.pyindex 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_SIDEfrom 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.pyindex 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_sessionfrom storage import credential_secrets+from core.inference.diffusion_conditioning import MAX_REQUEST_SIDEfrom 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.pyindex 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.pyindex 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.pyindex 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 == 422assert _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 == 422bad_mode = _post_generate(client, prompt = "p", localized_edit = {"mode": "lasso", "image": "QUJD"})assert bad_mode.status_code == 422diff --git a/studio/backend/tests/test_media_generation_preset_settings.py b/studio/backend/tests/test_media_generation_preset_settings.pyindex 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",