Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio 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.pyindex 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, Noneforced = 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_reasonwith _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_CPPif 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 ownpick, 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_MLXif 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_CPPif sd_cpp_pref in _DISABLE_TOKENS and not prefer_native:+ lora_guard(ENGINE_DIFFUSERS)return ENGINE_DIFFUSERSif native_gguf_only(fam, model_kind):prefer_native = True@@ -1020,6 +1103,7 @@ def predict_engine(gpu_ordinal = Nonepolicy_eligible = backend == "cpu" or (backend == "mps" and mps_enabled) or prefer_nativeif 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 choicediff --git a/studio/backend/core/inference/gpu_residency.py b/studio/backend/core/inference/gpu_residency.pyindex 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_enginefrom 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 Nonediff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.pyindex 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 Noneelse 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 Noneelse 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-clidiff --git a/studio/backend/tests/test_diffusion_mlx_engine_router.py b/studio/backend/tests/test_diffusion_mlx_engine_router.pyindex 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_MLXdiff --git a/studio/backend/tests/test_diffusion_routes.py b/studio/backend/tests/test_diffusion_routes.pyindex 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 seenvalidated = [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)