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 sd.cpp: --mmap for CPU renders on builds whose --mmap keeps the CPU repack (#16758)
Daniel Hanc014c8b3664a
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.pyindex c5f96efdeec..0bf59a0efc9 100644--- a/studio/backend/core/inference/sd_cpp_args.py+++ b/studio/backend/core/inference/sd_cpp_args.py@@ -410,8 +410,10 @@ def metal_placement_flags(offload: Sequence[str]) -> list[str]:return [f for f in flags if f not in offload]-# 1 / 0 forces sd.cpp's --mmap on / off on macOS; unset decides from the installed build (``mac_mmap_flags``).+# 1 / 0 forces sd.cpp's --mmap on / off; unset decides from the installed build (``mmap_flags``).SD_CPP_MMAP_ENV = "UNSLOTH_DIFFUSION_SD_CPP_MMAP"+# Help text of builds whose --mmap still repacks CPU weights (older ones run them unrepacked: slower, other pixels).+CPU_MMAP_REPACK_HELP = "weights the CPU repacks are still loaded"# leejet/stable-diffusion.cpp#2037 (master-907) maps mmapped weights through Metal device buffers. Older builds accept# --mmap but hand Metal a CPU buffer it cannot address, so the flag is only safe from this build on.METAL_MMAP_MIN_BUILD = 907@@ -499,6 +501,73 @@ def mac_mmap_flags(binary: Optional[str], extra_args: Optional[Sequence[str]] =return ["--mmap"] if build is not None and build >= METAL_MMAP_MIN_BUILD else [][email protected]_cache(maxsize = 8)+def _installed_sd_cpp_accelerator(binary: str) -> Optional[str]:+ """The accelerator class (``cpu`` / ``cuda`` / ``vulkan`` / ...) Studio's installer recorded next to ``binary``."""+ import json+ from pathlib import Path++ try:+ path = Path(binary).resolve()+ except Exception: # noqa: BLE001+ return None+ for parent in list(path.parents)[:3]:+ try:+ with open(parent / _INSTALL_RECORD, "r", encoding = "utf-8") as f:+ rec = json.load(f)+ except (OSError, ValueError):+ continue+ accel = rec.get("accelerator") if isinstance(rec, dict) else None+ return accel if isinstance(accel, str) and accel else None+ return None+++def sd_cpp_mmap_keeps_cpu_repack(binary: str) -> bool:+ """True when ``binary --help`` says its --mmap still repacks CPU weights. Fails closed."""+ try:+ st = os.stat(binary)+ except OSError:+ return False+ return _cpu_mmap_repack_in_help(str(binary), st.st_size, st.st_mtime_ns)++[email protected]_cache(maxsize = 16)+def _cpu_mmap_repack_in_help(binary: str, size: int, mtime_ns: int) -> bool:+ from core.inference.sd_cpp_backend import _sd_cpp_probe_output+ text = _sd_cpp_probe_output(binary, "--help")+ return text is not None and CPU_MMAP_REPACK_HELP in text+++def mmap_flags(+ binary: Optional[str],+ extra_args: Optional[Sequence[str]] = None,+ backend_args: Optional[Sequence[str]] = None,+) -> list[str]:+ """``--mmap`` on macOS Metal-mmap builds and on CPU renders whose --mmap still repacks CPU weights (keeps+ unrepacked weights file-backed: ~4.6 GB vs 13.3 GB anonymous, pixel-identical). GPU renders are left alone."""+ import sys++ if sys.platform == "darwin":+ return mac_mmap_flags(binary, extra_args)+ if "--mmap" in (extra_args or ()):+ return []+ forced = os.environ.get(SD_CPP_MMAP_ENV, "").strip().lower()+ if forced in ("0", "false", "no", "off"):+ return []+ if forced in ("1", "true", "yes", "on"):+ return ["--mmap"]+ if not binary:+ return []+ args = [*(backend_args or ()), *(extra_args or ())]+ target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])+ on_cpu = (+ target.lower() == "cpu"+ if target is not None+ else _installed_sd_cpp_accelerator(str(binary)) == "cpu"+ )+ return ["--mmap"] if on_cpu and sd_cpp_mmap_keeps_cpu_repack(str(binary)) else []++# Everything on the CPU backend. sd.cpp prefers GPU -> integrated GPU -> CPU and only `--backend` changes which# backend EXECUTES the graph (`--offload-to-cpu` moves parameters, not compute), so this is the one flag that removes# ggml-metal entirely.@@ -819,7 +888,7 @@ def build_sd_cpp_command(if offload:cmd += offloadcmd += metal_placement_flags(offload)- cmd += mac_mmap_flags(binary, extra_args)+ cmd += mmap_flags(binary, extra_args, offload)if verbose:cmd += ["-v"]if extra_args:@@ -917,7 +986,7 @@ def build_sd_cpp_video_command(if offload:cmd += offloadcmd += metal_placement_flags(offload)- cmd += mac_mmap_flags(binary, extra_args)+ cmd += mmap_flags(binary, extra_args, offload)if verbose:cmd.append("-v")if extra_args:@@ -1025,7 +1094,7 @@ def build_sd_cpp_server_command(native_speed_flags(native_speed, backend_args, accelerator, binary), offload)cmd += placement- cmd += mac_mmap_flags(binary, extra_args)+ cmd += mmap_flags(binary, extra_args, offload)if verbose:cmd += ["-v"]if extra_args:diff --git a/studio/backend/tests/test_sd_cpp_args.py b/studio/backend/tests/test_sd_cpp_args.pyindex 0266d00f1db..7431f6dcfd4 100644--- a/studio/backend/tests/test_sd_cpp_args.py+++ b/studio/backend/tests/test_sd_cpp_args.py@@ -1104,6 +1104,84 @@ def test_mmap_env_override_and_no_duplicate(monkeypatch, tmp_path):assert cmd.count("--mmap") == 1+# ── CPU mmap (repack-aware builds) ──────────────────────────────────────────++_REPACK_HELP = " --mmap whether to memory-map model (CPU: weights the CPU repacks are still loaded and repacked)\n"+_OLD_HELP = " --mmap whether to memory-map model\n"+++def _cpu_install(+ tmp_path,+ monkeypatch,+ help_text,+ accelerator = "cpu",+):+ import json++ import core.inference.sd_cpp_backend as backend++ root = tmp_path / f"sd-{accelerator}-{abs(hash(help_text)) % 10**6}"+ (root / "bin").mkdir(parents = True)+ binary = root / "bin" / "sd-cli"+ binary.write_text("")+ (root / ".unsloth-sd-cpp-install.json").write_text(+ json.dumps({"tag": "master-982-0518b34-uaba3a1c", "accelerator": accelerator})+ )+ for fn in (+ _sd_cpp_args_module._installed_sd_cpp_tag,+ _sd_cpp_args_module._installed_sd_cpp_accelerator,+ _sd_cpp_args_module._cpu_mmap_repack_in_help,+ ):+ fn.cache_clear()+ monkeypatch.setattr(backend, "_sd_cpp_probe_output", lambda b, *a, **k: help_text)+ return str(binary)++[email protected]("platform", ["linux", "win32"])+def test_cpu_mmap_on_repack_aware_cpu_builds_only(monkeypatch, tmp_path, platform):+ monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)+ monkeypatch.setattr("sys.platform", platform)+ new = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)+ for cmd in _all_builders(new):+ assert cmd.count("--mmap") == 1+ # The pinned build maps repackable weights and runs them unrepacked: never sent there.+ old = _cpu_install(tmp_path, monkeypatch, _OLD_HELP)+ assert all("--mmap" not in cmd for cmd in _all_builders(old))+ for accel in ("cuda", "vulkan", "rocm"):+ gpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP, accelerator = accel)+ assert all("--mmap" not in cmd for cmd in _all_builders(gpu))+++def test_cpu_mmap_follows_an_explicit_backend(monkeypatch, tmp_path):+ from core.inference.sd_cpp_args import mmap_flags++ monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)+ monkeypatch.setattr("sys.platform", "linux")+ gpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP, accelerator = "vulkan")+ assert mmap_flags(gpu, None, ["--backend", "cpu"]) == ["--mmap"]+ cpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)+ assert mmap_flags(cpu, None, ["--backend", "diffusion=vulkan0"]) == []+ assert mmap_flags(cpu, ["--mmap"], None) == []+ assert mmap_flags(None, None, None) == []+ # an unreadable / unprobeable binary fails closed+ assert (+ _cpu_install(tmp_path, monkeypatch, None)+ and mmap_flags(str(tmp_path / "missing" / "sd-cli")) == []+ )+++def test_cpu_mmap_env_override(monkeypatch, tmp_path):+ from core.inference.sd_cpp_args import mmap_flags++ monkeypatch.setattr("sys.platform", "linux")+ new = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "0")+ assert mmap_flags(new) == []+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "1")+ old = _cpu_install(tmp_path, monkeypatch, _OLD_HELP)+ assert mmap_flags(old) == ["--mmap"]++@pytest.mark.parametrize("ccs,expected",[