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 sd.cpp: stage server-mode image LoRAs as hard links so sd-server lists them (#14860)

Daniel Han3aa5e4d6abff
diff --git a/studio/backend/core/inference/diffusion_lora.py b/studio/backend/core/inference/diffusion_lora.py
index 50cbf3067d3..31e3933a783 100644
--- a/studio/backend/core/inference/diffusion_lora.py
+++ b/studio/backend/core/inference/diffusion_lora.py
@@ -590,12 +590,20 @@ def resolve_specs(
return out
-def materialize_native_dir(resolved: list[ResolvedLora], dest: Path) -> list[ResolvedLora]:
+def materialize_native_dir(
+ resolved: list[ResolvedLora],
+ dest: Path,
+ *,
+ real_files: bool = False,
+) -> list[ResolvedLora]:
"""Populate ``dest`` with symlinks (copy fallback) to the resolved LoRA files.
sd-cli resolves ``<lora:ALIAS:w>`` against filenames in ``--lora-model-dir``, so each adapter
needs a uniquely-named file in this dedicated managed directory. Returns the resolved list with
aliases updated to the (collision-broken) stems written, so the caller injects matching tags.
+ ``real_files``: hard links (copy fallback) instead of symlinks. sd-server (master-982+) canonicalizes
+ each file under ``--lora-model-dir`` and skips one that resolves outside it, so a symlink into the
+ LoRA cache is never listed and a request naming it is rejected.
"""
dest.mkdir(parents = True, exist_ok = True)
used: set[str] = set()
@@ -614,10 +622,21 @@ def materialize_native_dir(resolved: list[ResolvedLora], dest: Path) -> list[Res
try:
if link.exists() or link.is_symlink():
link.unlink()
- os.symlink(os.path.realpath(r.path), link)
+ if real_files:
+ os.link(os.path.realpath(r.path), link)
+ else:
+ os.symlink(os.path.realpath(r.path), link)
except OSError:
import shutil
- shutil.copy2(r.path, link)
+ try:
+ shutil.copy2(r.path, link)
+ except BaseException:
+ # A partial multi-GB copy (disk full, cancelled) must not outlive the failed request.
+ try:
+ link.unlink()
+ except OSError:
+ pass
+ raise
out.append(ResolvedLora(r.id, alias, str(link), r.fmt, r.weight))
return out
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index b2dc45bd716..8646f4ece5e 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -4786,19 +4786,22 @@ class SdCppDiffusionBackend:
# Stage LoRAs into a per-request subdir of the server lora-model-dir (so a prior request's adapters cannot
# leak in); removed after.
lora_payload: Optional[list[dict]] = None
- lora_stage: Optional[Path] = None
- if lora_resolved:
- server_lora_dir = state.server.lora_dir
- if server_lora_dir:
- lora_stage = Path(server_lora_dir) / f"gen_{os.urandom(6).hex()}"
- materialized = diffusion_lora.materialize_native_dir(lora_resolved, lora_stage)
- lora_payload = [
- {
- "path": f"{lora_stage.name}/{Path(m.path).name}",
- "multiplier": float(m.weight),
- }
- for m in materialized
- ]
+ lora_stages: list[Path] = []
+
+ def _stage_loras(server: Any) -> Optional[list[dict]]:
+ """The ``lora`` block, with the adapters staged into THIS server's lora-model-dir."""
+ if not lora_resolved or not server.lora_dir:
+ return None
+ stage = Path(server.lora_dir) / f"gen_{os.urandom(6).hex()}"
+ lora_stages.append(stage)
+ materialized = diffusion_lora.materialize_native_dir(
+ lora_resolved, stage, real_files = True
+ )
+ return [
+ {"path": f"{stage.name}/{Path(m.path).name}", "multiplier": float(m.weight)}
+ for m in materialized
+ ]
+
# One deadline for the whole request, shared by its chunks: a batch is chunked only because the server caps
# images per job, so each chunk gets whatever is left rather than its own full budget and a long batch still
# ends on time.
@@ -4832,6 +4835,7 @@ class SdCppDiffusionBackend:
)
try:
+ lora_payload = _stage_loras(state.server)
hires_payload = _stage_hires(state.server)
for offset in range(0, total, _MAX_SERVER_BATCH):
if cancel.is_set():
@@ -4880,6 +4884,14 @@ class SdCppDiffusionBackend:
with self._lock:
if self._state is not None and self._state.server is not None:
self._state = state
+ if lora_payload is not None:
+ # The replacement server has its own scratch dir: stage the LoRAs there again.
+ lora_payload = _stage_loras(server)
+ if lora_payload is None:
+ raise RuntimeError(
+ "The CPU-backend native server has no LoRA directory for the selected LoRAs."
+ )
+ payload["lora"] = list(lora_payload)
if hires_plan is not None:
# The replacement server has its own scratch dir: stage the upscaler there again.
hires_payload = _stage_hires(server)
@@ -4906,8 +4918,8 @@ class SdCppDiffusionBackend:
(chunk_seed + i // max(1, per)) & ((1 << 63) - 1) for i in range(len(kept))
)
finally:
- if lora_stage is not None:
- shutil.rmtree(lora_stage, ignore_errors = True)
+ for stage in lora_stages:
+ shutil.rmtree(stage, ignore_errors = True)
for staged in hires_staged:
try:
staged.unlink()
diff --git a/studio/backend/tests/test_diffusion_lora.py b/studio/backend/tests/test_diffusion_lora.py
index a3ff0ac0c61..99a7bfa180a 100644
--- a/studio/backend/tests/test_diffusion_lora.py
+++ b/studio/backend/tests/test_diffusion_lora.py
@@ -148,6 +148,41 @@ def test_materialize_native_dir_symlinks_and_breaks_collisions(tmp_path):
assert Path(r.path).parent == dest
+def test_materialize_native_dir_real_files_hardlinks_inside_dest(tmp_path):
+ # sd-server rejects a staged LoRA whose canonical path leaves --lora-model-dir, so server staging needs a real file.
+ src = tmp_path / "cache" / "a.safetensors"
+ src.parent.mkdir()
+ src.write_bytes(b"x")
+ dest = tmp_path / "managed"
+ out = dl.materialize_native_dir(
+ [dl.ResolvedLora("a", "a", str(src), "safetensors", 1.0)], dest, real_files = True
+ )
+ staged = Path(out[0].path)
+ assert not staged.is_symlink() and staged.is_file()
+ assert Path(os.path.realpath(staged)).parent == Path(os.path.realpath(dest))
+ assert os.path.samefile(staged, src) # a hard link, not a copy
+ staged.unlink()
+ assert src.read_bytes() == b"x"
+
+
+def test_materialize_native_dir_real_files_copies_when_hardlink_fails(tmp_path, monkeypatch):
+ src = tmp_path / "a.safetensors"
+ src.write_bytes(b"x")
+
+ def _no_link(*a, **k):
+ raise OSError(18, "Invalid cross-device link")
+
+ monkeypatch.setattr(dl.os, "link", _no_link)
+ out = dl.materialize_native_dir(
+ [dl.ResolvedLora("a", "a", str(src), "safetensors", 1.0)],
+ tmp_path / "managed",
+ real_files = True,
+ )
+ staged = Path(out[0].path)
+ assert not staged.is_symlink() and staged.read_bytes() == b"x"
+ assert not os.path.samefile(staged, src)
+
+
def test_list_loras_scans_local(tmp_path, monkeypatch):
d = tmp_path / "loras"
d.mkdir()
diff --git a/studio/backend/tests/test_sd_cpp_backend.py b/studio/backend/tests/test_sd_cpp_backend.py
index 47756b7f390..baadacc9fa5 100644
--- a/studio/backend/tests/test_sd_cpp_backend.py
+++ b/studio/backend/tests/test_sd_cpp_backend.py
@@ -6,6 +6,7 @@
from __future__ import annotations
import threading
+from pathlib import Path
import types
import pytest
@@ -1985,7 +1986,7 @@ def test_run_load_redacts_paths_in_progress_error(monkeypatch):
npl._NATIVE_PATH_REDACTIONS.remove(secret_root)
-def _fake_materialize(resolved, dest):
+def _fake_materialize(resolved, dest, **kwargs):
"""Stand-in for diffusion_lora.materialize_native_dir: write a stub file per adapter
into ``dest`` and return the resolved list pointing at the written paths (mirroring the
real helper's contract without touching the Hub / real weights)."""
@@ -2050,6 +2051,138 @@ def test_generate_server_stages_loras_and_sends_structured_field(monkeypatch, tm
assert not list(_P(tmp_path).glob("gen_*"))
+def test_generate_server_stages_loras_as_real_files_inside_the_lora_dir(monkeypatch, tmp_path):
+ # sd-server (master-982+) canonicalizes every file under --lora-model-dir and skips one resolving outside it
+ # (examples/server/runtime.cpp refresh_lora_cache / get_lora_full_path), so a symlink into the cache is dropped.
+ import os
+
+ from core.inference import diffusion_lora as dl
+
+ cache = tmp_path / "cache"
+ cache.mkdir()
+ src = cache / "adapter.safetensors"
+ src.write_bytes(b"weights")
+ server_dir = tmp_path / "server_loras"
+ server_dir.mkdir()
+ b = SdCppDiffusionBackend()
+ servers: list = []
+ _run_server_load(monkeypatch, b, servers)
+ servers[0].lora_dir = str(server_dir)
+ monkeypatch.setattr(dl, "supports_lora", lambda **k: True)
+ monkeypatch.setattr(
+ dl,
+ "resolve_specs",
+ lambda specs, **k: [dl.ResolvedLora("id1", "myalias", str(src), "safetensors", 0.7)],
+ )
+ real = dl.materialize_native_dir
+ seen = []
+
+ def _spy(resolved, dest, **kwargs):
+ out = real(resolved, dest, **kwargs)
+ for m in out:
+ seen.append(
+ (os.path.islink(m.path), os.path.realpath(m.path), Path(m.path).read_bytes())
+ )
+ return out
+
+ monkeypatch.setattr(dl, "materialize_native_dir", _spy)
+ b.generate(prompt = "x", steps = 4, seed = 1, batch_size = 1, loras = [("id1", 0.7)])
+ assert len(seen) == 1
+ is_link, resolved_path, data = seen[0]
+ assert not is_link
+ assert Path(resolved_path).is_relative_to(Path(os.path.realpath(server_dir)))
+ assert data == b"weights"
+ assert src.read_bytes() == b"weights"
+ assert not list(server_dir.glob("gen_*"))
+
+
+def _server_lora_run(monkeypatch, tmp_path, *, fail_first):
+ import dataclasses
+ import io
+
+ from core.inference import diffusion_lora as dl
+
+ buf = io.BytesIO()
+ Image.new("RGB", (64, 64)).save(buf, format = "PNG")
+ png = buf.getvalue()
+ seen = []
+
+ class _Server:
+ def __init__(self, lora_dir, fail):
+ self.lora_dir, self.fail = str(lora_dir), fail
+
+ def img_gen(self, payload, **kw):
+ # What sd-server would resolve: every payload path must exist under THIS server's lora dir.
+ seen.append(
+ (
+ self.lora_dir,
+ [(Path(self.lora_dir) / e["path"]).is_file() for e in payload["lora"]],
+ )
+ )
+ if self.fail:
+ raise RuntimeError("ggml unsupported op abort")
+ return [png]
+
+ @dataclasses.dataclass(frozen = True)
+ class _State:
+ family: object
+ server: object
+ sampling_method: object = None
+ flow_shift: object = None
+ sample_sigmas: object = None
+
+ src = tmp_path / "cache" / "a.safetensors"
+ src.parent.mkdir()
+ src.write_bytes(b"w")
+ old_dir, new_dir = tmp_path / "old", tmp_path / "new"
+ old_dir.mkdir()
+ new_dir.mkdir()
+ b = SdCppDiffusionBackend()
+ monkeypatch.setattr(
+ b, "_restart_server_on_cpu_backend", lambda state, text, cancel: _Server(new_dir, False)
+ )
+ b._generate_server(
+ _State(family = detect_family("flux.1"), server = _Server(old_dir, fail_first)),
+ prompt = "p",
+ negative_prompt = None,
+ width = 64,
+ height = 64,
+ steps = 4,
+ seed = 1,
+ batch_size = 1,
+ cfg_scale = None,
+ flux_guidance = None,
+ lora_resolved = [dl.ResolvedLora("id1", "a", str(src), "safetensors", 0.5)],
+ cancel = threading.Event(),
+ )
+ return seen, old_dir, new_dir
+
+
+def test_server_cpu_restart_restages_loras_in_the_new_server_dir(monkeypatch, tmp_path):
+ seen, old_dir, new_dir = _server_lora_run(monkeypatch, tmp_path, fail_first = True)
+ assert seen == [(str(old_dir), [True]), (str(new_dir), [True])]
+ assert not list(old_dir.glob("gen_*")) and not list(new_dir.glob("gen_*"))
+
+
+def test_server_lora_staging_failure_leaves_no_partial_stage(monkeypatch, tmp_path):
+ import shutil
+
+ from core.inference import diffusion_lora as dl
+
+ def _no_link(*a, **k):
+ raise OSError(18, "Invalid cross-device link")
+
+ def _partial_copy(src, dst, *a, **k):
+ Path(dst).write_bytes(b"part")
+ raise OSError(28, "No space left on device")
+
+ monkeypatch.setattr(dl.os, "link", _no_link)
+ monkeypatch.setattr(shutil, "copy2", _partial_copy)
+ with pytest.raises(OSError, match = "No space left"):
+ _server_lora_run(monkeypatch, tmp_path, fail_first = False)
+ assert not list((tmp_path / "old").iterdir())
+
+
def test_generate_rejects_loras_on_unsupported_family(monkeypatch):
b = _loaded_backend(engine = _FakeEngine())
_patch_lora(monkeypatch, [], supported = False)