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: cap sd.cpp threads at the cgroup CPU quota and honour UNSLOTH_CPU_THREADS (#13213)

Daniel Han88ff2ac66d8e
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index b553d9174ee..855f1776b19 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -254,14 +254,43 @@ def _base_sample_sigmas(
return grid, base
+def _cgroup_cpu_limit(
+ root: str = "/sys/fs/cgroup", proc_cgroup: str = "/proc/self/cgroup"
+) -> Optional[int]:
+ """Tightest cgroup v2 cpu.max over this cgroup and its parents, in whole CPUs; None if unreadable."""
+ try:
+ with open(proc_cgroup, encoding = "utf-8") as f:
+ rel = next(line.split("::", 1)[1].strip() for line in f if line.startswith("0::"))
+ except (OSError, StopIteration):
+ rel = "/"
+ limit: Optional[int] = None
+ path = os.path.normpath(os.path.join(root, rel.lstrip("/")))
+ while True:
+ try:
+ with open(os.path.join(path, "cpu.max"), encoding = "utf-8") as f:
+ quota, period = f.read().split()[:2]
+ if quota != "max":
+ cpus = max(1, -(-int(quota) // int(period)))
+ limit = cpus if limit is None else min(limit, cpus)
+ except (OSError, ValueError):
+ pass
+ if len(path) <= len(root.rstrip("/")) or path == os.path.dirname(path):
+ return limit
+ path = os.path.dirname(path)
+
+
def _default_threads() -> int:
- """Physical-core thread count for the sd.cpp CPU backend. ``threads = None`` lets sd.cpp pick
- its own default, which is the logical-core count (all hyperthreads). For the compute-bound
- GGML matmuls the diffusion CPU path runs, oversubscribing the hyperthreads adds scheduling
- contention without extra throughput, so pin to physical cores instead. Falls back to 8 when
- the count is unknown, and clamps to at least 1."""
+ """``UNSLOTH_CPU_THREADS``, else ``os.cpu_count() // 2`` capped by the cgroup quota ``os.cpu_count()`` ignores."""
+ try:
+ configured = int(os.environ.get("UNSLOTH_CPU_THREADS") or 0)
+ except ValueError:
+ configured = 0
+ if configured > 0:
+ return configured
cpu = os.cpu_count()
- return max(1, cpu // 2 if cpu else 8)
+ threads = cpu // 2 if cpu else 8
+ limit = _cgroup_cpu_limit() if sys.platform.startswith("linux") else None
+ return max(1, min(threads, limit) if limit else threads)
def _server_binary_runnable(binary: str) -> bool:
diff --git a/studio/backend/tests/test_sd_cpp_cpu_defaults.py b/studio/backend/tests/test_sd_cpp_cpu_defaults.py
new file mode 100644
index 00000000000..022fe73f138
--- /dev/null
+++ b/studio/backend/tests/test_sd_cpp_cpu_defaults.py
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""sd.cpp ``--threads``: ``UNSLOTH_CPU_THREADS`` reaches it, and a cgroup CPU quota caps the default."""
+
+from __future__ import annotations
+
+import pytest
+
+from core.inference import sd_cpp_backend as bk
+
+
+def _cgroups(
+ tmp_path,
+ quotas,
+ own = "/user.slice/app.scope",
+):
+ """A cgroup v2 tree where ``quotas`` maps a cgroup path to its cpu.max line, plus /proc/self/cgroup."""
+ root = tmp_path / "cg"
+ for rel, line in quotas.items():
+ d = root / rel.lstrip("/")
+ d.mkdir(parents = True, exist_ok = True)
+ (d / "cpu.max").write_text(line + "\n")
+ (root / own.lstrip("/")).mkdir(parents = True, exist_ok = True)
+ proc = tmp_path / "cgroup"
+ proc.write_text(f"0::{own}\n")
+ return str(root), str(proc)
+
+
+ "quotas, expected",
+ [
+ ({}, None),
+ ({"/user.slice/app.scope": "max 100000"}, None),
+ ({"/user.slice/app.scope": "400000 100000"}, 4),
+ ({"/user.slice/app.scope": "250000 100000"}, 3),
+ # A parent's quota binds too, and the tightest one wins.
+ ({"/user.slice": "200000 100000", "/user.slice/app.scope": "800000 100000"}, 2),
+ ({"/": "600000 100000"}, 6),
+ ({"/user.slice/app.scope": "garbage"}, None),
+ ],
+)
+def test_the_tightest_quota_over_the_own_cgroup_and_its_parents(tmp_path, quotas, expected):
+ root, proc = _cgroups(tmp_path, quotas)
+ assert bk._cgroup_cpu_limit(root, proc) == expected
+
+
+def test_a_container_with_its_own_cgroup_namespace_reads_the_root(tmp_path):
+ root, proc = _cgroups(tmp_path, {"/": "400000 100000"}, own = "/")
+ assert bk._cgroup_cpu_limit(root, proc) == 4
+
+
+def test_no_cgroup_v2_entry_reads_the_root_only(tmp_path):
+ root, _ = _cgroups(tmp_path, {"/": "300000 100000"})
+ missing = str(tmp_path / "missing")
+ assert bk._cgroup_cpu_limit(root, missing) == 3
+
+
+def _host(
+ monkeypatch,
+ *,
+ cpus = 192,
+ limit = None,
+ platform = "linux",
+):
+ 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)
+
+
+def test_without_a_quota_the_default_is_unchanged(monkeypatch):
+ _host(monkeypatch)
+ assert bk._default_threads() == 96
+ _host(monkeypatch, cpus = None)
+ assert bk._default_threads() == 8
+
+
+def test_a_quota_caps_the_default(monkeypatch):
+ _host(monkeypatch, limit = 4)
+ assert bk._default_threads() == 4
+ _host(monkeypatch, cpus = 8, limit = 16)
+ assert bk._default_threads() == 4
+
+
+def test_other_platforms_never_read_cgroups(monkeypatch):
+ _host(monkeypatch, cpus = 10, platform = "darwin")
+ monkeypatch.setattr(bk, "_cgroup_cpu_limit", lambda: pytest.fail("no cgroups off Linux"))
+ assert bk._default_threads() == 5
+
+
[email protected]("value, expected", [("12", 12), ("0", 4), ("x", 4), ("", 4), ("-3", 4)])
+def test_unsloth_cpu_threads_wins_over_the_default_and_the_quota(monkeypatch, value, expected):
+ _host(monkeypatch, limit = 4)
+ monkeypatch.setenv("UNSLOTH_CPU_THREADS", value)
+ assert bk._default_threads() == expected