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: opt-in MLX image engine for Apple Silicon (Z-Image) (#13379)

Daniel Han10bddef22e71
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 70f6cb8708e..545d0fa49bb 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -3385,7 +3385,7 @@ class DiffusionBackend:
# same predicate. Imported here, not at module import, because the router imports this module's siblings.
from .diffusion_engine_router import family_buildable_here
- if not family_buildable_here(fam, model_kind = kind):
+ if not family_buildable_here(fam, model_kind = kind, gguf_filename = gguf_filename):
assert_pipeline_class_available(fam.pipeline_class, fam.name)
# Whole-pipeline families take a GGUF only when it is whole too (stable-diffusion.cpp ``convert``).
if (
@@ -4819,6 +4819,7 @@ class DiffusionBackend:
text_encoder_quant: Optional[str] = None,
allow_device_probe: bool = True,
memory_verdict: bool = True,
+ discover_text_encoders: bool = True,
**load_kwargs: Any,
) -> dict[str, Any]:
"""The repos + exact files this pick needs, so the Hub download manager can fetch them with the
@@ -4837,6 +4838,7 @@ class DiffusionBackend:
verdict while training owns the GPU. It is not free: the pre-cast encoder and the DiT
prequant need a target to resolve, so clearing it also changes WHICH FILES the plan counts.
``memory_verdict=False`` suppresses only the oversized-unified-memory refusal.
+ ``discover_text_encoders=False`` keeps the base repo's encoder for an engine that never opens a single-file one.
"""
fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
kind = resolve_model_kind(gguf_filename, model_kind)
@@ -4859,7 +4861,11 @@ class DiffusionBackend:
fam, repo_id, gguf_filename, base, hf_token
) or speech_pick_refusal(repo_id, gguf_filename, hf_token)
component_overrides = None
- if not load_kwargs.get("text_encoder_files") and not load_kwargs.get("vae_file"):
+ if (
+ discover_text_encoders
+ and not load_kwargs.get("text_encoder_files")
+ and not load_kwargs.get("vae_file")
+ ):
# The same pick the load makes, so the plan stages no encoder the load will not open.
load_kwargs["text_encoder_files"] = (
self._comfy_text_encoders(
diff --git a/studio/backend/core/inference/diffusion_engine_router.py b/studio/backend/core/inference/diffusion_engine_router.py
index 46fdfea80d2..8b8d8c8c3d9 100644
--- a/studio/backend/core/inference/diffusion_engine_router.py
+++ b/studio/backend/core/inference/diffusion_engine_router.py
@@ -17,12 +17,22 @@ Env knobs:
UNSLOTH_DIFFUSION_SD_CPP_MPS=0|1 allow native on Apple MPS (default off)
UNSLOTH_DIFFUSION_SD_CPP_INSTALL=auto|0|1 allow lazy binary install (in sd_cpp_backend)
UNSLOTH_DIFFUSION_SD_CPP_DEVICE=nvidia[:N] run native on a card torch cannot see
+ UNSLOTH_DIFFUSION_MLX=0|1|auto opt in to the Apple Silicon MLX engine (default 0; auto
+ behaves like 0 until a real-Mac A/B against diffusers MPS
+ and sd.cpp Metal settles the default)
+
+The MLX engine (``mlx_diffusion_backend``) is considered only when UNSLOTH_DIFFUSION_MLX=1, on macOS 14+ on
+Apple Silicon, for a GGUF of a family that declares ``mlx_model_config`` in a quant the converter handles
+(Q4_0 / Q4_1 / Q8_0 / BF16 / F16), with ``mlx`` and ``mflux`` installed. Every refusal is recorded
+(``mlx_fallback_reason`` in the status) and falls through to the choice this module makes without it.
"""
from __future__ import annotations
import functools
+import importlib.util
import os
+import platform
import sys
import threading
from dataclasses import dataclass
@@ -31,6 +41,7 @@ from typing import Any, Callable, Optional
from core.inference.diffusion_device import resolve_diffusion_device_target
from core.inference.diffusion_families import (
DiffusionFamily,
+ family_mlx_supported,
family_pipeline_available,
family_sd_cpp_supported,
pipeline_available_family_names,
@@ -50,6 +61,7 @@ from core.inference.sd_cpp_backend import (
)
from core.inference.sd_cpp_engine import (
ENGINE_DIFFUSERS,
+ ENGINE_MLX,
ENGINE_SD_CPP,
SdCppEngine,
select_diffusion_engine,
@@ -162,6 +174,110 @@ _lock = threading.Lock()
_transition_lock = threading.Lock()
_active_engine_name: str = ENGINE_DIFFUSERS
_fallback_reason: Optional[str] = None
+_mlx_fallback_reason: Optional[str] = None
+
+_MLX_MIN_MACOS = (14, 0)
+
+
+def _mlx_requested() -> bool:
+ """``auto`` means off for now."""
+ return os.environ.get("UNSLOTH_DIFFUSION_MLX", "0").strip().lower() in _ENABLE_TOKENS
+
+
+def _mlx_host_refusal() -> Optional[str]:
+ if sys.platform != "darwin":
+ return "the MLX engine runs on macOS only"
+ if platform.machine().lower() not in ("arm64", "aarch64"):
+ return "the MLX engine needs Apple Silicon"
+ release = platform.mac_ver()[0]
+ try:
+ version = tuple(int(part) for part in release.split(".")[:2])
+ except ValueError:
+ version = ()
+ if not version or version < _MLX_MIN_MACOS:
+ return f"the MLX engine needs macOS 14 or newer (found {release or 'unknown'})"
+ return None
+
+
+# mflux's own darwin mlx range plus the light deps install_python_stack.py installs beside it (mflux goes in --no-deps).
+_MLX_RUNTIME_REQUIREMENTS: tuple[str, ...] = (
+ "mlx>=0.32.0,<0.33.0",
+ "piexif>=1.1.3,<2",
+ "platformdirs>=4,<5",
+ "toml>=0.10.2,<1",
+)
+
+
+def _installed_version(name: str) -> Optional[str]:
+ try:
+ from importlib.metadata import PackageNotFoundError, version
+ return version(name)
+ except (PackageNotFoundError, ValueError):
+ return None
+
+
+def _mlx_runtime_refusal() -> Optional[str]:
+ """find_spec and distribution metadata only: never import mlx / mflux here."""
+ missing = [name for name in ("mlx", "mflux") if importlib.util.find_spec(name) is None]
+ if missing:
+ return f"{' and '.join(missing)} not installed"
+ from core.inference.mlx_diffusion_convert import MFLUX_VERSION
+
+ try:
+ from packaging.requirements import Requirement
+ for spec in (f"mflux=={MFLUX_VERSION}", *_MLX_RUNTIME_REQUIREMENTS):
+ requirement = Requirement(spec)
+ installed = _installed_version(requirement.name)
+ if installed is None or not requirement.specifier.contains(installed, prereleases = True):
+ return f"the MLX engine needs {spec} (found {installed or 'none'})"
+ except Exception as exc: # noqa: BLE001 -- no packaging, or a version it cannot parse
+ return f"could not verify the MLX runtime versions ({exc})"
+ return None
+
+
+def mlx_selection(
+ fam: Optional[DiffusionFamily],
+ *,
+ model_kind: Optional[str],
+ gguf_filename: Optional[str],
+ backend: Optional[str] = None,
+) -> tuple[bool, Optional[str]]:
+ """``(use_mlx, refusal)``. Shared by selection and ``predict_engine`` so the download plan and the load
+ cannot disagree about MLX."""
+ if not _mlx_requested():
+ return False, None
+ forced = os.environ.get("UNSLOTH_DIFFUSION_ENGINE", "auto").strip().lower()
+ if forced in (ENGINE_DIFFUSERS, ENGINE_SD_CPP):
+ return False, f"UNSLOTH_DIFFUSION_ENGINE={forced} overrides UNSLOTH_DIFFUSION_MLX"
+ if model_kind and model_kind != "gguf":
+ return False, f"the MLX engine loads GGUF picks only (got {model_kind})"
+ if fam is None or not family_mlx_supported(fam):
+ name = getattr(fam, "name", None) or "unknown"
+ return False, f"family '{name}' has no MLX implementation"
+ from core.inference.mlx_diffusion_convert import quant_convertible
+
+ convertible, why = quant_convertible(gguf_filename)
+ if not convertible:
+ return False, why or "GGUF quant not convertible to MLX"
+ host = _mlx_host_refusal()
+ if host:
+ return False, host
+ if backend is None:
+ backend = resolve_diffusion_device_target().backend
+ if backend not in ("mps", "cpu"):
+ return False, f"device backend '{backend}' is not Apple MPS"
+ runtime = _mlx_runtime_refusal()
+ if runtime:
+ return False, runtime
+ return True, None
+
+
+def _note_mlx_refusal(reason: Optional[str]) -> None:
+ global _mlx_fallback_reason
+ with _lock:
+ _mlx_fallback_reason = reason
+ if reason:
+ logger.warning("UNSLOTH_DIFFUSION_MLX=1 but the MLX engine is not used: %s", reason)
def _engine_config() -> tuple[str, str, bool]:
@@ -177,6 +293,9 @@ def engine_for(name: str) -> Any:
if name == ENGINE_SD_CPP:
from core.inference.sd_cpp_backend import get_sd_cpp_backend
return get_sd_cpp_backend()
+ if name == ENGINE_MLX:
+ from core.inference.mlx_diffusion_backend import get_mlx_diffusion_backend
+ return get_mlx_diffusion_backend()
from core.inference.diffusion import get_diffusion_backend
return get_diffusion_backend()
@@ -187,16 +306,21 @@ def get_active_diffusion_engine() -> Any:
return engine_for(_active_engine_name)
+# (module, singleton attribute) of every image engine, read from sys.modules only.
+_ENGINE_SINGLETONS = (
+ ("core.inference.diffusion", "_diffusion_backend"),
+ ("core.inference.sd_cpp_backend", "_sd_cpp_backend"),
+ ("core.inference.mlx_diffusion_backend", "_mlx_diffusion_backend"),
+)
+
+
def cancel_generation_for_account(account_id: str) -> bool:
"""Stop an in-flight image generation owned by ``account_id``; True when one was signalled.
- Engines come from ``sys.modules`` (no import, no construction); both are checked because a
+ Engines come from ``sys.modules`` (no import, no construction); all are checked because a
deselected engine can still be draining."""
cancelled = False
- for module_name, attribute in (
- ("core.inference.diffusion", "_diffusion_backend"),
- ("core.inference.sd_cpp_backend", "_sd_cpp_backend"),
- ):
+ for module_name, attribute in _ENGINE_SINGLETONS:
module = sys.modules.get(module_name)
engine = getattr(module, attribute, None) if module is not None else None
if engine is None or engine._active_generate_account != account_id:
@@ -212,10 +336,7 @@ def retire_load_for_account(account_id: str) -> bool:
from hub.services.models.account_access import retire_media_load
retired = False
- for module_name, attribute in (
- ("core.inference.diffusion", "_diffusion_backend"),
- ("core.inference.sd_cpp_backend", "_sd_cpp_backend"),
- ):
+ for module_name, attribute in _ENGINE_SINGLETONS:
module = sys.modules.get(module_name)
engine = getattr(module, attribute, None) if module is not None else None
if retire_media_load("diffusion", account_id, engine):
@@ -263,6 +384,8 @@ def _activate(name: str, reason: Optional[str]) -> Any:
_fallback_reason = reason if name == ENGINE_DIFFUSERS else None
if name == ENGINE_SD_CPP:
logger.info("diffusion engine: sd_cpp")
+ elif name == ENGINE_MLX:
+ logger.info("diffusion engine: mlx")
else:
logger.info("diffusion engine: diffusers (%s)", reason or "selected")
return get_active_diffusion_engine()
@@ -305,6 +428,7 @@ def select_and_activate_engine(
model_kind: Optional[str] = None,
gpu_ordinal: Optional[int] = None,
before_fallback: Optional[Callable[[], None]] = None,
+ gguf_filename: Optional[str] = None,
) -> Any:
"""Pick + activate the engine for loading ``fam`` on this host; return the engine.
``before_fallback`` may raise to refuse a diffusers fallback before it unloads the resident model.
@@ -312,7 +436,14 @@ def select_and_activate_engine(
Falls back to diffusers (recording a reason) when the native route is disabled, the device has
a usable GPU, MPS is not enabled, the family has no native asset, or the binary is unavailable
-- always BEFORE the slow load, so a fallback never strands a half-native load.
+
+ With UNSLOTH_DIFFUSION_MLX=1 the MLX engine is tried first (``mlx_selection``, which needs
+ ``gguf_filename`` to judge the quant); a refusal is recorded and the choice below runs unchanged.
"""
+ use_mlx, mlx_refusal = mlx_selection(fam, model_kind = model_kind, gguf_filename = gguf_filename)
+ _note_mlx_refusal(mlx_refusal)
+ if use_mlx:
+ return _activate(ENGINE_MLX, None)
if model_kind and model_kind != "gguf":
return _activate(ENGINE_DIFFUSERS, f"non-GGUF load ({model_kind}) requires diffusers")
@@ -499,6 +630,7 @@ def predict_engine(
*,
model_kind: Optional[str] = None,
gpu_ordinal: Optional[int] = None,
+ gguf_filename: Optional[str] = None,
) -> str:
"""The engine a load of ``fam`` would select on this host, WITHOUT any side effect.
@@ -514,6 +646,8 @@ def predict_engine(
diffusers for the very first native load, when no binary is on disk yet) would mispredict the
common case: a fresh CPU host.
"""
+ if mlx_selection(fam, model_kind = model_kind, gguf_filename = gguf_filename)[0]:
+ return ENGINE_MLX
if model_kind and model_kind != "gguf":
return ENGINE_DIFFUSERS
@@ -545,7 +679,12 @@ def predict_engine(
)
-def family_buildable_here(fam: Optional[DiffusionFamily], *, model_kind: Optional[str]) -> bool:
+def family_buildable_here(
+ fam: Optional[DiffusionFamily],
+ *,
+ model_kind: Optional[str],
+ gguf_filename: Optional[str] = None,
+) -> bool:
"""True when THIS host can actually build ``fam`` for a ``model_kind`` load, by either engine.
The two engines need different things. diffusers instantiates ``fam.pipeline_class``, which the
@@ -566,6 +705,12 @@ def family_buildable_here(fam: Optional[DiffusionFamily], *, model_kind: Optiona
return False
if family_pipeline_available(fam):
return True
+ if model_kind == "gguf" and gguf_filename and family_mlx_supported(fam):
+ try:
+ if predict_engine(fam, model_kind = "gguf", gguf_filename = gguf_filename) == ENGINE_MLX:
+ return True
+ except Exception: # noqa: BLE001 -- a probe failure must not hide/refuse a usable model
+ pass
# only a GGUF can go native, and only for a family with the single-file assets sd.cpp needs
if model_kind != "gguf" or not family_sd_cpp_supported(fam):
return False
@@ -585,6 +730,7 @@ def annotate_status(status: dict[str, Any]) -> dict[str, Any]:
out = dict(status)
out["engine"] = _active_engine_name
out["fallback_reason"] = _fallback_reason
+ out["mlx_fallback_reason"] = _mlx_fallback_reason
out["supported_families"] = list(_supported_family_capabilities())
return out
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index 09d897f4444..92b8c5afd81 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -188,6 +188,9 @@ class DiffusionFamily:
# VAE latent-format override for sd-cli (--vae-format): "flux2" for FLUX.2, None otherwise
sd_cpp_vae_format: Optional[str] = None
sd_cpp_text_encoders: tuple[tuple[str, str, str], ...] = field(default_factory = tuple)
+ # mflux ModelConfig name (None = no MLX); ``_by_base`` maps a lowercase base repo to another config.
+ mlx_model_config: Optional[str] = None
+ mlx_model_config_by_base: tuple[tuple[str, str], ...] = field(default_factory = tuple)
# Family-specific sd-cli sampler settings so native output matches the model's supported invocation. None leaves
# sd-cli defaults.
sd_cpp_sampling_method: Optional[str] = None
@@ -660,6 +663,8 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
fp16_incompatible = True,
# The attention / FFN branches overflow float16 before their post-norm.
fp16_guard = "rescale_post_norm",
+ mlx_model_config = "z-image-turbo",
+ mlx_model_config_by_base = (("Tongyi-MAI/Z-Image", "z-image"),),
# Byte-identical mirror of Comfy-Org/z_image_turbo (AE + Qwen3-4B).
sd_cpp_vae = ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/vae/ae.safetensors"),
sd_cpp_text_encoders = (
@@ -2153,6 +2158,20 @@ def family_gguf_loadable(fam: DiffusionFamily) -> bool:
return not fam.single_file_is_pipeline and not fam.pipeline_only
+def family_mlx_supported(fam: Optional[DiffusionFamily]) -> bool:
+ return fam is not None and bool(getattr(fam, "mlx_model_config", None))
+
+
+def mlx_model_config_for(fam: DiffusionFamily, base_repo: Optional[str]) -> Optional[str]:
+ if not family_mlx_supported(fam):
+ return None
+ key = (base_repo or "").strip().lower()
+ for base, name in getattr(fam, "mlx_model_config_by_base", ()) or ():
+ if key == base.lower():
+ return name
+ return fam.mlx_model_config
+
+
def family_sd_cpp_supported(fam: DiffusionFamily) -> bool:
"""True when the family has the single-file VAE + text-encoder mapping sd.cpp needs; without it
the no-GPU route falls back to diffusers.
diff --git a/studio/backend/core/inference/media_locality.py b/studio/backend/core/inference/media_locality.py
index 9d58b581e6b..e186ed209a3 100644
--- a/studio/backend/core/inference/media_locality.py
+++ b/studio/backend/core/inference/media_locality.py
@@ -246,7 +246,7 @@ def planners_for(owner: str, pick: MediaModelPick) -> list:
if fam is None:
return [backend_for(owner)]
kind = resolve_model_kind(pick.gguf_filename, pick.model_kind)
- predicted = predict_engine(fam, model_kind = kind)
+ predicted = predict_engine(fam, model_kind = kind, gguf_filename = pick.gguf_filename)
names = [predicted]
if predicted == ENGINE_SD_CPP and not native_binary_installed():
names.append(ENGINE_DIFFUSERS)
diff --git a/studio/backend/core/inference/mlx_diffusion_backend.py b/studio/backend/core/inference/mlx_diffusion_backend.py
new file mode 100644
index 00000000000..7e229a5a610
--- /dev/null
+++ b/studio/backend/core/inference/mlx_diffusion_backend.py
@@ -0,0 +1,1356 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Opt-in MLX (mflux) image engine for Apple Silicon (``UNSLOTH_DIFFUSION_MLX=1``) on Studio's GGUF.
+
+Same duck-typed surface as the other image engines; selected only by ``diffusion_engine_router``.
+"""
+
+from __future__ import annotations
+
+import gc
+import json
+import os
+import random
+import subprocess
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+from core.inference.diffusion_families import (
+ DIFFUSION_CANCELLED_MSG,
+ DIFFUSION_NOT_LOADED_MSG,
+ DiffusionFamily,
+ DiffusionModelReplacedError,
+ LoadIdentity,
+ _is_local_path,
+ canonical_base,
+ detect_family_for_pick,
+ family_mlx_supported,
+ load_identity,
+ mirror_repo,
+ mlx_model_config_for,
+ named_variant_base,
+ prefer_ungated_mirror,
+ resolve_base_repo,
+ resolve_local_gguf_child,
+ supported_family_names,
+)
+from core.inference import mlx_diffusion_convert as convert
+from core.inference.diffusion_batched import SEED_MASK
+from loggers import get_logger
+from utils.account_context import account_thread, current_account_id
+from utils.gpu_memory_events import invalidates_gpu_memory as _invalidates_gpu_memory
+
+logger = get_logger(__name__)
+
+ENGINE_NAME = "mlx"
+
+BASE_ALLOW_PATTERNS = (
+ "text_encoder/*.safetensors",
+ "text_encoder/*.json",
+ "tokenizer/*",
+ "vae/*.safetensors",
+ "vae/*.json",
+)
+_LINKED_SUBDIRS = ("text_encoder", "tokenizer", "vae")
+_TE_GROUP_SIZE = 64
+_ENCODING_CACHE_SIZE = 8
+_LOW_RAM_BYTES = 16 * 1024**3
+
+
+class MlxCancelled(Exception):
+ """Raised in the mflux step callback to stop at the next step."""
+
+
+def clear_exception_locals(exc: Optional[BaseException]) -> None:
+ """Drop the locals of every finished frame in an exception chain, keeping the traceback text."""
+ import traceback
+
+ seen: set[int] = set()
+ while exc is not None and id(exc) not in seen:
+ seen.add(id(exc))
+ if exc.__traceback__ is not None:
+ traceback.clear_frames(exc.__traceback__)
+ exc = exc.__cause__ or exc.__context__
+
+
+def drop_exception_frames(exc: Optional[BaseException]) -> None:
+ """Clear frame locals along an exception chain: a retained traceback otherwise keeps the model alive."""
+ import traceback
+
+ seen: set[int] = set()
+ while exc is not None and id(exc) not in seen:
+ seen.add(id(exc))
+ if exc.__traceback__ is not None:
+ traceback.clear_frames(exc.__traceback__)
+ exc.__traceback__ = None
+ nxt = exc.__cause__ or exc.__context__
+ exc.__cause__ = None
+ exc.__context__ = None
+ exc = nxt
+
+
+def _total_ram_bytes() -> int:
+ try:
+ return int(os.sysconf("SC_PAGE_SIZE")) * int(os.sysconf("SC_PHYS_PAGES"))
+ except (AttributeError, ValueError, OSError):
+ return 0
+
+
+def _env_int(name: str, allowed: tuple[int, ...]) -> Optional[int]:
+ raw = os.environ.get(name, "").strip()
+ if not raw:
+ return None
+ try:
+ value = int(raw)
+ except ValueError:
+ logger.warning("%s=%r is not an integer; ignoring it", name, raw)
+ return None
+ if value not in allowed:
+ logger.warning("%s=%s is not one of %s; ignoring it", name, value, allowed)
+ return None
+ return value
+
+
+def text_encoder_bits(ram_bytes: Optional[int] = None) -> Optional[int]:
+ forced = _env_int("UNSLOTH_DIFFUSION_MLX_TE_BITS", (4, 8, 16))
+ if forced is not None:
+ return None if forced == 16 else forced
+ ram = _total_ram_bytes() if ram_bytes is None else ram_bytes
+ return 4 if 0 < ram <= _LOW_RAM_BYTES else 8
+
+
+def dense_bits(ram_bytes: Optional[int] = None) -> int:
+ forced = _env_int("UNSLOTH_DIFFUSION_MLX_DENSE_BITS", (0, 4, 8))
+ if forced is not None:
+ return forced
+ ram = _total_ram_bytes() if ram_bytes is None else ram_bytes
+ return 4 if 0 < ram <= _LOW_RAM_BYTES else 0
+
+
+def _chip_name() -> str:
+ try:
+ out = subprocess.run(
+ ["sysctl", "-n", "machdep.cpu.brand_string"],
+ capture_output = True,
+ text = True,
+ timeout = 5,
+ )
+ return (out.stdout or "").strip()
+ except Exception: # noqa: BLE001
+ return ""
+
+
+def compute_precision_name(chip: Optional[str] = None) -> str:
+ """M1 / M2 lack native bf16, so fp16 there."""
+ raw = os.environ.get("UNSLOTH_DIFFUSION_MLX_PRECISION", "auto").strip().lower()
+ if raw in ("fp16", "float16", "half"):
+ return "float16"
+ if raw in ("bf16", "bfloat16"):
+ return "bfloat16"
+ name = (chip if chip is not None else _chip_name()).lower()
+ return "float16" if ("apple m1" in name or "apple m2" in name) else "bfloat16"
+
+
+class MfluxRuntime:
+ """The only code that imports mlx / mflux. Tests replace it with a fake (``backend.runtime_factory``)."""
+
+ def build(
+ self, model_path: str, *, model_config: str, precision: str, te_bits: Optional[int]
+ ) -> Any:
+ import mlx.core as mx
+ import mlx.nn as nn
+ from mflux.models.common.config.model_config import ModelConfig
+ from mflux.models.z_image import ZImage
+
+ config = getattr(ModelConfig, model_config.replace("-", "_"))()
+ model = ZImage(
+ model_config = config,
+ model_path = model_path,
+ quantize = None,
+ compute_precision = mx.float16 if precision == "float16" else None,
+ )
+ if te_bits:
+
+ def _quantizable(_path, module):
+ weight = getattr(module, "weight", None)
+ return (
+ hasattr(module, "to_quantized")
+ and weight is not None
+ and weight.shape[-1] % _TE_GROUP_SIZE == 0
+ )
+
+ nn.quantize(
+ model.text_encoder,
+ group_size = _TE_GROUP_SIZE,
+ bits = te_bits,
+ class_predicate = _quantizable,
+ )
+ # Materialize in slices so peak memory stays near the quantized size, not the bf16 checkpoint.
+ from mlx.utils import tree_flatten
+
+ for component in (model.transformer, model.vae, model.text_encoder):
+ arrays = [a for _name, a in tree_flatten(component.parameters())]
+ for start in range(0, len(arrays), 32):
+ mx.eval(arrays[start : start + 32])
+ mx.eval(model.parameters())
+ return model
+
+ def generate(
+ self,
+ model: Any,
+ *,
+ prompt: str,
+ negative_prompt: Optional[str],
+ seed: int,
+ steps: int,
+ width: int,
+ height: int,
+ guidance: Optional[float],
+ on_step: Callable[[int], None],
+ ) -> Any:
+ import mlx.core as mx
+ from mflux.utils.exceptions import StopImageGenerationException
+
+ class _StepCallback:
+ def call_in_loop(self, t, seed, prompt, latents, config, time_steps): # noqa: ARG002
+ mx.eval(latents)
+ try:
+ on_step(int(t) + 1)
+ except MlxCancelled as exc:
+ raise StopImageGenerationException(str(exc)) from exc
+
+ callback = _StepCallback()
+ model.callbacks.register(callback)
+ cancelled = False
+ try:
+ result = model.generate_image(
+ seed = int(seed),
+ prompt = prompt,
+ negative_prompt = negative_prompt,
+ num_inference_steps = int(steps),
+ width = int(width),
+ height = int(height),
+ guidance = guidance,
+ )
+ except StopImageGenerationException as exc:
+ # The unwound mflux frames hold the model; uncleared, it survives unload().
+ drop_exception_frames(exc)
+ cancelled = True
+ except BaseException as exc:
+ # Same for a real failure, but keep the traceback for the caller's log.
+ clear_exception_locals(exc)
+ raise
+ finally:
+ try:
+ model.callbacks.in_loop.remove(callback)
+ except (AttributeError, ValueError):
+ pass
+ if cancelled:
+ raise MlxCancelled("cancelled")
+ return result.image
+
+ def cache_text_encodings(
+ self,
+ model: Any,
+ size: int = _ENCODING_CACHE_SIZE,
+ ) -> None:
+ original = model._encode_prompts
+ cache: OrderedDict = OrderedDict()
+
+ def _cached(*, prompt, negative_prompt, guidance):
+ cfg = float(guidance or 0.0) > 1.0
+ key = (prompt, negative_prompt if cfg else None, cfg)
+ if key in cache:
+ cache.move_to_end(key)
+ return cache[key]
+ value = original(prompt = prompt, negative_prompt = negative_prompt, guidance = guidance)
+ cache[key] = value
+ while len(cache) > size:
+ cache.popitem(last = False)
+ return value
+
+ model._encode_prompts = _cached
+
+ def free(self) -> None:
+ gc.collect()
+ try:
+ import mlx.core as mx
+ mx.clear_cache()
+ except Exception: # noqa: BLE001
+ pass
+
+ def supports_guidance(self, model: Any) -> bool:
+ return bool(getattr(getattr(model, "model_config", None), "supports_guidance", False))
+
+
+@dataclass
+class _MlxState:
+ repo_id: str
+ display_repo_id: Optional[str]
+ gguf_filename: str
+ base_repo: str
+ family: DiffusionFamily
+ model: Any
+ model_config: str
+ precision: str
+ te_bits: Optional[int]
+ dense_bits: int
+ convert_dir: str
+ timings: dict = field(default_factory = dict)
+
+
+@dataclass
+class _MlxLoading:
+ repo_id: str
+ base_repo: str
+ fetch_repo: Optional[str] = None
+ phase: str = "downloading"
+ downloaded_bytes: int = 0
+ expected_bytes: int = 0
+ fraction: float = 0.0
+ error: Optional[str] = None
+
+
+@dataclass
+class _MlxGen:
+ total_steps: int
+ step: int = 0
+ first_step_at: float = 0.0
+ eta_seconds: Optional[float] = None
+
+
+def _snapshot_revision(path: str) -> Optional[str]:
+ parts = Path(path).parts
+ if "snapshots" in parts:
+ index = parts.index("snapshots")
+ if index + 1 < len(parts):
+ return parts[index + 1]
+ return None
+
+
+def fetch_gguf(
+ repo_id: str,
+ gguf_filename: str,
+ hf_token: Optional[str],
+ *,
+ cancel_event: threading.Event,
+ local_files_only: bool,
+) -> str:
+ local_root = Path(repo_id).expanduser()
+ if local_root.exists():
+ return str(resolve_local_gguf_child(local_root, gguf_filename))
+ from utils.hf_xet_fallback import hf_hub_download_with_xet_fallback
+
+ return hf_hub_download_with_xet_fallback(
+ repo_id,
+ gguf_filename,
+ hf_token,
+ cancel_event = cancel_event,
+ reuse_other_cache_root = True,
+ local_files_only = local_files_only,
+ )
+
+
+def _holds_base_components(snapshot: str) -> bool:
+ root = Path(snapshot)
+ if not all((root / sub).is_dir() for sub in _LINKED_SUBDIRS):
+ return False
+ if not all((root / "tokenizer" / f).is_file() for f in ("tokenizer.json", "tokenizer_config.json")):
+ return False
+ for sub in ("text_encoder", "vae"):
+ folder = root / sub
+ shards: set[str] = set()
+ for index in folder.glob("*.safetensors.index.json"):
+ try:
+ shards.update(json.loads(index.read_text(encoding = "utf-8"))["weight_map"].values())
+ except (OSError, ValueError, KeyError, AttributeError):
+ return False
+ if shards:
+ if not all((folder / shard).is_file() for shard in shards):
+ return False
+ elif not any(folder.glob("*.safetensors")):
+ return False
+ return True
+
+
+def fetch_base_snapshot(
+ base_repo: str,
+ hf_token: Optional[str],
+ *,
+ local_files_only: bool,
+ cancel_event: Optional[threading.Event] = None,
+) -> str:
+ """The base repo's text encoder / tokenizer / VAE snapshot dir. Online, each file goes through the
+ same cancellable downloader as the GGUF, so an unload stops the transfer between and within files."""
+ local_root = Path(base_repo).expanduser()
+ if local_root.is_dir():
+ return str(local_root)
+ from huggingface_hub import snapshot_download
+
+ if local_files_only:
+ from huggingface_hub import constants
+ from huggingface_hub.errors import LocalEntryNotFoundError
+ from utils.hf_cache_settings import active_hf_hub_cache
+
+ missing: Optional[Exception] = None
+ incomplete: Optional[Exception] = None
+ # The plan may have staged the mirror even when the upstream holds some weights: try both.
+ repos = [prefer_ungated_mirror(base_repo, hf_token), base_repo]
+ if not os.environ.get("UNSLOTH_DIFFUSION_NO_MIRROR", "").strip():
+ repos.append(mirror_repo(base_repo))
+ for repo in dict.fromkeys(r for r in repos if r):
+ for cache_dir in dict.fromkeys((active_hf_hub_cache(), constants.HF_HUB_CACHE)):
+ try:
+ snapshot = snapshot_download(
+ repo,
+ allow_patterns = list(BASE_ALLOW_PATTERNS),
+ token = hf_token,
+ local_files_only = True,
+ cache_dir = cache_dir,
+ )
+ except LocalEntryNotFoundError as exc:
+ missing = exc
+ continue
+ if _holds_base_components(snapshot):
+ return snapshot
+ incomplete = incomplete or LocalEntryNotFoundError(
+ f"'{repo}' is cached without a complete text_encoder / tokenizer / vae"
+ )
+ raise incomplete or missing
+ import fnmatch
+
+ from huggingface_hub import HfApi
+ from utils.hf_xet_fallback import hf_hub_download_with_xet_fallback
+
+ def _listing(repo: str) -> tuple[Any, list[str]]:
+ info = HfApi().model_info(repo, token = hf_token, files_metadata = False)
+ return info, [
+ s.rfilename
+ for s in info.siblings or ()
+ if any(fnmatch.fnmatch(s.rfilename, pattern) for pattern in BASE_ALLOW_PATTERNS)
+ ]
+
+ info, wanted = _listing(base_repo)
+ # The repo the delegated download plan staged from: the ungated mirror unless the upstream is cached.
+ fetch_repo = prefer_ungated_mirror(base_repo, hf_token, files = wanted) if wanted else base_repo
+ if fetch_repo != base_repo:
+ info, wanted = _listing(fetch_repo)
+ if not wanted:
+ raise FileNotFoundError(f"'{fetch_repo}' has no text_encoder / tokenizer / vae files")
+ from huggingface_hub import constants, try_to_load_from_cache
+ from utils.hf_cache_settings import active_hf_hub_cache
+
+ def _holds_all(root: str) -> bool:
+ return all(
+ isinstance(
+ try_to_load_from_cache(fetch_repo, f, revision = info.sha, cache_dir = root), str
+ )
+ for f in wanted
+ )
+
+ # One root for every file: mflux reads the three directories out of a single snapshot.
+ cache_dir = active_hf_hub_cache()
+ if not _holds_all(cache_dir) and _holds_all(constants.HF_HUB_CACHE):
+ cache_dir = constants.HF_HUB_CACHE
+ snapshot_dir: Optional[str] = None
+ for filename in wanted:
+ if cancel_event is not None and cancel_event.is_set():
+ raise MlxCancelled("load cancelled")
+ path = hf_hub_download_with_xet_fallback(
+ fetch_repo,
+ filename,
+ hf_token,
+ cancel_event = cancel_event,
+ revision = info.sha,
+ cache_dir = cache_dir,
+ )
+ if snapshot_dir is None:
+ snapshot_dir = str(Path(path).parents[len(Path(filename).parts) - 1])
+ return snapshot_dir
+
+
+def resolve_variant_base(
+ repo_id: str,
+ fam: DiffusionFamily,
+ hf_token: Optional[str],
+ gguf_filename: Optional[str],
+ *,
+ fallback: str,
+ local_files_only: bool = False,
+) -> str:
+ """The diffusers loader's base resolution (trusted ``base_model`` card tag, then a named variant,
+ then the family default), so both engines read the same base for one pick. Cache-only reads no
+ card: the base an earlier online load recorded for this repo, else the name, else the default."""
+ if local_files_only:
+ return _cached_variant_base(repo_id, fam, gguf_filename, fallback)
+ if Path(repo_id).expanduser().exists():
+ named = _named_mlx_base(fam, repo_id, gguf_filename)
+ if named:
+ return named
+ try:
+ from core.inference.diffusion import _hf_base_model, _resolve_base_repo
+ except Exception as exc: # noqa: BLE001 -- no diffusers stack: the family default stands
+ logger.debug("mlx_diffusion.base_resolver_unavailable: %s", exc)
+ return fallback
+ named = _named_mlx_base(fam, repo_id, gguf_filename)
+ try:
+ # No card tag (none set, or the Hub read failed): the named variant decides, as offline.
+ explicit = named if named and _hf_base_model(repo_id, hf_token) is None else None
+ return _resolve_base_repo(repo_id, explicit, fam, hf_token, gguf_filename)
+ except Exception as exc: # noqa: BLE001 -- a metadata failure keeps the named variant or default
+ logger.debug("mlx_diffusion.base_resolve_failed: %s", exc)
+ return named or fallback
+
+
+def _cached_variant_base(
+ repo_id: str, fam: DiffusionFamily, gguf_filename: Optional[str], fallback: str
+) -> str:
+ candidates = {
+ b.lower()
+ for b in (
+ fam.base_repo,
+ *(getattr(fam, "named_variant_bases", ()) or ()),
+ *(b for b, _name in getattr(fam, "mlx_model_config_by_base", ()) or ()),
+ )
+ if b
+ }
+ try:
+ from hub.utils.companion_assets import read_companion_links
+ recorded = read_companion_links().get(repo_id.strip().lower(), ())
+ except Exception as exc: # noqa: BLE001 -- no record: the name decides
+ logger.debug("mlx_diffusion.companion_links_unreadable: %s", exc)
+ recorded = ()
+ named = _named_mlx_base(fam, repo_id, gguf_filename)
+ for base in reversed(recorded):
+ upstream = canonical_base(base)
+ # A recorded family default may be an earlier offline fallback, so it cannot overrule a name.
+ if upstream.lower() in candidates and not (
+ named and upstream.lower() == fam.base_repo.lower()
+ ):
+ return upstream
+ return named or named_variant_base(fam, repo_id, gguf_filename) or fallback
+
+
+def _named_mlx_base(fam: DiffusionFamily, *names: Optional[str]) -> Optional[str]:
+ """The ``mlx_model_config_by_base`` base the names spell, or None. Per name the longest spelling wins, so a Turbo
+ name (which also spells the undistilled ``Z-Image``) keeps the family default, and any name spelling the family
+ default (a Turbo repo holding a short file name) keeps it too."""
+
+ def fold(text: str) -> str:
+ return "".join(c for c in text.lower() if c.isalnum())
+
+ keyed = [
+ (b, fold(b.rsplit("/", 1)[-1]))
+ for b in (
+ fam.base_repo,
+ *(b for b, _name in getattr(fam, "mlx_model_config_by_base", ()) or ()),
+ )
+ if b
+ ]
+ found = None
+ for name in reversed([n for n in names if n]):
+ identity = fold(name.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1])
+ hits = [(len(key), b) for b, key in keyed if key and key in identity]
+ if hits:
+ best = max(hits)[1]
+ if best == fam.base_repo:
+ return None
+ found = found or best
+ return found
+
+
+def _companion_mirror(base: str) -> Optional[str]:
+ if os.environ.get("UNSLOTH_DIFFUSION_NO_MIRROR", "").strip():
+ return None
+ return mirror_repo(base)
+
+
+def _link_base_components(model_dir: Path, base_dir: str) -> None:
+ """Relinked every load: a new revision moves the snapshot."""
+ for sub in _LINKED_SUBDIRS:
+ source = Path(base_dir) / sub
+ if not source.is_dir():
+ raise FileNotFoundError(f"base repo snapshot has no {sub}/ directory")
+ link = model_dir / sub
+ if link.is_symlink() or link.is_file():
+ link.unlink()
+ elif link.is_dir():
+ import shutil
+ shutil.rmtree(link)
+ os.symlink(str(source.resolve()), str(link), target_is_directory = True)
+
+
+def _eta(total: int, step: int, first_at: float, now: float) -> Optional[float]:
+ if step <= 1 or first_at <= 0 or total <= step:
+ return 0.0 if total and step >= total else None
+ per_step = (now - first_at) / (step - 1)
+ return max(0.0, per_step * (total - step))
+
+
+def _round16(value: Optional[int], default: int) -> int:
+ v = int(value or default)
+ return max(64, (v // 16) * 16)
+
+
+class MlxDiffusionBackend:
+ runs_off_torch_device = False
+
+ def __init__(self, runtime_factory: Optional[Callable[[], Any]] = None) -> None:
+ self._lock = threading.Lock()
+ self._generate_lock = threading.Lock()
+ self.runtime_factory = runtime_factory or MfluxRuntime
+ self._runtime: Any = None
+ self._state: Optional[_MlxState] = None
+ self._loading: Optional[_MlxLoading] = None
+ self._load_token = 0
+ self._cancel_event = threading.Event()
+ self._active_generate_cancel: Optional[threading.Event] = None
+ self._active_generate_account: Optional[str] = None
+ self._gen: Optional[_MlxGen] = None
+ self._load_thread: Optional[threading.Thread] = None
+ self._unloading = 0
+ self._teardown_lock = threading.Lock()
+ self._free_pending = False
+ # Repos a cancelled load may still be reading until its worker is joined; see draining_repo_ids().
+ self._draining_repos: dict[int, tuple[str, ...]] = {}
+ self.last_timings: dict[str, Any] = {}
+
+ def _rt(self) -> Any:
+ if self._runtime is None:
+ self._runtime = self.runtime_factory()
+ return self._runtime
+
+ @property
+ def is_loaded(self) -> bool:
+ return self._state is not None
+
+ # ── Load ─────────────────────────────────────────────────────────────────
+
+ def begin_load(
+ self,
+ repo_id: str,
+ *,
+ local_files_only: bool = False,
+ display_repo_id: Optional[str] = None,
+ gguf_filename: Optional[str] = None,
+ base_repo: Optional[str] = None,
+ family_override: Optional[str] = None,
+ hf_token: Optional[Union[str, bool]] = None,
+ # Accepted and ignored: uniform route call.
+ cpu_offload: bool = False,
+ memory_mode: Optional[str] = None,
+ speed_mode: Optional[str] = None,
+ text_encoder_quant: Optional[str] = None,
+ transformer_quant: Optional[str] = None,
+ transformer_quant_fast_accum: Optional[bool] = None,
+ transformer_prequant_path: Optional[str] = None,
+ attention_backend: Optional[str] = None,
+ transformer_cache: Optional[str] = None,
+ transformer_cache_threshold: Optional[float] = None,
+ model_kind: Optional[str] = None,
+ loras: Optional[list[tuple[str, float]]] = None,
+ gpu_ids: Optional[list[int]] = None,
+ gpu_ordinal: Optional[int] = None,
+ **_ignored: Any,
+ ) -> dict[str, Any]:
+ if isinstance(hf_token, str):
+ hf_token = hf_token.strip() or None
+ if not gguf_filename:
+ raise ValueError(
+ "gguf_filename is required: the MLX engine loads GGUF checkpoints only."
+ )
+ if model_kind and model_kind != "gguf":
+ raise ValueError("The MLX engine loads GGUF checkpoints only.")
+ fam = detect_family_for_pick(repo_id, gguf_filename, family_override)
+ if fam is None:
+ raise ValueError(
+ f"'{repo_id}' is not a supported diffusion image model. Supported families: "
+ f"{', '.join(supported_family_names())}."
+ )
+ if not family_mlx_supported(fam):
+ raise ValueError(f"Family '{fam.name}' has no MLX implementation.")
+ convertible, why = convert.quant_convertible(gguf_filename)
+ if not convertible:
+ raise ValueError(why or "This GGUF quant is not convertible to MLX.")
+ if loras:
+ raise ValueError("LoRA adapters are not supported on the MLX engine yet.")
+ base = resolve_base_repo(fam, base_repo)
+ named = _named_mlx_base(fam, base) if _is_local_path(base) else None
+ model_config = mlx_model_config_for(fam, named or base)
+ with self._lock:
+ if self._loading is not None and self._loading.error is None:
+ raise RuntimeError("A diffusion load is already in progress.")
+ if self._unloading:
+ raise RuntimeError("A diffusion unload is in progress.")
+ if self._active_generate_cancel is not None:
+ self._active_generate_cancel.set()
+ self._load_token += 1
+ token = self._load_token
+ cancel_event = threading.Event()
+ self._cancel_event = cancel_event
+ self._loading = _MlxLoading(
+ repo_id = repo_id, base_repo = base, fetch_repo = _companion_mirror(base)
+ )
+ worker = account_thread(
+ target = self._run_load,
+ kwargs = dict(
+ repo_id = repo_id,
+ display_repo_id = display_repo_id,
+ gguf_filename = gguf_filename,
+ base = base,
+ fam = fam,
+ model_config = model_config,
+ hf_token = hf_token,
+ local_files_only = local_files_only,
+ _load_token = token,
+ _cancel_event = cancel_event,
+ explicit_base = bool((base_repo or "").strip()),
+ ),
+ daemon = True,
+ )
+ self._load_thread = worker
+ worker.start()
+ return self.status()
+
+ def _set_phase(
+ self,
+ token: int,
+ phase: str,
+ fraction: float = 0.0,
+ ) -> None:
+ with self._lock:
+ if self._load_token == token and self._loading is not None:
+ self._loading.phase = phase
+ self._loading.fraction = fraction
+
+ @_invalidates_gpu_memory("mlx diffusion load")
+ def _run_load(
+ self,
+ *,
+ repo_id: str,
+ display_repo_id: Optional[str],
+ gguf_filename: str,
+ base: str,
+ fam: DiffusionFamily,
+ model_config: str,
+ hf_token: Optional[str],
+ local_files_only: bool,
+ _load_token: int,
+ _cancel_event: threading.Event,
+ explicit_base: bool = True,
+ ) -> None:
+ timings: dict[str, Any] = {}
+ model = state = displaced = None
+ building = published = False
+ try:
+ if not explicit_base:
+ # The repo's base_model card tag can name the undistilled base: resolve it the way the
+ # diffusers loader and the delegated download plan do, before picking the mflux config.
+ base = resolve_variant_base(
+ repo_id,
+ fam,
+ hf_token,
+ gguf_filename,
+ fallback = base,
+ local_files_only = local_files_only,
+ )
+ model_config = mlx_model_config_for(fam, base)
+ with self._lock:
+ if self._load_token == _load_token and self._loading is not None:
+ self._loading.base_repo = base
+ self._loading.fetch_repo = _companion_mirror(base)
+ t0 = time.perf_counter()
+ gguf_path = fetch_gguf(
+ repo_id,
+ gguf_filename,
+ hf_token,
+ cancel_event = _cancel_event,
+ local_files_only = local_files_only,
+ )
+ base_dir = fetch_base_snapshot(
+ base,
+ hf_token,
+ local_files_only = local_files_only,
+ cancel_event = _cancel_event,
+ )
+ timings["fetch_s"] = round(time.perf_counter() - t0, 3)
+ if _cancel_event.is_set():
+ return
+ bits = dense_bits()
+ revision = _snapshot_revision(gguf_path)
+ if revision is None:
+ st = os.stat(gguf_path)
+ revision = f"local-{st.st_size}-{int(st.st_mtime)}"
+ out_dir = convert.cache_dir_for(repo_id, revision, gguf_filename, dense_bits = bits)
+ self._set_phase(_load_token, "finalizing", 0.0)
+ t1 = time.perf_counter()
+ if convert.conversion_complete(out_dir, source_path = gguf_path):
+ timings["convert_cached"] = True
+ else:
+ out_dir.mkdir(parents = True, exist_ok = True)
+
+ def _progress(done: int, total: int) -> None:
+ self._set_phase(_load_token, "finalizing", (done / total) if total else 0.0)
+
+ summary = convert.convert_gguf_to_mflux(
+ gguf_path,
+ out_dir,
+ dense_bits = bits,
+ cancel_event = _cancel_event,
+ progress = _progress,
+ )
+ timings["convert_cached"] = False
+ timings["convert_summary"] = {
+ k: v
+ for k, v in (summary or {}).items()
+ if isinstance(v, (int, float, str, dict))
+ }
+ timings["convert_s"] = round(time.perf_counter() - t1, 3)
+ _link_base_components(Path(out_dir), base_dir)
+ if _cancel_event.is_set():
+ return
+ precision = compute_precision_name()
+ te_bits = text_encoder_bits()
+ t2 = time.perf_counter()
+ runtime = self._rt()
+ # Free the replaced model first: two resident DiTs do not fit a small Mac.
+ with self._lock:
+ displaced = self._state if self._load_token == _load_token else None
+ if displaced is not None:
+ self._state = None
+ if displaced is not None:
+ del displaced
+ with self._generate_lock:
+ pass
+ runtime.free()
+ if _cancel_event.is_set():
+ return
+ building = True
+ model = runtime.build(
+ str(out_dir),
+ model_config = model_config,
+ precision = precision,
+ te_bits = te_bits,
+ )
+ runtime.cache_text_encodings(model)
+ timings["build_s"] = round(time.perf_counter() - t2, 3)
+ state = _MlxState(
+ repo_id = repo_id,
+ display_repo_id = display_repo_id,
+ gguf_filename = gguf_filename,
+ base_repo = base,
+ family = fam,
+ model = model,
+ model_config = model_config,
+ precision = precision,
+ te_bits = te_bits,
+ dense_bits = bits,
+ convert_dir = str(out_dir),
+ timings = timings,
+ )
+ with self._lock:
+ if self._load_token != _load_token:
+ superseded = True
+ else:
+ superseded = False
+ self._state = state
+ self._loading = None
+ published = True
+ if superseded:
+ del state, model
+ runtime.free()
+ return
+ logger.info(
+ "mlx_diffusion.loaded: repo=%s gguf=%s config=%s precision=%s te_bits=%s dense_bits=%s "
+ "timings=%s",
+ repo_id,
+ gguf_filename,
+ model_config,
+ precision,
+ te_bits,
+ bits,
+ timings,
+ )
+ except Exception as exc: # noqa: BLE001 -- surfaced via load_progress
+ clear_exception_locals(exc)
+ if self._load_token != _load_token or _cancel_event.is_set():
+ return
+ logger.error("mlx_diffusion.load_failed: %s", exc, exc_info = True)
+ if self._state is not None:
+ from .gpu_arbiter import DIFFUSION, restore_owner_account
+ from hub.services.models.account_access import restore_resident_metadata
+
+ restore_owner_account(DIFFUSION)
+ restore_resident_metadata("diffusion")
+ from utils.native_path_leases import redact_native_paths
+
+ with self._lock:
+ if self._load_token == _load_token and self._loading is not None:
+ self._loading.error = redact_native_paths(str(exc))
+ finally:
+ # A cached exception below (Hub helpers memoize import failures) can retain this frame;
+ # a model left in its locals would then survive unload().
+ model = state = displaced = None
+ if building and not published and self._runtime is not None:
+ self._runtime.free()
+
+ def download_plan(self, repo_id: str, **kwargs: Any) -> dict[str, Any]:
+ """The diffusers GGUF plan stages exactly the files this engine opens; its memory verdict does not apply."""
+ from core.inference.diffusion import get_diffusion_backend
+
+ kwargs["memory_verdict"] = False
+ if not (kwargs.get("base_repo") or "").strip():
+ gguf_filename = kwargs.get("gguf_filename")
+ fam = detect_family_for_pick(repo_id, gguf_filename, kwargs.get("family_override"))
+ if fam is not None and gguf_filename and family_mlx_supported(fam):
+ kwargs["base_repo"] = resolve_variant_base(
+ repo_id,
+ fam,
+ kwargs.get("hf_token"),
+ gguf_filename,
+ fallback = fam.base_repo,
+ local_files_only = bool(kwargs.get("local_files_only")),
+ )
+ # The loader always opens the base repo's text_encoder/ and vae/, never a single-file component.
+ kwargs.pop("text_encoder_files", None)
+ kwargs.pop("vae_file", None)
+ return get_diffusion_backend().download_plan(
+ repo_id, discover_text_encoders = False, **kwargs
+ )
+
+ def preflight_base_access(
+ self, repo_id: str, fam: Optional[DiffusionFamily], **kwargs: Any
+ ) -> None:
+ from core.inference.diffusion import get_diffusion_backend
+ get_diffusion_backend().preflight_base_access(repo_id, fam, **kwargs)
+
+ def load_progress(self) -> dict[str, Any]:
+ loading = self._loading
+ if loading is not None and loading.error:
+ return _progress("error", error = loading.error)
+ if loading is None:
+ return _progress("ready" if self._state is not None else None)
+ return _progress(
+ loading.phase,
+ loading.downloaded_bytes,
+ loading.expected_bytes,
+ loading.fraction,
+ )
+
+ def loading_repo_ids(self) -> tuple[str, ...]:
+ with self._lock:
+ loading = self._loading
+ if loading is None or loading.error is not None:
+ return ()
+ return tuple(
+ dict.fromkeys(
+ r for r in (loading.repo_id, loading.base_repo, loading.fetch_repo) if r
+ )
+ )
+
+ def draining_repo_ids(self) -> tuple[str, ...]:
+ """Repos a cancelled load is still reading until unload() has joined its worker, for the cache-deletion guards
+ only (``loading_repo_ids()`` reads as ownership elsewhere)."""
+ with self._lock:
+ return tuple(dict.fromkeys(r for repos in self._draining_repos.values() for r in repos))
+
+ def loaded_repo_ids(self) -> tuple[str, ...]:
+ with self._lock:
+ state = self._state
+ if state is None:
+ return ()
+ return tuple(dict.fromkeys((state.repo_id, state.base_repo)))
+
+ # ── Generate ─────────────────────────────────────────────────────────────
+
+ def generate(
+ self,
+ *,
+ prompt: str,
+ negative_prompt: Optional[str] = None,
+ width: Optional[int] = 1024,
+ height: Optional[int] = 1024,
+ steps: int = 9,
+ guidance: float = 0.0,
+ seed: Optional[int] = None,
+ batch_size: int = 1,
+ prompts: Optional[list[str]] = None,
+ seeds: Optional[list[int]] = None,
+ init_image: Optional[str] = None,
+ mask_image: Optional[str] = None,
+ strength: Optional[float] = None,
+ upscale: Optional[float] = None,
+ reference_images: Optional[list[str]] = None,
+ workflow: Optional[str] = None,
+ reference_resolution: Optional[int] = None,
+ localized_edit: Any = None,
+ loras: Optional[list[tuple[str, float]]] = None,
+ controlnet: Optional[tuple[str, str, str, float, float, float]] = None,
+ expected_load: Optional[LoadIdentity] = None,
+ allow_oversized: bool = False,
+ ) -> dict[str, Any]:
+ if (
+ init_image is not None
+ or mask_image is not None
+ or reference_images
+ or workflow not in (None, "txt2img")
+ or reference_resolution is not None
+ or localized_edit is not None
+ or (upscale is not None and upscale > 1)
+ ):
+ raise ValueError(
+ "The MLX engine runs text-to-image only; unset UNSLOTH_DIFFUSION_MLX for "
+ "img2img / inpaint / edit / reference / upscale."
+ )
+ if prompts is not None or seeds is not None:
+ raise ValueError(
+ "Batched prompt/seed lists are not supported on the MLX engine; use batch_size."
+ )
+ if controlnet is not None and controlnet[3] not in (None, 0, 0.0):
+ raise ValueError("ControlNet is not supported on the MLX engine.")
+ if loras:
+ raise ValueError("LoRA adapters are not supported on the MLX engine yet.")
+ steps = int(steps)
+ if steps < 1:
+ raise ValueError("steps must be at least 1")
+ batch = max(1, int(batch_size or 1))
+ base_seed = int(seed) if seed is not None else random.randint(0, 2**31 - 1)
+ w = _round16(width, 1024)
+ h = _round16(height, 1024)
+ family = getattr(self._state, "family", None)
+ if family is not None:
+ from core.inference.diffusion_conditioning import check_output_size
+ check_output_size(family, w, h)
+
+ cancel = threading.Event()
+ from hub.services.models.account_access import media_generation_slot
+
+ with self._generate_lock, media_generation_slot("diffusion"):
+ with self._lock:
+ state = self._state
+ if state is None:
+ raise RuntimeError(DIFFUSION_NOT_LOADED_MSG)
+ loaded_id = load_identity(state.repo_id, state.base_repo, state.family.name)
+ if expected_load is not None and expected_load != loaded_id:
+ raise DiffusionModelReplacedError(expected_load, loaded_id)
+ self._active_generate_cancel = cancel
+ self._active_generate_account = current_account_id()
+ self._gen = _MlxGen(total_steps = steps * batch)
+ try:
+ runtime = self._rt()
+ cfg = float(guidance or 0.0) if runtime.supports_guidance(state.model) else None
+ images = []
+ seeds_out = []
+ per_image: list[dict[str, float]] = []
+ for index in range(batch):
+ image_seed = (base_seed + index) & SEED_MASK
+ offset = index * steps
+ started = time.perf_counter()
+ marks: list[float] = []
+
+ def _on_step(
+ done: int,
+ offset = offset,
+ marks = marks,
+ ) -> None:
+ marks.append(time.perf_counter())
+ gen = self._gen
+ if gen is not None:
+ now = time.time()
+ gen.step = min(offset + done, gen.total_steps)
+ if gen.first_step_at == 0.0:
+ gen.first_step_at = now
+ gen.eta_seconds = _eta(
+ gen.total_steps, gen.step, gen.first_step_at, now
+ )
+ if cancel.is_set():
+ raise MlxCancelled("cancelled")
+
+ if cancel.is_set():
+ raise MlxCancelled("cancelled")
+ image = runtime.generate(
+ state.model,
+ prompt = prompt,
+ negative_prompt = negative_prompt,
+ seed = image_seed,
+ steps = steps,
+ width = w,
+ height = h,
+ guidance = cfg,
+ on_step = _on_step,
+ )
+ total = time.perf_counter() - started
+ timing = {"total_s": round(total, 3)}
+ if len(marks) >= 2:
+ # Exclude the first step: it includes prompt encoding.
+ timing["s_per_step"] = round((marks[-1] - marks[0]) / (len(marks) - 1), 4)
+ timing["first_step_s"] = round(marks[0] - started, 3)
+ timing["decode_s"] = round(time.perf_counter() - marks[-1], 3)
+ per_image.append(timing)
+ images.append(image)
+ seeds_out.append(image_seed)
+ with self._lock:
+ if cancel.is_set():
+ raise RuntimeError(DIFFUSION_CANCELLED_MSG)
+ if self._active_generate_cancel is cancel:
+ self._active_generate_cancel = None
+ self._active_generate_account = None
+ self.last_timings = {"width": w, "height": h, "steps": steps, "images": per_image}
+ logger.info(
+ "mlx_diffusion.generated: %dx%d steps=%d batch=%d timings=%s",
+ w,
+ h,
+ steps,
+ batch,
+ per_image,
+ )
+ return {
+ "images": images,
+ "seed": base_seed,
+ "seeds": seeds_out,
+ "negative_prompt": (negative_prompt or None) if cfg and cfg > 1.0 else None,
+ "repo_id": state.display_repo_id or state.repo_id,
+ "model_kind": "gguf",
+ "gguf_filename": state.gguf_filename,
+ # The MLX build on top of the GGUF: on-load quantization varies with RAM and env.
+ "transformer_quant": _dense_quant_name(state.dense_bits),
+ "text_encoder_quant": _te_quant_name(state.te_bits),
+ "memory_mode": None,
+ "offload_policy": "none",
+ "speed_mode": None,
+ "cpu_offload": False,
+ "workflow": "txt2img",
+ "reference_resolution": None,
+ "localized_edit": None,
+ }
+ except MlxCancelled as exc:
+ drop_exception_frames(exc)
+ raise RuntimeError(DIFFUSION_CANCELLED_MSG) from None
+ except BaseException as exc:
+ clear_exception_locals(exc)
+ raise
+ finally:
+ state = runtime = None
+ self._gen = None
+ with self._lock:
+ if self._active_generate_cancel is cancel:
+ self._active_generate_cancel = None
+ self._active_generate_account = None
+
+ def generate_progress(self) -> dict[str, Any]:
+ gen = self._gen
+ if gen is None or gen.total_steps <= 0:
+ return {
+ "active": False,
+ "step": 0,
+ "total_steps": 0,
+ "fraction": 0.0,
+ "eta_seconds": None,
+ }
+ return {
+ "active": True,
+ "step": gen.step,
+ "total_steps": gen.total_steps,
+ "fraction": min(gen.step / gen.total_steps, 1.0),
+ "eta_seconds": gen.eta_seconds,
+ }
+
+ def cancel_generate(self, expected_account: Optional[str] = None) -> bool:
+ with self._lock:
+ cancel = self._active_generate_cancel
+ if cancel is None:
+ return False
+ if expected_account is not None and self._active_generate_account not in (
+ None,
+ expected_account,
+ ):
+ return False
+ cancel.set()
+ return True
+
+ # ── Unload / status ──────────────────────────────────────────────────────
+
+ @_invalidates_gpu_memory("mlx diffusion unload")
+ def unload(self, *, expected_account: Optional[str] = None) -> dict[str, Any]:
+ with self._lock:
+ if expected_account is not None:
+ from .gpu_arbiter import DIFFUSION, GpuBusyForAnotherAccountError
+ from hub.services.models.account_access import require_resident_control
+
+ if (
+ self._active_generate_cancel is not None
+ and self._active_generate_account != expected_account
+ ):
+ raise GpuBusyForAnotherAccountError(DIFFUSION, 1)
+ require_resident_control(
+ DIFFUSION, self._state.repo_id if self._state is not None else None
+ )
+ self._cancel_event.set()
+ if self._active_generate_cancel is not None:
+ self._active_generate_cancel.set()
+ if self._state is not None:
+ self._free_pending = True
+ self._state = None
+ self._load_token += 1
+ # Left visible until joined: a concurrent unload must wait for the same worker.
+ worker = self._load_thread
+ if self._loading is not None and worker is not None:
+ self._draining_repos[id(worker)] = tuple(
+ dict.fromkeys(
+ r
+ for r in (
+ self._loading.repo_id,
+ self._loading.base_repo,
+ self._loading.fetch_repo,
+ )
+ if r
+ )
+ )
+ self._loading = None
+ # Held until the join and free below: a load started meanwhile would build beside the superseded one.
+ self._unloading += 1
+ try:
+ # Serialized so every unload returns only after the whole teardown, whichever caller runs it.
+ with self._teardown_lock:
+ # Barrier: on return the cancelled generation has released the model.
+ with self._generate_lock:
+ pass
+ # And a superseded load has stopped: a build in progress cannot be interrupted, and the
+ # caller treats this return as "memory is free" before activating another engine or load.
+ if worker is not None and worker is not threading.current_thread():
+ worker.join()
+ with self._lock:
+ if self._load_thread is worker:
+ self._load_thread = None
+ if worker is not None:
+ self._draining_repos.pop(id(worker), None)
+ free, self._free_pending = self._free_pending, False
+ if free and self._runtime is not None:
+ self._runtime.free()
+ finally:
+ with self._lock:
+ self._unloading -= 1
+ return self.status()
+
+ def status(self) -> dict[str, Any]:
+ state = self._state
+ if state is None:
+ return {
+ "loaded": False,
+ "repo_id": None,
+ "display_repo_id": None,
+ "family": None,
+ "base_repo": None,
+ "device": None,
+ "dtype": None,
+ "gguf_variant": None,
+ "cpu_offload": False,
+ "offload_policy": None,
+ "vae_tiling": False,
+ "memory_mode": None,
+ "speed_mode": None,
+ "speed_optims": [],
+ "text_encoder_quant": None,
+ "transformer_quant": None,
+ "attention_backend": None,
+ "transformer_cache": None,
+ "resolved": None,
+ "engine": ENGINE_NAME,
+ "native_mode": None,
+ "supports_lora": False,
+ "supports_controlnet": False,
+ "workflows": [],
+ "conditioning": None,
+ }
+ from core.inference.diffusion_conditioning import conditioning_capabilities
+ from hub.utils.gguf import extract_quant_token
+
+ conditioning = conditioning_capabilities(state.family, ["txt2img"])
+ conditioning["reference_resolutions"] = []
+ conditioning["notes"] = []
+ try:
+ negative = bool(self._rt().supports_guidance(state.model))
+ except Exception: # noqa: BLE001
+ negative = False
+ return {
+ "loaded": True,
+ "repo_id": state.repo_id,
+ "display_repo_id": state.display_repo_id,
+ "family": state.family.name,
+ "base_repo": state.base_repo,
+ "device": "mps",
+ "dtype": state.precision,
+ "model_kind": "gguf",
+ "gguf_filename": state.gguf_filename,
+ "gguf_variant": extract_quant_token(state.gguf_filename),
+ "cpu_offload": False,
+ "offload_policy": "none",
+ "vae_tiling": False,
+ "memory_mode": None,
+ "speed_mode": None,
+ "speed_optims": [],
+ "text_encoder_quant": _te_quant_name(state.te_bits),
+ "transformer_quant": _dense_quant_name(state.dense_bits),
+ "attention_backend": None,
+ "transformer_cache": None,
+ "resolved": None,
+ "engine": ENGINE_NAME,
+ "native_mode": None,
+ "mlx": {
+ "model_config": state.model_config,
+ "precision": state.precision,
+ "text_encoder_bits": state.te_bits,
+ "dense_bits": state.dense_bits,
+ "timings": dict(state.timings),
+ },
+ "supports_lora": False,
+ "supports_controlnet": False,
+ "supports_negative_prompt": negative,
+ "workflows": ["txt2img"],
+ "conditioning": conditioning,
+ }
+
+
+def _dense_quant_name(bits: Optional[int]) -> Optional[str]:
+ return f"mlx_int{bits}_dense" if bits else None
+
+
+def _te_quant_name(bits: Optional[int]) -> Optional[str]:
+ return f"mlx_int{bits}" if bits else None
+
+
+def _progress(
+ phase: Optional[str],
+ bytes_downloaded: int = 0,
+ bytes_total: int = 0,
+ fraction: float = 0.0,
+ *,
+ error: Optional[str] = None,
+) -> dict[str, Any]:
+ return {
+ "phase": phase,
+ "bytes_downloaded": bytes_downloaded,
+ "bytes_total": bytes_total,
+ "fraction": fraction,
+ "error": error,
+ }
+
+
+_mlx_diffusion_backend: Optional[MlxDiffusionBackend] = None
+
+
+def get_mlx_diffusion_backend() -> MlxDiffusionBackend:
+ global _mlx_diffusion_backend
+ if _mlx_diffusion_backend is None:
+ _mlx_diffusion_backend = MlxDiffusionBackend()
+ return _mlx_diffusion_backend
+
+
+def generation_in_flight() -> bool:
+ backend = _mlx_diffusion_backend
+ return backend is not None and backend._gen is not None
diff --git a/studio/backend/core/inference/mlx_diffusion_convert.py b/studio/backend/core/inference/mlx_diffusion_convert.py
new file mode 100644
index 00000000000..a95097f8907
--- /dev/null
+++ b/studio/backend/core/inference/mlx_diffusion_convert.py
@@ -0,0 +1,560 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Diffusion GGUF -> mflux pre-quantized transformer layout (numpy + gguf only, streamed per tensor).
+
+Q4_0 / Q4_1 / Q8_0 map exactly onto MLX affine group-32 (dequant = q * scale + bias):
+ Q4_0: scale d, bias -8d; Q4_1: scale d, bias m; Q8_0: q = qs + 128, scale d, bias -128d.
+K-quants are refused (not converted yet): their per-sub-block scale products do not round-trip exactly through MLX's 16-bit group scales, and Q6_K uses 16-element groups.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import struct
+import time
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+import numpy as np
+
+CONVERTER_VERSION = "1"
+MFLUX_VERSION = "0.22.0"
+GROUP_SIZE = 32
+OUTPUT_FILENAME = "0.safetensors"
+MARKER_FILENAME = "unsloth_mlx_convert.json"
+
+CONVERTIBLE_TYPES = frozenset({"Q4_0", "Q4_1", "Q8_0", "BF16", "F16", "F32"})
+CONVERTIBLE_QUANT_TOKENS = frozenset({"Q4_0", "Q4_1", "Q8_0", "BF16", "F16", "F32"})
+
+_BLOCK_BYTES = {"Q4_0": 18, "Q4_1": 20, "Q8_0": 34}
+_BLOCK_BITS = {"Q4_0": 4, "Q4_1": 4, "Q8_0": 8}
+_DENSE_TYPES = frozenset({"BF16", "F16", "F32"})
+_PAD_TOKENS = ("cap_pad_token", "x_pad_token")
+_QKV_PARTS = ("to_q", "to_k", "to_v")
+
+
+class UnsupportedGGUFError(ValueError):
+ """The GGUF holds a tensor type this converter cannot map onto MLX affine weights."""
+
+
+# ── Filename-level verdict (router) ─────────────────────────────────────────────────────────────
+
+_QUANT_RE = re.compile(
+ r"(?:^|[-_.])((?:UD-)?(?:I?Q\d+_[A-Z0-9_]+|Q\d+|BF16|F16|F32|MXFP4|TQ\d_\d))(?:\.gguf)?$",
+ re.IGNORECASE,
+)
+
+
+def _quant_token(gguf_filename: str) -> Optional[str]:
+ try:
+ from hub.utils.gguf import extract_quant_token
+ return extract_quant_token(gguf_filename)
+ except Exception: # noqa: BLE001 -- the regex below answers when the hub helper cannot
+ match = _QUANT_RE.search(Path(gguf_filename).name)
+ return match.group(1) if match else None
+
+
+def quant_convertible(gguf_filename: Optional[str]) -> tuple[bool, Optional[str]]:
+ """Filename verdict only; conversion re-checks every tensor."""
+ if not gguf_filename:
+ return (
+ False,
+ "GGUF quant unknown (no GGUF filename); the MLX engine needs Q4_0/Q4_1/Q8_0/BF16",
+ )
+ token = _quant_token(str(gguf_filename))
+ if not token:
+ return False, (
+ f"GGUF quant unknown for {Path(str(gguf_filename)).name!r}; the MLX engine needs "
+ "Q4_0/Q4_1/Q8_0/BF16"
+ )
+ upper = str(token).upper()
+ if upper in CONVERTIBLE_QUANT_TOKENS:
+ return True, None
+ return False, (f"GGUF quant {token} is not convertible to MLX yet (only Q4_0/Q4_1/Q8_0/BF16)")
+
+
+# ── Block math ──────────────────────────────────────────────────────────────────────────────────
+
+
+def _pack(q: np.ndarray, bits: int) -> np.ndarray:
+ """(R, C) integers in [0, 2**bits) -> (R, C * bits / 32) uint32, element i at bits*(i % per_word)."""
+ per_word = 32 // bits
+ rows, cols = q.shape
+ if cols % per_word:
+ raise ValueError(f"{cols} columns do not pack into {bits}-bit words")
+ q = q.reshape(rows, cols // per_word, per_word).astype(np.uint32)
+ shifts = (bits * np.arange(per_word, dtype = np.uint32)).astype(np.uint32)
+ return np.bitwise_or.reduce(q << shifts, axis = -1).astype(np.uint32)
+
+
+def _unpack(packed: np.ndarray, bits: int) -> np.ndarray:
+ per_word = 32 // bits
+ rows, words = packed.shape
+ shifts = (bits * np.arange(per_word, dtype = np.uint32)).astype(np.uint32)
+ mask = np.uint32((1 << bits) - 1)
+ q = (packed.astype(np.uint32)[..., None] >> shifts) & mask
+ return q.reshape(rows, words * per_word)
+
+
+def _f16_field(blocks: np.ndarray, start: int) -> np.ndarray:
+ return blocks[..., start : start + 2].copy().view(np.float16)[..., 0].astype(np.float32)
+
+
+def affine_from_ggml(
+ kind: str, raw: np.ndarray, rows: int, cols: int
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, int]:
+ """Q4_0 / Q4_1 / Q8_0 block bytes -> (packed uint32, scales f32, biases f32, bits), MLX affine g32."""
+ kind = str(kind).upper()
+ if kind not in _BLOCK_BYTES:
+ raise UnsupportedGGUFError(f"{kind} blocks have no exact MLX affine mapping")
+ if cols % GROUP_SIZE:
+ raise ValueError(f"{cols} columns are not a whole number of {GROUP_SIZE}-wide blocks")
+ nb = cols // GROUP_SIZE
+ raw = np.ascontiguousarray(np.asarray(raw)).view(np.uint8).reshape(-1)
+ expected = rows * nb * _BLOCK_BYTES[kind]
+ if raw.size != expected:
+ raise ValueError(f"{kind}: {raw.size} bytes for {rows}x{cols}, expected {expected}")
+ blocks = raw.reshape(rows, nb, _BLOCK_BYTES[kind])
+ if kind == "Q4_0":
+ d = _f16_field(blocks, 0)
+ qs = blocks[..., 2:]
+ q = np.concatenate([qs & 0xF, qs >> 4], axis = -1).reshape(rows, cols)
+ return _pack(q, 4), d, -8.0 * d, 4
+ if kind == "Q4_1":
+ d = _f16_field(blocks, 0)
+ m = _f16_field(blocks, 2)
+ qs = blocks[..., 4:]
+ q = np.concatenate([qs & 0xF, qs >> 4], axis = -1).reshape(rows, cols)
+ return _pack(q, 4), d, m, 4
+ d = _f16_field(blocks, 0)
+ qs = blocks[..., 2:].copy().view(np.int8).astype(np.int16) + 128
+ return _pack(qs.astype(np.uint8).reshape(rows, cols), 8), d, -128.0 * d, 8
+
+
+def _f32_to_bf16_bits(a: np.ndarray) -> np.ndarray:
+ """float32 -> bf16 bit patterns (uint16), round to nearest even; NaN stays NaN."""
+ a = np.ascontiguousarray(a, dtype = np.float32)
+ u = a.view(np.uint32)
+ rounded = ((u + (np.uint32(0x7FFF) + ((u >> 16) & np.uint32(1)))) >> 16).astype(np.uint16)
+ nan = np.isnan(a)
+ if nan.any():
+ rounded = np.where(nan, ((u >> 16) | np.uint32(0x40)).astype(np.uint16), rounded)
+ return rounded
+
+
+def _bf16_bits_to_f32(b: np.ndarray) -> np.ndarray:
+ return (np.asarray(b, dtype = np.uint16).astype(np.uint32) << 16).view(np.float32)
+
+
+def round_to_bf16(a: np.ndarray) -> np.ndarray:
+ """float32 values as they read back after a bf16 store."""
+ return _bf16_bits_to_f32(_f32_to_bf16_bits(a))
+
+
+def quantize_dense_affine(
+ w: np.ndarray,
+ bits: int,
+ group_size: int = GROUP_SIZE,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+ """Min/max affine quantization of a dense (R, C) weight; scale / bias already bf16-rounded."""
+ if bits not in (4, 8):
+ raise ValueError(f"dense quantization supports 4 or 8 bits, not {bits}")
+ w = np.asarray(w, dtype = np.float32)
+ rows, cols = w.shape
+ if cols % group_size:
+ raise ValueError(f"{cols} columns are not a whole number of {group_size}-wide groups")
+ g = w.reshape(rows, cols // group_size, group_size)
+ lo = g.min(axis = -1)
+ hi = g.max(axis = -1)
+ levels = float((1 << bits) - 1)
+ bias = round_to_bf16(lo)
+ scale = round_to_bf16((hi - bias) / levels)
+ flat = scale == 0
+ safe_scale = np.where(flat, np.float32(1.0), scale).astype(np.float32)
+ q = np.rint((g - bias[..., None]) / safe_scale[..., None])
+ q = np.where(flat[..., None], 0.0, q)
+ q = np.clip(q, 0, levels).astype(np.uint8).reshape(rows, cols)
+ return _pack(q, bits), scale.astype(np.float32), bias.astype(np.float32)
+
+
+def dequantize_affine(
+ packed: np.ndarray,
+ scales: np.ndarray,
+ biases: np.ndarray,
+ bits: int,
+ group_size: int = GROUP_SIZE,
+) -> np.ndarray:
+ q = _unpack(np.asarray(packed), bits).astype(np.float32)
+ rows, cols = q.shape
+ q = q.reshape(rows, cols // group_size, group_size)
+ s = np.asarray(scales, dtype = np.float32)[..., None]
+ b = np.asarray(biases, dtype = np.float32)[..., None]
+ return (q * s + b).reshape(rows, cols)
+
+
+# ── Names ───────────────────────────────────────────────────────────────────────────────────────
+
+
+def zimage_rename(name: str) -> str:
+ """Single-file Z-Image tensor name -> mflux's (the qkv split happens in the converter)."""
+ k = re.sub(r"^final_layer\.", "all_final_layer.2-1.", name)
+ k = re.sub(r"^x_embedder\.", "all_x_embedder.2-1.", k)
+ k = k.replace(
+ "all_final_layer.2-1.adaLN_modulation.1.", "all_final_layer.2-1.adaLN_modulation.0."
+ )
+ k = k.replace("t_embedder.mlp.0.", "t_embedder.linear1.").replace(
+ "t_embedder.mlp.2.", "t_embedder.linear2."
+ )
+ k = k.replace(".attention.out.", ".attention.to_out.0.")
+ k = k.replace(".attention.q_norm.", ".attention.norm_q.").replace(
+ ".attention.k_norm.", ".attention.norm_k."
+ )
+ return k
+
+
+# ── Planning ────────────────────────────────────────────────────────────────────────────────────
+
+_ST_DTYPE_BYTES = {"U32": 4, "BF16": 2, "F16": 2}
+
+
+def _type_name(tensor: Any) -> str:
+ return str(tensor.tensor_type.name).upper()
+
+
+def _gguf_dims(tensor: Any) -> list[int]:
+ """numpy-order shape (outermost first); GGUF stores the innermost dimension first."""
+ return [int(x) for x in reversed([int(v) for v in tensor.shape])]
+
+
+def _dense_f32(tensor: Any) -> np.ndarray:
+ kind = _type_name(tensor)
+ raw = np.asarray(tensor.data)
+ shape = _gguf_dims(tensor)
+ if kind == "BF16":
+ return _bf16_bits_to_f32(np.ascontiguousarray(raw).view(np.uint16)).reshape(shape)
+ if kind == "F16":
+ return np.ascontiguousarray(raw).view(np.float16).astype(np.float32).reshape(shape)
+ return np.ascontiguousarray(raw).view(np.float32).reshape(shape)
+
+
+def _dense_bf16_bits(tensor: Any) -> np.ndarray:
+ """Dense tensor as bf16 bit patterns; a BF16 source is copied bit for bit."""
+ if _type_name(tensor) == "BF16":
+ return (
+ np.ascontiguousarray(np.asarray(tensor.data))
+ .view(np.uint16)
+ .reshape(_gguf_dims(tensor))
+ )
+ return _f32_to_bf16_bits(_dense_f32(tensor))
+
+
+class _Job:
+ """One source tensor -> its output tensors, planned from shapes alone and produced on demand."""
+
+ def __init__(self, tensor: Any, outputs: list[tuple[str, str, list[int]]], produce: Callable):
+ self.tensor = tensor
+ self.outputs = outputs
+ self.produce = produce
+
+
+def _scale_store(a: np.ndarray, scale_dtype: str) -> np.ndarray:
+ if scale_dtype == "f16":
+ return np.ascontiguousarray(a, dtype = np.float32).astype(np.float16)
+ return _f32_to_bf16_bits(a)
+
+
+def _plan(reader: Any, *, dense_bits: int, scale_dtype: str) -> tuple[list[_Job], dict]:
+ sdt = "F16" if scale_dtype == "f16" else "BF16"
+ jobs: list[_Job] = []
+ bits_count = {4: 0, 8: 0}
+ for tensor in reader.tensors:
+ kind = _type_name(tensor)
+ name = zimage_rename(str(tensor.name))
+ dims = _gguf_dims(tensor)
+ if kind in _BLOCK_BYTES:
+ if not name.endswith(".weight"):
+ raise UnsupportedGGUFError(f"quantized tensor {tensor.name} is not a .weight")
+ cols = dims[-1]
+ rows = int(np.prod(dims[:-1])) if len(dims) > 1 else 1
+ bits = _BLOCK_BITS[kind]
+ bits_count[bits] += 1
+ base = name[: -len(".weight")]
+ parts = [(base, 0, rows)]
+ if base.endswith(".attention.qkv"):
+ if rows % 3:
+ raise UnsupportedGGUFError(
+ f"{tensor.name}: {rows} rows do not split into q/k/v"
+ )
+ n = rows // 3
+ stem = base[: -len("qkv")]
+ parts = [(stem + p, i * n, (i + 1) * n) for i, p in enumerate(_QKV_PARTS)]
+ outputs = []
+ for nm, a, b in parts:
+ r = b - a
+ outputs += [
+ (nm + ".weight", "U32", [r, cols * bits // 32]),
+ (nm + ".scales", sdt, [r, cols // GROUP_SIZE]),
+ (nm + ".biases", sdt, [r, cols // GROUP_SIZE]),
+ ]
+
+ def produce(
+ tensor = tensor,
+ kind = kind,
+ rows = rows,
+ cols = cols,
+ parts = parts,
+ ):
+ w, s, b, _bits = affine_from_ggml(kind, tensor.data, rows, cols)
+ for _nm, lo, hi in parts:
+ yield np.ascontiguousarray(w[lo:hi])
+ yield _scale_store(s[lo:hi], scale_dtype)
+ yield _scale_store(b[lo:hi], scale_dtype)
+
+ jobs.append(_Job(tensor, outputs, produce))
+ continue
+ if name in _PAD_TOKENS:
+ dims = [1, int(np.prod(dims))]
+ quantize = (
+ dense_bits
+ and len(dims) == 2
+ and name.endswith(".weight")
+ and dims[-1] % GROUP_SIZE == 0
+ and name not in _PAD_TOKENS
+ )
+ if name.endswith(".attention.qkv.weight"):
+ if dims[0] % 3:
+ raise UnsupportedGGUFError(f"{tensor.name}: {dims[0]} rows do not split into q/k/v")
+ n = dims[0] // 3
+ stem = name[: -len("qkv.weight")]
+ parts = [(stem + p, i * n, (i + 1) * n) for i, p in enumerate(_QKV_PARTS)]
+ else:
+ parts = [(name[: -len(".weight")] if quantize else name, 0, dims[0] if dims else 1)]
+ outputs = []
+ for nm, a, b in parts:
+ r = b - a
+ if quantize:
+ bits_count[dense_bits] += 1
+ outputs += [
+ (nm + ".weight", "U32", [r, dims[-1] * dense_bits // 32]),
+ (nm + ".scales", sdt, [r, dims[-1] // GROUP_SIZE]),
+ (nm + ".biases", sdt, [r, dims[-1] // GROUP_SIZE]),
+ ]
+ elif len(parts) > 1:
+ outputs.append((nm + ".weight", "BF16", [r, *dims[1:]]))
+ else:
+ outputs.append((nm, "BF16", list(dims)))
+
+ def produce_dense(
+ tensor = tensor,
+ dims = dims,
+ parts = parts,
+ quantize = quantize,
+ ):
+ if quantize:
+ full = _dense_f32(tensor).reshape(dims)
+ for _nm, lo, hi in parts:
+ w, s, b = quantize_dense_affine(round_to_bf16(full[lo:hi]), dense_bits)
+ yield w
+ yield _scale_store(s, scale_dtype)
+ yield _scale_store(b, scale_dtype)
+ return
+ bits16 = _dense_bf16_bits(tensor).reshape(dims)
+ for _nm, lo, hi in parts:
+ yield np.ascontiguousarray(bits16[lo:hi] if len(parts) > 1 else bits16)
+
+ jobs.append(_Job(tensor, outputs, produce_dense))
+ return jobs, bits_count
+
+
+def _check_types(reader: Any) -> dict[str, int]:
+ counts: dict[str, int] = {}
+ for tensor in reader.tensors:
+ kind = _type_name(tensor)
+ counts[kind] = counts.get(kind, 0) + 1
+ bad = {k: v for k, v in counts.items() if k not in CONVERTIBLE_TYPES}
+ if bad:
+ listed = ", ".join(f"{v} x {k}" for k, v in sorted(bad.items()))
+ raise UnsupportedGGUFError(
+ f"GGUF holds tensor types MLX conversion does not support yet: {listed} "
+ "(supported: Q4_0, Q4_1, Q8_0, BF16, F16, F32)"
+ )
+ return counts
+
+
+# ── Writer ──────────────────────────────────────────────────────────────────────────────────────
+
+
+def _nbytes(dtype: str, shape: list[int]) -> int:
+ return int(np.prod(shape)) * _ST_DTYPE_BYTES[dtype] if shape else _ST_DTYPE_BYTES[dtype]
+
+
+def _header_bytes(entries: list[tuple[str, str, list[int]]], metadata: dict[str, str]) -> bytes:
+ header: dict[str, Any] = {"__metadata__": metadata}
+ offset = 0
+ for name, dtype, shape in entries:
+ size = _nbytes(dtype, shape)
+ header[name] = {"dtype": dtype, "shape": shape, "data_offsets": [offset, offset + size]}
+ offset += size
+ blob = json.dumps(header, separators = (",", ":")).encode("utf-8")
+ blob += b" " * ((-len(blob)) % 8)
+ return blob
+
+
+def convert_gguf_to_mflux(
+ gguf_path: os.PathLike | str,
+ out_dir: os.PathLike | str,
+ *,
+ dense_bits: int = 0,
+ scale_dtype: str = "bf16",
+ cancel_event: Any = None,
+ progress: Optional[Callable[[int, int], None]] = None,
+) -> dict[str, Any]:
+ """Refuses unsupported types before writing; lands the file atomically, marker last."""
+ from gguf import GGUFReader
+
+ if dense_bits not in (0, 4, 8):
+ raise ValueError(f"dense_bits must be 0, 4 or 8, not {dense_bits}")
+ if scale_dtype not in ("bf16", "f16"):
+ raise ValueError(f"scale_dtype must be 'bf16' or 'f16', not {scale_dtype!r}")
+ started = time.perf_counter()
+ gguf_path = Path(gguf_path)
+ reader = GGUFReader(str(gguf_path))
+ counts = _check_types(reader)
+ jobs, bits_count = _plan(reader, dense_bits = dense_bits, scale_dtype = scale_dtype)
+ entries = [entry for job in jobs for entry in job.outputs]
+ names = [e[0] for e in entries]
+ if len(set(names)) != len(names):
+ raise UnsupportedGGUFError("tensor names collide after the mflux rename")
+ if bits_count[4] or bits_count[8]:
+ level = "8" if bits_count[8] > bits_count[4] else "4"
+ else:
+ level = "None"
+ metadata = {
+ "quantization_level": level,
+ "mflux_version": MFLUX_VERSION,
+ "source_gguf": gguf_path.name,
+ "unsloth_converter": CONVERTER_VERSION,
+ }
+ header = _header_bytes(entries, metadata)
+
+ target_dir = Path(out_dir) / "transformer"
+ target_dir.mkdir(parents = True, exist_ok = True)
+ final = target_dir / OUTPUT_FILENAME
+ marker = target_dir / MARKER_FILENAME
+ # A stale marker must not vouch for the file this run is about to replace.
+ with _suppress_missing():
+ marker.unlink()
+ tmp = target_dir / f".{OUTPUT_FILENAME}.{os.getpid()}.tmp"
+ total = len(jobs)
+ written = 0
+ try:
+ with open(tmp, "wb") as fh:
+ fh.write(struct.pack("<Q", len(header)))
+ fh.write(header)
+ for index, job in enumerate(jobs):
+ if cancel_event is not None and cancel_event.is_set():
+ raise RuntimeError("cancelled")
+ produced = list(job.produce())
+ if len(produced) != len(job.outputs):
+ raise RuntimeError(f"{job.tensor.name}: produced {len(produced)} tensors")
+ for (name, dtype, shape), array in zip(job.outputs, produced):
+ data = np.ascontiguousarray(array)
+ if list(data.shape) != list(shape) or data.nbytes != _nbytes(dtype, shape):
+ raise RuntimeError(
+ f"{name}: produced {data.dtype}{list(data.shape)}, planned {dtype}{shape}"
+ )
+ fh.write(data.tobytes())
+ written += data.nbytes
+ if progress is not None:
+ progress(index + 1, total)
+ os.replace(tmp, final)
+ except BaseException:
+ with _suppress_missing():
+ tmp.unlink()
+ raise
+ out_bytes = final.stat().st_size
+ stat = gguf_path.stat()
+ summary = {
+ "converter_version": CONVERTER_VERSION,
+ "source_gguf": gguf_path.name,
+ "source_size": int(stat.st_size),
+ "source_mtime": float(stat.st_mtime),
+ "counts": counts,
+ "dense_bits": dense_bits,
+ "scale_dtype": scale_dtype,
+ "quantization_level": level,
+ "n_out_tensors": len(entries),
+ "output_bytes": int(out_bytes),
+ "bytes": int(written),
+ "seconds": round(time.perf_counter() - started, 3),
+ }
+ marker_tmp = target_dir / f".{MARKER_FILENAME}.{os.getpid()}.tmp"
+ marker_tmp.write_text(json.dumps(summary, indent = 1), encoding = "utf-8")
+ os.replace(marker_tmp, marker)
+ return summary
+
+
+class _suppress_missing:
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb):
+ return exc_type is not None and issubclass(exc_type, FileNotFoundError)
+
+
+# ── Cache layout ────────────────────────────────────────────────────────────────────────────────
+
+
+def _safe(text: str) -> str:
+ out = re.sub(r"[^A-Za-z0-9._@-]+", "_", str(text).replace("\\", "/").replace("/", "--"))
+ return "_" if out in ("", ".", "..") else out
+
+
+def cache_dir_for(
+ repo_id: str,
+ revision: Optional[str],
+ gguf_filename: str,
+ *,
+ dense_bits: int,
+ scale_dtype: str = "bf16",
+) -> Path:
+ """``<studio cache>/mlx_diffusion/<repo>@<revision>/<gguf stem>-d<bits>-<scale dtype>``."""
+ from utils.paths.storage_roots import cache_root
+
+ stem = str(gguf_filename)
+ if stem.lower().endswith(".gguf"):
+ stem = stem[: -len(".gguf")]
+ return (
+ cache_root()
+ / "mlx_diffusion"
+ / f"{_safe(repo_id)}@{_safe(revision or 'local')}"
+ / f"{_safe(stem)}-d{int(dense_bits)}-{_safe(scale_dtype)}"
+ )
+
+
+def conversion_complete(
+ out_dir: os.PathLike | str, *, source_path: Optional[os.PathLike | str] = None
+) -> bool:
+ target_dir = Path(out_dir) / "transformer"
+ try:
+ marker = json.loads((target_dir / MARKER_FILENAME).read_text(encoding = "utf-8"))
+ size = (target_dir / OUTPUT_FILENAME).stat().st_size
+ except (OSError, ValueError):
+ return False
+ if not isinstance(marker, dict) or marker.get("converter_version") != CONVERTER_VERSION:
+ return False
+ if int(marker.get("output_bytes", -1)) != size:
+ return False
+ if source_path is not None:
+ try:
+ stat = Path(source_path).stat()
+ except OSError:
+ return False
+ if int(marker.get("source_size", -1)) != int(stat.st_size):
+ return False
+ if abs(float(marker.get("source_mtime", -1.0)) - float(stat.st_mtime)) > 1e-3:
+ return False
+ return True
diff --git a/studio/backend/core/inference/sd_cpp_engine.py b/studio/backend/core/inference/sd_cpp_engine.py
index fbf501003e9..fb46434fb72 100644
--- a/studio/backend/core/inference/sd_cpp_engine.py
+++ b/studio/backend/core/inference/sd_cpp_engine.py
@@ -972,6 +972,8 @@ class SdCppEngine:
ENGINE_DIFFUSERS = "diffusers"
ENGINE_SD_CPP = "sd_cpp"
+# Opt-in Apple Silicon MLX engine (core.inference.mlx_diffusion_backend), chosen only by the router, never here.
+ENGINE_MLX = "mlx"
# Backends diffusers serves well with GPU acceleration; everything else is native-engine territory.
_GPU_BACKENDS = frozenset({"cuda", "rocm", "xpu"})
diff --git a/studio/backend/main.py b/studio/backend/main.py
index cff05fccf0b..834e25e99d6 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -2012,6 +2012,7 @@ _MEDIA_BACKEND_MODULES = (
"core.inference.video",
"core.inference.diffusion",
"core.inference.sd_cpp_backend",
+ "core.inference.mlx_diffusion_backend",
"routes.inference",
)
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index dd4efddca6f..a9a8878791e 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -5245,7 +5245,10 @@ class DiffusionStatusResponse(BaseModel):
"max_output_side, max_output_pixels, reference_resolutions and localized_edit_modes. "
"Null when nothing is loaded.",
)
- engine: Optional[str] = Field(None, description = "Active diffusion engine: diffusers | sd_cpp")
+ engine: Optional[str] = Field(
+ None,
+ description = "Active diffusion engine: diffusers | sd_cpp | mlx (opt-in, Apple Silicon)",
+ )
native_mode: Optional[str] = Field(
None,
description = "Native sd.cpp execution mode: server (resident sd-server) | oneshot "
@@ -5255,6 +5258,11 @@ class DiffusionStatusResponse(BaseModel):
None,
description = "Why diffusers was chosen over the native sd.cpp engine (null when none)",
)
+ mlx_fallback_reason: Optional[str] = Field(
+ None,
+ description = "Why UNSLOTH_DIFFUSION_MLX=1 did not get the MLX engine on the last load (null when "
+ "MLX was not requested or is in use)",
+ )
supports_lora: bool = Field(
False,
description = "Whether the loaded model + quantisation can apply LoRA adapters (drives the "
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index d92fd4a5362..4e30efe9ef0 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -46236,6 +46236,14 @@ def _refuse_native_component_files(request: DiffusionLoadRequest) -> None:
)
+def _refuse_mlx_loras(request: DiffusionLoadRequest) -> None:
+ if request.loras:
+ raise HTTPException(
+ status_code = 400,
+ detail = "LoRA adapters are not supported on the MLX engine yet.",
+ )
+
+
@studio_router.post("/images/download-plan", response_model = DiffusionDownloadPlanResponse)
async def diffusion_download_plan(
request: DiffusionLoadRequest, current_subject: str = Depends(get_current_subject)
@@ -46265,7 +46273,7 @@ async def diffusion_download_plan(
resolve_model_kind,
)
from core.inference.diffusion_engine_router import predict_engine
- from core.inference.sd_cpp_engine import ENGINE_SD_CPP
+ from core.inference.sd_cpp_engine import ENGINE_MLX, ENGINE_SD_CPP
from utils.native_path_leases import redact_native_paths
backend = get_diffusion_backend()
@@ -46317,13 +46325,27 @@ async def diffusion_download_plan(
gpu_ordinal = await _selected_gpu_ordinal(request.gpu_ids, allow_ranking = not training)
# Plan for the engine /images/load will pick: a GGUF on a GPU-less host routes to native
# sd.cpp, which reads different files. Card-scoped, since the failure records are per card.
- if (
- fam is not None
- and predict_engine(fam, model_kind = kind, gpu_ordinal = gpu_ordinal) == ENGINE_SD_CPP
- ):
+ predicted = (
+ predict_engine(
+ fam,
+ model_kind = kind,
+ gpu_ordinal = gpu_ordinal,
+ gguf_filename = request.gguf_filename,
+ )
+ if fam is not None
+ else None
+ )
+ if predicted == ENGINE_SD_CPP:
_refuse_native_component_files(request)
from core.inference.sd_cpp_backend import get_sd_cpp_backend
planner = get_sd_cpp_backend()
+ elif predicted == ENGINE_MLX:
+ # Opt-in MLX engine (UNSLOTH_DIFFUSION_MLX=1): same single-GGUF contract as native.
+ _refuse_native_component_files(request)
+ _refuse_mlx_loras(request)
+ from core.inference.mlx_diffusion_backend import get_mlx_diffusion_backend
+
+ planner = get_mlx_diffusion_backend()
if fam is not None and not training:
if planner is backend:
await asyncio.to_thread(
@@ -46526,7 +46548,7 @@ async def load_diffusion_model_gated(
from core.inference.media_keepwarm import note_load_origin as note_media_load_origin
from hub.utils.gguf import extract_quant_token
from core.inference.sd_cpp_args import forces_cpu_backend
- from core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_SD_CPP
+ from core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_MLX, ENGINE_SD_CPP
from utils.native_path_leases import redact_native_paths
backend = get_diffusion_backend()
@@ -46592,12 +46614,20 @@ async def load_diffusion_model_gated(
try:
# Card-scoped like the activation below, or the wrong engine's preflight runs.
pending_name = (
- predict_engine(fam, model_kind = kind, gpu_ordinal = gpu_ordinal)
+ predict_engine(
+ fam,
+ model_kind = kind,
+ gpu_ordinal = gpu_ordinal,
+ gguf_filename = request.gguf_filename,
+ )
if fam is not None
else None
)
except Exception: # noqa: BLE001 -- a probe failure must not refuse a loadable pick
pending_name = None
+ # MLX drives the Apple GPU itself even where torch resolved "cpu": take the arbiter.
+ if pending_name == ENGINE_MLX:
+ needs_gpu = True
# Before selection: switching to diffusers would unload the resident off-torch model, then refuse.
if off_torch is not None and pending_name != ENGINE_SD_CPP:
_guard_diffusion_load_against_training()
@@ -46621,8 +46651,11 @@ async def load_diffusion_model_gated(
repo_id = request.model_path,
base_repo = request.base_repo,
)
- elif fam is not None and pending_name == ENGINE_SD_CPP:
+ elif fam is not None and pending_name in (ENGINE_SD_CPP, ENGINE_MLX):
+ # The opt-in MLX engine shares the native contract: one GGUF, no dense-quant knobs.
_refuse_native_component_files(request)
+ if pending_name == ENGINE_MLX:
+ _refuse_mlx_loras(request)
# The native engine accepts both knobs for interface parity and ignores them. It was
# excluded from the gate above so as not to refuse loads that work today, but the
# loads it "works" for are precisely the silent mismatch this whole change exists to
@@ -46668,6 +46701,8 @@ async def load_diffusion_model_gated(
before_fallback = (
_guard_diffusion_load_against_training if off_torch is not None else None
),
+ # Only the opt-in MLX engine reads it (to judge the GGUF quant).
+ gguf_filename = request.gguf_filename,
)
)
# predict_engine is selection's read-only twin: it never installs, so a host whose sd-cli
@@ -46684,8 +46719,10 @@ async def load_diffusion_model_gated(
# only when the prediction was inconclusive or wrong; a correct one already paid it.
activated = active_engine_name()
if fam is not None and activated != pending_name:
- if activated == ENGINE_SD_CPP:
+ if activated in (ENGINE_SD_CPP, ENGINE_MLX):
_refuse_native_component_files(request)
+ if activated == ENGINE_MLX:
+ _refuse_mlx_loras(request)
_assert_native_precision_unset(
transformer_quant = request.transformer_quant,
text_encoder_quant = request.text_encoder_quant,
@@ -46709,6 +46746,8 @@ async def load_diffusion_model_gated(
needs_gpu = False
else:
_guard_diffusion_load_against_training()
+ if activated == ENGINE_MLX:
+ needs_gpu = True
# sd.cpp runs a paravirtual Mac GPU on the CPU backend, so it takes no DIFFUSION claim.
if (
activated == ENGINE_SD_CPP
diff --git a/studio/backend/tests/test_comfy_auto_text_encoders.py b/studio/backend/tests/test_comfy_auto_text_encoders.py
index 3b5093bdc41..faf52f299fe 100644
--- a/studio/backend/tests/test_comfy_auto_text_encoders.py
+++ b/studio/backend/tests/test_comfy_auto_text_encoders.py
@@ -240,3 +240,40 @@ def test_download_plan_drops_the_base_encoder_a_comfy_file_replaces(tmp_path, mo
memory_verdict = False,
)
assert "text_encoder" in seen["skip_te_components"]
+
+
+def test_the_mlx_plan_keeps_the_base_encoder_it_always_opens(tmp_path, monkeypatch):
+ """The MLX loader reads the base repo's text_encoder/, so its plan never trades it for a single file."""
+ from core.inference import diffusion
+ from core.inference import mlx_diffusion_backend as mb
+
+ models = tmp_path / "ComfyUI" / "models"
+ for name in ("diffusion_models", "text_encoders", "vae", "loras"):
+ (models / name).mkdir(parents = True, exist_ok = True)
+ (models / "diffusion_models" / "z-image-turbo-Q4_K_M.gguf").write_bytes(b"x")
+ te = _encoder_file(models / "text_encoders" / "qwen_3_4b.safetensors")
+ base = _base(tmp_path)
+ seen = []
+
+ def _estimate(*args, **kwargs):
+ seen.append(tuple(kwargs["skip_te_components"]))
+ return 0, []
+
+ monkeypatch.setattr(
+ diffusion.DiffusionBackend, "_estimate_download_bytes", staticmethod(_estimate)
+ )
+ monkeypatch.setattr(diffusion, "_resolve_base_repo", lambda *a, **k: base)
+ backend = diffusion.DiffusionBackend.__new__(diffusion.DiffusionBackend)
+ monkeypatch.setattr(diffusion, "get_diffusion_backend", lambda: backend)
+ pick = dict(
+ gguf_filename = "z-image-turbo-Q4_K_M.gguf",
+ model_kind = "gguf",
+ allow_device_probe = False,
+ )
+ backend.download_plan(str(models / "diffusion_models"), memory_verdict = False, **pick)
+ mb.MlxDiffusionBackend().download_plan(str(models / "diffusion_models"), **pick)
+ mb.MlxDiffusionBackend().download_plan(
+ str(models / "diffusion_models"), text_encoder_files = [te], **pick
+ )
+ assert "text_encoder" in seen[0]
+ assert all("text_encoder" not in skip for skip in seen[1:])
diff --git a/studio/backend/tests/test_diffusion_mlx_engine_router.py b/studio/backend/tests/test_diffusion_mlx_engine_router.py
new file mode 100644
index 00000000000..0e6258bfe25
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_mlx_engine_router.py
@@ -0,0 +1,433 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Router matrix for the opt-in MLX image engine: defaults unchanged, refusals fall back, predict == select."""
+
+from __future__ import annotations
+
+import sys
+from types import SimpleNamespace
+
+import pytest
+
+from core.inference import diffusion_engine_router as r
+from core.inference.diffusion_families import detect_family
+from core.inference.sd_cpp_engine import ENGINE_DIFFUSERS, ENGINE_MLX, ENGINE_SD_CPP
+
+_ENVS = (
+ "UNSLOTH_DIFFUSION_ENGINE",
+ "UNSLOTH_DIFFUSION_SD_CPP",
+ "UNSLOTH_DIFFUSION_SD_CPP_MPS",
+ "UNSLOTH_DIFFUSION_SD_CPP_INSTALL",
+ "UNSLOTH_DIFFUSION_MLX",
+)
+_Q4 = "z-image-turbo-Q4_0.gguf"
+
+
[email protected](autouse = True)
+def _clean(monkeypatch):
+ r._supported_family_capabilities.cache_clear()
+ for e in _ENVS:
+ monkeypatch.delenv(e, raising = False)
+ monkeypatch.setattr(
+ r,
+ "get_active_diffusion_engine",
+ lambda: SimpleNamespace(
+ status = lambda: {"loaded": False, "repo_id": None}, unload = lambda: None
+ ),
+ )
+ # No sd.cpp binary anywhere and no install: today's MPS / CPU choice is then diffusers, never a real exec.
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_INSTALL", "0")
+ monkeypatch.setattr(r, "ensure_sd_server_binary", lambda **_: None)
+ monkeypatch.setattr(r, "ensure_sd_cpp_binary", lambda **_: None)
+ monkeypatch.setattr(r, "_server_binary_runnable", lambda *_a, **_k: False)
+ saved = (r._active_engine_name, r._fallback_reason, r._mlx_fallback_reason)
+ try:
+ yield
+ finally:
+ r._active_engine_name, r._fallback_reason, r._mlx_fallback_reason = saved
+ r._supported_family_capabilities.cache_clear()
+
+
+def _device(monkeypatch, backend):
+ monkeypatch.setattr(
+ r,
+ "resolve_diffusion_device_target",
+ lambda: SimpleNamespace(backend = backend, device = backend),
+ )
+
+
+def _host(
+ monkeypatch,
+ *,
+ system = "darwin",
+ machine = "arm64",
+ macos = "15.1",
+):
+ monkeypatch.setattr(r, "sys", SimpleNamespace(platform = system, modules = sys.modules))
+ monkeypatch.setattr(
+ r,
+ "platform",
+ SimpleNamespace(machine = lambda: machine, mac_ver = lambda: (macos, ("", "", ""), "")),
+ )
+
+
+_GOOD_VERSIONS = {
+ "mflux": "0.22.0",
+ "mlx": "0.32.3",
+ "piexif": "1.1.3",
+ "platformdirs": "4.3.8",
+ "toml": "0.10.2",
+}
+
+
+def _runtime(
+ monkeypatch,
+ *,
+ mlx = True,
+ mflux = True,
+ versions = None,
+):
+ present = {"mlx": mlx, "mflux": mflux}
+ versions = {**_GOOD_VERSIONS, **(versions or {})}
+ monkeypatch.setattr(r, "_installed_version", versions.get)
+ real_find_spec = r.importlib.util.find_spec
+ monkeypatch.setattr(
+ r,
+ "importlib",
+ SimpleNamespace(
+ util = SimpleNamespace(
+ find_spec = lambda name, *a, **k: (
+ (object() if present[name] else None)
+ if name in present
+ else real_find_spec(name, *a, **k)
+ )
+ )
+ ),
+ )
+
+
+def _apple(monkeypatch, backend = "mps"):
+ _host(monkeypatch)
+ _device(monkeypatch, backend)
+ _runtime(monkeypatch)
+
+
+def _select(
+ fam = "z-image",
+ gguf = _Q4,
+ kind = "gguf",
+):
+ r.select_and_activate_engine(detect_family(fam), model_kind = kind, gguf_filename = gguf)
+ return r.active_engine_name()
+
+
+def _predict(
+ fam = "z-image",
+ gguf = _Q4,
+ kind = "gguf",
+):
+ return r.predict_engine(detect_family(fam), model_kind = kind, gguf_filename = gguf)
+
+
+# ── opt-in on a capable Mac picks MLX ────────────────────────────────────────
+
+
[email protected]("value", ["1", "on", "true", "yes"])
+ "gguf",
+ [
+ _Q4,
+ "z-image-turbo-Q4_1.gguf",
+ "z-image-turbo-Q8_0.gguf",
+ "z-image-turbo-BF16.gguf",
+ ],
+)
+def test_opt_in_on_apple_silicon_picks_mlx(monkeypatch, value, gguf):
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", value)
+ assert _predict(gguf = gguf) == ENGINE_MLX
+ assert _select(gguf = gguf) == ENGINE_MLX
+ status = r.annotate_status({"loaded": False})
+ assert status["engine"] == ENGINE_MLX
+ assert status["mlx_fallback_reason"] is None
+ assert status["fallback_reason"] is None
+
+
+def test_opt_in_on_the_mps_less_cpu_backend_still_picks_mlx(monkeypatch):
+ # A Mac whose torch has no MPS resolves "cpu"; MLX drives the GPU itself.
+ _apple(monkeypatch, backend = "cpu")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ assert _predict() == _select() == ENGINE_MLX
+
+
+# ── default unchanged: unset / 0 / auto never consult MLX ────────────────────
+
+
[email protected]("value", [None, "0", "off", "auto", "AUTO", "garbage"])
+def test_default_and_auto_keep_todays_engine(monkeypatch, value):
+ _apple(monkeypatch)
+ if value is not None:
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", value)
+
+ def _no_probe(*_a, **_k):
+ raise AssertionError("MLX must not be probed when it was not asked for")
+
+ monkeypatch.setattr(r, "_mlx_runtime_refusal", _no_probe)
+ monkeypatch.setattr(r, "_mlx_host_refusal", _no_probe)
+ assert _predict() == ENGINE_DIFFUSERS
+ assert _select() == ENGINE_DIFFUSERS
+ status = r.annotate_status({})
+ assert status["mlx_fallback_reason"] is None
+ # Today's reason, untouched.
+ assert status["fallback_reason"] == "GPU backend 'mps' uses diffusers"
+
+
+def test_default_keeps_sd_cpp_where_sd_cpp_is_chosen_today(monkeypatch):
+ _host(monkeypatch)
+ _device(monkeypatch, "mps")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MPS", "1")
+ monkeypatch.setattr(r, "ensure_sd_cpp_binary", lambda **_: "/usr/bin/sd-cli")
+ monkeypatch.setattr(r, "SdCppEngine", lambda **_: SimpleNamespace(version = lambda: "v0"))
+ assert _predict() == ENGINE_SD_CPP
+ assert _select() == ENGINE_SD_CPP
+
+
+# ── refusals fall back to today's engine and say why ─────────────────────────
+
+
+ "fam, gguf, kind, needle",
+ [
+ ("sdxl", "sdxl-Q4_0.gguf", "gguf", "no MLX implementation"),
+ ("qwen-image", "qwen-image-Q4_0.gguf", "gguf", "no MLX implementation"),
+ ("z-image", "z-image-turbo-Q4_K_M.gguf", "gguf", "Q4_K_M"),
+ ("z-image", "z-image-turbo-Q6_K.gguf", "gguf", "Q6_K"),
+ ("z-image", "z-image-turbo-UD-Q4_K_XL.gguf", "gguf", "not convertible"),
+ ("z-image", None, "gguf", "unknown"),
+ ("z-image", None, "pipeline", "GGUF picks only"),
+ ("z-image", "model.safetensors", "single_file", "GGUF picks only"),
+ ],
+)
+def test_unsupported_family_quant_or_kind_falls_back_with_reason(
+ monkeypatch, fam, gguf, kind, needle
+):
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ predicted = _predict(fam, gguf, kind)
+ chosen = _select(fam, gguf, kind)
+ assert predicted == chosen == ENGINE_DIFFUSERS
+ reason = r.annotate_status({})["mlx_fallback_reason"] or ""
+ assert needle in reason
+
+
+ "host, needle",
+ [
+ ({"system": "linux", "machine": "x86_64"}, "macOS only"),
+ ({"system": "linux", "machine": "aarch64"}, "macOS only"),
+ ({"system": "win32", "machine": "AMD64"}, "macOS only"),
+ ({"system": "darwin", "machine": "x86_64"}, "Apple Silicon"),
+ ({"system": "darwin", "machine": "arm64", "macos": "13.6"}, "macOS 14"),
+ ({"system": "darwin", "machine": "arm64", "macos": ""}, "macOS 14"),
+ ],
+)
+def test_non_apple_silicon_hosts_never_get_mlx(monkeypatch, host, needle):
+ _host(monkeypatch, **host)
+ _device(monkeypatch, "cpu")
+ _runtime(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ assert _predict() == _select() == ENGINE_DIFFUSERS
+ assert needle in (r.annotate_status({})["mlx_fallback_reason"] or "")
+
+
[email protected]("gpu", ["cuda", "rocm", "xpu"])
+def test_gpu_backends_never_get_mlx(monkeypatch, gpu):
+ _host(monkeypatch)
+ _device(monkeypatch, gpu)
+ _runtime(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ assert _predict() == _select() == ENGINE_DIFFUSERS
+ assert "not Apple MPS" in (r.annotate_status({})["mlx_fallback_reason"] or "")
+
+
+def test_real_linux_host_never_gets_mlx(monkeypatch):
+ # No host stubs at all: this suite runs on Linux CI.
+ if sys.platform == "darwin":
+ pytest.skip("checks the real non-macOS host")
+ _device(monkeypatch, "cpu")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ assert _predict() != ENGINE_MLX
+ assert _select() != ENGINE_MLX
+ assert "macOS only" in (r.annotate_status({})["mlx_fallback_reason"] or "")
+
+
+ "mlx, mflux, needle",
+ [
+ (False, True, "mlx not installed"),
+ (True, False, "mflux not installed"),
+ (False, False, "mlx and mflux"),
+ ],
+)
+def test_missing_runtime_falls_back(monkeypatch, mlx, mflux, needle):
+ _host(monkeypatch)
+ _device(monkeypatch, "mps")
+ _runtime(monkeypatch, mlx = mlx, mflux = mflux)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ assert _predict() == _select() == ENGINE_DIFFUSERS
+ assert needle in (r.annotate_status({})["mlx_fallback_reason"] or "")
+
+
+ "versions, needle",
+ [
+ ({"mflux": "0.17.0"}, "mflux==0.22.0 (found 0.17.0)"),
+ ({"mlx": "0.29.1"}, "mlx>=0.32.0,<0.33.0 (found 0.29.1)"),
+ ({"mlx": None}, "mlx>=0.32.0,<0.33.0 (found none)"),
+ ({"toml": None}, "toml>=0.10.2,<1 (found none)"),
+ ({"platformdirs": "5.0.0"}, "platformdirs>=4,<5 (found 5.0.0)"),
+ ],
+)
+def test_an_incompatible_installed_runtime_falls_back(monkeypatch, versions, needle):
+ # An older mflux left behind by a failed upgrade still imports; selection must read the installed versions.
+ _host(monkeypatch)
+ _device(monkeypatch, "mps")
+ _runtime(monkeypatch, versions = versions)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ assert _predict() == _select() == ENGINE_DIFFUSERS
+ assert needle in (r.annotate_status({})["mlx_fallback_reason"] or "")
+
+
[email protected]("forced", ["diffusers", "sd_cpp"])
+def test_forced_engine_overrides_the_opt_in(monkeypatch, forced):
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_ENGINE", forced)
+ assert _predict() != ENGINE_MLX
+ assert _select() != ENGINE_MLX
+ assert "overrides" in (r.annotate_status({})["mlx_fallback_reason"] or "")
+
+
+def test_refusal_falls_through_to_sd_cpp_when_that_is_todays_choice(monkeypatch):
+ # A K-quant on a CPU-backend Mac with a runnable sd-cli stays on sd.cpp, exactly as without the opt-in.
+ _apple(monkeypatch, backend = "cpu")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ monkeypatch.setattr(r, "ensure_sd_cpp_binary", lambda **_: "/usr/bin/sd-cli")
+ monkeypatch.setattr(r, "SdCppEngine", lambda **_: SimpleNamespace(version = lambda: "v0"))
+ gguf = "z-image-turbo-Q4_K_M.gguf"
+ assert _predict(gguf = gguf) == _select(gguf = gguf) == ENGINE_SD_CPP
+ assert "Q4_K_M" in (r.annotate_status({})["mlx_fallback_reason"] or "")
+
+
+def test_a_later_default_selection_clears_the_mlx_reason(monkeypatch):
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ _select(gguf = "z-image-turbo-Q4_K_M.gguf")
+ assert r.annotate_status({})["mlx_fallback_reason"]
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_MLX")
+ _select()
+ assert r.annotate_status({})["mlx_fallback_reason"] is None
+
+
+# ── predict == select on the whole matrix ────────────────────────────────────
+
+
[email protected]("env", [None, "0", "auto", "1"])
[email protected]("backend", ["mps", "cpu", "cuda"])
[email protected]("gguf", [_Q4, "z-image-turbo-Q4_K_M.gguf", None])
[email protected]("fam", ["z-image", "flux.1"])
+def test_predict_matches_selection(monkeypatch, env, backend, gguf, fam):
+ _host(monkeypatch)
+ _device(monkeypatch, backend)
+ _runtime(monkeypatch)
+ if env is not None:
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", env)
+ predicted = _predict(fam, gguf)
+ r._active_engine_name = ENGINE_DIFFUSERS
+ assert _select(fam, gguf) == predicted
+ expect_mlx = env == "1" and backend != "cuda" and gguf == _Q4 and fam == "z-image"
+ assert (predicted == ENGINE_MLX) is expect_mlx
+
+
+# ── engine plumbing ──────────────────────────────────────────────────────────
+
+
+def test_engine_for_mlx_is_the_mlx_singleton():
+ from core.inference import mlx_diffusion_backend as mb
+
+ engine = r.engine_for(ENGINE_MLX)
+ assert isinstance(engine, mb.MlxDiffusionBackend)
+ assert engine is mb.get_mlx_diffusion_backend()
+
+
+def test_cancel_and_retire_scan_the_mlx_singleton(monkeypatch):
+ from core.inference import mlx_diffusion_backend as mb
+
+ calls = []
+ fake = SimpleNamespace(
+ _active_generate_account = "acct",
+ cancel_generate = lambda expected_account = None: calls.append(expected_account) or True,
+ )
+ monkeypatch.setattr(mb, "_mlx_diffusion_backend", fake)
+ assert (
+ "core.inference.mlx_diffusion_backend",
+ "_mlx_diffusion_backend",
+ ) in r._ENGINE_SINGLETONS
+ assert r.cancel_generation_for_account("acct") is True
+ assert calls == ["acct"]
+
+
+def test_switching_away_from_mlx_unloads_it(monkeypatch):
+ unloaded = []
+ monkeypatch.setattr(
+ r,
+ "get_active_diffusion_engine",
+ lambda: SimpleNamespace(status = lambda: {}, unload = lambda: unloaded.append(True)),
+ )
+ r._active_engine_name = ENGINE_MLX
+ _host(monkeypatch)
+ _device(monkeypatch, "mps")
+ assert _select() == ENGINE_DIFFUSERS
+ assert unloaded == [True]
+
+
+def test_family_buildable_here_counts_mlx_only_with_a_convertible_gguf(monkeypatch):
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ fam = detect_family("z-image")
+ monkeypatch.setattr(r, "family_pipeline_available", lambda _f: False)
+ assert r.family_buildable_here(fam, model_kind = "gguf", gguf_filename = _Q4) is True
+ assert r.family_buildable_here(fam, model_kind = "gguf") is False
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_MLX")
+ assert r.family_buildable_here(fam, model_kind = "gguf", gguf_filename = _Q4) is False
+
+
+def test_runtime_requirements_match_the_installer():
+ import ast
+ from pathlib import Path
+
+ from core.inference.mlx_diffusion_convert import MFLUX_VERSION
+
+ source = (Path(__file__).resolve().parents[2] / "install_python_stack.py").read_text()
+ literals = {
+ node.targets[0].id if isinstance(node, ast.Assign) else node.target.id: node.value
+ for node in ast.parse(source).body
+ if isinstance(node, (ast.Assign, ast.AnnAssign))
+ and isinstance(node.targets[0] if isinstance(node, ast.Assign) else node.target, ast.Name)
+ }
+ assert ast.literal_eval(literals["_MLX_DIFFUSION_PINS"]) == (f"mflux=={MFLUX_VERSION}",)
+ deps = set(ast.literal_eval(literals["_MLX_DIFFUSION_DEPS"]))
+ assert deps == {s for s in r._MLX_RUNTIME_REQUIREMENTS if not s.startswith("mlx")}
+
+
+def test_auto_switch_planner_judges_mlx_with_the_picks_gguf(monkeypatch):
+ from core.inference import media_locality
+ from core.inference.gpu_arbiter import DIFFUSION
+ from core.inference.media_model_index import MediaModelPick
+
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ monkeypatch.setattr(r, "engine_for", lambda name: name)
+ pick = MediaModelPick("unsloth/Z-Image-Turbo-GGUF", "unsloth/Z-Image-Turbo-GGUF", _Q4, "gguf")
+ assert media_locality.planners_for(DIFFUSION, pick) == [ENGINE_MLX]
diff --git a/studio/backend/tests/test_liveness_reports_inference_active.py b/studio/backend/tests/test_liveness_reports_inference_active.py
index 409181aed05..1607d80554c 100644
--- a/studio/backend/tests/test_liveness_reports_inference_active.py
+++ b/studio/backend/tests/test_liveness_reports_inference_active.py
@@ -113,6 +113,7 @@ media_modules = (
"core.inference.video",
"core.inference.diffusion",
"core.inference.sd_cpp_backend",
+ "core.inference.mlx_diffusion_backend",
"routes.inference",
)
# routes.inference is imported at startup regardless, so the ML-stack question is only
diff --git a/studio/backend/tests/test_media_auto_switch.py b/studio/backend/tests/test_media_auto_switch.py
index 41aeaeed4ce..a3b7df0e901 100644
--- a/studio/backend/tests/test_media_auto_switch.py
+++ b/studio/backend/tests/test_media_auto_switch.py
@@ -966,7 +966,7 @@ def test_the_native_fallback_is_only_verified_when_a_binary_must_be_installed(mo
router = __import__("core.inference.diffusion_engine_router", fromlist = ["x"])
families = __import__("core.inference.diffusion_families", fromlist = ["x"])
monkeypatch.setattr(families, "detect_family_for_pick", lambda *a, **k: object())
- monkeypatch.setattr(router, "predict_engine", lambda fam, model_kind = None: ENGINE_SD_CPP)
+ monkeypatch.setattr(router, "predict_engine", lambda fam, model_kind = None, **_k: ENGINE_SD_CPP)
monkeypatch.setattr(router, "engine_for", lambda name: name)
monkeypatch.setattr(router, "native_binary_installed", lambda: True)
diff --git a/studio/backend/tests/test_mlx_diffusion_backend.py b/studio/backend/tests/test_mlx_diffusion_backend.py
new file mode 100644
index 00000000000..bdfcad51c89
--- /dev/null
+++ b/studio/backend/tests/test_mlx_diffusion_backend.py
@@ -0,0 +1,1406 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Engine-surface tests for the MLX image engine with mlx / mflux stubbed out."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from pathlib import Path
+
+import pytest
+
+from core.inference import mlx_diffusion_backend as mb
+from core.inference.diffusion_families import (
+ DIFFUSION_CANCELLED_MSG,
+ DIFFUSION_NOT_LOADED_MSG,
+ _FAMILIES,
+ DiffusionModelReplacedError,
+ load_identity,
+)
+
+ZIMAGE = next(f for f in _FAMILIES if f.name == "z-image")
+
+REPO = "unsloth/Z-Image-Turbo-GGUF"
+GGUF = "z-image-turbo-Q4_0.gguf"
+_REAL_RESOLVE_VARIANT_BASE = getattr(mb, "resolve_variant_base", None)
+BASE = "Tongyi-MAI/Z-Image-Turbo"
+
+
+class FakeRuntime:
+ def __init__(self):
+ self.builds = []
+ self.generates = []
+ self.freed = 0
+ self.step_gate: threading.Event | None = None
+ self.in_step = threading.Event()
+
+ def build(self, model_path, *, model_config, precision, te_bits):
+ self.builds.append(
+ dict(
+ model_path = model_path,
+ model_config = model_config,
+ precision = precision,
+ te_bits = te_bits,
+ )
+ )
+ return {"model": model_config}
+
+ def cache_text_encodings(self, model):
+ model["cached"] = True
+
+ def supports_guidance(self, model):
+ return model["model"] == "z-image"
+
+ def generate(
+ self, model, *, prompt, negative_prompt, seed, steps, width, height, guidance, on_step
+ ):
+ from PIL import Image
+
+ self.generates.append(
+ dict(
+ prompt = prompt, seed = seed, steps = steps, width = width, height = height, guidance = guidance
+ )
+ )
+ for t in range(steps):
+ if self.step_gate is not None:
+ self.in_step.set()
+ self.step_gate.wait(5)
+ on_step(t + 1)
+ return Image.new("RGB", (width, height), (seed % 255, 0, 0))
+
+ def free(self):
+ self.freed += 1
+
+
+def env(monkeypatch, tmp_path):
+ """A backend whose fetch / convert / runtime are fakes; returns (backend, runtime, calls)."""
+ gguf_path = tmp_path / "hub" / "snapshots" / "abc123" / GGUF
+ gguf_path.parent.mkdir(parents = True)
+ gguf_path.write_bytes(b"GGUF" + b"\0" * 64)
+ base_dir = tmp_path / "base"
+ for sub in ("text_encoder", "tokenizer", "vae"):
+ (base_dir / sub).mkdir(parents = True)
+ calls = {"convert": 0, "fetch_gguf": [], "fetch_base": []}
+
+ def _fetch_gguf(repo_id, gguf_filename, hf_token, *, cancel_event, local_files_only):
+ calls["fetch_gguf"].append((repo_id, gguf_filename, local_files_only))
+ return str(gguf_path)
+
+ def _fetch_base(
+ base_repo,
+ hf_token,
+ *,
+ local_files_only,
+ cancel_event = None,
+ ):
+ calls["fetch_base"].append((base_repo, local_files_only))
+ return str(base_dir)
+
+ def _convert(
+ gguf,
+ out_dir,
+ *,
+ dense_bits,
+ cancel_event = None,
+ progress = None,
+ **_,
+ ):
+ calls["convert"] += 1
+ calls["dense_bits"] = dense_bits
+ out = Path(out_dir) / "transformer"
+ out.mkdir(parents = True, exist_ok = True)
+ (out / "0.safetensors").write_bytes(b"x" * 8)
+ (out / "unsloth_mlx_convert.json").write_text(
+ json.dumps({"source": {"size": Path(gguf).stat().st_size}, "bytes": 8})
+ )
+ if progress:
+ progress(1, 1)
+ return {"n_out_tensors": 1}
+
+ monkeypatch.setattr(mb, "fetch_gguf", _fetch_gguf)
+ monkeypatch.setattr(mb, "fetch_base_snapshot", _fetch_base)
+ # No card lookup in unit tests: the family default stands unless a test says otherwise.
+ monkeypatch.setattr(
+ mb, "resolve_variant_base", lambda *a, fallback, **k: fallback, raising = False
+ )
+ monkeypatch.setattr(mb.convert, "convert_gguf_to_mflux", _convert)
+ monkeypatch.setattr(
+ mb.convert,
+ "conversion_complete",
+ lambda d, **_k: (Path(d) / "transformer" / "0.safetensors").exists(),
+ )
+ monkeypatch.setattr(
+ mb.convert,
+ "cache_dir_for",
+ lambda repo, rev, fn, *, dense_bits, **_: tmp_path / "cache" / f"{rev}-{fn}-d{dense_bits}",
+ )
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_PRECISION", "fp16")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_TE_BITS", "4")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_DENSE_BITS", "4")
+ runtime = FakeRuntime()
+ backend = mb.MlxDiffusionBackend(runtime_factory = lambda: runtime)
+ return backend, runtime, calls
+
+
+def _wait_loaded(backend, timeout = 10.0):
+ deadline = time.time() + timeout
+ while time.time() < deadline:
+ progress = backend.load_progress()
+ if progress["phase"] in ("ready", "error"):
+ return progress
+ time.sleep(0.01)
+ raise AssertionError(f"load did not finish: {backend.load_progress()}")
+
+
+def _load(backend, **kw):
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf", **kw)
+ return _wait_loaded(backend)
+
+
+def test_surface_matches_the_other_engines():
+ from core.inference.sd_cpp_backend import SdCppDiffusionBackend
+
+ shared = {
+ "begin_load",
+ "generate",
+ "cancel_generate",
+ "unload",
+ "status",
+ "load_progress",
+ "generate_progress",
+ "loading_repo_ids",
+ "loaded_repo_ids",
+ "download_plan",
+ "preflight_base_access",
+ "is_loaded",
+ }
+ for name in shared:
+ assert hasattr(SdCppDiffusionBackend, name)
+ assert hasattr(mb.MlxDiffusionBackend, name), name
+ import inspect
+
+ sd_params = set(inspect.signature(SdCppDiffusionBackend.begin_load).parameters)
+ mlx_params = inspect.signature(mb.MlxDiffusionBackend.begin_load).parameters
+ # Every keyword the route passes to sd.cpp is accepted, and the route's extra component kwargs land in **_ignored.
+ assert sd_params <= set(mlx_params)
+ assert any(p.kind is p.VAR_KEYWORD for p in mlx_params.values())
+ assert set(inspect.signature(SdCppDiffusionBackend.generate).parameters) <= set(
+ inspect.signature(mb.MlxDiffusionBackend.generate).parameters
+ )
+
+
+def test_load_then_status_and_guards(env):
+ backend, runtime, calls = env
+ assert backend.status()["loaded"] is False
+ assert backend.status()["engine"] == "mlx"
+ assert _load(backend)["phase"] == "ready"
+ status = backend.status()
+ assert status["loaded"] and status["engine"] == "mlx"
+ assert (
+ status["repo_id"] == REPO and status["base_repo"] == BASE and status["family"] == "z-image"
+ )
+ assert status["gguf_filename"] == GGUF and status["model_kind"] == "gguf"
+ assert status["workflows"] == ["txt2img"]
+ assert status["mlx"]["precision"] == "float16" and status["mlx"]["text_encoder_bits"] == 4
+ assert runtime.builds[0]["model_config"] == "z-image-turbo"
+ model_dir = Path(runtime.builds[0]["model_path"])
+ for sub in ("text_encoder", "tokenizer", "vae"):
+ assert (model_dir / sub).is_symlink()
+ assert backend.loaded_repo_ids() == (REPO, BASE)
+ assert backend.loading_repo_ids() == ()
+ assert calls["dense_bits"] == 4
+
+
+def test_conversion_is_cached_across_loads(env):
+ backend, runtime, calls = env
+ _load(backend)
+ backend.unload()
+ _load(backend)
+ assert calls["convert"] == 1
+ assert backend.status()["mlx"]["timings"]["convert_cached"] is True
+
+
+def test_local_files_only_reaches_every_fetch(env):
+ backend, _rt, calls = env
+ _load(backend, local_files_only = True)
+ assert calls["fetch_gguf"][-1][2] is True
+ assert calls["fetch_base"][-1] == (BASE, True)
+
+
+ "kwargs, needle",
+ [
+ ({"gguf_filename": None}, "gguf_filename is required"),
+ ({"gguf_filename": "z-image-turbo-Q4_K_M.gguf"}, "Q4_K_M"),
+ ({"gguf_filename": GGUF, "model_kind": "pipeline"}, "GGUF"),
+ ({"gguf_filename": "sdxl-Q4_0.gguf", "family_override": "sdxl"}, "no MLX implementation"),
+ ({"gguf_filename": GGUF, "loras": [("a/b", 1.0)]}, "LoRA"),
+ ],
+)
+def test_begin_load_refuses_what_it_cannot_run(env, kwargs, needle):
+ backend, _rt, _calls = env
+ repo = "unsloth/SDXL-GGUF" if "sdxl" in str(kwargs.get("gguf_filename")) else REPO
+ with pytest.raises(ValueError, match = needle):
+ backend.begin_load(repo, **kwargs)
+ assert backend.loading_repo_ids() == ()
+
+
+def test_load_failure_surfaces_in_load_progress(env, monkeypatch):
+ backend, _rt, _calls = env
+
+ def _boom(*_a, **_k):
+ raise RuntimeError("converter exploded")
+
+ monkeypatch.setattr(mb.convert, "convert_gguf_to_mflux", _boom)
+ progress = _load(backend)
+ assert progress["phase"] == "error" and "converter exploded" in progress["error"]
+ assert backend.status()["loaded"] is False
+
+
+def test_generate_batch_seeds_and_progress(env):
+ backend, runtime, _calls = env
+ _load(backend)
+ seen = []
+ runtime_generate = runtime.generate
+
+ def _spy(*a, **k):
+ inner = k["on_step"]
+
+ def _on_step(n):
+ inner(n)
+ seen.append(backend.generate_progress())
+
+ k["on_step"] = _on_step
+ return runtime_generate(*a, **k)
+
+ runtime.generate = _spy
+ result = backend.generate(prompt = "a fox", width = 280, height = 270, steps = 3, seed = 7, batch_size = 2)
+ assert result["seeds"] == [7, 8] and result["seed"] == 7
+ assert len(result["images"]) == 2
+ assert result["images"][0].size == (272, 256) # rounded down to multiples of 16
+ assert (
+ result["model_kind"] == "gguf"
+ and result["gguf_filename"] == GGUF
+ and result["workflow"] == "txt2img"
+ )
+ assert [p["step"] for p in seen] == [1, 2, 3, 4, 5, 6]
+ assert all(p["active"] and p["total_steps"] == 6 for p in seen)
+ assert backend.generate_progress()["active"] is False
+ # Turbo has no CFG, so guidance is not forwarded and the negative prompt is not recorded.
+ assert runtime.generates[0]["guidance"] is None
+ assert backend.last_timings["images"][0]["s_per_step"] >= 0
+ assert mb.generation_in_flight() is False
+
+
+ "kwargs",
+ [
+ {"init_image": "data:"},
+ {"mask_image": "data:"},
+ {"reference_images": ["data:"]},
+ {"workflow": "edit"},
+ {"upscale": 2.0},
+ {"prompts": ["a", "b"]},
+ {"seeds": [1, 2]},
+ {"loras": [("x/y", 1.0)]},
+ {"controlnet": ("c", "img", "canny", 1.0, 0.0, 1.0)},
+ ],
+)
+def test_generate_refuses_unsupported_workflows(env, kwargs):
+ backend, _rt, _calls = env
+ _load(backend)
+ with pytest.raises(ValueError):
+ backend.generate(prompt = "x", steps = 1, **kwargs)
+
+
+def test_generate_without_a_model_and_with_a_replaced_model(env):
+ backend, _rt, _calls = env
+ with pytest.raises(RuntimeError, match = DIFFUSION_NOT_LOADED_MSG):
+ backend.generate(prompt = "x", steps = 1)
+ _load(backend)
+ stale = load_identity("someone/else", BASE, "z-image")
+ with pytest.raises(DiffusionModelReplacedError):
+ backend.generate(prompt = "x", steps = 1, expected_load = stale)
+ ok = load_identity(REPO, BASE, "z-image")
+ assert backend.generate(prompt = "x", steps = 1, seed = 1, width = 256, height = 256, expected_load = ok)[
+ "images"
+ ]
+
+
+def test_cancel_stops_at_the_next_step(env):
+ backend, runtime, _calls = env
+ _load(backend)
+ assert backend.cancel_generate() is False
+ runtime.step_gate = threading.Event()
+ errors = []
+
+ def _run():
+ try:
+ backend.generate(prompt = "x", steps = 4, seed = 1, width = 256, height = 256)
+ except RuntimeError as exc:
+ errors.append(str(exc))
+
+ worker = threading.Thread(target = _run)
+ worker.start()
+ assert runtime.in_step.wait(5)
+ assert mb.generation_in_flight() is False # the module singleton is not this instance
+ assert backend.generate_progress()["active"] is True
+ assert backend.cancel_generate() is True
+ runtime.step_gate.set()
+ worker.join(5)
+ assert errors == [DIFFUSION_CANCELLED_MSG]
+ assert backend.generate_progress()["active"] is False
+ assert backend.cancel_generate() is False
+
+
+def test_unload_frees_and_cancels(env):
+ backend, runtime, _calls = env
+ _load(backend)
+ status = backend.unload()
+ assert status["loaded"] is False and status["engine"] == "mlx"
+ assert runtime.freed == 1
+ assert backend.loaded_repo_ids() == ()
+ with pytest.raises(RuntimeError, match = DIFFUSION_NOT_LOADED_MSG):
+ backend.generate(prompt = "x", steps = 1)
+
+
+def test_unload_during_load_waits_for_the_build_and_discards_it(env, monkeypatch):
+ # A build cannot be interrupted, and the router treats unload()'s return as "memory is free"
+ # before it activates another engine, so unload must wait for the superseded worker.
+ backend, runtime, _calls = env
+ gate = threading.Event()
+ started = threading.Event()
+ real_build = runtime.build
+
+ def _slow_build(*a, **k):
+ started.set()
+ gate.wait(10)
+ return real_build(*a, **k)
+
+ runtime.build = _slow_build
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")
+ assert started.wait(5)
+ assert backend.loading_repo_ids() == (REPO, BASE, "unsloth/Z-Image-Turbo")
+ with pytest.raises(RuntimeError, match = "already in progress"):
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")
+ done = threading.Event()
+ unloader = threading.Thread(target = lambda: (backend.unload(), done.set()))
+ unloader.start()
+ assert not done.wait(0.5), "unload() returned while the superseded build was still running"
+ freed_before = runtime.freed
+ gate.set()
+ assert done.wait(5)
+ unloader.join(5)
+ assert runtime.freed == freed_before + 1 # the superseded worker freed what it built
+ assert backend.status()["loaded"] is False
+ assert backend.load_progress()["phase"] is None
+
+
+def test_a_load_racing_unload_waits_until_the_superseded_build_is_gone(env):
+ backend, runtime, _calls = env
+ gate = threading.Event()
+ started = threading.Event()
+ real_build = runtime.build
+
+ def _slow_build(*a, **k):
+ started.set()
+ gate.wait(10)
+ return real_build(*a, **k)
+
+ runtime.build = _slow_build
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")
+ assert started.wait(5)
+ unloader = threading.Thread(target = backend.unload)
+ unloader.start()
+ deadline = time.time() + 5
+ while backend.loading_repo_ids() and time.time() < deadline:
+ time.sleep(0.01)
+ try:
+ with pytest.raises(RuntimeError, match = "unload is in progress"):
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")
+ assert len(runtime.builds) == 0
+ finally:
+ gate.set()
+ unloader.join(5)
+ assert len(runtime.builds) == 1 # the superseded build, discarded
+ runtime.build = real_build
+ assert _load(backend)["phase"] == "ready"
+ assert len(runtime.builds) == 2
+
+
+def test_a_cache_only_load_resolves_the_variant_without_the_hub(env, monkeypatch):
+ import core.inference.diffusion as diffusion
+ import hub.utils.companion_assets as companion
+
+ backend, runtime, calls = env
+ monkeypatch.setattr(mb, "resolve_variant_base", _REAL_RESOLVE_VARIANT_BASE, raising = False)
+
+ def _no_hub(*_a, **_k):
+ raise AssertionError("a cache-only load read the model card")
+
+ monkeypatch.setattr(diffusion, "_hf_base_model", _no_hub)
+ links = {REPO.lower(): ["Tongyi-MAI/Z-Image-Turbo", "Tongyi-MAI/Z-Image", "Qwen/Qwen3-4B"]}
+ monkeypatch.setattr(companion, "read_companion_links", lambda: links)
+ _load(backend, local_files_only = True)
+ assert calls["fetch_base"][-1] == ("Tongyi-MAI/Z-Image", True)
+ assert runtime.builds[-1]["model_config"] == "z-image"
+ backend.unload()
+ links.clear()
+ _load(backend, local_files_only = True)
+ assert calls["fetch_base"][-1] == (BASE, True)
+
+
+def test_a_cache_only_undistilled_pick_with_no_record_builds_the_base_config(env, monkeypatch):
+ import hub.utils.companion_assets as companion
+
+ backend, runtime, calls = env
+ monkeypatch.setattr(mb, "resolve_variant_base", _REAL_RESOLVE_VARIANT_BASE, raising = False)
+ monkeypatch.setattr(companion, "read_companion_links", lambda: {})
+ backend.begin_load(
+ "unsloth/Z-Image-GGUF",
+ gguf_filename = "z-image-Q4_0.gguf",
+ model_kind = "gguf",
+ local_files_only = True,
+ )
+ assert _wait_loaded(backend)["phase"] == "ready"
+ assert calls["fetch_base"][-1] == ("Tongyi-MAI/Z-Image", True)
+ assert runtime.builds[-1]["model_config"] == "z-image"
+
+
+ "repo_id, gguf_filename, expected",
+ [
+ ("unsloth/Z-Image-GGUF", "z-image-Q4_K_M.gguf", "Tongyi-MAI/Z-Image"),
+ ("unsloth/Z-Image-GGUF", "z-image-BF16.gguf", "Tongyi-MAI/Z-Image"),
+ ("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf", BASE),
+ ("unsloth/Z-Image-GGUF", "z-image-turbo-Q4_0.gguf", BASE),
+ ("unsloth/Z-Image-Turbo-GGUF", "z-image-Q4_0.gguf", BASE),
+ ("leejet/Z-Image-Turbo-GGUF", "z_image_turbo-Q4_K.gguf", BASE),
+ ("someone/my-gguf-models", "model-Q4_K_M.gguf", BASE),
+ ("someone/Z-Image-GGUF", "model-Q4_K_M.gguf", "Tongyi-MAI/Z-Image"),
+ ("someone/z-image-turbo", "model-Q4_K_M.gguf", BASE),
+ ],
+)
+def test_the_name_resolves_the_z_image_variant_offline(
+ monkeypatch, repo_id, gguf_filename, expected
+):
+ import hub.utils.companion_assets as companion
+
+ fam = ZIMAGE
+ monkeypatch.setattr(companion, "read_companion_links", lambda: {})
+ assert mb._cached_variant_base(repo_id, fam, gguf_filename, BASE) == expected
+ assert mb.mlx_model_config_for(fam, expected) == (
+ "z-image" if expected != BASE else "z-image-turbo"
+ )
+
+
+def test_a_recorded_default_does_not_overrule_an_undistilled_name(monkeypatch):
+ import hub.utils.companion_assets as companion
+
+ fam = ZIMAGE
+ links = {"unsloth/z-image-gguf": [BASE]}
+ monkeypatch.setattr(companion, "read_companion_links", lambda: links)
+ assert mb._cached_variant_base("unsloth/Z-Image-GGUF", fam, "z-image-Q4_K_M.gguf", BASE) == (
+ "Tongyi-MAI/Z-Image"
+ )
+ links["unsloth/z-image-turbo-gguf"] = ["Tongyi-MAI/Z-Image"]
+ assert (
+ mb._cached_variant_base("unsloth/Z-Image-Turbo-GGUF", fam, "z-image-turbo-Q4_0.gguf", BASE)
+ == "Tongyi-MAI/Z-Image"
+ )
+
+
+def test_a_local_undistilled_gguf_resolves_without_the_hub(tmp_path, monkeypatch):
+ import core.inference.diffusion as diffusion
+
+ fam = ZIMAGE
+ monkeypatch.setattr(diffusion, "_remember_companion_base", lambda *a: None)
+ (tmp_path / "z-image-Q4_K_M.gguf").write_bytes(b"x")
+ (tmp_path / "z-image-turbo-Q4_K_M.gguf").write_bytes(b"x")
+ resolve = _REAL_RESOLVE_VARIANT_BASE
+ assert resolve(str(tmp_path), fam, None, "z-image-Q4_K_M.gguf", fallback = BASE) == (
+ "Tongyi-MAI/Z-Image"
+ )
+ assert resolve(str(tmp_path), fam, None, "z-image-turbo-Q4_K_M.gguf", fallback = BASE) == BASE
+
+
+def test_policy_helpers(monkeypatch):
+ for name in (
+ "UNSLOTH_DIFFUSION_MLX_TE_BITS",
+ "UNSLOTH_DIFFUSION_MLX_DENSE_BITS",
+ "UNSLOTH_DIFFUSION_MLX_PRECISION",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ gib = 1024**3
+ assert mb.text_encoder_bits(8 * gib) == 4 and mb.text_encoder_bits(16 * gib) == 4
+ assert mb.text_encoder_bits(32 * gib) == 8
+ assert mb.dense_bits(7 * gib) == 4 and mb.dense_bits(64 * gib) == 0
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_TE_BITS", "16")
+ assert mb.text_encoder_bits(8 * gib) is None
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_DENSE_BITS", "3") # not allowed: ignored
+ assert mb.dense_bits(64 * gib) == 0
+ assert mb.compute_precision_name("Apple M1 (Virtual)") == "float16"
+ assert mb.compute_precision_name("Apple M2 Max") == "float16"
+ assert mb.compute_precision_name("Apple M3 Pro") == "bfloat16"
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX_PRECISION", "bf16")
+ assert mb.compute_precision_name("Apple M1") == "bfloat16"
+
+
+def test_importing_the_engine_does_not_import_mlx():
+ import subprocess
+ import sys
+
+ code = (
+ "import sys; import core.inference.mlx_diffusion_backend as m; "
+ "print(any(k == 'mlx' or k.startswith(('mlx.', 'mflux')) for k in sys.modules))"
+ )
+ backend_root = Path(__file__).resolve().parent.parent
+ out = subprocess.run(
+ [sys.executable, "-c", code], cwd = backend_root, capture_output = True, text = True, timeout = 300
+ )
+ assert out.returncode == 0, out.stderr[-2000:]
+ assert out.stdout.strip().splitlines()[-1] == "False"
+
+
+def test_a_replacing_load_frees_the_old_model_first(env):
+ backend, runtime, _calls = env
+ _load(backend)
+ freed_before = runtime.freed
+ seen = []
+ real_build = runtime.build
+
+ def _build(*a, **k):
+ seen.append(backend.status()["loaded"])
+ return real_build(*a, **k)
+
+ runtime.build = _build
+ _load(backend)
+ assert seen == [False]
+ assert runtime.freed == freed_before + 1
+ assert backend.status()["loaded"] is True
+
+
+def test_a_cancelled_run_releases_its_frames():
+ # A cancel unwinds through the model's own frames; clearing them is what lets unload() free the model.
+ import gc
+ import weakref
+
+ class Model:
+ pass
+
+ def _inner(model):
+ raise mb.MlxCancelled("stop")
+
+ model = Model()
+ ref = weakref.ref(model)
+ try:
+ _inner(model)
+ except mb.MlxCancelled as exc:
+ kept = exc
+ mb.drop_exception_frames(exc)
+ del model
+ gc.collect()
+ assert ref() is None
+ assert kept.__traceback__ is None
+
+
+def test_a_cached_exception_below_the_load_does_not_pin_the_model(env, monkeypatch):
+ # The Hub helpers memoize import failures, and a memoized traceback keeps every frame up the
+ # stack, the load worker's included. The worker must not leave the model in its locals.
+ import gc
+ import weakref
+
+ backend, runtime, _calls = env
+ cache = {}
+ real_fetch = mb.fetch_gguf
+
+ def _fetch(*a, **k):
+ try:
+ raise ModuleNotFoundError("No module named 'unsloth_zoo'")
+ except ModuleNotFoundError as exc:
+ cache["error"] = exc # what hf_xet_fallback._load_shared does
+ return real_fetch(*a, **k)
+
+ class Model(dict):
+ pass
+
+ monkeypatch.setattr(mb, "fetch_gguf", _fetch)
+ real_build = runtime.build
+ runtime.build = lambda *a, **k: Model(real_build(*a, **k))
+ _load(backend)
+ ref = weakref.ref(backend._state.model)
+ backend.unload()
+ gc.collect()
+ assert "error" in cache
+ assert ref() is None
+
+
+def test_generate_rejects_sizes_beyond_the_family_limits(env):
+ backend, runtime, _calls = env
+ _load(backend)
+ with pytest.raises(ValueError):
+ backend.generate(prompt = "x", steps = 1, width = 4096, height = 4096)
+ assert runtime.generates == []
+
+
+def test_a_failed_generation_does_not_pin_the_model(env):
+ # Any error raised inside the render holds the model in its frames; a caller or logger that
+ # keeps the exception must not keep the model alive past unload().
+ import gc
+ import weakref
+
+ backend, runtime, _calls = env
+
+ class Model(dict):
+ pass
+
+ real_build = runtime.build
+ runtime.build = lambda *a, **k: Model(real_build(*a, **k))
+
+ def _boom(model, **_k):
+ raise RuntimeError("metal failure")
+
+ runtime.generate = _boom
+ _load(backend)
+ ref = weakref.ref(backend._state.model)
+ with pytest.raises(RuntimeError, match = "metal failure") as info:
+ backend.generate(prompt = "x", steps = 1, width = 256, height = 256)
+ kept = info.value # what an error handler or log record would hold
+ backend.unload()
+ gc.collect()
+ assert ref() is None
+ assert kept.__traceback__ is not None # the traceback text survives for the log
+
+
+def test_generated_images_record_the_mlx_build(env):
+ backend, _rt, _calls = env
+ _load(backend)
+ result = backend.generate(prompt = "x", steps = 1, width = 256, height = 256, seed = 1)
+ assert result["text_encoder_quant"] == "mlx_int4"
+ assert result["transformer_quant"] == "mlx_int4_dense"
+
+
+def test_an_undistilled_base_tag_selects_the_base_config_and_companions(env, monkeypatch):
+ # No explicit base_repo, as for a normal Hub pick: the repo's base_model card tag decides.
+ import core.inference.diffusion as diffusion
+
+ backend, runtime, calls = env
+ monkeypatch.setattr(mb, "resolve_variant_base", _REAL_RESOLVE_VARIANT_BASE, raising = False)
+ monkeypatch.setattr(diffusion, "_hf_base_model", lambda repo_id, token: "Tongyi-MAI/Z-Image")
+ _load(backend)
+ assert calls["fetch_base"][-1][0] == "Tongyi-MAI/Z-Image"
+ assert runtime.builds[-1]["model_config"] == "z-image"
+ assert backend.status()["base_repo"] == "Tongyi-MAI/Z-Image"
+
+
+ "card_tag, expected_base, expected_config",
+ [
+ (None, "Tongyi-MAI/Z-Image", "z-image"),
+ ("Tongyi-MAI/Z-Image-Turbo", BASE, "z-image-turbo"),
+ ],
+)
+def test_an_online_undistilled_pick_without_a_card_tag_keeps_the_named_variant(
+ env, monkeypatch, card_tag, expected_base, expected_config
+):
+ # A failed card read returns no tag: the name still decides, a real tag still wins.
+ import core.inference.diffusion as diffusion
+
+ backend, runtime, calls = env
+ monkeypatch.setattr(mb, "resolve_variant_base", _REAL_RESOLVE_VARIANT_BASE, raising = False)
+ monkeypatch.setattr(diffusion, "_hf_base_model", lambda repo_id, token: card_tag)
+ monkeypatch.setattr(diffusion, "_remember_companion_base", lambda *a: None)
+ backend.begin_load("unsloth/Z-Image-GGUF", gguf_filename = "z-image-Q4_0.gguf", model_kind = "gguf")
+ assert _wait_loaded(backend)["phase"] == "ready"
+ assert calls["fetch_base"][-1] == (expected_base, False)
+ assert runtime.builds[-1]["model_config"] == expected_config
+
+
+def test_a_resolver_error_keeps_the_named_variant(monkeypatch):
+ import core.inference.diffusion as diffusion
+
+ def _boom(*_a, **_k):
+ raise RuntimeError("hub down")
+
+ monkeypatch.setattr(diffusion, "_hf_base_model", _boom)
+ out = mb.resolve_variant_base(
+ "unsloth/Z-Image-GGUF", ZIMAGE, None, "z-image-Q4_0.gguf", fallback = BASE
+ )
+ assert out == "Tongyi-MAI/Z-Image"
+
+
+ "folder, expected", [("Z-Image", "z-image"), ("Z-Image-Turbo", "z-image-turbo")]
+)
+def test_an_explicit_local_base_selects_the_config_its_name_spells(env, tmp_path, folder, expected):
+ backend, runtime, calls = env
+ local_base = tmp_path / "models" / folder
+ local_base.mkdir(parents = True)
+ _load(backend, base_repo = str(local_base))
+ assert calls["fetch_base"][-1][0] == str(local_base)
+ assert runtime.builds[-1]["model_config"] == expected
+ assert backend.status()["base_repo"] == str(local_base)
+
+
+def test_base_fetch_is_cancellable_between_files(monkeypatch):
+ import huggingface_hub
+ import utils.hf_xet_fallback as xet
+
+ files = [
+ "text_encoder/a.safetensors",
+ "text_encoder/b.safetensors",
+ "vae/c.safetensors",
+ "README.md",
+ ]
+ info = type(
+ "Info", (), {"sha": "abc", "siblings": [type("S", (), {"rfilename": f}) for f in files]}
+ )
+ monkeypatch.setattr(huggingface_hub.HfApi, "model_info", lambda self, *a, **k: info)
+ cancel = threading.Event()
+ fetched = []
+
+ def _download(
+ repo,
+ filename,
+ token,
+ *,
+ cancel_event = None,
+ **_k,
+ ):
+ assert cancel_event is cancel
+ fetched.append(filename)
+ cancel.set() # an unload lands during the first file
+ return f"/hub/models--x/snapshots/abc/{filename}"
+
+ monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
+ with pytest.raises(mb.MlxCancelled):
+ mb.fetch_base_snapshot(
+ "Tongyi-MAI/Z-Image-Turbo", None, local_files_only = False, cancel_event = cancel
+ )
+ assert fetched == ["text_encoder/a.safetensors"]
+ cancel.clear()
+ fetched.clear()
+ monkeypatch.setattr(
+ xet,
+ "hf_hub_download_with_xet_fallback",
+ lambda repo, fn, tok, **k: fetched.append(fn) or f"/hub/snapshots/abc/{fn}",
+ )
+ out = mb.fetch_base_snapshot(
+ "Tongyi-MAI/Z-Image-Turbo", None, local_files_only = False, cancel_event = cancel
+ )
+ assert out == "/hub/snapshots/abc"
+ assert fetched == files[:3] # README is outside the allow patterns
+
+
[email protected]("predicted", ["mlx", None])
+def test_the_load_route_takes_the_gpu_arbiter_for_mlx_on_a_cpu_torch_host(monkeypatch, predicted):
+ # torch can resolve "cpu" on an Apple-Silicon Mac, but MLX still drives the Apple GPU: the route
+ # must evict / own the GPU through the arbiter instead of releasing it. Also when the prediction
+ # failed and only the activation says MLX.
+ import asyncio
+ import types
+ from unittest.mock import create_autospec
+
+ import core.inference.diffusion_device as device_module
+ import core.inference.diffusion_engine_router as router_module
+ import core.inference.gpu_arbiter as arbiter
+ from models.inference import DiffusionLoadRequest
+ from routes.inference import load_diffusion_model_gated
+
+ engine = create_autospec(mb.MlxDiffusionBackend, instance = True)
+ engine.begin_load.return_value = {"loaded": False, "repo_id": None}
+ engine.preflight_base_access.return_value = None
+
+ def _predict(*a, **k):
+ if predicted is None:
+ raise RuntimeError("probe failed")
+ return predicted
+
+ monkeypatch.setattr(router_module, "predict_engine", _predict)
+ monkeypatch.setattr(router_module, "active_engine_name", lambda: "mlx")
+ monkeypatch.setattr(router_module, "engine_for", lambda name: engine)
+ monkeypatch.setattr(router_module, "select_and_activate_engine", lambda *a, **k: engine)
+ monkeypatch.setattr(router_module, "begin_load_on", lambda _engine, start: start())
+ monkeypatch.setattr(router_module, "annotate_status", lambda status: status)
+ monkeypatch.setattr(
+ device_module,
+ "resolve_diffusion_device_target",
+ lambda: types.SimpleNamespace(device = "cpu"),
+ )
+ monkeypatch.setattr("routes.inference._guard_diffusion_load_against_training", lambda: None)
+
+ async def _no_ordinal(_gpu_ids):
+ return None
+
+ monkeypatch.setattr("routes.inference._selected_gpu_ordinal", _no_ordinal)
+ calls = []
+ monkeypatch.setattr(
+ arbiter, "acquire_for_request", lambda owner, fn: calls.append("acquire") or fn()
+ )
+ monkeypatch.setattr(arbiter, "release", lambda owner: calls.append("release"))
+ asyncio.run(
+ load_diffusion_model_gated(
+ DiffusionLoadRequest(model_path = REPO, gguf_filename = GGUF),
+ "test-user",
+ user_initiated = False,
+ )
+ )
+ engine.begin_load.assert_called_once()
+ assert calls == ["acquire"]
+
+
+def test_the_anonymous_token_sentinel_reaches_every_fetch(env, monkeypatch):
+ backend, _rt, _calls = env
+ seen = []
+ real_fetch_gguf, real_fetch_base = mb.fetch_gguf, mb.fetch_base_snapshot
+ monkeypatch.setattr(
+ mb,
+ "fetch_gguf",
+ lambda r, f, tok, **k: (seen.append(tok), real_fetch_gguf(r, f, tok, **k))[1],
+ )
+ monkeypatch.setattr(
+ mb,
+ "fetch_base_snapshot",
+ lambda b, tok, **k: (seen.append(tok), real_fetch_base(b, tok, **k))[1],
+ )
+ monkeypatch.setattr(
+ mb,
+ "resolve_variant_base",
+ lambda r, f, tok, *a, fallback, **k: (seen.append(tok), fallback)[1],
+ )
+ assert _load(backend, hf_token = False)["phase"] == "ready"
+ assert seen == [False, False, False]
+ seen.clear()
+ backend.unload()
+ assert _load(backend, hf_token = " hf_x ")["phase"] == "ready"
+ assert seen == ["hf_x", "hf_x", "hf_x"]
+ seen.clear()
+ backend.unload()
+ assert _load(backend, hf_token = " ")["phase"] == "ready"
+ assert seen == [None, None, None]
+
+
+def test_unload_racing_begin_load_never_joins_an_unstarted_worker(env, monkeypatch):
+ backend, _rt, _calls = env
+ started = []
+ real_thread = mb.account_thread
+
+ def _thread(**kw):
+ worker = real_thread(**kw)
+ real_start = worker.start
+
+ def _start():
+ # Publication and start share one critical section, so unload() never sees an unstarted worker.
+ held = not backend._lock.acquire(blocking = False)
+ if not held:
+ backend._lock.release()
+ assert held
+ started.append(worker)
+ real_start()
+
+ worker.start = _start
+ return worker
+
+ monkeypatch.setattr(mb, "account_thread", _thread)
+ _load(backend)
+ assert len(started) == 1
+
+
+def test_a_load_cancelled_while_waiting_on_generation_skips_the_build(env):
+ backend, runtime, _calls = env
+ _load(backend)
+ runtime.step_gate = threading.Event()
+ errors = []
+ gen = threading.Thread(
+ target = lambda: _swallow(errors, lambda: backend.generate(prompt = "x", steps = 1))
+ )
+ gen.start()
+ assert runtime.in_step.wait(5)
+ builds_before = len(runtime.builds)
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")
+ deadline = time.time() + 5
+ while backend._state is not None and time.time() < deadline:
+ time.sleep(0.01)
+ backend._cancel_event.set()
+ runtime.step_gate.set()
+ gen.join(5)
+ backend._load_thread.join(5)
+ assert len(runtime.builds) == builds_before
+ assert backend.status()["loaded"] is False
+
+
+def _swallow(errors, fn):
+ try:
+ fn()
+ except Exception as exc: # noqa: BLE001
+ errors.append(exc)
+
+
[email protected]("stage", ["build", "cache_text_encodings"])
+def test_a_failed_build_frees_the_runtime(env, stage):
+ backend, runtime, _calls = env
+
+ def _boom(*_a, **_k):
+ raise MemoryError("[metal::malloc] out of memory")
+
+ setattr(runtime, stage, _boom)
+ progress = _load(backend)
+ assert progress["phase"] == "error" and "out of memory" in progress["error"]
+ assert runtime.freed == 1
+ assert backend.status()["loaded"] is False
+
+
+def test_status_reports_the_engaged_mlx_quantization(env):
+ backend, _rt, _calls = env
+ _load(backend)
+ status = backend.status()
+ assert status["text_encoder_quant"] == "mlx_int4"
+ assert status["transformer_quant"] == "mlx_int4_dense"
+
+
+def test_derived_batch_seeds_stay_json_safe(env):
+ backend, runtime, _calls = env
+ _load(backend)
+ result = backend.generate(
+ prompt = "x", steps = 1, width = 256, height = 256, seed = 2**53 - 1, batch_size = 2
+ )
+ assert result["seeds"] == [2**53 - 1, 0]
+ assert [g["seed"] for g in runtime.generates] == [2**53 - 1, 0]
+
+
+def test_a_failed_replacement_hands_the_resident_model_back_to_its_owner(env, monkeypatch):
+ import core.inference.gpu_arbiter as arbiter
+ import hub.services.models.account_access as account_access
+
+ backend, _rt, _calls = env
+ restored = []
+ monkeypatch.setattr(
+ arbiter, "restore_owner_account", lambda owner, *a, **k: restored.append(owner)
+ )
+ monkeypatch.setattr(
+ account_access, "restore_resident_metadata", lambda kind: restored.append(kind)
+ )
+ real_fetch_gguf = mb.fetch_gguf
+ failing = [True]
+
+ def _fetch(*a, **k):
+ if failing[0]:
+ raise OSError("fetch failed")
+ return real_fetch_gguf(*a, **k)
+
+ monkeypatch.setattr(mb, "fetch_gguf", _fetch)
+ assert _load(backend)["phase"] == "error"
+ assert restored == [] # nothing resident to hand back
+ failing[0] = False
+ assert _load(backend)["phase"] == "ready"
+ failing[0] = True
+ assert _load(backend)["phase"] == "error"
+ assert backend.is_loaded
+ assert restored == [arbiter.DIFFUSION, "diffusion"]
+
+
+def _hub_listing(monkeypatch, files):
+ import huggingface_hub
+
+ listed = []
+ info = type(
+ "Info", (), {"sha": "abc", "siblings": [type("S", (), {"rfilename": f}) for f in files]}
+ )
+ monkeypatch.setattr(
+ huggingface_hub.HfApi,
+ "model_info",
+ lambda self, repo, *a, **k: listed.append(repo) or info,
+ )
+ return listed
+
+
+def test_base_companions_come_from_the_repo_the_plan_staged(monkeypatch):
+ import utils.hf_xet_fallback as xet
+
+ files = ["text_encoder/a.safetensors", "vae/c.safetensors"]
+ listed = _hub_listing(monkeypatch, files)
+ judged = []
+ monkeypatch.setattr(
+ mb,
+ "prefer_ungated_mirror",
+ lambda base, tok = None, *, files = None: judged.append(files) or "unsloth/Z-Image-Turbo",
+ raising = False,
+ )
+ fetched = []
+ monkeypatch.setattr(
+ xet,
+ "hf_hub_download_with_xet_fallback",
+ lambda repo, fn, tok, **k: fetched.append((repo, fn, k.get("revision")))
+ or f"/hub/snapshots/abc/{fn}",
+ )
+ mb.fetch_base_snapshot(BASE, None, local_files_only = False)
+ assert judged == [files]
+ assert listed == [BASE, "unsloth/Z-Image-Turbo"]
+ assert fetched == [("unsloth/Z-Image-Turbo", f, "abc") for f in files]
+
+
+def _companion_snapshot(root, complete = True, tokenizer_config = True):
+ root.mkdir(parents = True, exist_ok = True)
+ for sub in ("text_encoder", "tokenizer", "vae"):
+ (root / sub).mkdir(exist_ok = True)
+ (root / "tokenizer" / "tokenizer.json").write_text("{}")
+ if tokenizer_config:
+ (root / "tokenizer" / "tokenizer_config.json").write_text("{}")
+ (root / "vae" / "diffusion_pytorch_model.safetensors").write_bytes(b"x")
+ shards = ["model-00001-of-00002.safetensors", "model-00002-of-00002.safetensors"]
+ (root / "text_encoder" / "model.safetensors.index.json").write_text(
+ json.dumps({"weight_map": {"a": shards[0], "b": shards[1]}})
+ )
+ for shard in shards if complete else shards[:1]:
+ (root / "text_encoder" / shard).write_bytes(b"x")
+ return str(root)
+
+
+def test_cache_only_companions_read_the_mirror_and_the_live_cache_root(monkeypatch, tmp_path):
+ import huggingface_hub
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ import utils.hf_cache_settings as cache_settings
+
+ live = str(tmp_path / "live")
+ monkeypatch.setattr(cache_settings, "active_hf_hub_cache", lambda: live)
+ monkeypatch.setattr(
+ mb,
+ "prefer_ungated_mirror",
+ lambda base, tok = None, **k: "unsloth/Z-Image-Turbo",
+ raising = False,
+ )
+ mirror_snapshot = _companion_snapshot(tmp_path / "live" / "mirror-snap")
+ asked = []
+
+ def _snapshot(
+ repo,
+ *,
+ cache_dir = None,
+ local_files_only = False,
+ **_k,
+ ):
+ assert local_files_only
+ asked.append((repo, cache_dir))
+ if (repo, cache_dir) == ("unsloth/Z-Image-Turbo", live):
+ return mirror_snapshot
+ raise LocalEntryNotFoundError("not cached")
+
+ monkeypatch.setattr(huggingface_hub, "snapshot_download", _snapshot)
+ out = mb.fetch_base_snapshot(BASE, None, local_files_only = True)
+ assert out == mirror_snapshot
+ assert asked == [("unsloth/Z-Image-Turbo", live)]
+ asked.clear()
+ monkeypatch.setattr(mb, "prefer_ungated_mirror", lambda base, tok = None, **k: base)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_NO_MIRROR", "1")
+ with pytest.raises(LocalEntryNotFoundError):
+ mb.fetch_base_snapshot(BASE, None, local_files_only = True)
+ assert asked and all(repo == BASE for repo, _ in asked)
+ assert asked[0] == (BASE, live)
+
+
+def test_cache_only_companions_skip_an_incomplete_upstream_for_the_staged_mirror(
+ monkeypatch, tmp_path
+):
+ # The upstream holds some weights, so the fetch-repo choice keeps it, but the plan staged the mirror.
+ import huggingface_hub
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ import utils.hf_cache_settings as cache_settings
+
+ live = str(tmp_path / "live")
+ monkeypatch.setattr(cache_settings, "active_hf_hub_cache", lambda: live)
+ monkeypatch.setattr(mb, "prefer_ungated_mirror", lambda base, tok = None, **k: base)
+ snapshots = {
+ BASE: _companion_snapshot(tmp_path / "upstream", complete = False),
+ "unsloth/Z-Image-Turbo": _companion_snapshot(tmp_path / "mirror"),
+ }
+
+ def _snapshot(repo, *, cache_dir = None, local_files_only = False, **_k):
+ assert local_files_only
+ if cache_dir != live or repo not in snapshots:
+ raise LocalEntryNotFoundError("not cached")
+ return snapshots[repo]
+
+ monkeypatch.setattr(huggingface_hub, "snapshot_download", _snapshot)
+ assert mb.fetch_base_snapshot(BASE, None, local_files_only = True) == snapshots["unsloth/Z-Image-Turbo"]
+ del snapshots["unsloth/Z-Image-Turbo"]
+ with pytest.raises(LocalEntryNotFoundError, match = "complete"):
+ mb.fetch_base_snapshot(BASE, None, local_files_only = True)
+
+
+def _mlx_route_stubs(monkeypatch, *, predicted = "mlx"):
+ import core.inference.diffusion_engine_router as router_module
+ import core.inference.gpu_arbiter as arbiter
+
+ touched = []
+ monkeypatch.setattr(router_module, "predict_engine", lambda *a, **k: predicted)
+ monkeypatch.setattr(router_module, "active_engine_name", lambda: "diffusers")
+ monkeypatch.setattr(
+ router_module, "engine_for", lambda name: touched.append(("engine_for", name))
+ )
+ monkeypatch.setattr(
+ router_module,
+ "select_and_activate_engine",
+ lambda *a, **k: touched.append("select"),
+ )
+ monkeypatch.setattr(arbiter, "acquire_for_request", lambda *a, **k: touched.append("acquire"))
+ monkeypatch.setattr("routes.inference._guard_diffusion_load_against_training", lambda: None)
+ monkeypatch.setattr("routes.inference._training_is_active", lambda: False)
+
+ async def _no_ordinal(_gpu_ids, **_k):
+ return None
+
+ monkeypatch.setattr("routes.inference._selected_gpu_ordinal", _no_ordinal)
+ return touched
+
+
+def test_the_load_route_refuses_mlx_loras_before_activation_or_eviction(monkeypatch):
+ import asyncio
+
+ from fastapi import HTTPException
+
+ from models.inference import DiffusionLoadRequest
+ from routes.inference import load_diffusion_model_gated
+
+ touched = _mlx_route_stubs(monkeypatch)
+ request = DiffusionLoadRequest(
+ model_path = REPO, gguf_filename = GGUF, loras = [{"id": "a/b", "weight": 1.0}]
+ )
+ with pytest.raises(HTTPException) as err:
+ asyncio.run(load_diffusion_model_gated(request, "test-user", user_initiated = False))
+ assert err.value.status_code == 400
+ assert "LoRA" in err.value.detail
+ assert touched == []
+
+
+def test_the_download_plan_refuses_mlx_loras_before_planning(monkeypatch):
+ import asyncio
+
+ from fastapi import HTTPException
+
+ from models.inference import DiffusionLoadRequest
+ from routes import inference as routes
+
+ touched = _mlx_route_stubs(monkeypatch)
+ monkeypatch.setattr(
+ mb.MlxDiffusionBackend,
+ "download_plan",
+ lambda self, *a, **k: touched.append("plan") or {},
+ )
+ request = DiffusionLoadRequest(
+ model_path = REPO, gguf_filename = GGUF, loras = [{"id": "a/b", "weight": 1.0}]
+ )
+ with pytest.raises(HTTPException) as err:
+ asyncio.run(routes.diffusion_download_plan(request, current_subject = "u"))
+ assert err.value.status_code == 400
+ assert "LoRA" in err.value.detail
+ assert "plan" not in touched
+
+
+def test_a_concurrent_unload_waits_for_the_active_teardown(env):
+ backend, runtime, _calls = env
+ gate = threading.Event()
+ started = threading.Event()
+ real_build = runtime.build
+
+ def _slow_build(*a, **k):
+ started.set()
+ gate.wait(10)
+ return real_build(*a, **k)
+
+ runtime.build = _slow_build
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")
+ assert started.wait(5)
+ first = threading.Thread(target = backend.unload)
+ first.start()
+ deadline = time.time() + 5
+ while not backend._unloading and time.time() < deadline:
+ time.sleep(0.01)
+ done = threading.Event()
+ second = threading.Thread(target = lambda: (backend.unload(), done.set()))
+ second.start()
+ try:
+ assert not done.wait(
+ 0.5
+ ), "a second unload returned while the first was still joining the build"
+ finally:
+ gate.set()
+ first.join(5)
+ second.join(5)
+ assert done.is_set()
+ assert runtime.freed == 1
+
+
+def test_a_cancelled_load_keeps_its_repos_draining_until_the_worker_is_joined(env, monkeypatch):
+ import core.inference.diffusion_engine_router as router
+ from hub.services.models import deletion
+
+ backend, runtime, _calls = env
+ monkeypatch.setattr(router, "get_active_diffusion_engine", lambda: backend)
+ gate = threading.Event()
+ started = threading.Event()
+ real_build = runtime.build
+
+ def _slow_build(*a, **k):
+ started.set()
+ gate.wait(10)
+ return real_build(*a, **k)
+
+ runtime.build = _slow_build
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")
+ assert started.wait(5)
+ unloader = threading.Thread(target = backend.unload)
+ unloader.start()
+ deadline = time.time() + 5
+ while not backend._unloading and time.time() < deadline:
+ time.sleep(0.01)
+ try:
+ assert backend.loading_repo_ids() == ()
+ assert REPO in backend.draining_repo_ids()
+ assert "still releasing" in (deletion._diffusion_blocks_delete(REPO) or "")
+ finally:
+ gate.set()
+ unloader.join(5)
+ assert backend.draining_repo_ids() == ()
+
+
+def test_online_companions_land_under_one_cache_root(monkeypatch, tmp_path):
+ import huggingface_hub
+ from huggingface_hub import constants
+
+ import utils.hf_cache_settings as cache_settings
+ import utils.hf_xet_fallback as xet
+
+ files = ["text_encoder/a.safetensors", "tokenizer/b.json", "vae/c.safetensors"]
+ _hub_listing(monkeypatch, files)
+ monkeypatch.setattr(mb, "prefer_ungated_mirror", lambda base, tok = None, **k: base)
+ live, old = str(tmp_path / "live"), str(tmp_path / "old")
+ monkeypatch.setattr(cache_settings, "active_hf_hub_cache", lambda: live)
+ monkeypatch.setattr(constants, "HF_HUB_CACHE", old)
+ # Only the first file survives under the import-time root; the rest are cached nowhere.
+ monkeypatch.setattr(
+ huggingface_hub,
+ "try_to_load_from_cache",
+ lambda repo, fn, *, cache_dir = None, **k: (
+ f"{old}/snapshots/abc/{fn}" if cache_dir in (None, old) and fn == files[0] else None
+ ),
+ )
+ roots = []
+
+ def _download(
+ repo,
+ fn,
+ tok,
+ *,
+ cache_dir = None,
+ reuse_other_cache_root = False,
+ **k,
+ ):
+ root = old if reuse_other_cache_root and fn == files[0] else (cache_dir or live)
+ roots.append(root)
+ return f"{root}/snapshots/abc/{fn}"
+
+ monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _download)
+ out = mb.fetch_base_snapshot(BASE, None, local_files_only = False)
+ assert roots == [live] * len(files)
+ assert out == f"{live}/snapshots/abc"
+
+
+def test_cache_only_companions_skip_a_snapshot_without_tokenizer_config(monkeypatch, tmp_path):
+ # AutoTokenizer cannot resolve the tokenizer class without tokenizer_config.json.
+ import huggingface_hub
+ from huggingface_hub.errors import LocalEntryNotFoundError
+
+ import utils.hf_cache_settings as cache_settings
+
+ live = str(tmp_path / "live")
+ monkeypatch.setattr(cache_settings, "active_hf_hub_cache", lambda: live)
+ monkeypatch.setattr(mb, "prefer_ungated_mirror", lambda base, tok = None, **k: base)
+ snapshots = {
+ BASE: _companion_snapshot(tmp_path / "upstream", tokenizer_config = False),
+ "unsloth/Z-Image-Turbo": _companion_snapshot(tmp_path / "mirror"),
+ }
+
+ def _snapshot(repo, *, cache_dir = None, local_files_only = False, **_k):
+ if cache_dir != live or repo not in snapshots:
+ raise LocalEntryNotFoundError("not cached")
+ return snapshots[repo]
+
+ monkeypatch.setattr(huggingface_hub, "snapshot_download", _snapshot)
+ assert mb.fetch_base_snapshot(BASE, None, local_files_only = True) == snapshots["unsloth/Z-Image-Turbo"]
+
+
+def test_a_cancelled_load_keeps_the_companion_mirror_guarded(env, monkeypatch):
+ import core.inference.diffusion_engine_router as router
+ from hub.services.models import deletion
+
+ backend, runtime, _calls = env
+ monkeypatch.setattr(router, "get_active_diffusion_engine", lambda: backend)
+ gate = threading.Event()
+ started = threading.Event()
+ real_build = runtime.build
+
+ def _slow_build(*a, **k):
+ started.set()
+ gate.wait(10)
+ return real_build(*a, **k)
+
+ runtime.build = _slow_build
+ backend.begin_load(REPO, gguf_filename = GGUF, model_kind = "gguf")
+ assert started.wait(5)
+ assert "unsloth/Z-Image-Turbo" in backend.loading_repo_ids()
+ assert "using this repo" in (deletion._diffusion_blocks_delete("unsloth/Z-Image-Turbo") or "")
+ unloader = threading.Thread(target = backend.unload)
+ unloader.start()
+ deadline = time.time() + 5
+ while not backend._unloading and time.time() < deadline:
+ time.sleep(0.01)
+ try:
+ assert "unsloth/Z-Image-Turbo" in backend.draining_repo_ids()
+ assert "still releasing" in (deletion._diffusion_blocks_delete("unsloth/Z-Image-Turbo") or "")
+ finally:
+ gate.set()
+ unloader.join(5)
+ assert backend.draining_repo_ids() == ()
+
+
+class _PlanRecorder:
+ def __init__(self):
+ self.calls = []
+
+ def download_plan(self, repo_id, **kwargs):
+ self.calls.append(kwargs)
+ return {"entries": [], "total_bytes": 0}
+
+
+def test_the_mlx_plan_forces_off_the_memory_verdict(monkeypatch):
+ import core.inference.diffusion as diffusion
+
+ recorder = _PlanRecorder()
+ monkeypatch.setattr(diffusion, "get_diffusion_backend", lambda: recorder)
+ mb.MlxDiffusionBackend().download_plan(
+ REPO, gguf_filename = GGUF, base_repo = BASE, memory_verdict = True
+ )
+ assert recorder.calls[-1]["memory_verdict"] is False
+
+
+def test_the_mlx_plan_names_the_base_the_load_will_read(monkeypatch, tmp_path):
+ import core.inference.diffusion as diffusion
+
+ recorder = _PlanRecorder()
+ monkeypatch.setattr(diffusion, "get_diffusion_backend", lambda: recorder)
+ local = tmp_path / "picks"
+ local.mkdir()
+ gguf = "z-image-Q4_0.gguf"
+ (local / gguf).write_bytes(b"GGUF")
+ mb.MlxDiffusionBackend().download_plan(str(local), gguf_filename = gguf)
+ assert recorder.calls[-1]["base_repo"] == "Tongyi-MAI/Z-Image"
+ mb.MlxDiffusionBackend().download_plan(str(local), gguf_filename = "z-image-turbo-Q4_0.gguf")
+ assert recorder.calls[-1]["base_repo"] == BASE
+ mb.MlxDiffusionBackend().download_plan(str(local), gguf_filename = gguf, base_repo = BASE)
+ assert recorder.calls[-1]["base_repo"] == BASE
diff --git a/studio/backend/tests/test_mlx_diffusion_convert.py b/studio/backend/tests/test_mlx_diffusion_convert.py
new file mode 100644
index 00000000000..1bc8319dd94
--- /dev/null
+++ b/studio/backend/tests/test_mlx_diffusion_convert.py
@@ -0,0 +1,365 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""GGUF -> MLX affine converter for the opt-in MLX image engine: numpy + gguf only, runs on Linux."""
+
+import json
+import struct
+import threading
+
+import numpy as np
+import pytest
+
+gguf = pytest.importorskip("gguf")
+from gguf import GGMLQuantizationType as T # noqa: E402
+from gguf import quants # noqa: E402
+
+from core.inference import mlx_diffusion_convert as conv # noqa: E402
+
+
+def _rng(seed = 0):
+ return np.random.default_rng(seed)
+
+
+def _blocks(
+ kind,
+ rows,
+ cols,
+ seed = 0,
+):
+ x = (_rng(seed).standard_normal((rows, cols)) * 0.05).astype(np.float32)
+ return quants.quantize(x, kind)
+
+
[email protected]("kind", [T.Q4_0, T.Q4_1, T.Q8_0])
[email protected]("cols", [64, 96])
+def test_affine_matches_gguf_dequantize_exactly(kind, cols):
+ raw = _blocks(kind, 6, cols, seed = cols)
+ reference = quants.dequantize(raw, kind).astype(np.float32)
+ w, s, b, bits = conv.affine_from_ggml(kind.name, raw, 6, cols)
+ assert bits == (8 if kind == T.Q8_0 else 4)
+ assert w.dtype == np.uint32 and w.shape == (6, cols * bits // 32)
+ assert s.shape == b.shape == (6, cols // 32)
+ got = conv.dequantize_affine(w, s, b, bits)
+ assert np.array_equal(got, reference)
+ # fp16 scales are lossless: d, m, -8d and -128d are all fp16 values
+ s16 = s.astype(np.float16).astype(np.float32)
+ b16 = b.astype(np.float16).astype(np.float32)
+ assert np.array_equal(s16, s) and np.array_equal(b16, b)
+ assert np.array_equal(conv.dequantize_affine(w, s16, b16, bits), reference)
+
+
[email protected]("kind", [T.Q4_0, T.Q4_1, T.Q8_0])
+def test_affine_bf16_scales_within_rounding_bound(kind):
+ raw = _blocks(kind, 8, 128, seed = 3)
+ reference = quants.dequantize(raw, kind).astype(np.float32)
+ w, s, b, bits = conv.affine_from_ggml(kind.name, raw, 8, 128)
+ sb, bb = conv.round_to_bf16(s), conv.round_to_bf16(b)
+ got = conv.dequantize_affine(w, sb, bb, bits)
+ q = conv._unpack(w, bits).astype(np.float32).reshape(8, 4, 32)
+ bound = (q * np.abs(sb - s)[..., None] + np.abs(bb - b)[..., None]).reshape(8, 128)
+ assert np.all(np.abs(got - reference) <= bound * 1.0001 + 1e-12)
+ # and bf16 keeps ~8 bits: never worse than 2^-8 relative on the scale
+ assert np.all(np.abs(sb - s) <= np.abs(s) * 2.0**-8)
+
+
+def test_affine_rejects_kquant_and_bad_sizes():
+ with pytest.raises(conv.UnsupportedGGUFError):
+ conv.affine_from_ggml("Q4_K", np.zeros(144, np.uint8), 1, 256)
+ with pytest.raises(ValueError):
+ conv.affine_from_ggml("Q4_0", np.zeros(17, np.uint8), 1, 32)
+
+
[email protected]("bits", [4, 8])
+def test_quantize_dense_roundtrip(bits):
+ w = (_rng(1).standard_normal((5, 64)) * 0.1).astype(np.float32)
+ packed, s, b = conv.quantize_dense_affine(w, bits)
+ assert packed.shape == (5, 64 * bits // 32) and s.shape == b.shape == (5, 2)
+ assert np.array_equal(conv.round_to_bf16(s), s) and np.array_equal(conv.round_to_bf16(b), b)
+ got = conv.dequantize_affine(packed, s, b, bits)
+ err = np.abs(got - w).reshape(5, 2, 32)
+ # half a step from rounding, plus the top edge the bf16 rounding of scale may shave off
+ slack = (s * 2.0**-8 * ((1 << bits) - 1) + np.abs(b) * 2.0**-8)[..., None]
+ assert np.all(err <= s[..., None] / 2 + slack + 1e-7)
+
+
+def test_quantize_dense_constant_group():
+ w = np.full((2, 32), 0.25, np.float32)
+ w[1] = -3.0
+ packed, s, b = conv.quantize_dense_affine(w, 4)
+ assert np.all(s == 0)
+ assert np.array_equal(conv.dequantize_affine(packed, s, b, 4), w)
+
+
+ "src, dst",
+ [
+ ("final_layer.adaLN_modulation.1.weight", "all_final_layer.2-1.adaLN_modulation.0.weight"),
+ ("final_layer.linear.weight", "all_final_layer.2-1.linear.weight"),
+ ("x_embedder.weight", "all_x_embedder.2-1.weight"),
+ ("t_embedder.mlp.0.weight", "t_embedder.linear1.weight"),
+ ("t_embedder.mlp.2.bias", "t_embedder.linear2.bias"),
+ ("layers.3.attention.out.weight", "layers.3.attention.to_out.0.weight"),
+ ("layers.3.attention.q_norm.weight", "layers.3.attention.norm_q.weight"),
+ ("layers.3.attention.k_norm.weight", "layers.3.attention.norm_k.weight"),
+ ("layers.3.attention.qkv.weight", "layers.3.attention.qkv.weight"),
+ ("layers.3.feed_forward.w1.weight", "layers.3.feed_forward.w1.weight"),
+ ],
+)
+def test_zimage_rename(src, dst):
+ assert conv.zimage_rename(src) == dst
+
+
+ "name, ok",
+ [
+ ("z-image-turbo-Q4_0.gguf", True),
+ ("z-image-turbo-Q4_1.gguf", True),
+ ("z-image-turbo-Q8_0.gguf", True),
+ ("z-image-turbo-BF16.gguf", True),
+ ("z-image-turbo-F16.gguf", True),
+ ("z_image_turbo-Q4_K_M.gguf", False),
+ ("z-image-turbo-UD-Q4_K_XL.gguf", False),
+ ("z-image-turbo-Q6_K.gguf", False),
+ ("z-image-turbo-Q5_0.gguf", False),
+ ("z-image-turbo-IQ4_XS.gguf", False),
+ ("z-image-turbo-MXFP4.gguf", False),
+ ("z-image-turbo.gguf", False),
+ (None, False),
+ ],
+)
+def test_quant_convertible(name, ok):
+ verdict, reason = conv.quant_convertible(name)
+ assert verdict is ok
+ assert (reason is None) is ok
+ if not ok:
+ assert "MLX" in reason
+
+
+def test_quant_convertible_names_the_kquant():
+ _ok, reason = conv.quant_convertible("z_image_turbo-Q4_K_M.gguf")
+ assert "Q4_K_M" in reason and "not convertible" in reason
+
+
+# ── End to end on a tiny synthetic GGUF ─────────────────────────────────────────────────────────
+
+
+def _read_safetensors(path):
+ data = path.read_bytes()
+ (n,) = struct.unpack("<Q", data[:8])
+ header = json.loads(data[8 : 8 + n])
+ body = data[8 + n :]
+ meta = header.pop("__metadata__")
+ np_dtype = {"U32": np.uint32, "BF16": np.uint16, "F16": np.float16}
+ tensors = {}
+ end = 0
+ for name, info in sorted(header.items(), key = lambda kv: kv[1]["data_offsets"][0]):
+ a, b = info["data_offsets"]
+ assert a == end, "offsets must be contiguous"
+ end = b
+ tensors[name] = (
+ info["dtype"],
+ np.frombuffer(body[a:b], dtype = np_dtype[info["dtype"]]).reshape(info["shape"]),
+ )
+ assert end == len(body)
+ return meta, tensors
+
+
+def _bf16(bits16):
+ return conv._bf16_bits_to_f32(bits16)
+
+
+def _write_gguf(path, extra = None):
+ rng = _rng(7)
+ sources = {}
+ w = gguf.GGUFWriter(str(path), "z-image")
+
+ def add_q(name, kind, rows, cols):
+ x = (rng.standard_normal((rows, cols)) * 0.05).astype(np.float32)
+ raw = quants.quantize(x, kind)
+ sources[name] = (kind, raw)
+ w.add_tensor(name, raw, raw_dtype = kind)
+
+ add_q("layers.0.attention.qkv.weight", T.Q4_0, 3 * 64, 64)
+ add_q("layers.0.feed_forward.w1.weight", T.Q8_0, 96, 64)
+ add_q("layers.0.attention.out.weight", T.Q4_1, 64, 64)
+ dense = (rng.standard_normal((32, 64)) * 0.05).astype(np.float32)
+ sources["context_refiner.0.feed_forward.w2.weight"] = (T.BF16, dense)
+ w.add_tensor(
+ "context_refiner.0.feed_forward.w2.weight",
+ quants.quantize(dense, T.BF16),
+ raw_dtype = T.BF16,
+ )
+ norm = rng.standard_normal(64).astype(np.float32)
+ sources["layers.0.attention.q_norm.weight"] = (T.F32, norm)
+ w.add_tensor("layers.0.attention.q_norm.weight", norm)
+ pad = rng.standard_normal(64).astype(np.float32)
+ sources["cap_pad_token"] = (T.F32, pad)
+ w.add_tensor("cap_pad_token", pad)
+ if extra:
+ extra(w)
+ w.write_header_to_file()
+ w.write_kv_data_to_file()
+ w.write_tensors_to_file()
+ w.close()
+ return sources
+
+
+def test_convert_end_to_end(tmp_path):
+ src = tmp_path / "z-image-turbo-Q4_0.gguf"
+ sources = _write_gguf(src)
+ seen = []
+ summary = conv.convert_gguf_to_mflux(
+ src, tmp_path / "out", progress = lambda d, t: seen.append((d, t))
+ )
+ assert summary["counts"] == {"Q4_0": 1, "Q8_0": 1, "Q4_1": 1, "BF16": 1, "F32": 2}
+ assert seen[-1] == (6, 6)
+ out = tmp_path / "out" / "transformer" / "0.safetensors"
+ meta, tensors = _read_safetensors(out)
+ assert meta["quantization_level"] == "4"
+ assert meta["mflux_version"] and meta["source_gguf"] == src.name
+ assert meta["unsloth_converter"] == conv.CONVERTER_VERSION
+ names = set(tensors)
+ for p in ("to_q", "to_k", "to_v"):
+ for suffix in ("weight", "scales", "biases"):
+ assert f"layers.0.attention.{p}.{suffix}" in names
+ assert not any(".qkv." in n for n in names)
+ assert "layers.0.attention.to_out.0.scales" in names
+ assert "layers.0.attention.norm_q.weight" in names
+ kind, raw = sources["layers.0.attention.qkv.weight"]
+ ref = quants.dequantize(raw, kind).astype(np.float32)
+ for i, p in enumerate(("to_q", "to_k", "to_v")):
+ dt, packed = tensors[f"layers.0.attention.{p}.weight"]
+ assert dt == "U32" and packed.shape == (64, 8)
+ s = _bf16(tensors[f"layers.0.attention.{p}.scales"][1])
+ b = _bf16(tensors[f"layers.0.attention.{p}.biases"][1])
+ got = conv.dequantize_affine(packed, s, b, 4)
+ np.testing.assert_allclose(got, ref[i * 64 : (i + 1) * 64], atol = 2e-3, rtol = 0)
+ # Q8_0 packs 4 per word
+ assert tensors["layers.0.feed_forward.w1.weight"][1].shape == (96, 16)
+ # dense BF16 stays bit-identical; F32 is rounded to bf16; pad token is (1, -1)
+ dt, bits16 = tensors["context_refiner.0.feed_forward.w2.weight"]
+ assert dt == "BF16" and bits16.shape == (32, 64)
+ np.testing.assert_array_equal(
+ _bf16(bits16), conv.round_to_bf16(sources["context_refiner.0.feed_forward.w2.weight"][1])
+ )
+ assert tensors["cap_pad_token"][1].shape == (1, 64)
+ np.testing.assert_array_equal(
+ _bf16(tensors["layers.0.attention.norm_q.weight"][1]),
+ conv.round_to_bf16(sources["layers.0.attention.q_norm.weight"][1]),
+ )
+ marker = json.loads((out.parent / conv.MARKER_FILENAME).read_text())
+ assert marker["output_bytes"] == out.stat().st_size and marker["dense_bits"] == 0
+ assert conv.conversion_complete(tmp_path / "out")
+ assert conv.conversion_complete(tmp_path / "out", source_path = src)
+ assert not list(out.parent.glob(".*tmp"))
+
+
+def test_convert_f16_scales_are_exact(tmp_path):
+ src = tmp_path / "z-image-turbo-Q4_0.gguf"
+ sources = _write_gguf(src)
+ conv.convert_gguf_to_mflux(src, tmp_path / "out", scale_dtype = "f16")
+ _meta, tensors = _read_safetensors(tmp_path / "out" / "transformer" / "0.safetensors")
+ kind, raw = sources["layers.0.attention.out.weight"]
+ dt, packed = tensors["layers.0.attention.to_out.0.weight"]
+ s = tensors["layers.0.attention.to_out.0.scales"]
+ b = tensors["layers.0.attention.to_out.0.biases"]
+ assert s[0] == b[0] == "F16"
+ got = conv.dequantize_affine(packed, s[1].astype(np.float32), b[1].astype(np.float32), 4)
+ assert np.array_equal(got, quants.dequantize(raw, kind).astype(np.float32))
+
+
+def test_convert_dense_bits_quantizes_dense_linears(tmp_path):
+ src = tmp_path / "z-image-turbo-Q4_0.gguf"
+ sources = _write_gguf(src)
+ summary = conv.convert_gguf_to_mflux(src, tmp_path / "out", dense_bits = 4)
+ assert summary["dense_bits"] == 4
+ _meta, tensors = _read_safetensors(tmp_path / "out" / "transformer" / "0.safetensors")
+ base = "context_refiner.0.feed_forward.w2"
+ assert tensors[base + ".weight"][0] == "U32"
+ got = conv.dequantize_affine(
+ tensors[base + ".weight"][1],
+ _bf16(tensors[base + ".scales"][1]),
+ _bf16(tensors[base + ".biases"][1]),
+ 4,
+ )
+ dense = sources[base + ".weight"][1]
+ assert np.max(np.abs(got - dense)) < 0.05
+ # norms (1-D) and pad tokens stay dense
+ assert tensors["layers.0.attention.norm_q.weight"][0] == "BF16"
+ assert tensors["cap_pad_token"][0] == "BF16"
+
+
+def test_convert_refuses_kquant_before_writing(tmp_path):
+ src = tmp_path / "z-image-turbo-Q4_K_M.gguf"
+
+ def extra(w):
+ raw = _rng(2).integers(0, 255, size = (4, 144), dtype = np.uint8)
+ w.add_tensor("layers.0.feed_forward.w2.weight", raw, raw_dtype = T.Q4_K)
+
+ _write_gguf(src, extra = extra)
+ with pytest.raises(conv.UnsupportedGGUFError, match = "Q4_K"):
+ conv.convert_gguf_to_mflux(src, tmp_path / "out")
+ assert not (tmp_path / "out" / "transformer" / "0.safetensors").exists()
+ assert not conv.conversion_complete(tmp_path / "out")
+
+
+def test_convert_cancel_leaves_no_file(tmp_path):
+ src = tmp_path / "z-image-turbo-Q4_0.gguf"
+ _write_gguf(src)
+ cancel = threading.Event()
+ cancel.set()
+ with pytest.raises(RuntimeError, match = "cancelled"):
+ conv.convert_gguf_to_mflux(src, tmp_path / "out", cancel_event = cancel)
+ target = tmp_path / "out" / "transformer"
+ assert not (target / "0.safetensors").exists()
+ assert not list(target.glob(".*"))
+
+
+def test_conversion_complete_detects_truncation_and_source_change(tmp_path):
+ src = tmp_path / "z-image-turbo-Q4_0.gguf"
+ _write_gguf(src)
+ conv.convert_gguf_to_mflux(src, tmp_path / "out")
+ out = tmp_path / "out" / "transformer" / "0.safetensors"
+ with open(out, "ab") as fh:
+ fh.write(b"x")
+ assert not conv.conversion_complete(tmp_path / "out")
+ conv.convert_gguf_to_mflux(src, tmp_path / "out")
+ assert conv.conversion_complete(tmp_path / "out", source_path = src)
+ with open(src, "ab") as fh:
+ fh.write(b"\0" * 32)
+ assert not conv.conversion_complete(tmp_path / "out", source_path = src)
+
+
+def test_cache_dir_for(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path))
+ d = conv.cache_dir_for(
+ "unsloth/Z-Image-Turbo-GGUF", "abc123", "z-image-turbo-Q4_0.gguf", dense_bits = 4
+ )
+ assert d.parent.name == "unsloth--Z-Image-Turbo-GGUF@abc123"
+ assert d.name == "z-image-turbo-Q4_0-d4-bf16"
+ assert d.parent.parent.name == "mlx_diffusion"
+ assert str(d).startswith(str(tmp_path.resolve())) or str(d).startswith(str(tmp_path))
+ local = conv.cache_dir_for("../x", None, "sub/../m.gguf", dense_bits = 0)
+ assert ".." not in local.parts and local.parent.name.endswith("@local")
+
+
+def test_mlx_loads_the_output_when_available(tmp_path):
+ mx = pytest.importorskip("mlx.core")
+ src = tmp_path / "z-image-turbo-Q4_0.gguf"
+ sources = _write_gguf(src)
+ conv.convert_gguf_to_mflux(src, tmp_path / "out")
+ loaded, meta = mx.load(
+ str(tmp_path / "out" / "transformer" / "0.safetensors"), return_metadata = True
+ )
+ assert meta["quantization_level"] == "4"
+ name = "layers.0.attention.to_out.0"
+ got = mx.dequantize(
+ loaded[name + ".weight"],
+ loaded[name + ".scales"],
+ loaded[name + ".biases"],
+ group_size = 32,
+ bits = 4,
+ ).astype(mx.float32)
+ kind, raw = sources["layers.0.attention.out.weight"]
+ np.testing.assert_allclose(np.array(got), quants.dequantize(raw, kind), atol = 2e-3, rtol = 0)
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 9553e32d93a..e63cafbc2f9 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -10514,6 +10514,49 @@ _MLX_VLM_SPEC = "mlx-vlm>=0.4.4,<=0.7.4"
# Exact: llguidance.mlx / llguidance.hf are the API grammar_constraint.py binds to.
_LLGUIDANCE_PIN = "llguidance==1.8.0"
_MLX_NAMES: tuple[str, ...] = tuple(spec.partition("==")[0] for spec in _MLX_PINS) + ("mlx-vlm",)
+# mflux goes in --no-deps: its declared torch / transformers floors would move the MLX pins, and Z-Image
+# needs only the deps below. Best-effort: a failure must never mark the MLX stack broken.
+_MLX_DIFFUSION_PINS: tuple[str, ...] = ("mflux==0.22.0",)
+_MLX_DIFFUSION_DEPS: tuple[str, ...] = (
+ "piexif>=1.1.3,<2",
+ "platformdirs>=4,<5",
+ "toml>=0.10.2,<1",
+)
+
+
+def _mlx_diffusion_engine_is_current() -> bool:
+ """Whether mflux is at its pin and its light runtime deps are inside their ranges."""
+ if not all(_exact_distribution_spec_is_installed(spec) for spec in _MLX_DIFFUSION_PINS):
+ return False
+ try:
+ from packaging.requirements import Requirement
+ for spec in _MLX_DIFFUSION_DEPS:
+ requirement = Requirement(spec)
+ installed = _installed_distribution_version(requirement.name)
+ if installed is None or not requirement.specifier.contains(installed, prereleases = True):
+ return False
+ except Exception: # noqa: BLE001 - no packaging, or a version it cannot parse
+ return False
+ return True
+
+
+def _install_mlx_diffusion_engine() -> None:
+ """Install the opt-in MLX image engine; a failure is noted, never fatal."""
+ if not _full_deps_requested() and _mlx_diffusion_engine_is_current():
+ return
+ try:
+ pip_install(
+ "Installing the MLX image engine (mflux)",
+ "--no-cache-dir",
+ "--no-deps",
+ *_MLX_DIFFUSION_PINS,
+ *_MLX_DIFFUSION_DEPS,
+ )
+ except SystemExit:
+ _note(
+ f"{_MLX_DIFFUSION_PINS[0]} failed to install; image generation keeps its "
+ "current engine (UNSLOTH_DIFFUSION_MLX has no effect)"
+ )
def _mlx_vlm_spec_for_installed_zoo() -> str:
@@ -12402,6 +12445,9 @@ def install_python_stack() -> int:
*_MLX_PINS,
_mlx_vlm_spec_for_installed_zoo(),
)
+ # Inside the MLX slot, after the pins it runs on; its own check, so a satisfied
+ # stack still gets a missing engine.
+ _install_mlx_diffusion_engine()
_mlx_vlm_spec_used = _mlx_vlm_spec_for_installed_zoo()
else:
_progress("MLX stack (skipped, no wheel for this macOS or Python)")
diff --git a/tests/studio/install/test_mlx_install.py b/tests/studio/install/test_mlx_install.py
index 0e50067fdcd..50782ea7e77 100644
--- a/tests/studio/install/test_mlx_install.py
+++ b/tests/studio/install/test_mlx_install.py
@@ -30,6 +30,7 @@ def _run_to_extras(
shared_base = False,
mlx_error = None,
mlx_installable = True,
+ engine_error = None,
):
monkeypatch.setenv("SKIP_STUDIO_BASE", "1" if skip_base else "0")
for name in ("STUDIO_LOCAL_REPO", "STUDIO_PACKAGE_NAME", "UNSLOTH_CI_SOURCE_OVERLAY"):
@@ -66,6 +67,8 @@ def _run_to_extras(
def record_install(label, *args, **kwargs):
if label.startswith("Installing MLX") and mlx_error is not None:
raise mlx_error
+ if label.startswith("Installing the MLX image engine") and engine_error is not None:
+ raise engine_error
install = Mock(side_effect = record_install)
monkeypatch.setattr(stack, "pip_install", install)
@@ -84,6 +87,11 @@ def _run_to_extras(
stack.install_python_stack()
# Labels reached before the stop, for callers asserting on the step not the install.
_run_to_extras.steps = steps
+ _run_to_extras.engine_calls = [
+ call
+ for call in install.call_args_list
+ if call.args[0].startswith("Installing the MLX image engine")
+ ]
return [call for call in install.call_args_list if call.args[0].startswith("Installing MLX")]
@@ -446,3 +454,85 @@ def test_an_unchanged_zoo_does_not_re_resolve_mlx(monkeypatch):
calls = _run_to_extras(monkeypatch, platform = "macos_arm", skip_base = False, no_torch = False)
assert len(calls) == 1
assert "MLX stack (zoo unchanged, skipped)" in _run_to_extras.steps
+
+
+# ── Opt-in MLX image engine (mflux) ──────────────────────────────────────────
+
+
+def test_mlx_image_engine_pins_leave_the_mlx_stack_alone():
+ assert stack._MLX_PINS == ("mlx==0.32.3", "mlx-metal==0.32.3", "mlx-lm==0.31.3")
+ names = {Requirement(spec).name.lower() for spec in stack._MLX_DIFFUSION_PINS}
+ names |= {Requirement(spec).name.lower() for spec in stack._MLX_DIFFUSION_DEPS}
+ assert names == {"mflux", "piexif", "platformdirs", "toml"}
+ # The heavy declared deps of mflux stay out: --no-deps plus this list is the whole install.
+ assert not names & {
+ "opencv-python",
+ "opencv-python-headless",
+ "matplotlib",
+ "torch",
+ "transformers",
+ "mlx",
+ "mlx-metal",
+ "mlx-lm",
+ }
+ (pin,) = stack._MLX_DIFFUSION_PINS
+ assert pin.startswith("mflux==0.22.")
+
+
[email protected]("platform", ["macos_arm", "macos_intel", "linux", "windows"])
[email protected]("no_torch", [False, True], ids = ["training", "gguf_only"])
+def test_mlx_image_engine_installs_no_deps_only_where_the_mlx_stack_does(
+ monkeypatch, platform, no_torch
+):
+ monkeypatch.setattr(stack, "_mlx_vlm_spec_for_installed_zoo", lambda: stack._MLX_VLM_SPEC)
+ monkeypatch.setattr(stack, "_mlx_diffusion_engine_is_current", lambda: False)
+ _run_to_extras(monkeypatch, platform = platform, skip_base = True, no_torch = no_torch)
+ calls = _run_to_extras.engine_calls
+ assert len(calls) == int(platform == "macos_arm" and not no_torch)
+ if calls:
+ args = list(calls[0].args[1:])
+ assert "--no-deps" in args
+ specs = [arg for arg in args if not arg.startswith("-")]
+ assert specs == [*stack._MLX_DIFFUSION_PINS, *stack._MLX_DIFFUSION_DEPS]
+ assert not any("opencv" in arg or "matplotlib" in arg for arg in args)
+
+
+def test_mlx_image_engine_skipped_off_the_wheel_floor(monkeypatch):
+ monkeypatch.setattr(stack, "_mlx_diffusion_engine_is_current", lambda: False)
+ _run_to_extras(
+ monkeypatch, platform = "macos_arm", skip_base = True, no_torch = False, mlx_installable = False
+ )
+ assert _run_to_extras.engine_calls == []
+
+
+def test_satisfied_mlx_image_engine_is_not_reinstalled(monkeypatch):
+ monkeypatch.setattr(stack, "_mlx_diffusion_engine_is_current", lambda: True)
+ monkeypatch.setattr(stack, "_full_deps_requested", lambda: False)
+ _run_to_extras(monkeypatch, platform = "macos_arm", skip_base = True, no_torch = False)
+ assert _run_to_extras.engine_calls == []
+
+
[email protected]("skip_base", [True, False], ids = ["fresh", "update"])
+def test_failed_mlx_image_engine_install_is_not_fatal(monkeypatch, skip_base):
+ # The MLX stack still installs, and the pass carries on to the extras step.
+ monkeypatch.setattr(stack, "_mlx_diffusion_engine_is_current", lambda: False)
+ noted = Mock()
+ monkeypatch.setattr(stack, "_note", noted)
+ calls = _run_to_extras(
+ monkeypatch,
+ platform = "macos_arm",
+ skip_base = skip_base,
+ no_torch = False,
+ engine_error = SystemExit(1),
+ )
+ assert calls and len(_run_to_extras.engine_calls) == 1
+ assert any("mflux" in str(call.args[0]) for call in noted.call_args_list)
+
+
+def test_mlx_image_engine_is_not_part_of_the_mlx_gate():
+ # The self-heal and the chat-only gate judge mlx / mlx-lm / mlx-vlm only.
+ assert "mflux" not in _repair_specs()
+ source = (Path(stack.SCRIPT_DIR) / "backend" / "utils" / "mlx_repair.py").read_text(
+ encoding = "utf-8"
+ )
+ assert "mflux" not in source