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: preserve partial state for canceled GGUF companions (#11018)

Etherl4e4ab1233ed2
diff --git a/studio/backend/hub/services/models/gguf_variants.py b/studio/backend/hub/services/models/gguf_variants.py
index 7fc3f754f46..50e6ef4e061 100644
--- a/studio/backend/hub/services/models/gguf_variants.py
+++ b/studio/backend/hub/services/models/gguf_variants.py
@@ -1183,15 +1183,100 @@ async def get_gguf_variants_answer(
default_variant = default_variant,
)
- def _with_state_partials(response: GgufVariantsResponse) -> GgufVariantsResponse:
- """Add quants known only from download state. A sibling cancelled
- before any file landed has no snapshot entry, so a listing built
- from the cache alone reads as if it were never asked for, and the
- row loses its resume."""
+ def _with_state_partials(
+ response: GgufVariantsResponse, snapshot_dir: Optional[Path]
+ ) -> GgufVariantsResponse:
+ """Reconcile cache rows with download state and add state-only quants.
+
+ Main GGUF completeness is only an intermediate readiness signal: a
+ same-quant manifest can still require a missing companion, and an
+ applicable cancellation marker remains authoritative until the
+ download lifecycle clears it. Preserve the real cache row while
+ overlaying that positive state; state-only quants keep the existing
+ synthetic-row fallback.
+ """
state = _quants_from_state(repo_id, hub_cache)
if state is None:
return response
- listed = {v.quant.lower() for v in response.variants if v.quant}
+
+ state_by_quant = {v.quant.lower(): v for v in state[0] if v.quant}
+ listed: set[str] = set()
+ variants: list[GgufVariantDetail] = []
+ changed = False
+ repo_signal_applies = hf_cache_scan.repo_signal_applies_to_snapshot(
+ repo_cache_dir,
+ snapshot_dir,
+ )
+ complete_here = (
+ {quant.lower() for quant in (_complete_quants_under(str(snapshot_dir)) or ())}
+ if snapshot_dir is not None
+ else set()
+ )
+
+ for detail in response.variants:
+ key = detail.quant.lower() if detail.quant else ""
+ if key:
+ listed.add(key)
+ state_variant = state_by_quant.get(key)
+ if state_variant is None:
+ variants.append(detail)
+ continue
+ try:
+ is_partial = hf_cache_scan.is_variant_partial(
+ repo_id,
+ detail.quant,
+ snapshot_dir,
+ repo_cache_dir = repo_cache_dir,
+ # a ready row absent here comes from a complete sibling snapshot.
+ repo_signal_applies = (
+ repo_signal_applies if key in complete_here else not detail.downloaded
+ ),
+ )
+ except Exception as e:
+ logger.warning(
+ "State-based partial check failed for %s/%s: %s",
+ repo_id,
+ detail.quant,
+ e,
+ )
+ variants.append(detail)
+ continue
+ if not is_partial:
+ variants.append(detail)
+ continue
+
+ state_download_size = int(
+ state_variant.download_size_bytes or state_variant.size_bytes or 0
+ )
+ detail = detail.model_copy(
+ update = {
+ "download_size_bytes": (
+ state_download_size
+ if state_download_size > 0
+ else detail.download_size_bytes
+ ),
+ "download_remaining_bytes": variant_remaining_bytes_from_state(
+ repo_id,
+ detail.quant,
+ repo_cache_dir,
+ ),
+ "downloaded": False,
+ "partial": True,
+ "partial_transport": _partial_transport_for_variant(
+ repo_id,
+ detail.quant,
+ repo_cache_dir,
+ ),
+ "partial_resumable": _partial_resumable_for_variant(
+ repo_id,
+ detail.quant,
+ repo_cache_dir,
+ ),
+ }
+ )
+ changed = True
+ variants.append(detail)
+
extra = [
GgufVariantDetail(
filename = v.filename,
@@ -1218,9 +1303,18 @@ async def get_gguf_variants_answer(
for v in state[0]
if v.quant and v.quant.lower() not in listed
]
- if not extra:
+ if not (changed or extra):
return response
- return response.model_copy(update = {"variants": [*response.variants, *extra]})
+ variants.extend(extra)
+ ready = [v for v in variants if v.downloaded and not v.partial]
+ best = pick_best_gguf(_default_variant_candidates(ready or variants))
+ default_variant = gguf_variant_key(best) if best else None
+ return response.model_copy(
+ update = {
+ "variants": variants,
+ "default_variant": default_variant,
+ }
+ )
# Load-path parity: from_identifier resolves existence-first, so a marker-less relative name that
# exists here is a local model, not a Hub id, and a direct .gguf file loads without the metadata
@@ -1319,7 +1413,8 @@ async def get_gguf_variants_answer(
return _with_state_partials(
_local_response(
repo_id, variants, has_vision, _complete_quants_under(str(snapshot_scope))
- )
+ ),
+ snapshot_scope,
)
local_only = prefer_local_cache or offline
@@ -1341,7 +1436,8 @@ async def get_gguf_variants_answer(
answered_from[0] = str(snapshot)
# The lister leaves torn quants in: they stay listed for management, but not ready.
return _with_state_partials(
- _local_response(repo_id, variants, has_vision, complete)
+ _local_response(repo_id, variants, has_vision, complete),
+ snapshot,
)
if local_path and is_local_path(local_path):
variants, has_vision = list_local_gguf_variants(local_path)
@@ -1390,7 +1486,8 @@ async def get_gguf_variants_answer(
# Same reason as the local_only branch above: an unreachable Hub is exactly when a resume has
# nowhere else to surface, so state partials are included.
return _with_state_partials(
- _local_response(repo_id, variants, has_vision, complete)
+ _local_response(repo_id, variants, has_vision, complete),
+ snapshot,
)
partial = _quants_from_state(repo_id, hub_cache)
if partial is not None:
diff --git a/studio/backend/hub/tests/test_model_services.py b/studio/backend/hub/tests/test_model_services.py
index 6be4399eff5..9ad6c721d72 100644
--- a/studio/backend/hub/tests/test_model_services.py
+++ b/studio/backend/hub/tests/test_model_services.py
@@ -4309,6 +4309,166 @@ def test_gguf_variants_partial_marker_overrides_size_only_downloaded(monkeypatch
assert result.variants[0].partial is True
+def test_local_gguf_state_demotes_matching_main_until_companion_completes(monkeypatch, tmp_path):
+ repo_id = "Org/CompanionRepo"
+ quant = "UD-Q4_K_XL"
+ state_quant = quant.lower()
+ main_name = "Model-UD-Q4_K_XL.gguf"
+ companion_name = "MTP/mtp-Q8_0.gguf"
+ hub_cache = tmp_path / "hub"
+ repo_dir = hub_cache / "models--Org--CompanionRepo"
+ snapshot = repo_dir / "snapshots" / ("a" * 40)
+ snapshot.mkdir(parents = True)
+ (repo_dir / "blobs").mkdir()
+ (repo_dir / "blobs" / "main").write_bytes(b"m")
+ (repo_dir / "refs").mkdir()
+ (repo_dir / "refs" / "main").write_text("a" * 40, encoding = "utf-8")
+ (snapshot / main_name).write_bytes(b"m")
+ (snapshot / "Model-Q8_0.gguf").write_bytes(b"8")
+
+ monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "studio-state")
+ monkeypatch.setattr(inventory_scan, "hf_cache_roots", lambda **_kw: [hub_cache])
+ monkeypatch.setattr(
+ "utils.hf_cache_settings.get_hf_cache_paths",
+ lambda: SimpleNamespace(hub_cache = hub_cache),
+ )
+ inventory_scan.invalidate_hf_cache_scans()
+ assert download_manifest.write_manifest(
+ "model",
+ repo_id,
+ state_quant,
+ [
+ download_manifest.ExpectedFile(path = main_name, size = 1, sha256 = "main"),
+ download_manifest.ExpectedFile(
+ path = companion_name,
+ size = 2,
+ sha256 = "companion",
+ ),
+ ],
+ "xet",
+ hub_cache = hub_cache,
+ )
+ assert download_manifest.write_cancel_marker(
+ "model",
+ repo_id,
+ state_quant,
+ "xet",
+ hub_cache = hub_cache,
+ )
+
+ try:
+ partial = asyncio.run(
+ gguf_variants.get_gguf_variants_response(repo_id, prefer_local_cache = True)
+ )
+ rows = [row for row in partial.variants if row.quant.lower() == state_quant]
+ assert len(rows) == 1
+ row = rows[0]
+ assert row.filename == main_name
+ assert row.quant == quant
+ assert row.size_bytes == 1
+ assert row.download_size_bytes == 3
+ assert row.download_remaining_bytes == 2
+ assert row.downloaded is False
+ assert row.partial is True
+ assert row.partial_transport == "xet"
+ assert row.partial_resumable is False
+ assert partial.default_variant == "Q8_0"
+
+ download_manifest.clear_cancel_marker(
+ "model",
+ repo_id,
+ state_quant,
+ hub_cache = hub_cache,
+ )
+ companion = snapshot / companion_name
+ companion.parent.mkdir()
+ companion.write_bytes(b"mt")
+ inventory_scan.invalidate_hf_cache_scans()
+
+ completed = asyncio.run(
+ gguf_variants.get_gguf_variants_response(repo_id, prefer_local_cache = True)
+ )
+ finally:
+ inventory_scan.invalidate_hf_cache_scans()
+
+ completed_row = next(row for row in completed.variants if row.quant == quant)
+ assert completed_row.filename == main_name
+ assert completed_row.downloaded is True
+ assert completed_row.partial is False
+ assert completed_row.partial_transport is None
+ assert completed.default_variant == quant
+
+
[email protected]("pin_snapshot", [True, False])
+def test_complete_gguf_ignores_newer_state_but_keeps_state_only_quant(
+ monkeypatch, tmp_path, pin_snapshot
+):
+ repo_id = "Org/PinnedRepo"
+ hub_cache = tmp_path / "hub"
+ repo_dir = hub_cache / "models--Org--PinnedRepo"
+ old_snapshot = repo_dir / "snapshots" / "old"
+ new_snapshot = repo_dir / "snapshots" / "new"
+ old_snapshot.mkdir(parents = True)
+ new_snapshot.mkdir(parents = True)
+ (repo_dir / "blobs").mkdir()
+ (repo_dir / "refs").mkdir()
+ (repo_dir / "refs" / "main").write_text("new", encoding = "utf-8")
+ (old_snapshot / "Model-Q4_K_M.gguf").write_bytes(b"4")
+ (new_snapshot / "Model-Q8_0.gguf").write_bytes(b"8")
+ os.utime(old_snapshot, (1, 1))
+ os.utime(new_snapshot, (2, 2))
+
+ monkeypatch.setattr(state_dir, "cache_root", lambda: tmp_path / "studio-state")
+ monkeypatch.setattr(inventory_scan, "hf_cache_roots", lambda **_kw: [hub_cache])
+ monkeypatch.setattr(
+ "utils.hf_cache_settings.get_hf_cache_paths",
+ lambda: SimpleNamespace(hub_cache = hub_cache),
+ )
+ inventory_scan.invalidate_hf_cache_scans()
+ assert download_manifest.write_manifest(
+ "model",
+ repo_id,
+ "Q4_K_M",
+ [
+ download_manifest.ExpectedFile(
+ path = "Model-Q4_K_M.gguf",
+ size = 1,
+ sha256 = "newer-main",
+ )
+ ],
+ "xet",
+ hub_cache = hub_cache,
+ )
+ assert download_manifest.write_cancel_marker(
+ "model", repo_id, "Q4_K_M", "xet", hub_cache = hub_cache
+ )
+ assert download_manifest.write_cancel_marker(
+ "model", repo_id, "q5_k_m", "xet", hub_cache = hub_cache
+ )
+
+ try:
+ result = asyncio.run(
+ gguf_variants.get_gguf_variants_response(
+ repo_id,
+ prefer_local_cache = True,
+ local_path = str(old_snapshot) if pin_snapshot else None,
+ )
+ )
+ finally:
+ inventory_scan.invalidate_hf_cache_scans()
+
+ q4 = next(row for row in result.variants if row.quant == "Q4_K_M")
+ assert q4.filename == "Model-Q4_K_M.gguf"
+ assert q4.downloaded is True
+ assert q4.partial is False
+ q5_rows = [row for row in result.variants if row.quant.lower() == "q5_k_m"]
+ assert len(q5_rows) == 1
+ assert q5_rows[0].downloaded is False
+ assert q5_rows[0].partial is True
+ assert q5_rows[0].partial_transport == "xet"
+ assert result.default_variant == "Q4_K_M"
+
+
def test_gguf_variants_scopes_partial_state_to_requested_cache(monkeypatch, tmp_path):
async def _run_inline(fn, *args, **kwargs):
return fn(*args, **kwargs)
diff --git a/studio/backend/tests/test_gguf_variant_rows.py b/studio/backend/tests/test_gguf_variant_rows.py
index 9c286fdb26a..d3112ffeaf3 100644
--- a/studio/backend/tests/test_gguf_variant_rows.py
+++ b/studio/backend/tests/test_gguf_variant_rows.py
@@ -1096,7 +1096,8 @@ def test_the_load_guard_sees_the_alias_the_delete_accepts():
def test_every_branch_derives_the_default_from_the_root_rows():
"""Remote, cached and partial-local all answer /gguf-variants, so all three have to define a
bare repo id the way _match_variant(None, ...) and local_model_resolver do -- the ROOT
- checkpoint -- or the automatic default depends on which branch served the request."""
+ checkpoint -- or the automatic default depends on which branch served the request. Cached
+ rows derive it once more after download-state reconciliation can demote the original default."""
import inspect
import types
@@ -1111,7 +1112,7 @@ def test_every_branch_derives_the_default_from_the_root_rows():
assert service._default_variant_candidates(rows[:1]) == ["distilled/model-Q6_K.gguf"]
# No branch may call pick_best_gguf on the raw filenames any more.
source = inspect.getsource(service)
- assert source.count("pick_best_gguf(_default_variant_candidates(") == 3
+ assert source.count("pick_best_gguf(_default_variant_candidates(") == 4
assert "pick_best_gguf(filenames)" not in source