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 MLX images: a LoRA load keeps sd.cpp or diffusers instead of routing into the MLX refusal (#14874)

Daniel Han8ef8dfecb49f
diff --git a/studio/backend/core/inference/diffusion_engine_router.py b/studio/backend/core/inference/diffusion_engine_router.py
index 77eae789ce7..b4ec171586f 100644
--- a/studio/backend/core/inference/diffusion_engine_router.py
+++ b/studio/backend/core/inference/diffusion_engine_router.py
@@ -430,6 +430,24 @@ def _mlx_runtime_refusal() -> Optional[str]:
return None
+def has_active_loras(loras: Any) -> bool:
+ """Every loader drops weight-0 entries (``diffusion_lora.resolve_specs``, sd.cpp's ``active_loras``),
+ so routing must ignore them too. An unreadable weight counts as active so a real adapter never hits MLX."""
+ for entry in loras or ():
+ weight = getattr(entry, "weight", None)
+ if weight is None:
+ try:
+ _lid, weight = entry
+ except (TypeError, ValueError):
+ return True
+ try:
+ if float(weight) != 0:
+ return True
+ except (TypeError, ValueError):
+ return True
+ return False
+
+
def mlx_selection(
fam: Optional[DiffusionFamily],
*,
@@ -437,9 +455,11 @@ def mlx_selection(
gguf_filename: Optional[str],
backend: Optional[str] = None,
engine: Optional[str] = None,
+ with_loras: bool = False,
) -> tuple[bool, Optional[str]]:
"""``(use_mlx, refusal)``. Shared by selection and ``predict_engine`` so the download plan and the load
- cannot disagree about MLX. ``engine`` is the load's own pick (``/images/load``'s ``engine`` field)."""
+ cannot disagree about MLX. ``engine`` is the load's own pick (``/images/load``'s ``engine`` field);
+ ``with_loras``: MLX cannot apply LoRAs, so such a load keeps its non-MLX engine."""
if not _mlx_requested():
return False, None
forced = os.environ.get("UNSLOTH_DIFFUSION_ENGINE", "auto").strip().lower()
@@ -449,6 +469,8 @@ def mlx_selection(
return False, f"the load asked for the {engine} engine"
if model_kind and model_kind != "gguf":
return False, f"the MLX engine loads GGUF picks only (got {model_kind})"
+ if with_loras:
+ return False, "the MLX engine does not apply LoRA adapters yet"
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"
@@ -470,6 +492,36 @@ def mlx_selection(
return True, None
+def _refuse_lora_fallback(
+ fam: DiffusionFamily,
+ choice: str,
+ *,
+ with_loras: bool,
+ model_kind: Optional[str],
+ gguf_filename: Optional[str],
+ engine: Optional[str],
+) -> None:
+ """Raise before unloading when MLX is skipped for LoRAs and the fallback engine cannot apply them."""
+ if (
+ not with_loras
+ or not mlx_selection(
+ fam, model_kind = model_kind, gguf_filename = gguf_filename, engine = engine
+ )[0]
+ ):
+ return
+ from .diffusion_lora import supports_lora
+
+ if supports_lora(engine = choice, family = fam.name, model_kind = "gguf", transformer_quant = None):
+ return
+ via = (
+ "the native sd.cpp engine" if choice == ENGINE_SD_CPP else "the diffusers engine on a GGUF"
+ )
+ raise ValueError(
+ "LoRA adapters are not supported on the MLX engine yet, and this load would fall back to "
+ f"{via}, which cannot apply them here either. Load it without LoRA adapters."
+ )
+
+
def _note_mlx_refusal(reason: Optional[str]) -> None:
global _mlx_fallback_reason
with _lock:
@@ -712,6 +764,7 @@ def select_and_activate_engine(
before_fallback: Optional[Callable[[], None]] = None,
gguf_filename: Optional[str] = None,
engine: Optional[str] = None,
+ with_loras: bool = False,
) -> Any:
"""Pick + activate the engine for loading ``fam`` on this host; return the engine.
@@ -729,7 +782,11 @@ def select_and_activate_engine(
requested = _requested_engine(engine)
refuse_engine_pick(fam, engine = engine, model_kind = model_kind)
use_mlx, mlx_refusal = mlx_selection(
- fam, model_kind = model_kind, gguf_filename = gguf_filename, engine = requested
+ fam,
+ model_kind = model_kind,
+ gguf_filename = gguf_filename,
+ engine = requested,
+ with_loras = with_loras,
)
_note_mlx_refusal(mlx_refusal)
if use_mlx:
@@ -747,8 +804,17 @@ def select_and_activate_engine(
else "forced (UNSLOTH_DIFFUSION_ENGINE=diffusers)",
)
+ lora_guard = functools.partial(
+ _refuse_lora_fallback,
+ fam,
+ with_loras = with_loras,
+ model_kind = model_kind,
+ gguf_filename = gguf_filename,
+ engine = requested,
+ )
prefer_native = forced == ENGINE_SD_CPP
if sd_cpp_pref in _DISABLE_TOKENS and not prefer_native:
+ lora_guard(ENGINE_DIFFUSERS)
return _activate(ENGINE_DIFFUSERS, "native engine disabled (UNSLOTH_DIFFUSION_SD_CPP=0)")
if native_gguf_only(fam, model_kind):
prefer_native = True
@@ -858,6 +924,7 @@ def select_and_activate_engine(
choice = select_diffusion_engine(
backend, native_available = native_available, prefer_native = prefer_native
)
+ lora_guard(choice)
if choice == ENGINE_SD_CPP:
return _activate(ENGINE_SD_CPP, None)
@@ -981,6 +1048,7 @@ def predict_engine(
gpu_ordinal: Optional[int] = None,
gguf_filename: Optional[str] = None,
engine: Optional[str] = None,
+ with_loras: bool = False,
) -> str:
"""The engine a load of ``fam`` would select on this host, WITHOUT any side effect. ``engine`` is the load's own
pick, as in ``select_and_activate_engine``; a pick selection would refuse raises the same ValueError here.
@@ -1000,7 +1068,13 @@ def predict_engine(
requested = _requested_engine(engine)
# The plan must refuse what the load will refuse, rather than plan (and stage) for the other engine.
refuse_engine_pick(fam, engine = engine, model_kind = model_kind)
- if mlx_selection(fam, model_kind = model_kind, gguf_filename = gguf_filename, engine = requested)[0]:
+ if mlx_selection(
+ fam,
+ model_kind = model_kind,
+ gguf_filename = gguf_filename,
+ engine = requested,
+ with_loras = with_loras,
+ )[0]:
return ENGINE_MLX
if model_kind and model_kind != "gguf":
return ENGINE_DIFFUSERS
@@ -1008,8 +1082,17 @@ def predict_engine(
forced, sd_cpp_pref, mps_enabled = _engine_config(engine)
if forced == ENGINE_DIFFUSERS:
return ENGINE_DIFFUSERS
+ lora_guard = functools.partial(
+ _refuse_lora_fallback,
+ fam,
+ with_loras = with_loras,
+ model_kind = model_kind,
+ gguf_filename = gguf_filename,
+ engine = requested,
+ )
prefer_native = forced == ENGINE_SD_CPP
if sd_cpp_pref in _DISABLE_TOKENS and not prefer_native:
+ lora_guard(ENGINE_DIFFUSERS)
return ENGINE_DIFFUSERS
if native_gguf_only(fam, model_kind):
prefer_native = True
@@ -1020,6 +1103,7 @@ def predict_engine(
gpu_ordinal = None
policy_eligible = backend == "cpu" or (backend == "mps" and mps_enabled) or prefer_native
if not (policy_eligible and family_sd_cpp_supported(fam)):
+ lora_guard(ENGINE_DIFFUSERS)
return ENGINE_DIFFUSERS
# A permitted install counts as available only where selection would actually perform one.
@@ -1047,6 +1131,7 @@ def predict_engine(
else f"no usable sd.cpp build here supports '{fam.name}'"
)
raise ValueError(f"The native sd.cpp engine cannot load this model here: {why}.")
+ lora_guard(choice)
return choice
diff --git a/studio/backend/core/inference/gpu_residency.py b/studio/backend/core/inference/gpu_residency.py
index 1a4ec9e5e73..e6f483423df 100644
--- a/studio/backend/core/inference/gpu_residency.py
+++ b/studio/backend/core/inference/gpu_residency.py
@@ -220,7 +220,7 @@ def _image_need(request: Any, gpu_ordinal: Optional[int]) -> Optional[tuple[int,
resolve_model_kind,
)
from core.inference.diffusion_auto_policy import resident_bytes_from_declared
- from core.inference.diffusion_engine_router import predict_engine
+ from core.inference.diffusion_engine_router import has_active_loras, predict_engine
from core.inference.diffusion_families import (
detect_family_for_pick,
local_pipeline_components_are_complete,
@@ -244,7 +244,13 @@ def _image_need(request: Any, gpu_ordinal: Optional[int]) -> Optional[tuple[int,
fam = detect_family_for_pick(repo, name, request.family_override)
if (
fam is None
- or predict_engine(fam, model_kind = kind, gpu_ordinal = gpu_ordinal, gguf_filename = name)
+ or predict_engine(
+ fam,
+ model_kind = kind,
+ gpu_ordinal = gpu_ordinal,
+ gguf_filename = name,
+ with_loras = has_active_loras(getattr(request, "loras", None)),
+ )
!= ENGINE_DIFFUSERS
):
return None
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 5b482ec4895..d29936e2c71 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -51535,8 +51535,14 @@ def _refuse_native_component_files(request: DiffusionLoadRequest) -> None:
)
+def _has_active_loras(loras: Any) -> bool:
+ from core.inference.diffusion_engine_router import has_active_loras
+ return has_active_loras(loras)
+
+
def _refuse_mlx_loras(request: DiffusionLoadRequest) -> None:
- if request.loras:
+ # Zero-weight entries are dropped before loading, so only an applied adapter is refused.
+ if _has_active_loras(request.loras):
raise HTTPException(
status_code = 400,
detail = "LoRA adapters are not supported on the MLX engine yet.",
@@ -51645,6 +51651,7 @@ async def diffusion_download_plan(
gpu_ordinal = gpu_ordinal,
gguf_filename = request.gguf_filename,
engine = request.engine,
+ with_loras = _has_active_loras(request.loras),
)
if fam is not None
else None
@@ -51970,6 +51977,7 @@ async def load_diffusion_model_gated(
gpu_ordinal = gpu_ordinal,
gguf_filename = request.gguf_filename,
engine = request.engine,
+ with_loras = _has_active_loras(request.loras),
)
if fam is not None
else None
@@ -52114,6 +52122,7 @@ async def load_diffusion_model_gated(
gguf_filename = request.gguf_filename,
# The load's own engine pick (auto when absent); refused there rather than swapped.
engine = request.engine,
+ with_loras = _has_active_loras(request.loras),
),
)
# predict_engine is selection's read-only twin: it never installs, so a host whose sd-cli
diff --git a/studio/backend/tests/test_diffusion_mlx_engine_router.py b/studio/backend/tests/test_diffusion_mlx_engine_router.py
index 6c6777f7c6f..00a7926ec79 100644
--- a/studio/backend/tests/test_diffusion_mlx_engine_router.py
+++ b/studio/backend/tests/test_diffusion_mlx_engine_router.py
@@ -438,3 +438,118 @@ def test_auto_switch_planner_judges_mlx_with_the_picks_gguf(monkeypatch):
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]
+
+
+# ── a LoRA load never lands on MLX, which refuses adapters ───────────────────
+
+
+ "gguf",
+ [
+ "z-image-turbo-Q4_K_M.gguf",
+ "z-image-turbo-Q5_K_M.gguf",
+ "z-image-turbo-Q6_K.gguf",
+ "z-image-turbo-Q5_0.gguf",
+ "z-image-turbo-Q5_1.gguf",
+ _Q4,
+ ],
+)
+def test_a_lora_load_keeps_sd_cpp_under_the_mlx_opt_in(monkeypatch, gguf):
+ # An MPS Mac running native sd.cpp today with a LoRA: the opt-in must not divert it into MLX's refusal.
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ 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"))
+ fam = detect_family("z-image")
+ assert _predict(gguf = gguf) == _select(gguf = gguf) == ENGINE_MLX
+ kw = dict(model_kind = "gguf", gguf_filename = gguf, with_loras = True)
+ assert r.predict_engine(fam, **kw) == ENGINE_SD_CPP
+ r.select_and_activate_engine(fam, **kw)
+ assert r.active_engine_name() == ENGINE_SD_CPP
+ assert "LoRA" in (r.annotate_status({})["mlx_fallback_reason"] or "")
+
+
[email protected]("sd_cpp_off", [False, True])
+def test_a_lora_load_with_no_lora_capable_fallback_is_refused_before_the_switch(
+ monkeypatch, sd_cpp_off
+):
+ # No native engine: diffusers cannot apply GGUF LoRAs, so refuse before unloading.
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ if sd_cpp_off:
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP", "0")
+ fam = detect_family("z-image")
+ kw = dict(model_kind = "gguf", gguf_filename = "z-image-turbo-Q4_K_M.gguf", with_loras = True)
+ r._active_engine_name = ENGINE_MLX
+ with pytest.raises(ValueError, match = "LoRA"):
+ r.predict_engine(fam, **kw)
+ with pytest.raises(ValueError, match = "LoRA"):
+ r.select_and_activate_engine(fam, **kw)
+ assert r.active_engine_name() == ENGINE_MLX
+
+
+def test_a_lora_load_without_the_mlx_opt_in_still_falls_back_to_diffusers(monkeypatch):
+ _apple(monkeypatch)
+ fam = detect_family("z-image")
+ kw = dict(model_kind = "gguf", gguf_filename = "z-image-turbo-Q4_K_M.gguf", with_loras = True)
+ assert r.predict_engine(fam, **kw) == ENGINE_DIFFUSERS
+ r.select_and_activate_engine(fam, **kw)
+ assert r.active_engine_name() == ENGINE_DIFFUSERS
+
+
+def test_every_load_route_passes_its_loras_to_engine_selection():
+ import ast
+ from pathlib import Path
+
+ source = (Path(__file__).resolve().parents[1] / "routes" / "inference.py").read_text(
+ encoding = "utf-8"
+ )
+ calls = [
+ c
+ for c in ast.walk(ast.parse(source))
+ if isinstance(c, ast.Call)
+ and (
+ getattr(c.func, "id", None) == "predict_engine"
+ or (
+ getattr(c.func, "id", None) == "partial"
+ or getattr(c.func, "attr", None) == "partial"
+ )
+ and c.args
+ and getattr(c.args[0], "id", None) == "select_and_activate_engine"
+ )
+ ]
+ assert len(calls) >= 3
+ for call in calls:
+ kw = {k.arg: k.value for k in call.keywords}
+ assert "with_loras" in kw, ast.unparse(call)[:120]
+ # A zero-weight entry is dropped before loading, so it must not count as a LoRA load.
+ assert getattr(kw["with_loras"].func, "id", None) == "_has_active_loras", ast.unparse(call)[
+ :120
+ ]
+
+
+ "loras, active",
+ [
+ (None, False),
+ ([], False),
+ ([("a", 0.0)], False),
+ ([("a", 0), ("b", 0.0)], False),
+ ([SimpleNamespace(id = "a", weight = 0.0)], False),
+ ([("a", 0.0), ("b", 0.5)], True),
+ ([SimpleNamespace(id = "a", weight = 1.0)], True),
+ ([object()], True),
+ ],
+)
+def test_has_active_loras_ignores_zero_weight_entries(loras, active):
+ assert r.has_active_loras(loras) is active
+
+
+def test_a_zero_weight_lora_load_still_lands_on_mlx(monkeypatch):
+ _apple(monkeypatch)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
+ gguf = "z-image-turbo-Q4_K_M.gguf"
+ fam = detect_family("z-image")
+ kw = dict(model_kind = "gguf", gguf_filename = gguf, with_loras = r.has_active_loras([("a", 0.0)]))
+ assert r.predict_engine(fam, **kw) == ENGINE_MLX
diff --git a/studio/backend/tests/test_diffusion_routes.py b/studio/backend/tests/test_diffusion_routes.py
index 1d0141b8157..2e73ec99470 100644
--- a/studio/backend/tests/test_diffusion_routes.py
+++ b/studio/backend/tests/test_diffusion_routes.py
@@ -3314,3 +3314,19 @@ def test_a_retired_flux3_full_copy_reaches_the_backend_as_its_base(client):
assert ("load", "black-forest-labs/flux-3-image-klein") in seen
validated = [entry[2:] for entry in seen if entry[0] == "validate"]
assert validated and set(validated) == {(None, "pipeline")}, seen
+
+
+def test_zero_weight_loras_neither_refuse_mlx_nor_route_away_from_it():
+ # Weight 0 disables an adapter and every loader drops it, so an all-zero list is no LoRA load.
+ from fastapi import HTTPException
+ from models.inference import DiffusionLoadRequest, LoraSpec
+
+ off = DiffusionLoadRequest(model_path = "x/y", loras = [LoraSpec(id = "a", weight = 0.0)])
+ inference_routes._refuse_mlx_loras(off)
+ assert inference_routes._has_active_loras(off.loras) is False
+ on = DiffusionLoadRequest(
+ model_path = "x/y", loras = [LoraSpec(id = "a", weight = 0.0), LoraSpec(id = "b", weight = 0.5)]
+ )
+ assert inference_routes._has_active_loras(on.loras) is True
+ with pytest.raises(HTTPException):
+ inference_routes._refuse_mlx_loras(on)