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: answer slow cache sizes at once and walk cache trees faster (#15627)
Daniel Han78ef9b53f42c
diff --git a/studio/backend/hub/utils/inventory_scan.py b/studio/backend/hub/utils/inventory_scan.pyindex 6822ea0f096..5a08e47d060 100644--- a/studio/backend/hub/utils/inventory_scan.py+++ b/studio/backend/hub/utils/inventory_scan.py@@ -100,6 +100,13 @@ def invalidate_hf_cache_scans() -> None:_hf_cache_scans_cached_at = 0.0_hf_cache_scans_epoch += 1invalidate_scan_memos()+ # Settings may answer a slow cache from its last walk; a download or delete must not show the old size.+ try:+ from utils.cache_inventory import invalidate_cache_size+ for key in ("hf_hub", "hf_xet", "hf_datasets", "hf_assets"):+ invalidate_cache_size(key)+ except Exception: # noqa: BLE001 - the Settings sizes are best effort+ passtry:from core.inference.audio_cpp_models import forgetexcept Exception: # noqa: BLE001 - no audio.cpp support, nothing memoizeddiff --git a/studio/backend/tests/test_cache_inventory_walk.py b/studio/backend/tests/test_cache_inventory_walk.pynew file mode 100644index 00000000000..560218d4540--- /dev/null+++ b/studio/backend/tests/test_cache_inventory_walk.py@@ -0,0 +1,338 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The cache walk must size exactly what the original per-entry walk sized, and a slow+cache must not hold the Settings page once it has been measured."""++import os+import sys+import threading+import time+from pathlib import Path+from typing import Iterable, Optional++import pytest++from utils import cache_inventory+from utils.cache_inventory import LinkLedger, definition_for+++def _reference_measure_tree(path: Path, ledger: LinkLedger) -> int:+ """The walk as it was before it was tuned, kept here as the oracle."""+ count = 0+ stack = [path]+ while stack:+ current = stack.pop()+ try:+ with os.scandir(current) as entries:+ for entry in entries:+ count += 1+ if entry.is_symlink():+ continue+ if entry.is_dir(follow_symlinks = False):+ if cache_inventory._descendable(entry):+ stack.append(Path(entry.path))+ continue+ cache_inventory._record_entry(entry, ledger)+ except OSError:+ continue+ return count+++def _reference_measure_root(root: Path, patterns: Optional[Iterable[str]] = None) -> tuple:+ ledger = LinkLedger()+ entries = 0+ try:+ if root.is_symlink() or cache_inventory._is_junction(root) or not root.is_dir():+ return 0, 0+ except OSError:+ return 0, 0+ try:+ with os.scandir(root) as scan:+ for entry in scan:+ if not cache_inventory._matching(entry.name, patterns):+ continue+ entries += 1+ if entry.is_symlink():+ continue+ if entry.is_dir(follow_symlinks = False):+ if cache_inventory._descendable(entry):+ _reference_measure_tree(Path(entry.path), ledger)+ continue+ cache_inventory._record_entry(entry, ledger)+ except OSError:+ pass+ return ledger.freeable_bytes(), entries+++def _blob(path: Path, size: int) -> Path:+ path.parent.mkdir(parents = True, exist_ok = True)+ path.write_bytes(b"x" * size)+ return path+++def awkward_tree(tmp_path):+ """Nested dirs, symlinks in and out, hard links in and out, and dirs the walk cannot read."""+ root = tmp_path / "cache"+ outside = tmp_path / "outside"+ _blob(outside / "big.bin", 1 << 20)+ _blob(root / "top.bin", 11)+ for archive in range(4):+ for depth in range(3):+ nested = (+ root / "archive-v0" / f"a{archive}" / Path(*[f"d{d}" for d in range(depth + 1)])+ )+ _blob(nested / f"f{archive}_{depth}.py", 100 + archive * 10 + depth)+ os.symlink(outside, root / "archive-v0" / "linked_dir")+ os.symlink(outside / "big.bin", root / "archive-v0" / "a0" / "linked_file.bin")+ os.symlink(root / "missing", root / "dangling")+ # Both links inside: counted once. One link outside: not reclaimable, so not counted.+ inner = _blob(root / "wheels" / "pkg" / "inner.bin", 5000)+ os.link(inner, root / "archive-v0" / "a1" / "inner_link.bin")+ shared = _blob(root / "wheels" / "pkg" / "shared.bin", 7000)+ os.link(shared, outside / "venv_link.bin")+ # A three-link inode with two links in two different top-level dirs and one outside.+ triple = _blob(root / "builds" / "t.bin", 3000)+ os.link(triple, root / "wheels" / "t_link.bin")+ os.link(triple, outside / "t_out.bin")+ # Unlistable, and listable but not searchable.+ _blob(root / "locked" / "hidden.bin", 900)+ _blob(root / "noexec" / "child.bin", 800)+ _blob(root / "archive-v0" / "a2" / "deep_locked" / "deeper" / "x.bin", 700)+ os.chmod(root / "locked", 0)+ os.chmod(root / "noexec", 0o600)+ os.chmod(root / "archive-v0" / "a2" / "deep_locked", 0)+ yield root+ for path in (root / "locked", root / "noexec", root / "archive-v0" / "a2" / "deep_locked"):+ os.chmod(path, 0o755)++[email protected](sys.platform == "win32", reason = "symlinks and chmod 0 need POSIX semantics")[email protected]("patterns", [None, ("archive-v0", "wheels"), ("*.bin",)])+def test_the_walk_sizes_exactly_what_the_reference_walk_sizes(awkward_tree, patterns):+ expected = _reference_measure_root(awkward_tree, patterns)+ assert cache_inventory._measure_root(awkward_tree, patterns = patterns) == expected+ if patterns is None:+ # Sanity on the oracle itself: the outside-linked and unreadable bytes are not counted.+ nested = sum(100 + a * 10 + d for a in range(4) for d in range(3))+ # Root bypasses permission checks (capabilities(7) CAP_DAC_OVERRIDE), so it reads the locked dirs.+ locked = 900 + 800 + 700 if getattr(os, "geteuid", lambda: -1)() == 0 else 0+ assert expected == (11 + nested + 5000 + locked, 7)++[email protected](sys.platform == "win32", reason = "symlinks need POSIX semantics")+def test_the_tree_walk_counts_entries_like_the_reference(awkward_tree):+ target = awkward_tree / "archive-v0"+ reference, tuned = LinkLedger(), LinkLedger()+ assert cache_inventory._measure_tree(target, tuned) == _reference_measure_tree(+ target, reference+ )+ assert tuned.freeable_bytes() == reference.freeable_bytes()+++def test_the_walk_matches_the_reference_on_a_portable_tree(tmp_path):+ """Runs on Windows too, where the awkward tree's symlinks and chmod are unavailable."""+ root = tmp_path / "cache"+ outside = tmp_path / "outside"+ _blob(root / "top.bin", 11)+ for archive in range(3):+ _blob(root / f"a{archive}" / "d0" / "d1" / f"f{archive}.py", 100 + archive)+ inner = _blob(root / "wheels" / "inner.bin", 5000)+ os.link(inner, root / "a1" / "inner_link.bin")+ shared = _blob(root / "wheels" / "shared.bin", 7000)+ _blob(outside / "keep.txt", 1)+ os.link(shared, outside / "venv_link.bin")+ for patterns in (None, ("a*",), ("*.bin",)):+ assert cache_inventory._measure_root(root, patterns = patterns) == _reference_measure_root(+ root, patterns+ )+++def test_a_junction_below_the_top_level_is_still_not_walked(tmp_path, monkeypatch):+ root = tmp_path / "cache"+ _blob(root / "a" / "b" / "junction" / "elsewhere.bin", 4096)+ _blob(root / "a" / "kept.bin", 3)+ monkeypatch.setattr(cache_inventory, "_is_junction", lambda path: Path(path).name == "junction")+ assert cache_inventory._measure_root(root) == (3, 1)+++def clean_memo(monkeypatch):+ monkeypatch.setattr(cache_inventory, "_size_cache", {})+ monkeypatch.setattr(cache_inventory, "_size_epochs", {})+ monkeypatch.setattr(cache_inventory, "_size_flights", {})+ # A background walk an earlier test left running (a real cache walk under load) must not hold these up.+ monkeypatch.setattr(cache_inventory, "_background_walk_lock", threading.Lock())+++def _expire(key: str, *, walk_seconds: float) -> None:+ begun, _stored, entry, *_rest = cache_inventory._size_cache[key]+ past = time.monotonic() - cache_inventory._INVENTORY_TTL_SECONDS - 1+ cache_inventory._size_cache[key] = (past - walk_seconds, past, entry, walk_seconds)+++def test_an_expired_slow_cache_answers_at_once_and_refreshes_behind(monkeypatch, clean_memo):+ definition = definition_for("uv")+ sizes = iter([10, 20])+ release = threading.Event()+ walked = threading.Event()++ def describe(target):+ size = next(sizes)+ if size == 20:+ walked.set()+ release.wait(10)+ return {"key": target.key, "size_bytes": size}++ monkeypatch.setattr(cache_inventory, "describe_cache", describe)+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10+ _expire("uv", walk_seconds = cache_inventory._BACKGROUND_WALK_SECONDS + 5)++ started = time.monotonic()+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10+ assert time.monotonic() - started < 1.0+ assert walked.wait(5), "no background walk was started"+ # A second read while that walk runs neither waits nor starts another.+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10+ release.set()+ for _ in range(100):+ if cache_inventory._size_cache["uv"][2]["size_bytes"] == 20:+ break+ time.sleep(0.05)+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 20+++def test_a_studio_download_or_delete_is_never_answered_from_the_older_walk(monkeypatch, clean_memo):+ """Downloads and deletes call invalidate_hf_cache_scans; Settings must then walk, as base did after the TTL."""+ from hub.utils.inventory_scan import invalidate_hf_cache_scans+ for key in ("hf_hub", "hf_xet", "hf_datasets", "hf_assets"):+ definition = definition_for(key)+ sizes = iter([100, 999])+ monkeypatch.setattr(+ cache_inventory,+ "describe_cache",+ lambda target, sizes = sizes: {"key": target.key, "size_bytes": next(sizes)},+ )+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 100+ _expire(key, walk_seconds = cache_inventory._BACKGROUND_WALK_SECONDS + 5)+ invalidate_hf_cache_scans()+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 999, key+++def test_an_expired_quick_cache_is_still_walked_in_the_request(monkeypatch, clean_memo):+ definition = definition_for("pip")+ sizes = iter([10, 20])+ monkeypatch.setattr(+ cache_inventory,+ "describe_cache",+ lambda target: {"key": target.key, "size_bytes": next(sizes)},+ )+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10+ _expire("pip", walk_seconds = 0.01)+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 20+++def test_recheck_waits_for_a_fresh_walk_even_for_a_slow_cache(monkeypatch, clean_memo):+ definition = definition_for("triton")+ sizes = iter([10, 20])+ monkeypatch.setattr(+ cache_inventory,+ "describe_cache",+ lambda target: {"key": target.key, "size_bytes": next(sizes)},+ )+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10+ _expire("triton", walk_seconds = 60)+ assert cache_inventory._described(definition, refresh = True)["size_bytes"] == 20+++def test_a_background_walk_overtaken_by_a_purge_does_not_store_its_size(monkeypatch, clean_memo):+ definition = definition_for("uv")+ sizes = iter([10, 20, 0])+ walked = threading.Event()+ release = threading.Event()++ def describe(target):+ size = next(sizes)+ if size == 20:+ walked.set()+ release.wait(10)+ return {"key": target.key, "size_bytes": size}++ monkeypatch.setattr(cache_inventory, "describe_cache", describe)+ cache_inventory._described(definition, refresh = False)+ _expire("uv", walk_seconds = 30)+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 10+ assert walked.wait(5)+ cache_inventory.invalidate_cache_size("uv")+ release.set()+ # The purge's own read waits for the stale walk, then walks again rather than keep 20.+ assert cache_inventory._described(definition, refresh = False)["size_bytes"] == 0+++def test_background_walks_run_one_at_a_time(monkeypatch, clean_memo):+ running: list = []+ peak: list = []+ lock = threading.Lock()+ first_pass = {"uv": True, "triton": True}++ def describe(target):+ if first_pass.pop(target.key, False):+ return {"key": target.key, "size_bytes": 1}+ with lock:+ running.append(target.key)+ peak.append(len(running))+ time.sleep(0.2)+ with lock:+ running.remove(target.key)+ return {"key": target.key, "size_bytes": 2}++ monkeypatch.setattr(cache_inventory, "describe_cache", describe)+ for key in ("uv", "triton"):+ cache_inventory._described(definition_for(key), refresh = False)+ _expire(key, walk_seconds = 30)+ for key in ("uv", "triton"):+ assert cache_inventory._described(definition_for(key), refresh = False)["size_bytes"] == 1+ for _ in range(100):+ if all(cache_inventory._size_cache[key][2]["size_bytes"] == 2 for key in ("uv", "triton")):+ break+ time.sleep(0.05)+ assert peak == [1, 1]+++def test_the_inventory_starts_background_walks_after_its_own(monkeypatch, clean_memo):+ order: list = []+ real_refresh = cache_inventory._refresh_in_background+ monkeypatch.setattr(+ cache_inventory,+ "describe_cache",+ lambda target: (+ order.append(("walk", target.key)),+ {+ "key": target.key,+ "size_bytes": 1,+ "present": False,+ "purgeable": False,+ "opt_in": False,+ },+ )[1],+ )+ monkeypatch.setattr(cache_inventory, "_free_bytes", lambda: None)+ monkeypatch.setattr(cache_inventory, "_total_disk_bytes", lambda: None)+ cache_inventory.cache_inventory()+ for definition in cache_inventory.CACHE_DEFINITIONS:+ _expire(definition.key, walk_seconds = 30 if definition.key == "uv" else 0.01)+ order.clear()+ monkeypatch.setattr(+ cache_inventory,+ "_refresh_in_background",+ lambda definition: (order.append(("background", definition.key)), real_refresh(definition)),+ )+ cache_inventory.cache_inventory()+ for _ in range(100):+ if ("walk", "uv") in order:+ break+ time.sleep(0.05)+ foreground = [key for kind, key in order if kind == "walk" and key != "uv"]+ assert len(foreground) == len(cache_inventory.CACHE_DEFINITIONS) - 1+ assert order.index(("background", "uv")) == len(foreground)diff --git a/studio/backend/utils/cache_inventory.py b/studio/backend/utils/cache_inventory.pyindex 803ab1c041a..9b684664b38 100644--- a/studio/backend/utils/cache_inventory.py+++ b/studio/backend/utils/cache_inventory.py@@ -711,6 +711,9 @@ class LinkLedger:else:record[2] += 1+ def add_single_link_bytes(self, size: int) -> None:+ self._single += size+def freeable_bytes(self) -> int:return self._single + sum(size for size, links, met in self._multi.values() if met >= links)@@ -728,28 +731,50 @@ def _descendable(entry: os.DirEntry) -> bool:return not _is_junction(entry.path)-def _measure_tree(path: Path, ledger: LinkLedger) -> int:- """Size is left to the ledger: a multi-link inode's cost is only known after every root is walked."""+def _walk_into(stack: list, ledger: LinkLedger) -> int:+ """Sizes every directory on the stack and below it; returns the entries seen.++ A uv or triton cache can hold millions of files, so the loop body is the whole cost: paths+ stay strings and single-link sizes are summed locally rather than through the ledger.+ """count = 0- stack = [path]- while stack:- current = stack.pop()- try:- with os.scandir(current) as entries:- for entry in entries:- count += 1- if entry.is_symlink():- continue- if entry.is_dir(follow_symlinks = False):- if _descendable(entry):- stack.append(Path(entry.path))- continue- _record_entry(entry, ledger)- except OSError:- continue+ single = 0+ add = ledger.add+ pop = stack.pop+ push = stack.append+ try:+ while stack:+ current = pop()+ try:+ with os.scandir(current) as entries:+ for entry in entries:+ count += 1+ if entry.is_symlink():+ continue+ if entry.is_dir(follow_symlinks = False):+ if _descendable(entry):+ push(entry.path)+ continue+ try:+ found = entry.stat(follow_symlinks = False)+ except OSError:+ continue+ if found.st_nlink <= 1:+ single += found.st_size+ else:+ add(found)+ except OSError:+ continue+ finally:+ ledger.add_single_link_bytes(single)return count+def _measure_tree(path: Path, ledger: LinkLedger) -> int:+ """Size is left to the ledger: a multi-link inode's cost is only known after every root is walked."""+ return _walk_into([os.fspath(path)], ledger)++def _measure_root(root: Path, *, patterns: Optional[Iterable[str]] = None) -> tuple[int, int]:ledger = LinkLedger()entries = 0@@ -758,6 +783,8 @@ def _measure_root(root: Path, *, patterns: Optional[Iterable[str]] = None) -> tureturn 0, 0except OSError:return 0, 0+ # Subdirectories are walked after the listing, in one loop, so they are still sized when it fails part way.+ subdirs: list = []try:with os.scandir(root) as scan:for entry in scan:@@ -768,11 +795,13 @@ def _measure_root(root: Path, *, patterns: Optional[Iterable[str]] = None) -> tucontinueif entry.is_dir(follow_symlinks = False):if _descendable(entry):- _measure_tree(Path(entry.path), ledger)+ subdirs.append(entry.path)continue_record_entry(entry, ledger)except OSError as exc:logger.debug(f"Could not size {root}: {exc}")+ subdirs.reverse()+ _walk_into(subdirs, ledger)return ledger.freeable_bytes(), entries@@ -865,8 +894,10 @@ def _patterns_for(definition: CacheDefinition) -> Optional[tuple[str, ...]]:# Walks take seconds on large uv/triton caches, so repeat reads within the TTL reuse the last answer._INVENTORY_TTL_SECONDS = 60.0-# Tuple of (walk start, store time, entry): TTL uses store time, forced reads compare walk start.-_size_cache: dict[str, tuple[float, float, dict]] = {}+# Past the TTL, a cache whose last walk took this long answers from it and re-walks in the background.+_BACKGROUND_WALK_SECONDS = 2.0+# Tuple of (walk start, store time, entry, walk seconds): TTL uses store time, forced reads compare walk start.+_size_cache: dict[str, tuple[float, float, dict, float]] = {}# Bumped per invalidation so a walk begun earlier cannot store a stale size._size_epochs: dict[str, int] = {}_size_cache_lock = threading.Lock()@@ -880,6 +911,8 @@ def invalidate_cache_size(key: str) -> None:_size_flights: dict[str, threading.Lock] = {}_size_flights_lock = threading.Lock()+# Background walks run one at a time: two stat-bound walks in one process only trade the GIL.+_background_walk_lock = threading.Lock()def _flight_for(key: str) -> threading.Lock:@@ -887,12 +920,61 @@ def _flight_for(key: str) -> threading.Lock:return _size_flights.setdefault(key, threading.Lock())-def _described(definition: CacheDefinition, *, refresh: bool) -> dict:+def _walk_and_remember(definition: CacheDefinition, epoch: int) -> dict:+ """Caller holds the key's flight; an invalidation since ``epoch`` keeps the answer out of the memo."""+ begun = time.monotonic()+ entry = describe_cache(definition)+ finished = time.monotonic()+ with _size_cache_lock:+ if _size_epochs.get(definition.key, 0) == epoch:+ _size_cache[definition.key] = (begun, finished, entry, finished - begun)+ return entry+++def _refresh_in_background(definition: CacheDefinition) -> None:+ """At most one walk per cache: one already running, foreground or not, stores the newer size anyway."""+ flight = _flight_for(definition.key)+ if not flight.acquire(blocking = False):+ return++ def walk() -> None:+ try:+ with _background_walk_lock:+ with _size_cache_lock:+ epoch = _size_epochs.get(definition.key, 0)+ _walk_and_remember(definition, epoch)+ except Exception as exc: # noqa: BLE001 - a failed refresh leaves the last size in place+ logger.debug(f"Could not refresh the {definition.key} cache size: {exc}")+ finally:+ flight.release()++ try:+ threading.Thread(target = walk, name = f"cache-size-{definition.key}", daemon = True).start()+ except Exception as exc: # noqa: BLE001 - e.g. no thread left; the next read walks in the foreground+ flight.release()+ logger.debug(f"Could not start a {definition.key} cache size refresh: {exc}")+++def _described(+ definition: CacheDefinition,+ *,+ refresh: bool,+ deferred: Optional[list] = None,+) -> dict:+ """``deferred`` collects the background refreshes for the caller to start, after its own walks."""started = time.monotonic()with _size_cache_lock:remembered = None if refresh else _size_cache.get(definition.key)- if remembered is not None and started - remembered[1] < _INVENTORY_TTL_SECONDS:- return remembered[2]+ if remembered is not None:+ if started - remembered[1] < _INVENTORY_TTL_SECONDS:+ return remembered[2]+ # A forced read (the Recheck button) still waits for a fresh walk below.+ if remembered[3] >= _BACKGROUND_WALK_SECONDS:+ if deferred is None:+ _refresh_in_background(definition)+ else:+ deferred.append(definition)+ return remembered[2]# One walk per cache at a time, or simultaneous misses (e.g. two open tabs) each pay a cold walk.with _flight_for(definition.key):with _size_cache_lock:@@ -905,16 +987,18 @@ def _described(definition: CacheDefinition, *, refresh: bool) -> dict:return remembered[2]elif time.monotonic() - remembered[1] < _INVENTORY_TTL_SECONDS:return remembered[2]- begun = time.monotonic()- entry = describe_cache(definition)- with _size_cache_lock:- if _size_epochs.get(definition.key, 0) == epoch:- _size_cache[definition.key] = (begun, time.monotonic(), entry)- return entry+ return _walk_and_remember(definition, epoch)def cache_inventory(*, refresh: bool = False) -> dict:- entries = [_described(definition, refresh = refresh) for definition in CACHE_DEFINITIONS]+ # Started after the foreground walks, which would otherwise share the GIL with them.+ deferred: list = []+ entries = [+ _described(definition, refresh = refresh, deferred = deferred)+ for definition in CACHE_DEFINITIONS+ ]+ for definition in deferred:+ _refresh_in_background(definition)total = sum(entry["size_bytes"] for entry in entries if entry["present"])reclaimable = sum(entry["size_bytes"]