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: keep distinct symlink aliases as separate local inventory rows (#10644)

Sourav Rajvifc555661f4de
diff --git a/studio/backend/hub/schemas/inventory.py b/studio/backend/hub/schemas/inventory.py
index 808ac0edcd2..292ba13afd0 100644
--- a/studio/backend/hub/schemas/inventory.py
+++ b/studio/backend/hub/schemas/inventory.py
@@ -6,7 +6,7 @@
Kept independent from upstream models/models.py so the Hub module can ship
without modifying any upstream schema."""
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, PrivateAttr
from typing import List, Literal, Optional
@@ -156,6 +156,8 @@ class LocalModelCapabilities(BaseModel):
class LocalModelInfo(BaseModel):
"""Discovered local model candidate."""
+ _scan_root: Optional[str] = PrivateAttr(None)
+
id: str = Field(..., description = "Identifier to use for loading/training")
inventory_id: Optional[str] = Field(
None, description = "Stable semantic inventory row identifier"
diff --git a/studio/backend/hub/services/models/local_inventory.py b/studio/backend/hub/services/models/local_inventory.py
index 503b238a032..b820378a037 100644
--- a/studio/backend/hub/services/models/local_inventory.py
+++ b/studio/backend/hub/services/models/local_inventory.py
@@ -8,6 +8,7 @@ from __future__ import annotations
import asyncio
import os
+import stat
from pathlib import Path
from typing import List, NamedTuple, Optional
@@ -640,6 +641,86 @@ def _inventory_physical_identity(raw_path: str) -> str:
return gguf.local_path_physical_identity(raw_path)
+_IO_REPARSE_TAG_MOUNT_POINT = getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", 0xA0000003)
+
+
+def _is_link_component(path: Path) -> bool:
+ # is_symlink() is False for a Windows junction (mklink /J needs no admin), so read the reparse tag too.
+ try:
+ st = os.lstat(path)
+ except OSError:
+ return False
+ return stat.S_ISLNK(st.st_mode) or (
+ getattr(st, "st_reparse_tag", 0) == _IO_REPARSE_TAG_MOUNT_POINT
+ )
+
+
+def _local_model_path_is_symlink(raw_path: str) -> bool:
+ path = Path(raw_path)
+ return any(_is_link_component(p) for p in (path, *path.parents))
+
+
+def _prefer_local_inventory_row(candidate: LocalModelInfo, existing: LocalModelInfo) -> bool:
+ if candidate.partial != existing.partial:
+ return not candidate.partial
+ if (candidate.active_cache is True) != (existing.active_cache is True):
+ return candidate.active_cache is True
+ candidate_link = _local_model_path_is_symlink(candidate.path)
+ existing_link = _local_model_path_is_symlink(existing.path)
+ if candidate_link != existing_link:
+ return not candidate_link
+ return _prefer_complete_larger(
+ candidate.partial,
+ candidate.size_bytes,
+ existing.partial,
+ existing.size_bytes,
+ )
+
+
+def _custom_alias_key(model: LocalModelInfo) -> str:
+ # Resolve only the scan root: two registered roots reaching one folder are one alias, links below it are not.
+ root = model._scan_root
+ if not root:
+ return model.path
+ try:
+ return os.path.join(os.path.realpath(root), os.path.relpath(model.path, root))
+ except (OSError, ValueError):
+ return model.path
+
+
+def _dedupe_custom_local_models(custom_models: List[LocalModelInfo]) -> list[LocalModelInfo]:
+ """Distinct symlink aliases of one model stay separate rows so each keeps its own settings (#10605)."""
+ by_physical: dict[tuple[str, str], list[LocalModelInfo]] = {}
+ for model in custom_models:
+ physical = _inventory_physical_identity(model.path)
+ by_physical.setdefault((physical, model.model_format), []).append(model)
+
+ kept: list[LocalModelInfo] = []
+ for group in by_physical.values():
+ by_alias_path: dict[str, list[LocalModelInfo]] = {}
+ for model in group:
+ by_alias_path.setdefault(_custom_alias_key(model), []).append(model)
+ unique_rows: list[LocalModelInfo] = []
+ for alias_group in by_alias_path.values():
+ winner = alias_group[0]
+ for candidate in alias_group[1:]:
+ if _prefer_local_inventory_row(candidate, winner):
+ winner = candidate
+ unique_rows.append(winner)
+
+ symlinks = [m for m in unique_rows if _local_model_path_is_symlink(m.path)]
+ non_symlinks = [m for m in unique_rows if not _local_model_path_is_symlink(m.path)]
+ if len(symlinks) >= 2 and not non_symlinks:
+ kept.extend(unique_rows)
+ continue
+ winner = unique_rows[0]
+ for candidate in unique_rows[1:]:
+ if _prefer_local_inventory_row(candidate, winner):
+ winner = candidate
+ kept.append(winner)
+ return kept
+
+
def _coerce_scan_folder_path(raw_path: str) -> str:
"""Normalize a scan registration target; the registry stores directories, so a pasted weight-file path is reduced to its parent folder."""
if not raw_path or not raw_path.strip():
@@ -824,7 +905,10 @@ async def _collect_models_from_default_sources(
continue
# Off the loop, like the scan above it: the probe opens directories, and on a stalled network mount scandir sits in the kernel with nothing to yield to.
await asyncio.to_thread(note_scan_folder_scanned, row_path, found = bool(custom_models))
- local_models.extend(_promote_to_custom_source(model) for model in custom_models)
+ for model in custom_models:
+ row = _promote_to_custom_source(model)
+ row._scan_root = str(folder_path)
+ local_models.append(row)
return local_models
@@ -931,7 +1015,11 @@ async def _load_custom_folders() -> list[dict]:
def _dedupe_local_models(local_models: List[LocalModelInfo]) -> list[LocalModelInfo]:
deduped: dict[str, LocalModelInfo] = {}
+ custom_models: list[LocalModelInfo] = []
for model in local_models:
+ if model.source == "custom":
+ custom_models.append(model)
+ continue
if model.source == "hf_cache" and model.model_id:
key = "\x00".join(
(
@@ -941,13 +1029,6 @@ def _dedupe_local_models(local_models: List[LocalModelInfo]) -> list[LocalModelI
model.format_variant or "",
)
)
- elif model.source == "custom":
- key = _local_inventory_id(
- "custom",
- model.model_format,
- _inventory_physical_identity(model.path),
- None,
- )
else:
row_key = model.inventory_id or model.id
key = row_key
@@ -968,7 +1049,7 @@ def _dedupe_local_models(local_models: List[LocalModelInfo]) -> list[LocalModelI
if prefer_candidate:
deduped[key] = model
- deduped_values = list(deduped.values())
+ deduped_values = list(deduped.values()) + _dedupe_custom_local_models(custom_models)
custom_values = [model for model in deduped_values if model.source == "custom"]
return sorted(
[model for model in deduped_values if model.source != "custom"]
diff --git a/studio/backend/hub/tests/conftest.py b/studio/backend/hub/tests/conftest.py
index 9ca16fc35bf..e1663847e16 100644
--- a/studio/backend/hub/tests/conftest.py
+++ b/studio/backend/hub/tests/conftest.py
@@ -95,6 +95,7 @@ _stub_unless_installed(
types.SimpleNamespace(
BaseModel = _BaseModel,
Field = _field,
+ PrivateAttr = _field,
model_validator = _model_validator,
),
)
diff --git a/studio/backend/hub/tests/test_custom_gguf_discovery.py b/studio/backend/hub/tests/test_custom_gguf_discovery.py
index 54b9aea7f87..5f926b2eebf 100644
--- a/studio/backend/hub/tests/test_custom_gguf_discovery.py
+++ b/studio/backend/hub/tests/test_custom_gguf_discovery.py
@@ -31,10 +31,10 @@ def _write_gguf(path: Path, size: int = 4) -> Path:
def _custom_rows(*roots: Path):
rows = []
for root in roots:
- rows.extend(
- local_inventory._promote_to_custom_source(row)
- for row in local_inventory._scan_custom_folder(root)
- )
+ for row in local_inventory._scan_custom_folder(root):
+ row = local_inventory._promote_to_custom_source(row)
+ row._scan_root = str(root)
+ rows.append(row)
return local_inventory._dedupe_local_models(rows)
@@ -594,6 +594,53 @@ def test_symlinked_model_directory_stays_grouped(tmp_path):
assert [Path(row.path) for row in _custom_rows(root)] == [alias]
+def test_two_symlink_aliases_to_one_model_stay_distinct(tmp_path):
+ real_model = tmp_path / "outside" / "model"
+ _write_gguf(real_model / "model-Q4_K_M.gguf")
+ _write_gguf(real_model / "model-Q8_0.gguf")
+ root = tmp_path / "root"
+ root.mkdir()
+ alias_a = root / "alias-a"
+ alias_b = root / "alias-b"
+ _symlink_dir(alias_a, real_model)
+ _symlink_dir(alias_b, real_model)
+
+ rows = _custom_rows(root)
+
+ assert {Path(row.path) for row in rows} == {alias_a, alias_b}
+ assert {row.load_id for row in rows} == {str(alias_a), str(alias_b)}
+
+
[email protected](os.name != "nt", reason = "directory junctions exist only on Windows")
+def test_two_junction_aliases_to_one_model_stay_distinct(tmp_path):
+ import _winapi
+
+ real_model = tmp_path / "outside" / "model"
+ _write_gguf(real_model / "model-Q4_K_M.gguf")
+ _write_gguf(real_model / "model-Q8_0.gguf")
+ root = tmp_path / "root"
+ root.mkdir()
+ alias_a = root / "alias-a"
+ alias_b = root / "alias-b"
+ _winapi.CreateJunction(str(real_model), str(alias_a))
+ _winapi.CreateJunction(str(real_model), str(alias_b))
+
+ assert {Path(row.path) for row in _custom_rows(root)} == {alias_a, alias_b}
+
+
+def test_two_symlinked_scan_roots_to_one_folder_list_the_model_once(tmp_path):
+ real_root = tmp_path / "real"
+ _write_gguf(real_root / "model" / "model-Q4_K_M.gguf")
+ _write_gguf(real_root / "model" / "model-Q8_0.gguf")
+ link_a = tmp_path / "link-a"
+ link_b = tmp_path / "link-b"
+ _symlink_dir(link_a, real_root)
+ _symlink_dir(link_b, real_root)
+
+ assert len(_custom_rows(link_a, link_b)) == 1
+ assert len(_custom_rows(real_root, link_a)) == 1
+
+
def test_physical_identity_preserves_native_posix_names(tmp_path):
if os.sep == "\\":
pytest.skip("names are not distinct on Windows")
diff --git a/studio/backend/hub/tests/test_model_services.py b/studio/backend/hub/tests/test_model_services.py
index c9e925d0f4e..a1993f4dfcd 100644
--- a/studio/backend/hub/tests/test_model_services.py
+++ b/studio/backend/hub/tests/test_model_services.py
@@ -715,6 +715,69 @@ def test_local_inventory_prefers_active_cache_when_copies_are_equally_complete(t
assert local_inventory._dedupe_local_models([previous, active]) == [active]
+def _custom_gguf_row(
+ tmp_path: Path,
+ *,
+ load_path: Path,
+ size_bytes: int = 10,
+):
+ return model_common._local_model_info(
+ scan_path = load_path,
+ load_path = load_path,
+ source = "custom",
+ model_format = "gguf",
+ size_bytes = size_bytes,
+ )
+
+
+def test_custom_dedupe_overlapping_symlink_scans_collapse_to_one_row(tmp_path):
+ target = tmp_path / "weights"
+ target.mkdir()
+ gguf_file = target / "model.gguf"
+ gguf_file.write_bytes(b"x" * 10)
+ scan_root = tmp_path / "scan-link"
+ try:
+ scan_root.symlink_to(target, target_is_directory = True)
+ except OSError as error:
+ pytest.skip(f"symlink creation unavailable: {error}")
+ row = _custom_gguf_row(tmp_path, load_path = scan_root / "model.gguf")
+ assert local_inventory._dedupe_custom_local_models([row, row]) == [row]
+
+
+def test_custom_dedupe_collapses_duplicate_scanner_rows_for_one_symlink_alias(tmp_path):
+ target = tmp_path / "weights"
+ target.mkdir()
+ (target / "model.gguf").write_bytes(b"x" * 10)
+ alias = tmp_path / "alias"
+ try:
+ alias.symlink_to(target, target_is_directory = True)
+ except OSError as error:
+ pytest.skip(f"symlink creation unavailable: {error}")
+ row = _custom_gguf_row(tmp_path, load_path = alias / "model.gguf")
+ duplicate = _custom_gguf_row(tmp_path, load_path = alias / "model.gguf", size_bytes = 20)
+ result = local_inventory._dedupe_custom_local_models([row, duplicate])
+ assert len(result) == 1
+ assert result[0].size_bytes == 20
+
+
+def test_custom_dedupe_distinct_symlink_aliases_stay_separate_rows(tmp_path):
+ target = tmp_path / "weights"
+ target.mkdir()
+ (target / "model.gguf").write_bytes(b"x" * 10)
+ alias_a = tmp_path / "alias-a"
+ alias_b = tmp_path / "alias-b"
+ try:
+ alias_a.symlink_to(target, target_is_directory = True)
+ alias_b.symlink_to(target, target_is_directory = True)
+ except OSError as error:
+ pytest.skip(f"symlink creation unavailable: {error}")
+ row_a = _custom_gguf_row(tmp_path, load_path = alias_a / "model.gguf")
+ row_b = _custom_gguf_row(tmp_path, load_path = alias_b / "model.gguf")
+ result = local_inventory._dedupe_custom_local_models([row_a, row_b])
+ assert len(result) == 2
+ assert {r.path for r in result} == {row_a.path, row_b.path}
+
+
def test_loaded_repo_match_accepts_previous_cache_snapshot_path(monkeypatch, tmp_path):
repo_dir = tmp_path / "old-hub" / "models--Org--Model"
snapshot = repo_dir / "snapshots" / "revision"
diff --git a/studio/frontend/tests/model-identity.test.ts b/studio/frontend/tests/model-identity.test.ts
index f8b81d2f1a6..050437524db 100644
--- a/studio/frontend/tests/model-identity.test.ts
+++ b/studio/frontend/tests/model-identity.test.ts
@@ -272,6 +272,26 @@ test("a POSIX path is case sensitive, so its two spellings stay separate", () =>
);
});
+test("symlink alias paths keep independent remembered settings", () => {
+ store.clear();
+ savePerModelConfig("/models/alias-a", "Q4_K_M", config(4096));
+ savePerModelConfig("/models/alias-b", "Q4_K_M", config(32768, "q8_0"));
+
+ assert.equal(storedKeys().length, 2);
+ assert.equal(
+ resolveInitialConfig("/models/alias-a", "Q4_K_M").config.maxSeqLength,
+ 4096,
+ );
+ assert.equal(
+ resolveInitialConfig("/models/alias-b", "Q4_K_M").config.maxSeqLength,
+ 32768,
+ );
+ assert.equal(
+ resolveInitialConfig("/models/alias-b", "Q4_K_M").config.kvCacheDtype,
+ "q8_0",
+ );
+});
+
// Every answer below is the backend's split_quant_suffix. The backfill folds a stored key with
// this before comparing, so a disagreement collapses two models onto one key.
const CASES: [string, [string, string] | null][] = [