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 Images: enable GGUF LoRAs on MLX and diffusers, and explain when unavailable (#16053)

oobabooga6d5a4d845768
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 7cbc2af66ec..a3d9b1cb24e 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -8154,7 +8154,7 @@ class DiffusionBackend:
transformer_quant_decline: Optional[str] = None
small_dit_kept_bf16 = False
transformer_quant_decline_status = RESOLVED_FELL_BACK
- # A GGUF is excluded while it bakes LoRAs: only the dense build can carry them.
+ # A GGUF is excluded while it bakes LoRAs: only the dense build bakes them at load.
if (
transformer_quant == TQ_AUTO
and pipeline_seed_scheme is None
@@ -12773,40 +12773,18 @@ class DiffusionBackend:
invalidate_cfg_replica(pipe, "the LoRA adapters changed", logger)
return
- if _small_host_int8(pipe):
- raise ValueError(
- "LoRA is not available on this load: system RAM was too small for the dense model, so Unsloth "
- "stored the transformer as int8 weights (small-host route), which cannot carry adapters. Load the "
- "model with the LoRA selected (Unsloth then keeps the dense transformer), or use a host with more RAM."
- )
- if comfy_block_runtime_layers(getattr(pipe, "transformer", None)):
- raise ValueError(
- "LoRA is not available on this load: the ComfyUI file's nvfp4 / mxfp8 layers run on their own "
- "quantized Linears, which cannot carry adapters. Load the file with the LoRA selected (Unsloth then "
- "dequantizes those layers), or set UNSLOTH_DIFFUSION_COMFY_NVFP4=0 / UNSLOTH_DIFFUSION_COMFY_MXFP8=0."
- )
- if fp8_stored_layers(getattr(pipe, "transformer", None)):
- raise ValueError(
- "LoRA is not available on this load: the file's fp8 layers are stored as fp8 and widened per layer "
- "(this GPU has no fp8 GEMM), which cannot carry adapters. Load the file with the LoRA selected "
- "(Unsloth then widens those layers at load), or set UNSLOTH_DIFFUSION_FP8_STORAGE=0."
- )
- if not diffusion_lora.supports_lora(
+ blocked = _lora_load_block_reason(pipe)
+ if blocked:
+ raise ValueError(blocked)
+ unavailable = diffusion_lora.lora_unavailable_reason(
engine = "diffusers",
family = getattr(state.family, "name", None),
model_kind = state.kind,
transformer_quant = state.transformer_quant,
compiled = "compiled" in (getattr(state, "speed_optims", ()) or ()),
- ):
- # Name only routes the user can actually reach: a GPU host never selects the native engine on its own
- raise ValueError(
- "LoRA is not supported for this model/quantisation on the diffusers engine "
- "(GGUF-via-diffusers, or a torch.compile'd Speed=default/max load). Reload with "
- "transformer_quant int8 or fp8, which rebuilds the GGUF into a LoRA-capable dense "
- "transformer, or use a bf16 / bnb-4bit load at Speed=off/eager. To keep the GGUF "
- "weights themselves, reload it on the native engine (Advanced > Engine > Native, "
- "or engine=sd_cpp on the load), which a GPU host does not select on its own."
- )
+ )
+ if unavailable:
+ raise ValueError(unavailable)
desired = self._resolve_lora_set(
specs,
@@ -14771,10 +14749,10 @@ class DiffusionBackend:
transformer_quant = state.transformer_quant,
)
compiled = "compiled" in (getattr(state, "speed_optims", ()) or ())
- lora_load_ok = (
- not _small_host_int8(state.pipe)
- and not comfy_block_runtime_layers(getattr(state.pipe, "transformer", None))
- and not fp8_stored_layers(getattr(state.pipe, "transformer", None))
+ lora_block = _lora_load_block_reason(state.pipe)
+ lora_load_ok = lora_block is None
+ lora_reason = lora_block or diffusion_lora.lora_unavailable_reason(
+ compiled = compiled, **lora_gate
)
return {
"loaded": True,
@@ -14842,8 +14820,8 @@ class DiffusionBackend:
"conditioning": conditioning_capabilities(
state.family, _family_workflows(state.family)
),
- "supports_lora": lora_load_ok
- and diffusion_lora.supports_lora(compiled = compiled, **lora_gate),
+ "supports_lora": lora_reason is None,
+ "lora_unavailable_reason": lora_reason,
# Only Speed=Auto's 3rd-image compile blocks LoRA: a reload stays eager until then.
"lora_after_reload": lora_load_ok
and compiled
@@ -14868,6 +14846,30 @@ def _small_host_int8(pipe: Any) -> bool:
return any(str(v).startswith("int8") for v in (info.get("components") or {}).values())
+def _lora_load_block_reason(pipe: Any) -> Optional[str]:
+ """Why this load's transformer cannot carry adapters whatever the family and quant allow, or None."""
+ if _small_host_int8(pipe):
+ return (
+ "LoRA is not available on this load: system RAM was too small for the dense model, so Unsloth "
+ "stored the transformer as int8 weights (small-host route), which cannot carry adapters. Use a host "
+ "with more RAM, or name the LoRA in the API load request (Unsloth then keeps the dense transformer)."
+ )
+ if comfy_block_runtime_layers(getattr(pipe, "transformer", None)):
+ return (
+ "LoRA is not available on this load: the ComfyUI file's nvfp4 / mxfp8 layers run on their own "
+ "quantized Linears, which cannot carry adapters. Set UNSLOTH_DIFFUSION_COMFY_NVFP4=0 / "
+ "UNSLOTH_DIFFUSION_COMFY_MXFP8=0, or name the LoRA in the API load request (Unsloth then dequantizes "
+ "those layers)."
+ )
+ if fp8_stored_layers(getattr(pipe, "transformer", None)):
+ return (
+ "LoRA is not available on this load: the file's fp8 layers are stored as fp8 and widened per layer "
+ "(this GPU has no fp8 GEMM), which cannot carry adapters. Set UNSLOTH_DIFFUSION_FP8_STORAGE=0, or name "
+ "the LoRA in the API load request (Unsloth then widens those layers at load)."
+ )
+ return None
+
+
def _transformer_quant_backend(state: Any) -> Optional[str]:
"""Which NVFP4 kernel path the loaded denoiser runs, read from the MODULE TREE, or None. Never raises."""
if getattr(state, "transformer_quant", None) != TQ_NVFP4:
diff --git a/studio/backend/core/inference/diffusion_engine_router.py b/studio/backend/core/inference/diffusion_engine_router.py
index a309e013e26..2f7d0dcedf8 100644
--- a/studio/backend/core/inference/diffusion_engine_router.py
+++ b/studio/backend/core/inference/diffusion_engine_router.py
@@ -482,8 +482,8 @@ def mlx_selection(
) -> 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).
- ``with_loras`` says the load applies LoRA adapters, which the MLX engine cannot, so the load keeps the engine it
- would have had without MLX (in every mode) instead of reaching the MLX LoRA refusal.
+ ``with_loras`` says the load applies LoRA adapters: a family whose MLX build cannot keeps the engine it would have
+ had without MLX (in every mode) instead of reaching the MLX LoRA refusal.
``load_blocker`` (``mlx_load_blocker``) names a load option MLX cannot honour: in ``auto`` it keeps the load on
diffusers; a forced MLX engine refuses that load in the route instead, as before."""
mode = mlx_mode()
@@ -500,11 +500,13 @@ def mlx_selection(
return False, "UNSLOTH_DIFFUSION_SD_CPP_MPS=1 asks for the native engine on the Mac GPU"
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"
+ if with_loras:
+ from core.inference.mlx_diffusion_routing import mlx_capabilities
+ if not mlx_capabilities(fam.name).loras:
+ return False, f"the MLX engine does not apply LoRA adapters to {fam.name} yet"
from core.inference.mlx_diffusion_convert import quant_convertible
convertible, why = quant_convertible(gguf_filename)
@@ -527,14 +529,12 @@ def mlx_selection(
def mlx_load_blocker(
*,
- loras: Any = None,
component_files: Any = None,
transformer_quant: Optional[str] = None,
text_encoder_quant: Optional[str] = None,
) -> Optional[str]:
from core.inference.mlx_diffusion_routing import load_blocker
return load_blocker(
- loras = loras,
component_files = component_files,
transformer_quant = transformer_quant,
text_encoder_quant = text_encoder_quant,
@@ -558,9 +558,7 @@ def _refuse_lora_fallback(
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"
- )
+ via = "the native sd.cpp engine" if choice == ENGINE_SD_CPP else "the diffusers engine"
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."
diff --git a/studio/backend/core/inference/diffusion_lora.py b/studio/backend/core/inference/diffusion_lora.py
index 9033b08d7fb..bd1365588a2 100644
--- a/studio/backend/core/inference/diffusion_lora.py
+++ b/studio/backend/core/inference/diffusion_lora.py
@@ -658,27 +658,69 @@ def diffusers_lora_family_message(family: Optional[str]) -> str:
)
-def supports_lora(
+def _whole_pipeline_label(family: str) -> Optional[str]:
+ from .diffusion_families import detect_family
+
+ fam = detect_family("", override = family) if family else None
+ if fam is None or not fam.single_file_is_pipeline:
+ return None
+ return fam.label or fam.name
+
+
+def lora_unavailable_reason(
*,
engine: Optional[str],
family: Optional[str],
model_kind: Optional[str],
transformer_quant: Optional[str],
compiled: bool = False,
-) -> bool:
- """Adapters bake before torch.compile for torchao int8/fp8; native sd_cpp is LoRA-capable families only, nvfp4/mxfp8 unsupported."""
+) -> Optional[str]:
+ """Why ``engine`` cannot apply LoRAs to this build, shown on the Images page; None when it can."""
fam = (family or "").lower()
+ name = family or "this model"
+ if engine == "mlx":
+ from .mlx_diffusion_routing import mlx_capabilities
+ if mlx_capabilities(fam).loras:
+ return None
+ return f"The MLX engine does not apply LoRAs to {name} yet."
if engine == "sd_cpp":
- return any(tok in fam for tok in _NATIVE_LORA_FAMILY_TOKENS)
+ if any(tok in fam for tok in _NATIVE_LORA_FAMILY_TOKENS):
+ return None
+ return f"The native sd.cpp engine cannot apply LoRAs to {name}."
if not diffusers_lora_family_supported(fam):
- return False
+ return f"LoRAs are not supported for {name} yet: its pipeline has no LoRA loader."
quant = (transformer_quant or "").lower()
if quant in _DIFFUSERS_LORA_BAKED_QUANT:
- return True # load-time bake; adapters ride inside the compiled quantized build
+ return None # load-time bake; adapters ride inside the compiled quantized build
if quant in _DIFFUSERS_LORA_BLOCKED_QUANT:
- return False
- if model_kind == "gguf":
- return False # GGUF diffusers transformer: use the native engine for LoRA
+ return f"LoRAs cannot be applied to a {quant.upper()} transformer."
+ # A GGUF transformer takes adapters unfused (peft wraps each GGUFLinear); only a whole-pipeline GGUF is refused.
+ whole = _whole_pipeline_label(fam) if model_kind == "gguf" else None
+ if whole:
+ return (
+ f"LoRAs are not applied to a whole-pipeline {whole} GGUF. "
+ "Load the .safetensors checkpoint to use LoRAs."
+ )
if compiled:
- return False # can't load an adapter onto an already-compiled transformer
- return True
+ return "Speed compiled this model, so LoRAs are off. Reload it with Speed set to Off or Eager to use LoRAs."
+ return None
+
+
+def supports_lora(
+ *,
+ engine: Optional[str],
+ family: Optional[str],
+ model_kind: Optional[str],
+ transformer_quant: Optional[str],
+ compiled: bool = False,
+) -> bool:
+ return (
+ lora_unavailable_reason(
+ engine = engine,
+ family = family,
+ model_kind = model_kind,
+ transformer_quant = transformer_quant,
+ compiled = compiled,
+ )
+ is None
+ )
diff --git a/studio/backend/core/inference/mlx_diffusion_backend.py b/studio/backend/core/inference/mlx_diffusion_backend.py
index 2702f1c2f87..b9f7e64c004 100644
--- a/studio/backend/core/inference/mlx_diffusion_backend.py
+++ b/studio/backend/core/inference/mlx_diffusion_backend.py
@@ -41,6 +41,7 @@ from core.inference.diffusion_families import (
supported_family_names,
)
from core.inference import mlx_diffusion_convert as convert
+from core.inference.mlx_diffusion_routing import mlx_capabilities
from core.inference.diffusion_batched import SEED_MASK
from loggers import get_logger
from utils.account_context import account_thread, current_account_id
@@ -421,6 +422,48 @@ class MfluxRuntime:
mx.eval(model.parameters())
return model
+ def apply_loras(self, model: Any, loras: list[tuple[str, float]]) -> None:
+ """Swap in ``loras`` ((path, scale) pairs) unbaked, since baking requantizes; [] restores the base layers."""
+ import mlx.core as mx
+ from mflux.models.common.lora.mapping.lora_loader import LoRALoader
+ from mflux.models.z_image.weights.z_image_lora_mapping import ZImageLoRAMapping
+
+ self.strip_loras(model)
+ if not loras:
+ return
+ try:
+ LoRALoader.load_and_apply_lora(
+ lora_mapping = ZImageLoRAMapping.get_mapping(),
+ transformer = model.transformer,
+ lora_paths = [path for path, _scale in loras],
+ lora_scales = [float(scale) for _path, scale in loras],
+ bake_lora = False,
+ )
+ mx.eval(model.transformer.parameters())
+ except BaseException:
+ self.strip_loras(model)
+ raise
+
+ def strip_loras(self, model: Any) -> None:
+ from mflux.models.common.lora.layer.fused_linear_lora_layer import FusedLoRALinear
+ from mflux.models.common.lora.layer.linear_lokr_layer import LoKrLinear
+ from mflux.models.common.lora.layer.linear_lora_layer import LoRALinear
+ from mflux.models.common.lora.mapping.lora_loader import LoRALoader
+
+ transformer = model.transformer
+ wrapped = [
+ name
+ for name, module in transformer.named_modules()
+ if isinstance(module, (LoRALinear, LoKrLinear, FusedLoRALinear))
+ ]
+ # A fused layer lists its adapters as children: restore only the outermost wrapper.
+ for name in wrapped:
+ if any(name.startswith(outer + ".") for outer in wrapped):
+ continue
+ module = LoRALoader._get_target_module(transformer, name)
+ base = module.base_linear if isinstance(module, FusedLoRALinear) else module.linear
+ LoRALoader._replace_target_module(transformer, name, base)
+
def generate(
self,
model: Any,
@@ -566,6 +609,8 @@ class _MlxState:
convert_dir: str
timings: dict = field(default_factory = dict)
gguf_path: Optional[str] = None
+ hf_token: Optional[str] = None
+ loras: tuple = ()
@dataclass
@@ -945,8 +990,10 @@ class MlxDiffusionBackend:
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.")
+ if loras and not mlx_capabilities(fam.name).loras:
+ raise ValueError(
+ f"LoRA adapters are not supported on the MLX engine for {fam.name} 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)
@@ -1137,6 +1184,7 @@ class MlxDiffusionBackend:
convert_dir = str(out_dir),
timings = timings,
gguf_path = str(gguf_path),
+ hf_token = hf_token,
)
with self._lock:
if self._load_token != _load_token:
@@ -1304,8 +1352,7 @@ class MlxDiffusionBackend:
)
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.")
+ specs = [(i, w) for (i, w) in (loras or []) if w != 0]
steps = int(steps)
if steps < 1:
raise ValueError("steps must be at least 1")
@@ -1337,6 +1384,7 @@ class MlxDiffusionBackend:
self._gen = _MlxGen(total_steps = steps * batch)
try:
runtime = self._rt()
+ self._apply_loras(runtime, state, specs, cancel)
cfg = float(guidance or 0.0) if runtime.supports_guidance(state.model) else None
images = []
seeds_out = []
@@ -1439,6 +1487,35 @@ class MlxDiffusionBackend:
self._active_generate_cancel = None
self._active_generate_account = None
+ @staticmethod
+ def _apply_loras(
+ runtime: Any, state: _MlxState, specs: list[tuple[str, float]], cancel: threading.Event
+ ) -> None:
+ from core.inference import diffusion_lora
+
+ if specs and not mlx_capabilities(state.family.name).loras:
+ raise ValueError(
+ f"LoRA adapters are not supported on the MLX engine for {state.family.name} yet."
+ )
+ resolved = diffusion_lora.resolve_specs(
+ specs, family = state.family.name, hf_token = state.hf_token, cancel_event = cancel
+ )
+ bad = [r.id for r in resolved if r.fmt != "safetensors"]
+ if bad:
+ raise ValueError(
+ "GGUF LoRA adapters are not supported on the MLX engine "
+ f"({', '.join(bad)}); use a .safetensors adapter, or the native engine."
+ )
+ desired = tuple((r.path, float(r.weight)) for r in resolved)
+ if desired == state.loras:
+ return
+ state.loras = ()
+ try:
+ runtime.apply_loras(state.model, list(desired))
+ except Exception as exc: # noqa: BLE001 -- surface as a clean 400; the base layers are restored
+ raise ValueError(f"Failed to apply LoRA: {exc}") from exc
+ state.loras = desired
+
def generate_progress(self) -> dict[str, Any]:
gen = self._gen
if gen is None or gen.total_steps <= 0:
@@ -1573,6 +1650,7 @@ class MlxDiffusionBackend:
"conditioning": None,
}
from core.inference.diffusion_conditioning import conditioning_capabilities
+ from core.inference.diffusion_lora import lora_unavailable_reason
from hub.utils.gguf import extract_quant_token
conditioning = conditioning_capabilities(state.family, ["txt2img"])
@@ -1582,6 +1660,9 @@ class MlxDiffusionBackend:
guided = bool(self._rt().supports_guidance(state.model))
except Exception: # noqa: BLE001
guided = False
+ lora_reason = lora_unavailable_reason(
+ engine = ENGINE_NAME, family = state.family.name, model_kind = "gguf", transformer_quant = None
+ )
return {
"loaded": True,
"repo_id": state.repo_id,
@@ -1614,7 +1695,8 @@ class MlxDiffusionBackend:
"dense_bits": state.dense_bits,
"timings": dict(state.timings),
},
- "supports_lora": False,
+ "supports_lora": lora_reason is None,
+ "lora_unavailable_reason": lora_reason,
"supports_controlnet": False,
"supports_negative_prompt": guided,
# CFG, and with it the negative prompt, engages only above guidance 1 (cache_text_encodings, generate).
diff --git a/studio/backend/core/inference/mlx_diffusion_routing.py b/studio/backend/core/inference/mlx_diffusion_routing.py
index b4c22dde6bc..8aafe744e19 100644
--- a/studio/backend/core/inference/mlx_diffusion_routing.py
+++ b/studio/backend/core/inference/mlx_diffusion_routing.py
@@ -38,7 +38,7 @@ class MlxCapabilities:
_DEFAULT_CAPABILITIES = MlxCapabilities()
-MLX_CAPABILITIES: dict[str, MlxCapabilities] = {"z-image": _DEFAULT_CAPABILITIES}
+MLX_CAPABILITIES: dict[str, MlxCapabilities] = {"z-image": MlxCapabilities(loras = True)}
def mlx_capabilities(family: Optional[str]) -> MlxCapabilities:
@@ -58,15 +58,11 @@ def _positive(value: Any) -> bool:
def load_blocker(
*,
- loras: Any = None,
component_files: Any = None,
transformer_quant: Optional[str] = None,
text_encoder_quant: Optional[str] = None,
) -> Optional[str]:
- from core.inference.diffusion_engine_router import has_active_loras
-
- if has_active_loras(loras):
- return "LoRA adapters selected at load time need the diffusers engine"
+ """Load options MLX cannot honour. LoRAs are not one: ``mlx_selection`` weighs them per family."""
if component_files:
return "separate text-encoder / VAE files need the diffusers engine"
if _explicit(transformer_quant):
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index 281094ca460..bf05e7bad63 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -5420,6 +5420,9 @@ class SdCppDiffusionBackend:
"For transparent output on the native engine, raise Guidance above 1 (upstream uses 6)."
)
conditioning["notes"] = notes
+ lora_reason = diffusion_lora.lora_unavailable_reason(
+ engine = "sd_cpp", family = state.family.name, model_kind = "gguf", transformer_quant = None
+ )
return {
"loaded": True,
@@ -5449,12 +5452,8 @@ class SdCppDiffusionBackend:
"transformer_cache": None,
"resolved": state.resolved,
"engine": "sd_cpp",
- "supports_lora": diffusion_lora.supports_lora(
- engine = "sd_cpp",
- family = state.family.name,
- model_kind = "gguf",
- transformer_quant = None,
- ),
+ "supports_lora": lora_reason is None,
+ "lora_unavailable_reason": lora_reason,
"supports_controlnet": False,
"supports_negative_prompt": state.family.name not in _EMBEDDED_GUIDANCE_FAMILIES,
"negative_prompt_min_guidance": _negative_prompt_guidance_threshold(state.family),
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index de476c68dd6..2e68d6e8126 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -6117,7 +6117,12 @@ class DiffusionStatusResponse(BaseModel):
"LoRA picker's enabled state). torchao int8/fp8 builds support LoRA via the load-time "
"bake: select the adapters when loading; weight changes apply live, a different adapter "
"set needs a reload. False on unsupported families/quant (e.g. nvfp4/mxfp8, "
- "GGUF-via-diffusers, or Qwen-Image on the native engine).",
+ "a whole-pipeline SDXL GGUF, or Qwen-Image on the native engine).",
+ )
+ lora_unavailable_reason: Optional[str] = Field(
+ None,
+ description = "Why the loaded model cannot apply LoRA adapters on its current engine, shown on the "
+ "Images page in place of the LoRA picker. Null when supports_lora is true or nothing is loaded.",
)
supports_controlnet: bool = Field(
False,
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 55b7505c266..4ae83c8cc0d 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -47391,7 +47391,6 @@ def _refuse_native_component_files(request: DiffusionLoadRequest) -> None:
def _mlx_load_blocker(request: DiffusionLoadRequest) -> Optional[str]:
from core.inference.diffusion_engine_router import mlx_load_blocker
return mlx_load_blocker(
- loras = request.loras,
component_files = _component_file_kwargs(request),
transformer_quant = request.transformer_quant,
text_encoder_quant = request.text_encoder_quant,
@@ -47403,12 +47402,14 @@ def _has_active_loras(loras: Any) -> bool:
return has_active_loras(loras)
-def _refuse_mlx_loras(request: DiffusionLoadRequest) -> None:
+def _refuse_mlx_loras(request: DiffusionLoadRequest, fam: Any) -> None:
# Zero-weight entries are dropped before loading, so only an applied adapter is refused.
- if _has_active_loras(request.loras):
+ from core.inference.mlx_diffusion_routing import mlx_capabilities
+ name = getattr(fam, "name", None)
+ if _has_active_loras(request.loras) and not mlx_capabilities(name).loras:
raise HTTPException(
status_code = 400,
- detail = "LoRA adapters are not supported on the MLX engine yet.",
+ detail = f"LoRA adapters are not supported on the MLX engine for {name} yet.",
)
@@ -47512,7 +47513,7 @@ async def diffusion_download_plan(
planner = get_sd_cpp_backend()
elif predicted == ENGINE_MLX:
_refuse_native_component_files(request)
- _refuse_mlx_loras(request)
+ _refuse_mlx_loras(request, fam)
from core.inference.mlx_diffusion_backend import get_mlx_diffusion_backend
planner = get_mlx_diffusion_backend()
@@ -47874,7 +47875,7 @@ async def load_diffusion_model_gated(
# 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)
+ _refuse_mlx_loras(request, fam)
# 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
@@ -47969,7 +47970,7 @@ async def load_diffusion_model_gated(
if activated in (ENGINE_SD_CPP, ENGINE_MLX):
_refuse_native_component_files(request)
if activated == ENGINE_MLX:
- _refuse_mlx_loras(request)
+ _refuse_mlx_loras(request, fam)
_assert_native_precision_unset(
transformer_quant = request.transformer_quant,
text_encoder_quant = request.text_encoder_quant,
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 71ab97d2523..9c0ebee53c4 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -1131,6 +1131,7 @@ def test_speed_auto_compile_reports_that_a_reload_brings_lora_back(
backend = DiffusionBackend()
status = _load_into(backend, tmp_path, **load)
assert (status["supports_lora"], status["lora_after_reload"]) == (True, False)
+ assert status["lora_unavailable_reason"] is None
for p in ("one", "two", "three"):
backend.generate(prompt = p)
status = backend.status()
@@ -1143,15 +1144,62 @@ def test_speed_auto_compile_reports_that_a_reload_brings_lora_back(
status = _load_into(backend, tmp_path, **load)
assert (status["supports_lora"], status["lora_after_reload"]) == (True, False)
- # An explicit compiled tier compiles at load: a reload would not help, so no hint.
+ # An explicit compiled tier compiles at load: a reload would not help, so no hint, only the reason.
backend.unload()
status = _load_into(backend, tmp_path, speed_mode = "default", **load)
assert "compiled" in status["speed_optims"]
assert (status["supports_lora"], status["lora_after_reload"]) == (False, False)
+ assert "Speed" in DiffusionStatusResponse(**status).lora_unavailable_reason
backend.unload()
assert backend.status()["lora_after_reload"] is False
+def test_a_gguf_on_diffusers_applies_loras_unfused(fake_runtime, tmp_path, monkeypatch):
+ backend = _loaded_backend(tmp_path)
+ status = backend.status()
+ assert (status["model_kind"], status["transformer_quant"]) == ("gguf", None)
+ assert status["supports_lora"] is True and status["lora_unavailable_reason"] is None
+ applied: list = []
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_resolve_lora_set",
+ lambda self, specs, **kw: (("style", "/loras/style.safetensors", 0.7),),
+ )
+ monkeypatch.setattr(
+ _FakePipe,
+ "load_lora_weights",
+ lambda self, path, adapter_name = None: applied.append((path, adapter_name)),
+ raising = False,
+ )
+ monkeypatch.setattr(
+ _FakePipe,
+ "set_adapters",
+ lambda self, names, adapter_weights = None: applied.append((names, adapter_weights)),
+ raising = False,
+ )
+ monkeypatch.setattr(_FakePipe, "unload_lora_weights", lambda self: None, raising = False)
+ backend.generate(prompt = "a fox", loras = [("style", 0.7)])
+ assert applied == [("/loras/style.safetensors", "style"), (["style"], [0.7])]
+ assert getattr(backend._state.pipe, "_unsloth_loras_baked", False) is False
+ backend.unload()
+
+
+def test_a_load_that_cannot_carry_adapters_reports_why(fake_runtime, tmp_path, monkeypatch):
+ from core.inference import diffusion as dmod
+
+ (tmp_path / "model.safetensors").write_bytes(b"weights")
+ backend = DiffusionBackend()
+ _load_into(backend, tmp_path, gguf_filename = "model.safetensors", family_override = "qwen-image")
+ monkeypatch.setattr(dmod, "_small_host_int8", lambda pipe: True)
+ status = backend.status()
+ assert status["supports_lora"] is False
+ assert "small-host route" in status["lora_unavailable_reason"]
+ with pytest.raises(ValueError) as raised:
+ backend.generate(prompt = "a fox", loras = [("adapter", 1.0)])
+ assert str(raised.value) == status["lora_unavailable_reason"]
+ backend.unload()
+
+
def test_deferred_speed_stays_off_when_only_an_explicit_tier_may_compile(
fake_runtime, tmp_path, monkeypatch
):
diff --git a/studio/backend/tests/test_diffusion_lora.py b/studio/backend/tests/test_diffusion_lora.py
index 99a7bfa180a..cb309efd0ec 100644
--- a/studio/backend/tests/test_diffusion_lora.py
+++ b/studio/backend/tests/test_diffusion_lora.py
@@ -89,9 +89,25 @@ def test_supports_lora_matrix():
assert not dl.supports_lora(
engine = "diffusers", family = "flux.1", model_kind = "single_file", transformer_quant = "mxfp8"
)
- assert not dl.supports_lora(
+ assert dl.supports_lora(
engine = "diffusers", family = "flux.1", model_kind = "gguf", transformer_quant = None
)
+ assert dl.supports_lora(
+ engine = "diffusers", family = "z-image", model_kind = "gguf", transformer_quant = None
+ )
+ assert not dl.supports_lora(
+ engine = "diffusers", family = "sdxl", model_kind = "gguf", transformer_quant = None
+ )
+ assert dl.supports_lora(
+ engine = "diffusers", family = "sdxl", model_kind = "single_file", transformer_quant = None
+ )
+ assert not dl.supports_lora(
+ engine = "diffusers",
+ family = "z-image",
+ model_kind = "gguf",
+ transformer_quant = None,
+ compiled = True,
+ )
# diffusers needs a non-hotswap adapter loaded before compilation.
assert not dl.supports_lora(
engine = "diffusers",
@@ -109,6 +125,50 @@ def test_supports_lora_matrix():
)
[email protected]("engine", ["diffusers", "sd_cpp", "mlx"])
+ "family", ["flux.1", "z-image", "qwen-image", "lumina-2", "sdxl", "moss-image", None]
+)
[email protected]("model_kind", ["gguf", "pipeline", "single_file"])
[email protected]("quant", [None, "int8", "fp8", "nvfp4", "mxfp8"])
[email protected]("compiled", [False, True])
+def test_every_build_without_lora_names_a_reason(engine, family, model_kind, quant, compiled):
+ # The Images page shows this reason in place of the picker, so a False gate must never come without one.
+ gate = dict(
+ engine = engine,
+ family = family,
+ model_kind = model_kind,
+ transformer_quant = quant,
+ compiled = compiled,
+ )
+ reason = dl.lora_unavailable_reason(**gate)
+ assert dl.supports_lora(**gate) is (reason is None)
+ assert reason is None or reason.strip()
+
+
+def test_lora_unavailable_reason_names_the_cause():
+ gguf = dict(model_kind = "gguf", transformer_quant = None)
+ assert dl.lora_unavailable_reason(engine = "mlx", family = "z-image", **gguf) is None
+ assert "MLX" in dl.lora_unavailable_reason(engine = "mlx", family = "flux.1", **gguf)
+ assert "qwen-image" in dl.lora_unavailable_reason(engine = "sd_cpp", family = "qwen-image", **gguf)
+ assert dl.lora_unavailable_reason(engine = "diffusers", family = "lumina-2", **gguf) is None
+ sdxl = dl.lora_unavailable_reason(engine = "diffusers", family = "sdxl", **gguf)
+ assert "whole-pipeline" in sdxl and ".safetensors" in sdxl
+ assert "NVFP4" in dl.lora_unavailable_reason(
+ engine = "diffusers", family = "flux.1", model_kind = "pipeline", transformer_quant = "nvfp4"
+ )
+ assert "no LoRA loader" in dl.lora_unavailable_reason(
+ engine = "diffusers", family = "moss-image", model_kind = "pipeline", transformer_quant = None
+ )
+ assert "Speed" in dl.lora_unavailable_reason(
+ engine = "diffusers",
+ family = "flux.1",
+ model_kind = "pipeline",
+ transformer_quant = None,
+ compiled = True,
+ )
+
+
def test_resolve_specs_maps_cancelled_to_diffusion_sentinel(tmp_path, monkeypatch):
# A cancelled Hub download raises RuntimeError("Cancelled"); it maps to the sentinel so the route returns 409.
def _boom(spec_id, weight, **kw):
diff --git a/studio/backend/tests/test_diffusion_mlx_engine_router.py b/studio/backend/tests/test_diffusion_mlx_engine_router.py
index 861298319b1..f62bce543cc 100644
--- a/studio/backend/tests/test_diffusion_mlx_engine_router.py
+++ b/studio/backend/tests/test_diffusion_mlx_engine_router.py
@@ -14,6 +14,13 @@ 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
+
+def _mlx_without_lora(monkeypatch):
+ """Z-Image's MLX build applies LoRAs; the fallback rules below are for a family whose build does not."""
+ from core.inference import mlx_diffusion_routing as routing
+ monkeypatch.setitem(routing.MLX_CAPABILITIES, "z-image", routing.MlxCapabilities(loras = False))
+
+
_ENVS = (
"UNSLOTH_DIFFUSION_ENGINE",
"UNSLOTH_DIFFUSION_SD_CPP",
@@ -201,7 +208,6 @@ def test_auto_on_other_hosts_is_todays_engine_and_records_nothing(monkeypatch, v
@pytest.mark.parametrize(
"blocker_kwargs, needle",
[
- ({"loras": [("some/lora", 1.0)]}, "LoRA"),
({"component_files": {"vae_file": "vae.safetensors"}}, "text-encoder / VAE"),
({"transformer_quant": "int8"}, "transformer precision (int8)"),
({"text_encoder_quant": "fp8"}, "text-encoder precision (fp8)"),
@@ -233,7 +239,7 @@ def test_native_lora_pick_on_a_mac_is_never_an_mlx_refusal(monkeypatch, value):
monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", value)
monkeypatch.setattr(r, "ensure_sd_cpp_binary", lambda **_: "/usr/bin/sd-cli")
monkeypatch.setattr(r, "SdCppEngine", lambda **_: SimpleNamespace(version = lambda: "v0"))
- blocker = r.mlx_load_blocker(loras = [("some/lora", 1.0)])
+ blocker = r.mlx_load_blocker()
fam = detect_family("z-image")
use_mlx, reason = r.mlx_selection(
fam, model_kind = "gguf", gguf_filename = _Q4, engine = ENGINE_SD_CPP, load_blocker = blocker
@@ -573,8 +579,25 @@ def test_auto_switch_planner_judges_mlx_with_the_picks_gguf(monkeypatch):
@pytest.mark.parametrize("value", [None, "auto"])
@pytest.mark.parametrize("gguf", [_Q4, "z-image-turbo-Q4_K_M.gguf", "z-image-turbo-Q5_1.gguf"])
-def test_a_lora_load_declines_mlx_under_default_routing(monkeypatch, value, gguf):
+def test_a_lora_load_stays_on_mlx_when_its_build_applies_loras(monkeypatch, value, gguf):
+ _apple(monkeypatch)
+ if value is not None:
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", value)
+ fam = detect_family("z-image")
+ kw = dict(model_kind = "gguf", gguf_filename = gguf, with_loras = True)
+ assert r.predict_engine(fam, **kw) == ENGINE_MLX
+ r.select_and_activate_engine(fam, **kw)
+ assert r.active_engine_name() == ENGINE_MLX
+ assert r.annotate_status({})["mlx_fallback_reason"] is None
+
+
[email protected]("value", [None, "auto"])
[email protected]("gguf", [_Q4, "z-image-turbo-Q4_K_M.gguf", "z-image-turbo-Q5_1.gguf"])
+def test_a_lora_load_declines_an_mlx_build_without_loras_under_default_routing(
+ monkeypatch, value, gguf
+):
_apple(monkeypatch)
+ _mlx_without_lora(monkeypatch)
if value is not None:
monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", value)
fam = detect_family("z-image")
@@ -586,14 +609,34 @@ def test_a_lora_load_declines_mlx_under_default_routing(monkeypatch, value, gguf
assert "LoRA" in (r.annotate_status({})["mlx_fallback_reason"] or "")
[email protected]("sd_cpp_off", [False, True])
+def test_a_forced_mlx_lora_load_falls_back_to_diffusers_which_applies_them_to_the_gguf(
+ monkeypatch, sd_cpp_off
+):
+ _apple(monkeypatch)
+ _mlx_without_lora(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)
+ assert r.predict_engine(fam, **kw) == ENGINE_DIFFUSERS
+ r.select_and_activate_engine(fam, **kw)
+ assert r.active_engine_name() == ENGINE_DIFFUSERS
+
+
@pytest.mark.parametrize("sd_cpp_off", [False, True])
def test_a_forced_mlx_lora_load_with_no_lora_capable_fallback_is_refused_before_the_switch(
monkeypatch, sd_cpp_off
):
+ from core.inference import diffusion_lora
+
_apple(monkeypatch)
monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", "1")
if sd_cpp_off:
monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP", "0")
+ _mlx_without_lora(monkeypatch)
+ monkeypatch.setattr(diffusion_lora, "supports_lora", lambda **_: False)
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
@@ -604,8 +647,26 @@ def test_a_forced_mlx_lora_load_with_no_lora_capable_fallback_is_refused_before_
assert r.active_engine_name() == ENGINE_MLX
[email protected]("value", [None, "1"])
+def test_a_lora_load_stays_on_mlx_over_the_native_mps_knob_only_when_forced(monkeypatch, value):
+ _apple(monkeypatch)
+ if value is not None:
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_MLX", value)
+ 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")
+ kw = dict(model_kind = "gguf", gguf_filename = _Q4, with_loras = True)
+ # The knob already sends an auto load to sd.cpp; a forced MLX engine now keeps a LoRA load.
+ expected = ENGINE_MLX if value == "1" else ENGINE_SD_CPP
+ assert r.predict_engine(fam, **kw) == expected
+ r.select_and_activate_engine(fam, **kw)
+ assert r.active_engine_name() == expected
+
+
def test_a_forced_mlx_lora_load_keeps_a_lora_capable_sd_cpp(monkeypatch):
_apple(monkeypatch)
+ _mlx_without_lora(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")
@@ -686,6 +747,7 @@ def test_every_load_route_and_the_residency_estimate_pass_loras_to_engine_select
)
def test_a_lora_load_keeps_sd_cpp_under_the_mlx_opt_in(monkeypatch, gguf):
_apple(monkeypatch)
+ _mlx_without_lora(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")
@@ -701,6 +763,7 @@ def test_a_lora_load_keeps_sd_cpp_under_the_mlx_opt_in(monkeypatch, gguf):
def test_a_lora_load_without_the_mlx_opt_in_still_falls_back_to_diffusers(monkeypatch):
_apple(monkeypatch)
+ _mlx_without_lora(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
@@ -732,4 +795,3 @@ def test_a_zero_weight_lora_load_still_lands_on_mlx(monkeypatch):
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
- assert r.mlx_load_blocker(loras = [("a", 0.0)]) is None
diff --git a/studio/backend/tests/test_diffusion_routes.py b/studio/backend/tests/test_diffusion_routes.py
index c743148b686..eb95c03d2ac 100644
--- a/studio/backend/tests/test_diffusion_routes.py
+++ b/studio/backend/tests/test_diffusion_routes.py
@@ -3517,17 +3517,23 @@ def test_the_image_unload_answers_are_declared_in_the_schema(token_client):
assert stale == {"unloaded": False, "outcome": "superseded"}
-def test_zero_weight_loras_neither_refuse_mlx_nor_route_away_from_it():
+def test_zero_weight_loras_neither_refuse_mlx_nor_route_away_from_it(monkeypatch):
# Weight 0 disables an adapter and every loader drops it, so an all-zero list is no LoRA load.
from fastapi import HTTPException
+ from core.inference import mlx_diffusion_routing as routing
+ from core.inference.diffusion_families import detect_family
from models.inference import DiffusionLoadRequest, LoraSpec
+ z_image = detect_family("z-image")
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(off.loras) is False
assert inference_routes._has_active_loras(on.loras) is True
+ inference_routes._refuse_mlx_loras(off, z_image)
+ inference_routes._refuse_mlx_loras(on, z_image)
+ monkeypatch.setitem(routing.MLX_CAPABILITIES, "z-image", routing.MlxCapabilities(loras = False))
+ inference_routes._refuse_mlx_loras(off, z_image)
with pytest.raises(HTTPException):
- inference_routes._refuse_mlx_loras(on)
+ inference_routes._refuse_mlx_loras(on, z_image)
diff --git a/studio/backend/tests/test_mlx_diffusion_backend.py b/studio/backend/tests/test_mlx_diffusion_backend.py
index 4422dd1a933..e0fdca211d8 100644
--- a/studio/backend/tests/test_mlx_diffusion_backend.py
+++ b/studio/backend/tests/test_mlx_diffusion_backend.py
@@ -33,6 +33,8 @@ class FakeRuntime:
def __init__(self):
self.builds = []
self.generates = []
+ self.lora_calls = []
+ self.lora_error: Exception | None = None
self.freed = 0
self.step_gate: threading.Event | None = None
self.in_step = threading.Event()
@@ -71,6 +73,13 @@ class FakeRuntime:
on_step(t + 1)
return Image.new("RGB", (width, height), (seed % 255, 0, 0))
+ def apply_loras(self, model, loras):
+ self.lora_calls.append(list(loras))
+ if self.lora_error is not None:
+ model["loras"] = []
+ raise self.lora_error
+ model["loras"] = list(loras)
+
def free(self):
self.freed += 1
@@ -206,6 +215,8 @@ def test_load_then_status_and_guards(env):
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 status["supports_lora"] is True
+ assert status["lora_unavailable_reason"] is None
assert runtime.builds[0]["model_config"] == "z-image-turbo"
model_dir = Path(runtime.builds[0]["model_path"])
for sub in ("text_encoder", "tokenizer", "vae"):
@@ -252,7 +263,6 @@ def test_local_files_only_reaches_every_fetch(env):
({"gguf_filename": "z-image-turbo-Q3_K_M.gguf"}, "Q3_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):
@@ -320,7 +330,6 @@ def test_generate_batch_seeds_and_progress(env):
{"upscale": 2.0},
{"prompts": ["a", "b"]},
{"seeds": [1, 2]},
- {"loras": [("x/y", 1.0)]},
{"controlnet": ("c", "img", "canny", 1.0, 0.0, 1.0)},
],
)
@@ -1472,6 +1481,78 @@ def test_cache_only_companions_skip_an_incomplete_upstream_for_the_staged_mirror
mb.fetch_base_snapshot(BASE, None, local_files_only = True)
+def _resolved_loras(monkeypatch, fmt = "safetensors"):
+ from core.inference import diffusion_lora
+
+ seen = []
+
+ def _resolve(
+ specs,
+ *,
+ family,
+ hf_token,
+ cancel_event = None,
+ ):
+ seen.append((list(specs), family))
+ return [
+ diffusion_lora.ResolvedLora(
+ i, diffusion_lora.sanitize_alias(i), f"/loras/{i}.{fmt}", fmt, w
+ )
+ for i, w in specs
+ ]
+
+ monkeypatch.setattr(diffusion_lora, "resolve_specs", _resolve)
+ return seen
+
+
+def test_generate_attaches_resolved_loras_and_reattaches_only_on_change(env, monkeypatch):
+ backend, runtime, _calls = env
+ seen = _resolved_loras(monkeypatch)
+ _load(backend, loras = [("style", 1.0)])
+ backend.generate(prompt = "x", steps = 1, loras = [("style", 0.8), ("off", 0.0)])
+ assert seen[-1] == ([("style", 0.8)], "z-image")
+ assert runtime.lora_calls == [[("/loras/style.safetensors", 0.8)]]
+ backend.generate(prompt = "x", steps = 1, loras = [("style", 0.8)])
+ assert len(runtime.lora_calls) == 1
+ backend.generate(prompt = "x", steps = 1, loras = [("style", 0.5)])
+ assert runtime.lora_calls[-1] == [("/loras/style.safetensors", 0.5)]
+ backend.generate(prompt = "x", steps = 1)
+ assert runtime.lora_calls[-1] == []
+ assert len(runtime.generates) == 4
+ backend.generate(prompt = "x", steps = 1)
+ assert len(runtime.lora_calls) == 3
+
+
+def test_generate_refuses_a_gguf_adapter_and_reports_a_failed_attach(env, monkeypatch):
+ backend, runtime, _calls = env
+ _load(backend)
+ _resolved_loras(monkeypatch, fmt = "gguf")
+ with pytest.raises(ValueError, match = "GGUF LoRA adapters are not supported on the MLX engine"):
+ backend.generate(prompt = "x", steps = 1, loras = [("style", 1.0)])
+ assert runtime.lora_calls == [] and runtime.generates == []
+ _resolved_loras(monkeypatch)
+ runtime.lora_error = RuntimeError("no layer matched")
+ with pytest.raises(ValueError, match = "Failed to apply LoRA: no layer matched"):
+ backend.generate(prompt = "x", steps = 1, loras = [("style", 1.0)])
+ assert backend._state.loras == () and runtime.generates == []
+ runtime.lora_error = None
+ backend.generate(prompt = "x", steps = 1, loras = [("style", 1.0)])
+ assert backend._state.loras == (("/loras/style.safetensors", 1.0),)
+
+
+def test_a_family_without_mlx_loras_is_still_refused(env, monkeypatch):
+ from core.inference import mlx_diffusion_routing as routing
+
+ backend, _runtime, _calls = env
+ monkeypatch.setitem(routing.MLX_CAPABILITIES, "z-image", routing.MlxCapabilities(loras = False))
+ with pytest.raises(ValueError, match = "LoRA"):
+ backend.begin_load(REPO, gguf_filename = GGUF, loras = [("a/b", 1.0)])
+ _load(backend)
+ with pytest.raises(ValueError, match = "LoRA"):
+ backend.generate(prompt = "x", steps = 1, loras = [("a/b", 1.0)])
+ assert backend.status()["supports_lora"] is False
+
+
def _mlx_route_stubs(monkeypatch, *, predicted = "mlx"):
import core.inference.diffusion_engine_router as router_module
import core.inference.gpu_arbiter as arbiter
@@ -1498,9 +1579,27 @@ def _mlx_route_stubs(monkeypatch, *, predicted = "mlx"):
return touched
+def _mlx_without_lora(monkeypatch):
+ from core.inference import mlx_diffusion_routing as routing
+ monkeypatch.setitem(routing.MLX_CAPABILITIES, "z-image", routing.MlxCapabilities(loras = False))
+
+
+def test_the_load_route_keeps_z_image_loras_on_mlx():
+ from core.inference.diffusion_families import detect_family
+ from models.inference import DiffusionLoadRequest
+ from routes.inference import _refuse_mlx_loras
+
+ request = DiffusionLoadRequest(
+ model_path = REPO, gguf_filename = GGUF, loras = [{"id": "a/b", "weight": 1.0}]
+ )
+ _refuse_mlx_loras(request, detect_family("z-image"))
+
+
def test_the_load_route_refuses_mlx_loras_before_activation_or_eviction(monkeypatch):
import asyncio
+ _mlx_without_lora(monkeypatch)
+
from fastapi import HTTPException
from models.inference import DiffusionLoadRequest
@@ -1520,6 +1619,8 @@ def test_the_load_route_refuses_mlx_loras_before_activation_or_eviction(monkeypa
def test_the_download_plan_refuses_mlx_loras_before_planning(monkeypatch):
import asyncio
+ _mlx_without_lora(monkeypatch)
+
from fastapi import HTTPException
from models.inference import DiffusionLoadRequest
diff --git a/studio/backend/tests/test_mlx_diffusion_routing.py b/studio/backend/tests/test_mlx_diffusion_routing.py
index 9298e51f0df..50540f75303 100644
--- a/studio/backend/tests/test_mlx_diffusion_routing.py
+++ b/studio/backend/tests/test_mlx_diffusion_routing.py
@@ -295,7 +295,6 @@ def test_when_both_fit_both_stay_resident_and_txt2img_returns_to_mlx(rig):
({"upscale": 2.0}, "upscaling"),
({"prompts": ["a", "b"]}, "lists"),
({"seeds": [1, 2]}, "lists"),
- ({"loras": [("l", 1.0)]}, "LoRA"),
({"controlnet": ("c", "img", "canny", 0.8, 0.0, 1.0)}, "ControlNet"),
({"sampler": "euler"}, "sampler"),
({"schedule_type": "karras"}, "sampler"),
@@ -640,6 +639,20 @@ def test_a_pinned_original_precision_keeps_the_load_on_diffusers(field, value):
assert blocker and value in blocker
+def test_a_lora_request_stays_on_mlx_for_a_family_whose_build_applies_loras(rig):
+ assert routing.mlx_capabilities("z-image").loras is True
+ assert (
+ routing.request_blocker(
+ {"prompt": "p", "loras": [("l", 1.0)]},
+ family = "z-image",
+ mlx_params = frozenset({"prompt", "loras"}),
+ )
+ is None
+ )
+ assert rig.engine.generate(prompt = "p", loras = [("l", 1.0)])["engine"] == "mlx"
+ assert "LoRA" in routing.request_blocker({"prompt": "p", "loras": [("l", 1.0)]}, family = "other")
+
+
def test_unload_forwards_the_account_scope_to_the_fallback(rig):
rig.fit["coexist"] = True
_img2img(rig.engine)
@@ -690,7 +703,6 @@ def test_generate_signature_is_the_union_of_both_engines(rig):
def test_load_blocker_matrix():
assert routing.load_blocker() is None
assert routing.load_blocker(transformer_quant = "auto", text_encoder_quant = "default") is None
- assert "LoRA" in routing.load_blocker(loras = [("a", 1.0)])
assert "VAE" in routing.load_blocker(component_files = {"vae_file": "v"})
assert "int8" in routing.load_blocker(transformer_quant = "int8")
assert "fp8" in routing.load_blocker(text_encoder_quant = "fp8")
diff --git a/studio/backend/tests/test_sd_cpp_backend.py b/studio/backend/tests/test_sd_cpp_backend.py
index 9a5d697fdcd..24a1e059c21 100644
--- a/studio/backend/tests/test_sd_cpp_backend.py
+++ b/studio/backend/tests/test_sd_cpp_backend.py
@@ -850,6 +850,16 @@ def test_status_loaded_shape():
assert st["gguf_variant"] is None
for k in ("transformer_quant", "attention_backend", "transformer_cache", "text_encoder_quant"):
assert st[k] is None
+ assert st["supports_lora"] is True and st["lora_unavailable_reason"] is None
+
+
+def test_status_names_why_a_native_family_has_no_lora():
+ st = _loaded_backend(fam_name = "qwen-image").status()
+ assert st["supports_lora"] is False
+ assert (
+ st["lora_unavailable_reason"]
+ == "The native sd.cpp engine cannot apply LoRAs to qwen-image."
+ )
def test_generate_returns_images_and_seed():
diff --git a/studio/frontend/src/features/images/api.ts b/studio/frontend/src/features/images/api.ts
index f9e118c6dea..c7f470f340f 100644
--- a/studio/frontend/src/features/images/api.ts
+++ b/studio/frontend/src/features/images/api.ts
@@ -75,6 +75,8 @@ export interface DiffusionStatus {
lora_after_reload?: boolean;
// Whether the loaded model + quantisation can apply LoRA adapters (drives the LoRA picker enabled state).
supports_lora?: boolean;
+ // Why supports_lora is false, shown in the LoRA slot when no reload would turn LoRA on.
+ lora_unavailable_reason?: string | null;
supports_controlnet?: boolean;
supports_negative_prompt?: boolean;
// Whether the loaded model's inpaint pipeline can crop to the mask (diffusers padding_mask_crop).
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index 0b16e4d5204..59c3ba54ada 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -429,6 +429,7 @@ import {
engineRequestField,
engineSelectVisible,
loadedEngineChoice,
+ loraUnavailableNote,
nativeLoadAdvanced,
nativeReloadTarget,
offersCompiledLoraReload,
@@ -2154,6 +2155,7 @@ export function ImagesPage({
// Refresh the LoRA picker when the loaded family changes, since a LoRA is family-specific.
// Not on first load or unload (a restore can precede the load), so track it in a ref.
const loraCapable = Boolean(!external && status?.loaded && status?.supports_lora);
+ const loraOffNote = external ? null : loraUnavailableNote(status);
const prevLoraFamilyRef = useRef<string | null | undefined>(undefined);
const bakedLorasOnLoad = useRef(false);
useEffect(() => {
@@ -6576,7 +6578,7 @@ export function ImagesPage({
)}
{!external && !loraCapable && offersNativeLoraReload(status) && (
<div className="flex items-center justify-between gap-2 rounded-lg border border-dashed px-3 py-2 text-xs text-muted-foreground">
- <span>LoRAs need the native engine for this GGUF; diffusers runs it without them.</span>
+ <span>LoRAs are off on this load; the native engine applies them to this GGUF.</span>
<Button size="sm" variant="secondary" className="shrink-0 text-xs" disabled={busy !== null} onClick={handleNativeReload}>
Reload with native engine
</Button>
@@ -6592,6 +6594,9 @@ export function ImagesPage({
)}
</div>
)}
+ {loraOffNote && (
+ <div className="rounded-lg border border-dashed px-3 py-2 text-xs text-muted-foreground">{loraOffNote}</div>
+ )}
{/* LoRA adapters: shown whenever the loaded model + quant can apply them. Each carries a 0-2 weight. */}
{loraCapable && (
<Field
diff --git a/studio/frontend/src/features/images/lib/engine-choice.ts b/studio/frontend/src/features/images/lib/engine-choice.ts
index 29a78f9f9d4..eed348b2f91 100644
--- a/studio/frontend/src/features/images/lib/engine-choice.ts
+++ b/studio/frontend/src/features/images/lib/engine-choice.ts
@@ -14,7 +14,7 @@ export const ENGINE_OPTIONS: Array<[EngineChoice, string]> = [
];
export const ENGINE_HINT =
- "Which engine runs this GGUF. Auto keeps the host's choice: diffusers on a GPU, native sd.cpp on CPU. Native applies LoRAs to GGUF models and usually needs less VRAM, but has no torch.compile or quantised fast paths and is often slower on CUDA. Diffusers runs a GGUF without LoRA. Applies on the next load (Reapply).";
+ "Which engine runs this GGUF. Auto keeps the host's choice: diffusers on a GPU, native sd.cpp on CPU. Native usually needs less VRAM, but has no torch.compile or quantised fast paths and is often slower on CUDA. Applies on the next load (Reapply).";
const KEY = "unsloth:images:engine-by-model";
@@ -75,6 +75,7 @@ interface EngineStatus {
lora_via_native?: boolean;
lora_after_reload?: boolean;
supports_lora?: boolean;
+ lora_unavailable_reason?: string | null;
resolved?: Record<string, { source: string; requested?: string | boolean | null }> | null;
}
@@ -103,6 +104,13 @@ export function offersCompiledLoraReload(status: EngineStatus | null | undefined
return Boolean(status?.loaded && status.lora_after_reload && !status.supports_lora);
}
+/** The LoRA slot's text when LoRA is off and neither reload note applies, so the slot never renders blank. */
+export function loraUnavailableNote(status: EngineStatus | null | undefined): string | null {
+ if (!status?.loaded || status.supports_lora) return null;
+ if (offersNativeLoraReload(status) || offersCompiledLoraReload(status)) return null;
+ return status.lora_unavailable_reason || "LoRAs cannot be applied to this model on its current engine.";
+}
+
interface ReloadStatus {
loaded: boolean;
repo_id?: string | null;
diff --git a/studio/frontend/tests/image-engine-choice.test.ts b/studio/frontend/tests/image-engine-choice.test.ts
index 7c5b93cdac6..6556c1ae2ce 100644
--- a/studio/frontend/tests/image-engine-choice.test.ts
+++ b/studio/frontend/tests/image-engine-choice.test.ts
@@ -9,6 +9,7 @@ import {
engineRequestField,
engineSelectVisible,
loadedEngineChoice,
+ loraUnavailableNote,
nativeLoadAdvanced,
nativeReloadTarget,
offersCompiledLoraReload,
@@ -111,6 +112,20 @@ test("the LoRA note offers a native reload only where it would turn LoRA on", ()
assert.equal(offersNativeLoraReload({ loaded: false }), false);
});
+test("the LoRA slot names why LoRA is off when no reload note applies", () => {
+ const reason = "LoRAs are not applied to a whole-pipeline SDXL GGUF. Load the .safetensors checkpoint to use LoRAs.";
+ const noNative = { ...ggufOnDiffusers, lora_via_native: false, lora_unavailable_reason: reason };
+ assert.equal(loraUnavailableNote(noNative), reason);
+ // A server pin suppresses the native reload note, so the reason shows instead.
+ assert.equal(loraUnavailableNote({ ...ggufOnDiffusers, engine_forced: "diffusers", lora_unavailable_reason: reason }), reason);
+ assert.equal(loraUnavailableNote({ ...ggufOnDiffusers, lora_unavailable_reason: reason }), null);
+ assert.equal(loraUnavailableNote({ loaded: true, supports_lora: false, lora_after_reload: true }), null);
+ assert.match(loraUnavailableNote({ loaded: true, supports_lora: false }) ?? "", /cannot be applied/);
+ assert.equal(loraUnavailableNote({ loaded: true, supports_lora: true }), null);
+ assert.equal(loraUnavailableNote({ loaded: false }), null);
+ assert.equal(loraUnavailableNote(null), null);
+});
+
test("the engine badge names the engine", () => {
assert.equal(formatResolvedValue("engine", "sd_cpp"), "Native");
assert.equal(formatResolvedValue("engine", "diffusers"), "Diffusers");