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: one CPU thread per usable physical core on Linux (#14694)

Daniel Hanf2e45b56a7bf
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index 552e130e738..db43e62af89 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -354,8 +354,31 @@ def _apple_performance_cores() -> Optional[int]:
return total or _sysctl("hw.perflevel0.physicalcpu") or _sysctl("hw.physicalcpu")
+def _linux_physical_cores(sysfs: str = "/sys/devices/system/cpu") -> Optional[int]:
+ """Physical cores among the CPUs this process may run on: distinct ``thread_siblings_list`` sets over the affinity
+ mask, so a host without SMT counts every core and a taskset / container cpuset counts only its own. None when the
+ mask or the topology is unreadable."""
+ try:
+ allowed = os.sched_getaffinity(0)
+ except (AttributeError, OSError):
+ return None
+ cores: set[str] = set()
+ for cpu in allowed:
+ try:
+ with open(f"{sysfs}/cpu{cpu}/topology/thread_siblings_list", encoding = "utf-8") as f:
+ siblings = f.read().strip()
+ except OSError:
+ return None
+ if not siblings:
+ return None
+ cores.add(siblings)
+ return len(cores) or None
+
+
def _default_threads() -> int:
- """``UNSLOTH_CPU_THREADS``, else macOS P-cores, else ``os.cpu_count() // 2`` capped by the cgroup quota."""
+ """``UNSLOTH_CPU_THREADS``, else macOS P-cores, else (Linux) the physical cores in the affinity mask, else
+ ``os.cpu_count() // 2``; capped by the cgroup quota on Linux. Half the logical CPUs is one thread per core only on
+ a 2-way SMT host that may use all of them: it halves a host without SMT and oversubscribes a cpuset."""
try:
configured = int(os.environ.get("UNSLOTH_CPU_THREADS") or 0)
except ValueError:
@@ -365,15 +388,28 @@ def _default_threads() -> int:
performance_cores = _apple_performance_cores()
if performance_cores:
return performance_cores
- cpu = os.cpu_count()
- threads = cpu // 2 if cpu else 8
- limit = _cgroup_cpu_limit() if sys.platform.startswith("linux") else None
+ linux = sys.platform.startswith("linux")
+ physical = _linux_physical_cores() if linux else None
+ if physical:
+ threads = physical
+ else:
+ cpu = os.cpu_count()
+ threads = cpu // 2 if cpu else 8
+ limit = _cgroup_cpu_limit() if linux else None
return max(1, min(threads, limit) if limit else threads)
+def _sd_cpp_default_threads(cpu: Optional[int]) -> Optional[int]:
+ """What an sd.cpp build without its own topology read runs (``hardware_concurrency`` halved above 4 CPUs)."""
+ if not cpu:
+ return None
+ return cpu if cpu <= 4 else cpu // 2
+
+
def _explicit_threads() -> Optional[int]:
- """``UNSLOTH_CPU_THREADS``, the macOS fast cores, or a cgroup quota below sd.cpp's physical-core default; None
- keeps that default."""
+ """``UNSLOTH_CPU_THREADS``, the macOS fast cores, or (Linux) the thread count above whenever it differs from what
+ sd.cpp would pick by itself; None keeps sd.cpp's default. sd.cpp builds before the fork's topology fix count half
+ the logical CPUs and ignore the affinity mask, so a host without SMT or a cpuset needs the count passed."""
try:
configured = int(os.environ.get("UNSLOTH_CPU_THREADS") or 0)
except ValueError:
@@ -384,10 +420,9 @@ def _explicit_threads() -> Optional[int]:
if performance_cores:
return performance_cores
if sys.platform.startswith("linux"):
- limit = _cgroup_cpu_limit()
- cpu = os.cpu_count()
- if limit and cpu and limit < cpu // 2:
- return max(1, limit)
+ threads = _default_threads()
+ if threads != _sd_cpp_default_threads(os.cpu_count()):
+ return threads
return None
diff --git a/studio/backend/tests/test_sd_cpp_cpu_defaults.py b/studio/backend/tests/test_sd_cpp_cpu_defaults.py
index 6662f8dbb2d..a88ea83b02e 100644
--- a/studio/backend/tests/test_sd_cpp_cpu_defaults.py
+++ b/studio/backend/tests/test_sd_cpp_cpu_defaults.py
@@ -61,11 +61,13 @@ def _host(
cpus = 192,
limit = None,
platform = "linux",
+ physical = None,
):
monkeypatch.delenv("UNSLOTH_CPU_THREADS", raising = False)
monkeypatch.setattr(bk.sys, "platform", platform)
monkeypatch.setattr(bk.os, "cpu_count", lambda: cpus)
monkeypatch.setattr(bk, "_cgroup_cpu_limit", lambda: limit)
+ monkeypatch.setattr(bk, "_linux_physical_cores", lambda *a, **k: physical)
def test_without_a_quota_the_default_is_unchanged(monkeypatch):
@@ -264,6 +266,11 @@ def test_h3_video_keeps_sd_cpps_default_threads_unless_studio_knows_better(monke
monkeypatch.setattr(bk.os, "cpu_count", lambda: 32)
monkeypatch.setattr(bk.sys, "platform", "linux")
monkeypatch.setattr(bk, "_cgroup_cpu_limit", lambda *a, **k: None)
+ monkeypatch.setattr(bk, "_linux_physical_cores", lambda *a, **k: None)
+ assert bk._explicit_threads() is None
+ monkeypatch.setattr(
+ bk, "_linux_physical_cores", lambda *a, **k: 16
+ ) # 2-way SMT: what sd.cpp picks too
assert bk._explicit_threads() is None
monkeypatch.setattr(
bk, "_cgroup_cpu_limit", lambda *a, **k: 16
@@ -278,3 +285,102 @@ def test_h3_video_keeps_sd_cpps_default_threads_unless_studio_knows_better(monke
monkeypatch.delenv("UNSLOTH_CPU_THREADS")
monkeypatch.setattr(bk, "_apple_performance_cores", lambda: 10)
assert bk._explicit_threads() == 10
+
+
+def _sysfs(tmp_path, siblings):
+ """``/sys/devices/system/cpu`` with ``siblings[cpu]`` as each CPU's thread_siblings_list."""
+ root = tmp_path / "cpu"
+ for cpu, line in siblings.items():
+ d = root / f"cpu{cpu}" / "topology"
+ d.mkdir(parents = True)
+ (d / "thread_siblings_list").write_text(line + "\n")
+ return str(root)
+
+
+_SMT8 = {
+ c: f"{c % 4},{c % 4 + 4}" for c in range(8)
+} # 4 cores, 2 threads each (siblings c and c + 4)
+_NO_SMT8 = {c: str(c) for c in range(8)}
+
+
+ "siblings, allowed, expected",
+ [
+ (_SMT8, set(range(8)), 4),
+ (_SMT8, {0, 1, 2, 3}, 4), # one thread of each core
+ (_SMT8, {0, 4}, 1), # both threads of one core
+ (_SMT8, {0, 4, 1}, 2),
+ (_NO_SMT8, set(range(8)), 8),
+ (_NO_SMT8, {2, 5, 7}, 3),
+ ],
+)
+def test_physical_cores_count_distinct_sibling_sets_in_the_affinity_mask(
+ monkeypatch, tmp_path, siblings, allowed, expected
+):
+ monkeypatch.setattr(bk.os, "sched_getaffinity", lambda pid: allowed, raising = False)
+ assert bk._linux_physical_cores(_sysfs(tmp_path, siblings)) == expected
+
+
+def test_physical_cores_is_none_without_topology_or_affinity(monkeypatch, tmp_path):
+ monkeypatch.setattr(bk.os, "sched_getaffinity", lambda pid: {0, 1}, raising = False)
+ assert bk._linux_physical_cores(_sysfs(tmp_path, {0: "0"})) is None # cpu1 has no topology
+ assert bk._linux_physical_cores(_sysfs(tmp_path / "e", {0: "", 1: "1"})) is None
+
+ def _denied(pid):
+ raise OSError("no")
+
+ monkeypatch.setattr(bk.os, "sched_getaffinity", _denied, raising = False)
+ assert bk._linux_physical_cores(_sysfs(tmp_path / "x", _NO_SMT8)) is None
+ monkeypatch.delattr(bk.os, "sched_getaffinity", raising = False)
+ assert bk._linux_physical_cores(_sysfs(tmp_path / "y", _NO_SMT8)) is None
+
+
+def test_the_linux_default_is_the_physical_core_count(monkeypatch):
+ # No SMT: every core, not half of them
+ _host(monkeypatch, cpus = 8, physical = 8)
+ assert bk._default_threads() == 8
+ # A 4-CPU cpuset (2 cores) on a 192-CPU host: 2, not 96
+ _host(monkeypatch, cpus = 192, physical = 2)
+ assert bk._default_threads() == 2
+ # 2-way SMT with the whole machine: unchanged
+ _host(monkeypatch, cpus = 192, physical = 96)
+ assert bk._default_threads() == 96
+ # The quota still caps it, and an unreadable topology keeps half the CPUs
+ _host(monkeypatch, cpus = 8, physical = 8, limit = 3)
+ assert bk._default_threads() == 3
+ _host(monkeypatch, cpus = 12, physical = None)
+ assert bk._default_threads() == 6
+
+
+def test_the_physical_count_is_never_read_off_linux(monkeypatch):
+ _host(monkeypatch, cpus = 8, platform = "win32")
+ monkeypatch.setattr(bk, "_linux_physical_cores", lambda *a, **k: pytest.fail("Linux only"))
+ assert bk._default_threads() == 4
+
+
+ "cpus, physical, limit, expected",
+ [
+ (32, 16, None, None), # SMT: sd.cpp's own default is the same count
+ (8, 8, None, 8), # no SMT: sd.cpp's fallback would run 4
+ (192, 2, None, 2), # cpuset: sd.cpp ignores the affinity mask
+ (4, 4, None, None), # sd.cpp keeps every CPU at 4 or fewer
+ (32, 16, 6, 6), # a tighter quota, as before
+ ],
+)
+def test_explicit_threads_passes_the_count_when_sd_cpp_would_pick_another(
+ monkeypatch, cpus, physical, limit, expected
+):
+ _host(monkeypatch, cpus = cpus, physical = physical, limit = limit)
+ monkeypatch.setattr(bk, "_apple_performance_cores", lambda: None)
+ assert bk._explicit_threads() == expected
+
+
+def test_the_real_host_topology_reads(monkeypatch):
+ """On this test host: a positive count, never more than the CPUs this process may use."""
+ if not hasattr(bk.os, "sched_getaffinity"):
+ pytest.skip("no affinity API")
+ count = bk._linux_physical_cores()
+ if count is None:
+ pytest.skip("no sysfs topology here")
+ assert 1 <= count <= len(bk.os.sched_getaffinity(0))