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: keep GGUF variant listings off the default thread pool so a stalled Hub cannot block downloaded models (#14134)
Daniel Han336590e7ff67
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.pyindex fe2b49558f6..60e729947e2 100644--- a/studio/backend/hub/services/models/gguf_variants.py+++ b/studio/backend/hub/services/models/gguf_variants.py@@ -8,6 +8,8 @@ from __future__ import annotationsfrom hub.services.models import account_accessimport asyncio+import contextvars+import functoolsimport hashlibimport jsonimport re@@ -15,6 +17,7 @@ import threadingimport timeimport weakreffrom collections import OrderedDict+from concurrent.futures import ThreadPoolExecutorfrom pathlib import Pathfrom typing import NamedTuple, Optional@@ -1033,8 +1036,24 @@ def _complete_with_servable(snapshot: str, complete, variants):# running, and 23 retries filled all 20 default-executor workers._VARIANTS_INFLIGHT: "weakref.WeakKeyDictionary" = weakref.WeakKeyDictionary()+# Not the default executor: a stalled Hub holds a remote listing's thread until it answers, and enough+# of them blocked every asyncio.to_thread caller (load, chat) and the On Device disk-only listing (#14038).+_HUB_LISTING_POOL = ThreadPoolExecutor(thread_name_prefix = "gguf-hub-listing")+_DISK_LISTING_POOL = ThreadPoolExecutor(thread_name_prefix = "gguf-disk-listing")-async def _shared_variants_scan(key: tuple, compute):++async def listing_thread(offline: bool, fn, /, *args, **kwargs):+ """``asyncio.to_thread`` on the listing pool for *offline* (context variables carried along)."""+ loop = asyncio.get_running_loop()+ call = functools.partial(contextvars.copy_context().run, fn, *args, **kwargs)+ return await loop.run_in_executor(_DISK_LISTING_POOL if offline else _HUB_LISTING_POOL, call)+++async def _shared_variants_scan(+ key: tuple,+ compute,+ offline: bool = False,+):"""*compute* in a thread, shared with any identical request already running."""loop = asyncio.get_running_loop()inflight = _VARIANTS_INFLIGHT.get(loop)@@ -1044,7 +1063,7 @@ async def _shared_variants_scan(key: tuple, compute):task = inflight.get(key)if task is None:- task = asyncio.ensure_future(asyncio.to_thread(compute))+ task = asyncio.ensure_future(listing_thread(offline, compute))def _release(finished: asyncio.Future) -> None:inflight.pop(key, None)@@ -1096,11 +1115,11 @@ async def _audio_cpp_variants_answer(return Nonereal_repo = audio_cpp_models.repo_of(text) or textif account_access.managed_account():- await asyncio.to_thread(account_access.require_model_access, real_repo)+ await listing_thread(False, account_access.require_model_access, real_repo)network = not (offline or audio_cpp_models.hub_offline())try:- model = await asyncio.to_thread(- audio_cpp_models.resolve, text, None, hf_token, network = network+ model = await listing_thread(+ not network, audio_cpp_models.resolve, text, None, hf_token, network = network)except Exception as exc: # noqa: BLE001 - the generic lister reports an unreadable repologger.debug("audio.cpp variants for %s unavailable: %s", text, exc)@@ -1200,7 +1219,7 @@ async def _audio_cpp_variants_answer()return rows- details = await asyncio.to_thread(_details)+ details = await listing_thread(not network, _details)loadable = [row.quant for row in details if row.downloaded]return VariantsAnswer(GgufVariantsResponse(@@ -1327,7 +1346,7 @@ async def _mlx_precision_variants_answer(variant_format = "mlx",)- response = await asyncio.to_thread(_listing)+ response = await listing_thread(offline, _listing)if response is None:return Nonereturn VariantsAnswer(response, None, cache_authorized = False)@@ -1352,8 +1371,8 @@ async def get_gguf_variants_answer(access_options = {"offline": True} if offline else {}if local_path:if account_access.managed_account():- await asyncio.to_thread(- account_access.require_model_access, local_path, **access_options+ await listing_thread(+ offline, account_access.require_model_access, local_path, **access_options)hf_token = account_access.account_hf_token(hf_token)from core.inference.audio_cpp_models import is_umbrella_id@@ -1365,7 +1384,9 @@ async def get_gguf_variants_answer(return audio_cpp_answerif account_access.managed_account():try:- await asyncio.to_thread(account_access.require_model_access, repo_id, **access_options)+ await listing_thread(+ offline, account_access.require_model_access, repo_id, **access_options+ )except HTTPException:# No grant exists before the first download, so for a private repo the caller's own# token proves Hub access instead. Offline requests need an existing grant or public proof.@@ -1373,7 +1394,9 @@ async def get_gguf_variants_answer(raiseif is_local_path(repo_id) or not _is_valid_repo_id(repo_id):raise- await asyncio.to_thread(account_access.authorize_download, repo_id, "model", hf_token)+ await listing_thread(+ False, account_access.authorize_download, repo_id, "model", hf_token+ )# Returned with the listing because the HF cache answers before local_path, so a caller cannot infer# the copy from the request alone.answered_from: list[Optional[str]] = [None]@@ -2549,7 +2572,9 @@ async def get_gguf_variants_answer(configured_cache_key(),)try:- answer = await _shared_variants_scan(inflight_key, _compute_with_cleanables)+ answer = await _shared_variants_scan(+ inflight_key, _compute_with_cleanables, offline = bool(offline)+ )# Only after an empty GGUF listing, so GGUF answers never change.if not answer.response.variants and not local_path:mlx_answer = await _mlx_precision_variants_answer(diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.pyindex b2747be898b..b0779d889a5 100644--- a/studio/backend/routes/models.py+++ b/studio/backend/routes/models.py@@ -4757,13 +4757,17 @@ async def get_gguf_variants(# it is the only name an API-key caller has for a local GGUF (see the /hub twin).repo_id = resolve_host_path_reference(repo_id) or repo_idlocal_path = resolve_host_path_reference(local_path) or local_path+ from hub.services.models import gguf_variants as hub_gguf_variants+if account_access.managed_account():- await asyncio.to_thread(- account_access.require_model_access, repo_id, **({"offline": True} if offline else {})+ await hub_gguf_variants.listing_thread(+ offline,+ account_access.require_model_access,+ repo_id,+ **({"offline": True} if offline else {}),)try:hf_token = _resolve_hub_token(hf_token_header, hf_token)- from hub.services.models import gguf_variants as hub_gguf_variantsanswer = await hub_gguf_variants.get_gguf_variants_answer(repo_id,diff --git a/studio/backend/tests/test_gguf_listing_threads.py b/studio/backend/tests/test_gguf_listing_threads.pynew file mode 100644index 00000000000..2943f1cace9--- /dev/null+++ b/studio/backend/tests/test_gguf_listing_threads.py@@ -0,0 +1,152 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""GGUF variant listings stay off the default executor (#14038).++A stalled Hub holds a remote listing's thread until it answers. On the shared default executor+enough of them blocked every ``asyncio.to_thread`` caller, and the On Device picker's disk-only+listing of a downloaded repo timed out behind them.+"""++import asyncio+import threading+from concurrent.futures import ThreadPoolExecutor+from types import SimpleNamespace++from hub.services.models import gguf_variants+++def _cached_repo(root, repo_id, quants):+ # Plain files, not blob symlinks: the layout huggingface_hub writes where symlinks are unavailable (Windows).+ repo_dir = root / f"models--{repo_id.replace('/', '--')}"+ sha = "a" * 40+ snapshot = repo_dir / "snapshots" / sha+ snapshot.mkdir(parents = True)+ (repo_dir / "refs").mkdir()+ (repo_dir / "refs" / "main").write_text(sha)+ leaf = repo_id.split("/")[1].removesuffix("-GGUF")+ for i, quant in enumerate(quants):+ (snapshot / f"{leaf}-{quant}.gguf").write_bytes(b"GGUF" + bytes([i]) * 4096)+++def _pin_cache_roots(monkeypatch, active, home):+ monkeypatch.setattr(+ "utils.hf_cache_settings.get_hf_cache_paths",+ lambda: SimpleNamespace(hub_cache = active, hf_home = home, source = "studio", cache_home = home),+ )+ monkeypatch.setattr("hub.utils.hf_cache_state.hf_cache_roots", lambda **kw: [active])+ monkeypatch.setattr(+ "hub.utils.hf_cache_state.hf_cache_root",+ lambda create = False, root = None, **kw: root if root is not None else active,+ )+++async def _with_saturated_default_executor(body):+ """Run *body* while the loop's only default-executor worker is held, as stalled Hub calls do."""+ loop = asyncio.get_running_loop()+ loop.set_default_executor(ThreadPoolExecutor(max_workers = 1))+ gate = threading.Event()+ holder = asyncio.ensure_future(asyncio.to_thread(gate.wait, 30))+ await asyncio.sleep(0.05)+ try:+ return await body()+ finally:+ gate.set()+ await holder+++def test_disk_only_listing_answers_while_the_default_executor_is_saturated(monkeypatch, tmp_path):+ hub = tmp_path / "hub"+ _cached_repo(hub, "unsloth/Qwen3.8-27B-GGUF", ["UD-Q4_K_XL", "Q8_0"])+ _pin_cache_roots(monkeypatch, hub, tmp_path)++ async def listing():+ answer = await asyncio.wait_for(+ gguf_variants.get_gguf_variants_answer(+ "unsloth/Qwen3.8-27B-GGUF",+ prefer_local_cache = True,+ offline = True,+ include_cache_locations = True,+ ),+ 10,+ )+ return answer.response++ response = asyncio.run(_with_saturated_default_executor(listing))+ assert sorted(v.quant for v in response.variants) == ["Q8_0", "UD-Q4_K_XL"]+ assert all(v.downloaded for v in response.variants)+++def test_a_stalled_hub_listing_leaves_the_default_executor_free():+ async def body():+ loop = asyncio.get_running_loop()+ loop.set_default_executor(ThreadPoolExecutor(max_workers = 1))+ gate = threading.Event()+ stalled = asyncio.ensure_future(+ gguf_variants._shared_variants_scan(("stalled-hub-listing",), lambda: gate.wait(30))+ )+ await asyncio.sleep(0.05)+ try:+ # What model load, chat and every other to_thread caller need.+ return await asyncio.wait_for(asyncio.to_thread(lambda: "free"), 10)+ finally:+ gate.set()+ await stalled++ assert asyncio.run(body()) == "free"+++def test_a_disk_only_listing_does_not_queue_behind_stalled_hub_listings(monkeypatch):+ monkeypatch.setattr(gguf_variants, "_HUB_LISTING_POOL", ThreadPoolExecutor(max_workers = 1))++ async def body():+ gate = threading.Event()+ stalled = asyncio.ensure_future(+ gguf_variants._shared_variants_scan(("hub",), lambda: gate.wait(30))+ )+ await asyncio.sleep(0.05)+ try:+ return await asyncio.wait_for(+ gguf_variants._shared_variants_scan(("disk",), lambda: "disk", offline = True), 10+ )+ finally:+ gate.set()+ await stalled++ assert asyncio.run(body()) == "disk"+++def test_listing_threads_carry_context_variables():+ import contextvars++ marker = contextvars.ContextVar("marker", default = None)++ async def body():+ marker.set("request")+ return await gguf_variants.listing_thread(True, marker.get)++ assert asyncio.run(body()) == "request"+++def test_a_stalled_managed_account_preflight_leaves_the_default_executor_free(monkeypatch):+ # For an ungranted repo the preflight asks the Hub, so it stalls with it.+ gate = threading.Event()+ monkeypatch.setattr(gguf_variants.account_access, "managed_account", lambda: True)+ monkeypatch.setattr(+ gguf_variants.account_access, "require_model_access", lambda *a, **k: gate.wait(30)+ )++ async def body():+ loop = asyncio.get_running_loop()+ loop.set_default_executor(ThreadPoolExecutor(max_workers = 1))+ listing = asyncio.ensure_future(+ gguf_variants.get_gguf_variants_answer("unsloth/Stalled-GGUF", local_path = "/x")+ )+ await asyncio.sleep(0.05)+ try:+ return await asyncio.wait_for(asyncio.to_thread(lambda: "free"), 10)+ finally:+ gate.set()+ listing.cancel()++ assert asyncio.run(body()) == "free"diff --git a/studio/backend/tests/test_mlx_precision_variants.py b/studio/backend/tests/test_mlx_precision_variants.pyindex 6086d5cc7f1..06f3f27de45 100644--- a/studio/backend/tests/test_mlx_precision_variants.py+++ b/studio/backend/tests/test_mlx_precision_variants.py@@ -140,7 +140,11 @@ def _no_gguf_rows(monkeypatch, cache_authorized = True):gguf_variants.GgufVariantsResponse(repo_id = _REPO), None, cache_authorized)- async def _scan(key, compute):+ async def _scan(+ key,+ compute,+ offline = False,+ ):return emptymonkeypatch.setattr(gguf_variants, "_shared_variants_scan", _scan)@@ -182,7 +186,11 @@ def test_gguf_listing_is_answered_without_asking_for_mlx_folders(monkeypatch):gguf_variants.GgufVariantsResponse(repo_id = "a/b-GGUF", variants = [row]), None)- async def _scan(key, compute):+ async def _scan(+ key,+ compute,+ offline = False,+ ):return ggufclass _NoHub: