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: fetch every image component from unsloth repos (#14008)

Daniel Hana6da154b302a
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 42b90988391..6ffef0a0d43 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -30,7 +30,7 @@ import sys
import threading
import time
import traceback
-from dataclasses import dataclass, replace
+from dataclasses import dataclass, field, replace
from pathlib import Path
from typing import Any, Callable, Mapping, Optional, Sequence
@@ -77,6 +77,7 @@ from .diffusion_families import (
detect_family_for_pick,
excluded_model_reason,
prefer_ungated_mirror,
+ mirror_hosts_artifacts,
prequant_only_repo_ids,
prequant_repo_role,
resolve_base_repo,
@@ -435,6 +436,85 @@ def _record_revision(out: Optional[dict[str, str]], repo_id: str, info: Any) ->
out[repo_id] = sha
+def _planned_progress_files(
+ repo_id: str,
+ gguf_filename: Optional[str],
+ *,
+ kind: str,
+ base: str,
+ fetch_base: str,
+ base_files: Sequence[str],
+ file_sizes: dict[str, dict[str, int]],
+ dit_prequant: Optional[tuple[str, str, int]] = None,
+ te_hub_files: Sequence[tuple[str, str, int]] = (),
+) -> tuple[tuple[str, str, int], ...]:
+ """``(repo, filename, size)`` for every file a diffusers load downloads, keyed by the repo the bytes LAND in: the
+ selected checkpoint, the base files under the repo they are fetched from, the hosted prequant denoiser and the
+ pre-cast encoders. One file named twice (a combined repo, a prequant in the companion repo) is listed once. The
+ single source of a load's expected_bytes and of the progress scan."""
+ out: dict[tuple[str, str], tuple[str, str, int]] = {}
+
+ def add(repo: Optional[str], name: Optional[str], size: Any) -> None:
+ if not repo or not name or _is_local_path(repo):
+ return
+ out.setdefault((repo.lower(), name), (repo, name, int(size or 0)))
+
+ if kind != "pipeline" and gguf_filename:
+ add(repo_id, gguf_filename, (file_sizes.get(repo_id) or {}).get(gguf_filename, 0))
+ base_sizes = (
+ file_sizes.get(base) or file_sizes.get(repo_id if kind == "pipeline" else base) or {}
+ )
+ for name in base_files:
+ add(fetch_base or base, name, base_sizes.get(name, 0))
+ if dit_prequant is not None:
+ add(dit_prequant[0], dit_prequant[1], dit_prequant[2])
+ for repo, name, size in te_hub_files:
+ add(repo, name, size)
+ return tuple(out.values())
+
+
+def _sibling_blob_key(sibling: Any) -> Optional[str]:
+ """The name huggingface_hub gives this file's blob (and its ``<key>.incomplete`` while downloading): the LFS
+ sha256 for an LFS file, else the git blob id. None when the listing did not say."""
+ lfs = getattr(sibling, "lfs", None)
+ sha = (
+ (lfs.get("sha256") if isinstance(lfs, dict) else getattr(lfs, "sha256", None))
+ if lfs
+ else None
+ )
+ key = sha or getattr(sibling, "blob_id", None)
+ return str(key) if key else None
+
+
+def _planned_blob_keys(
+ planned: Sequence[tuple[str, str, int]],
+ file_keys: dict[str, dict[str, str]],
+ *,
+ repo_id: str,
+ base: str,
+ fetch_base: str,
+) -> dict[tuple[str, str], str]:
+ """Blob keys for ``planned``, read off the listing that sized each file (the checkpoint under ``repo_id``, the
+ base files under ``base`` while they land in ``fetch_base``). A file with no key is left out."""
+ out: dict[tuple[str, str], str] = {}
+ for repo, name, _size in planned:
+ for source in dict.fromkeys((repo, repo_id, base) if repo == fetch_base else (repo,)):
+ key = (file_keys.get(source) or {}).get(name)
+ if key:
+ out[(repo.lower(), name)] = key
+ break
+ return out
+
+
+def _listing_extra(listing_repo: str, rfilename: str) -> bool:
+ """A file an artifact mirror ships beside the upstream folders that no pipeline load reads (its sample renders);
+ the root checkpoints are already excluded by every listing filter's top-level rule."""
+ return mirror_hosts_artifacts(listing_repo) and rfilename.split("/", 1)[0] in (
+ "samples",
+ "assets",
+ )
+
+
def hub_cache_dir() -> str:
"""The cache root every loader call must be pinned to. diffusers resolves an unset cache_dir
through huggingface_hub's import-time constant, which a mid-session cache-folder change does
@@ -1287,6 +1367,20 @@ class _LoadingState:
# ONE named file: the scan counts what this load adds, not every byte already in the repo.
asset_files: tuple[tuple[str, str, int, int], ...] = ()
account_id: Optional[str] = None
+ # The single file this load reads from ``repo_id``, so progress through an artifact mirror counts that one
+ # checkpoint rather than every sibling quant cached beside it.
+ gguf_filename: Optional[str] = None
+ # ``(repo, filename, size)`` for every file this load downloads, from ``_planned_progress_files``: the ONE answer
+ # to "which files of which repos does this load count", which expected_bytes is the sum of and load_progress
+ # scans. Empty when the size estimate failed; load_progress then keeps its repo-level scan.
+ planned_files: tuple[tuple[str, str, int], ...] = ()
+ # ``{incomplete blob path: size}`` in the planned repos when this load claimed them: a cancelled sibling download
+ # leaves ``*.incomplete`` blobs behind, and only growth past this snapshot is this load's own bytes.
+ incomplete_baseline: dict[str, int] = field(default_factory = dict)
+ # ``{(repo_lower, filename): blob key}`` for the planned files whose listing named one. huggingface_hub writes a
+ # download to ``blobs/<key>.incomplete``, so an in-flight blob with a planned key IS that file, resumed bytes
+ # included, and every other ``.incomplete`` (a cancelled sibling's) is ignored outright.
+ planned_blob_keys: dict[tuple[str, str], str] = field(default_factory = dict)
# (expected_bytes, downloaded) once every expected byte was on disk.
finalized_scan: Optional[tuple[int, int]] = None
@@ -3711,6 +3805,9 @@ class DiffusionBackend:
and not _is_local_path(repo_id)
):
bases, schemes, te_schemes = prequant_repo_role(fam, repo_id)
+ if not bases and mirror_hosts_artifacts(repo_id):
+ # An artifact mirror: its folders are its base's pipeline, so name that base, not the family default.
+ bases = (canonical_base(repo_id),)
shown = " or ".join(bases) or fam.base_repo
knobs = []
if schemes:
@@ -3718,9 +3815,8 @@ class DiffusionBackend:
if te_schemes:
knobs.append(f"the text encoder precision to {' or '.join(te_schemes)}")
raise ValueError(
- f"'{repo_id}' hosts pre-quantised checkpoints for {shown} and is not a diffusers pipeline "
- f"(it has no model_index.json). Pick {shown} and set {' and '.join(knobs) or 'a precision'} "
- f"instead."
+ f"'{repo_id}' hosts pre-quantised checkpoints for {shown}; it is not a pipeline to pick "
+ f"directly. Pick {shown} and set {' and '.join(knobs) or 'a precision'} instead."
)
# Refuse a too-old diffusers here, not deep in the load, but only when this load builds the diffusers
# pipeline: a GGUF this host routes to native sd.cpp never instantiates the class. The picker gate reads the
@@ -3971,7 +4067,10 @@ class DiffusionBackend:
self._cancel_event = cancel_event
# Seed with the family fallback; the worker resolves the real base and updates this.
self._loading = _LoadingState(
- repo_id = repo_id, base_repo = fam.base_repo, account_id = current_account_id()
+ repo_id = repo_id,
+ base_repo = fam.base_repo,
+ account_id = current_account_id(),
+ gguf_filename = gguf_filename,
)
account_thread(
@@ -4151,6 +4250,8 @@ class DiffusionBackend:
resident_sizes: list[tuple[str, int]] = []
skipped_transformer_files: list[str] = []
fetch_repos: dict[str, str] = {}
+ planned_sizes: dict[str, dict[str, int]] = {}
+ planned_keys: dict[str, dict[str, str]] = {}
expected, base_files = self._estimate_download_bytes(
kwargs["repo_id"],
kwargs.get("gguf_filename"),
@@ -4179,6 +4280,8 @@ class DiffusionBackend:
local_files_only = local_files_only,
resident_file_sizes_out = resident_sizes,
fetch_repos_out = fetch_repos,
+ file_sizes_out = planned_sizes,
+ file_keys_out = planned_keys,
)
# An OPERATOR'S OWN checkpoint has no Hub entry, so the plan drops no shards and the seed costs no bytes.
# Suppressing it would ignore the file the load was asked to use and quantise the released bf16 shards in
@@ -4284,10 +4387,36 @@ class DiffusionBackend:
raise RuntimeError(shortfall)
# Outside the lock: a disk scan, and nothing of ours has written to the artifact repo yet.
asset_baseline = self._cache_bytes(dit_prequant[0]) if skip_transformer_weights else 0
+ planned_files = _planned_progress_files(
+ kwargs["repo_id"],
+ kwargs.get("gguf_filename"),
+ kind = kind,
+ base = base,
+ fetch_base = fetch_base,
+ base_files = base_files,
+ file_sizes = planned_sizes,
+ dit_prequant = dit_prequant,
+ te_hub_files = te_hub_files,
+ )
with self._load_cancel_lock:
if self._load_token == token and self._loading is not None:
self._loading.base_repo = base
self._loading.fetch_repo = fetch_base
+ # One list for both numbers, so they cannot disagree. Used only when it accounts for the whole
+ # estimate: a total that came back without per-file sizes keeps the repo-level scan.
+ planned_total = sum(size for _r, _n, size in planned_files)
+ if planned_total and planned_total == expected:
+ self._loading.planned_files = planned_files
+ self._loading.planned_blob_keys = _planned_blob_keys(
+ planned_files,
+ planned_keys,
+ repo_id = kwargs["repo_id"],
+ base = base,
+ fetch_base = fetch_base,
+ )
+ self._loading.incomplete_baseline = self._incomplete_blob_sizes(
+ {repo for repo, _n, _s in planned_files}
+ )
self._loading.expected_bytes = expected
if skip_transformer_weights:
# Claimed before a byte moves. File entry first: load_progress reads lock-free.
@@ -4403,18 +4532,41 @@ class DiffusionBackend:
# Nothing left to download: another tree walk only holds the GIL the load thread needs.
return _progress("finalizing", finalized[1], finalized[0], 1.0)
+ if loading.planned_files and sum(size for _r, _n, size in loading.planned_files) > 0:
+ downloaded = DiffusionBackend._planned_progress_bytes(
+ loading.planned_files, loading.incomplete_baseline, loading.planned_blob_keys
+ )
+ return DiffusionBackend._progress_from(loading, downloaded)
# Sum checkpoint + companion cache, scanning the repo the bytes LAND in (the mirror when one was swapped in),
# else a mirrored companion download reads as zero and the bar sits still.
companion = loading.fetch_repo or loading.base_repo
+
+ def _companion_progress_bytes(repo_id: str) -> int:
+ # An artifact mirror (``mirror_hosts_artifacts``) also holds root GGUF / prequant checkpoints the plan
+ # never counted, so only its diffusers part is scanned, plus the in-flight blobs (this load's own
+ # pipeline files). Every other repo is scanned exactly as before.
+ if mirror_hosts_artifacts(repo_id):
+ return self._cache_bytes(repo_id, pipeline_only = True, in_flight = True)
+ return self._cache_bytes(repo_id)
+
if loading.base_repo and loading.base_repo == loading.repo_id:
# Full pipeline: base IS the repo, so count it once. Summing would add the upstream's stale partial blobs,
# the very thing that selects the mirror, to the mirror's live bytes, pushing the bar to 100% / finalizing
# mid-download.
- downloaded = self._cache_bytes(companion or loading.repo_id)
+ downloaded = _companion_progress_bytes(companion or loading.repo_id)
+ elif loading.gguf_filename and mirror_hosts_artifacts(loading.repo_id):
+ # A GGUF picked straight from an artifact mirror: the repo is also the companion, and also holds sibling
+ # quants and sample renders the plan never counted. The selected file, the pipeline folders and the
+ # in-flight blobs are what this load downloads.
+ downloaded = self._cache_file_bytes(
+ loading.repo_id, loading.gguf_filename
+ ) + _companion_progress_bytes(loading.repo_id)
+ if companion and companion.lower() != loading.repo_id.lower():
+ downloaded += _companion_progress_bytes(companion)
else:
downloaded = self._cache_bytes(loading.repo_id)
if companion and companion != loading.repo_id:
- downloaded += self._cache_bytes(companion)
+ downloaded += _companion_progress_bytes(companion)
# Repos read before files (_run_load stores files first), so every repo seen has its file entry.
asset_repos = loading.asset_repos
asset_files = loading.asset_files
@@ -4431,6 +4583,10 @@ class DiffusionBackend:
size,
self._cache_file_bytes(repo, filename) + max(0, self._cache_bytes(repo) - baseline),
)
+ return DiffusionBackend._progress_from(loading, downloaded)
+
+ @staticmethod
+ def _progress_from(loading: "_LoadingState", downloaded: int) -> dict[str, Any]:
expected = loading.expected_bytes
# Downloads done, still finalizing. The cache scan can exceed the estimate, so clamp to 100%.
if expected > 0 and downloaded >= expected * 0.999:
@@ -4999,6 +5155,7 @@ class DiffusionBackend:
resident_file_sizes_out: Optional[list[tuple[str, int]]] = None,
revisions_out: Optional[dict[str, str]] = None,
fetch_repos_out: Optional[dict[str, str]] = None,
+ file_keys_out: Optional[dict[str, dict[str, str]]] = None,
skip_te_components: tuple[str, ...] = (),
skip_transformer_weights: bool = False,
skipped_files_out: Optional[list[str]] = None,
@@ -5036,8 +5193,9 @@ class DiffusionBackend:
return 0, []
from huggingface_hub import HfApi
- # No swap on purpose: the Hub gates only the BYTE endpoint, so model_info answers anonymously and the mirror
- # lists the same names. _prefetch_files swaps when it pulls.
+ # Metadata comes from the repo the bytes will: the base's unsloth mirror unless the upstream already holds
+ # them (prefer_ungated_mirror), so a fresh install asks the vendor nothing, and a cached upstream keeps the
+ # listing and the commit pin its cache probe needs.
from .diffusion_te_prequant import is_prequant_covered_weight
api = HfApi()
@@ -5099,11 +5257,13 @@ class DiffusionBackend:
# model_index.json would never find a cached upstream and restage the mirror.
metadata_repo = prefer_ungated_mirror(repo_id, hf_token, files = (base_manifest,))
info, components, picked = _pipeline_listing(metadata_repo)
+ picked = [s for s in picked if not _listing_extra(metadata_repo, s.rfilename)]
base_files = [s.rfilename for s in picked]
fetch_repo = prefer_ungated_mirror(repo_id, hf_token, files = base_files)
if fetch_repo.lower() != metadata_repo.lower():
metadata_repo = fetch_repo
info, components, picked = _pipeline_listing(metadata_repo)
+ picked = [s for s in picked if not _listing_extra(metadata_repo, s.rfilename)]
base_files = [s.rfilename for s in picked]
total = sum(s.size or 0 for s in picked)
if fetch_repos_out is not None:
@@ -5112,6 +5272,10 @@ class DiffusionBackend:
sizes_out[repo_id] = total
if file_sizes_out is not None:
file_sizes_out[repo_id] = {s.rfilename: int(s.size or 0) for s in picked}
+ if file_keys_out is not None:
+ file_keys_out[repo_id] = {
+ s.rfilename: k for s in picked if (k := _sibling_blob_key(s))
+ }
if resident_file_sizes_out is not None and components is not None:
resident_file_sizes_out.extend(
(s.rfilename, int(s.size or 0))
@@ -5132,6 +5296,12 @@ class DiffusionBackend:
for s in info.siblings
if s.rfilename == gguf_filename
}
+ if file_keys_out is not None:
+ file_keys_out[repo_id] = {
+ s.rfilename: k
+ for s in info.siblings
+ if s.rfilename == gguf_filename and (k := _sibling_blob_key(s))
+ }
_record_revision(revisions_out, repo_id, info)
# A whole-pipeline single file (SDXL, or its GGUF) needs only the base's config/tokenizer, not its weights.
if kind in ("single_file", "gguf") and single_file_is_pipeline:
@@ -5151,18 +5321,33 @@ class DiffusionBackend:
rfilename, include_transformer = include_transformer, manifest = base_manifest
)
- # FLUX.3's mirror is its FP8 repo, whose companion folders are BFL's byte for byte and whose extra root
- # files base_filter never stages, so the listing comes from the repo the prefetch pulls: an anonymous
- # load then never asks the gated vendor repo anything. Its revision is the mirror's, recorded under it.
- listing_repo = (
- prefer_ungated_mirror(base_repo, hf_token)
- if companion_components is not None
- else base_repo
- )
- base_info = api.model_info(listing_repo, files_metadata = True, token = hf_token)
- _record_revision(revisions_out, listing_repo, base_info)
+ def _base_listing(listing_repo: str) -> list[Any]:
+ info = api.model_info(listing_repo, files_metadata = True, token = hf_token)
+ # Under the repo it describes: a mirror's commit says nothing about a cached upstream snapshot.
+ _record_revision(revisions_out, listing_repo, info)
+ return [s for s in info.siblings if not _listing_extra(listing_repo, s.rfilename)]
+
+ listing_repo = prefer_ungated_mirror(base_repo, hf_token)
+ base_siblings = _base_listing(listing_repo)
+ # Same two-step choice as the pipeline listing above: "any weight cached" picks the listing repo, the exact
+ # companion set then picks the repo they come from, and a different answer re-lists from that repo. The
+ # plan still takes its own fetch decision from the final file list. FLUX.3's mirror is its FP8 repo, whose
+ # companion folders are BFL's byte for byte and whose extra root files base_filter never stages, so its
+ # listing stays on the repo the prefetch pulls: an anonymous load never asks the gated vendor repo anything.
+ if companion_components is None:
+ wanted = [
+ s.rfilename
+ for s in base_siblings
+ if _base_file_downloaded(
+ s.rfilename, include_transformer = False, manifest = base_manifest
+ )
+ ]
+ fetch_repo = prefer_ungated_mirror(base_repo, hf_token, files = wanted)
+ if fetch_repo.lower() != listing_repo.lower():
+ listing_repo = fetch_repo
+ base_siblings = _base_listing(listing_repo)
if callable(include_transformer):
- kept = [s.rfilename for s in base_info.siblings if not _dense_te_shard(s.rfilename)]
+ kept = [s.rfilename for s in base_siblings if not _dense_te_shard(s.rfilename)]
companions = tuple(
f
for f in kept
@@ -5184,15 +5369,32 @@ class DiffusionBackend:
)
# Rebinding before base_filter is ever CALLED, so the loop below reads the answer.
include_transformer = bool(include_transformer(companions, transformer_files))
+ # The mirror choice above saw only the companions. Once the verdict may have widened the set to the dense
+ # transformer shards, decide again on the FINAL list: a gated upstream holding the companions but not the
+ # shards must not stay the fetch repo, or the shards 401 for an anonymous user. Recorded for the plan and
+ # the load, which stage and read from this one answer.
+ final_files = [
+ s.rfilename
+ for s in base_siblings
+ if base_filter(s.rfilename) and not _dense_te_shard(s.rfilename)
+ ]
+ final_repo = prefer_ungated_mirror(base_repo, hf_token, files = final_files)
+ if final_repo.lower() != listing_repo.lower():
+ listing_repo = final_repo
+ base_siblings = _base_listing(listing_repo)
+ if fetch_repos_out is not None and not _is_local_path(base_repo):
+ fetch_repos_out.setdefault(base_repo, listing_repo)
# Do not stage a combined repo's checkpoint again as a companion.
counted = {gguf_filename} if base_repo == repo_id and gguf_filename else set()
base_bytes = 0
base_sizes: dict[str, int] = {}
- for s in base_info.siblings:
+ for s in base_siblings:
if not base_filter(s.rfilename) or _dense_te_shard(s.rfilename):
continue
if s.rfilename in counted:
continue
+ if file_keys_out is not None and (k := _sibling_blob_key(s)):
+ file_keys_out.setdefault(base_repo, {})[s.rfilename] = k
base_files.append(s.rfilename)
base_bytes += s.size or 0
base_sizes[s.rfilename] = int(s.size or 0)
@@ -5203,7 +5405,6 @@ class DiffusionBackend:
sizes_out[base_repo] = sizes_out.get(base_repo, 0) + base_bytes
if file_sizes_out is not None:
file_sizes_out.setdefault(base_repo, {}).update(base_sizes)
- _record_revision(revisions_out, listing_repo, base_info)
except Exception as exc: # noqa: BLE001 - estimate is best-effort
logger.warning("diffusion.size_estimate_failed: %s", exc)
# Recorded so a caller that must not guess (media auto-switch refuses rather than download) can tell a
@@ -5890,7 +6091,70 @@ class DiffusionBackend:
return best
@staticmethod
- def _cache_bytes(repo_id: str) -> int:
+ def _incomplete_blob_sizes(repos) -> dict[str, int]:
+ """``{path: size}`` of every ``blobs/*.incomplete`` of ``repos`` across cache roots. Never raises."""
+ out: dict[str, int] = {}
+ for repo in repos:
+ for repo_dir in DiffusionBackend._hub_cache_repo_dirs(repo):
+ try:
+ for entry in (repo_dir / "blobs").iterdir():
+ if entry.name.endswith(".incomplete"):
+ out[str(entry)] = entry.stat().st_size
+ except OSError:
+ continue
+ return out
+
+ @staticmethod
+ def _planned_progress_bytes(
+ planned: Sequence[tuple[str, str, int]],
+ baseline: Optional[dict[str, int]] = None,
+ blob_keys: Optional[dict[tuple[str, str], str]] = None,
+ ) -> int:
+ """Bytes on disk of exactly the files ``_planned_progress_files`` chose. Each finished file counts up to its
+ planned size (its largest copy across cache roots); a repo's ``*.incomplete`` blobs are the file it is
+ writing right now, capped so the repo never counts more than its planned files. Sibling quants, sample
+ renders, root checkpoints and other schemes already in the same repo are simply not in the list."""
+ by_repo: dict[str, list[tuple[str, int]]] = {}
+ for repo, name, size in planned:
+ by_repo.setdefault(repo, []).append((name, int(size or 0)))
+ total = 0
+ for repo, files in by_repo.items():
+ planned_total = sum(size for _n, size in files)
+ done_by_file = {
+ name: (min(size, DiffusionBackend._cache_file_bytes(repo, name)) if size else 0)
+ for name, size in files
+ }
+ # A planned file's in-flight blob is ``<its blob key>.incomplete``: counted in full (resumed bytes are
+ # this file's), up to what the file still lacks. Any other ``.incomplete`` belongs to some other download
+ # and is ignored, unless a planned file's key is unknown: only then does growth past the load's baseline
+ # stand in for it.
+ remaining_by_key: dict[str, int] = {}
+ unkeyed = False
+ for name, size in files:
+ key = (blob_keys or {}).get((repo.lower(), name))
+ if key:
+ remaining_by_key[key] = remaining_by_key.get(key, 0) + max(
+ 0, size - done_by_file[name]
+ )
+ elif size:
+ unkeyed = True
+ in_flight = 0
+ for path, size in DiffusionBackend._incomplete_blob_sizes((repo,)).items():
+ stem = Path(path).name[: -len(".incomplete")]
+ if stem in remaining_by_key:
+ in_flight += min(size, remaining_by_key[stem])
+ elif unkeyed:
+ in_flight += max(0, size - (baseline or {}).get(path, 0))
+ total += min(planned_total, sum(done_by_file.values()) + in_flight)
+ return total
+
+ @staticmethod
+ def _cache_bytes(
+ repo_id: str,
+ *,
+ pipeline_only: bool = False,
+ in_flight: bool = False,
+ ) -> int:
"""Bytes of ``repo_id`` on disk across every cache root, for progress and the pipeline plan.
Scoped per root to the revision that root serves (``refs/main``), because ``blobs/`` is
@@ -5899,6 +6163,11 @@ class DiffusionBackend:
partial one and ``load_progress`` reports finalizing through the rest of a multi-GB pull.
The in-flight ``blobs/*.incomplete`` still counts: those are this download's own bytes.
+ ``pipeline_only`` counts just the diffusers part of the snapshot (``model_index.json`` and the component
+ folders), for a repo that also carries root GGUF / prequant checkpoints the pipeline never reads. Blobs
+ that cannot be attributed to a path are left out there, unless ``in_flight`` asks for the
+ ``*.incomplete`` ones: a load's progress counts what it is downloading right now.
+
Keyed by blob filename, not summed per root: a blob is named after the file's etag, so a
copy present in both roots counts once. Scanning only the live root reports 0 for a load a
moved cache serves entirely off disk.
@@ -5919,16 +6188,25 @@ class DiffusionBackend:
except OSError:
blobs = [] # repo not in this root yet / unreadable / no-symlink cache mode
if snapshot is None:
- for entry in blobs:
- _add(entry.name, entry)
+ if not pipeline_only:
+ for entry in blobs:
+ _add(entry.name, entry)
continue
- for entry in blobs:
- if entry.name.endswith(".incomplete"):
- _add(entry.name, entry)
+ if not pipeline_only or in_flight:
+ for entry in blobs:
+ if entry.name.endswith(".incomplete"):
+ _add(entry.name, entry)
try:
for f in snapshot.rglob("*"):
if not f.is_file():
continue
+ if pipeline_only:
+ rel = f.relative_to(snapshot).as_posix()
+ if "/" not in rel and rel != "model_index.json":
+ continue
+ # The same predicate the plan's listing drops these with, so the two cannot drift.
+ if _listing_extra(repo_id, rel):
+ continue
# Dedupe on the path INSIDE the snapshot, so one logical file counts once however many roots hold
# it. The etag would not: each root serves its own revision, so a republished file summed both
# copies and could report finalizing at half the real progress. Works for a no-symlink cache too,
@@ -10258,7 +10536,9 @@ class DiffusionBackend:
self._local_dir_weight_bytes(staged_repo, exclude_transformer = False)
if staged_repo is not None and staged_repo.is_dir()
else 0,
- self._cache_bytes(cache_repo) if cache_repo else 0,
+ self._cache_bytes(cache_repo, pipeline_only = mirror_hosts_artifacts(cache_repo))
+ if cache_repo
+ else 0,
)
if load_dtype is not None:
# Cached bytes are what the repo STORES, not what the load holds at this dtype.
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index 463eb4ff1ef..acbdad30e20 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -302,6 +302,24 @@ _HIDREAM_BF16_WHEN_RESIDENT = (
"INT8 is barely faster than compiled bf16 on a card that holds bf16 and changes image detail"
)
+# FLUX.1's sd-cli encoders are BFL's own diffusers files, read as-is: sd.cpp loads the CLIP-L text_encoder and the
+# sharded T5 through its index (the shards sit beside it in the snapshot). The shards are listed so every fetch,
+# size and cache probe sees them as plain files; ``*_shard`` kinds are fetched but never handed to sd-cli. dev, Krea
+# and Kontext reuse schnell's files, as they shared one repack before.
+_FLUX1_SD_CPP_TEXT_ENCODERS: tuple[tuple[str, str, str], ...] = (
+ ("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors", "clip_l"),
+ ("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model.safetensors.index.json", "t5xxl"),
+ (
+ "black-forest-labs/FLUX.1-schnell",
+ "text_encoder_2/model-00001-of-00002.safetensors",
+ "t5xxl_shard",
+ ),
+ (
+ "black-forest-labs/FLUX.1-schnell",
+ "text_encoder_2/model-00002-of-00002.safetensors",
+ "t5xxl_shard",
+ ),
+)
# FLUX.3 Klein's encoder is Qwen3-VL-4B-Instruct (byte-identical), read by sd.cpp through --llm with hidden states 4..32.
# References go through the VAE, not the vision tower, so editing needs no projector. Q8_0 rather than Q4_K_M: the
# encoder quant dominates the error here. Against a BF16 DiT + BF16 encoder render (sd.cpp, 4 prompts, 1024, same
@@ -378,11 +396,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
controlnet_pipeline_class = "FluxControlNetPipeline",
controlnet_model_class = "FluxControlNetModel",
sd_cpp_vae = ("black-forest-labs/FLUX.1-schnell", "ae.safetensors"),
- # Byte-identical mirror of comfyanonymous/flux_text_encoders (CLIP-L + T5-XXL fp16).
- sd_cpp_text_encoders = (
- ("unsloth/flux-text-encoders", "clip_l.safetensors", "clip_l"),
- ("unsloth/flux-text-encoders", "t5xxl_fp16.safetensors", "t5xxl"),
- ),
+ sd_cpp_text_encoders = _FLUX1_SD_CPP_TEXT_ENCODERS,
),
# FLUX.2-klein is Flux2KleinPipeline (Qwen3 encoder), not the Mistral Flux2Pipeline, so it must precede a generic
# flux match.
@@ -436,15 +450,13 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
inpaint_pipeline_class = "Flux2KleinInpaintPipeline",
# FLUX.2 scales >1MP inputs to ~1MP, so outpaint can't grow.
inpaint_preserves_size = False,
- sd_cpp_vae = ("unsloth/FLUX.2-VAE", "split_files/vae/flux2-vae.safetensors"),
+ # BFL's own diffusers VAE file, byte-identical to the single-file repack this used to name.
+ sd_cpp_vae = ("black-forest-labs/FLUX.2-dev", "vae/diffusion_pytorch_model.safetensors"),
sd_cpp_vae_format = "flux2",
- sd_cpp_text_encoders = (
- (
- "unsloth/Z-Image-Turbo-ComfyUI",
- "split_files/text_encoders/qwen_3_4b.safetensors",
- "llm",
- ),
- ),
+ # Klein 4B's text encoder IS Qwen3-4B (byte-identical shards to unsloth/Qwen3-4B; the BF16 GGUF matches it
+ # tensor for tensor and renders pixel-identical to the old single-file encoder), so sd-cli reads unsloth's
+ # own GGUF of it. Q8_0, not Q4_K_M: on klein 4B the Q4 encoder moved renders by LPIPS 0.15, Q8 by 0.06.
+ sd_cpp_text_encoders = (("unsloth/Qwen3-4B-GGUF", "Qwen3-4B-Q8_0.gguf", "llm"),),
),
# FLUX.3 Image Klein: a 5.6B flow-map DiT with a Qwen3-VL-4B encoder (layers 4..32 stacked) and the FLUX.2 VAE.
# Diffusers ships it only as modular blocks, so diffusion_flux3 assembles it per component behind a classic
@@ -550,8 +562,8 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
sd_cpp_reference = True,
),
# FLUX.2-dev: full (non-distilled) FLUX.2 on the Mistral Flux2Pipeline, so its own entry. Gated base,
- # text-to-image only; sd-cli takes the Mistral encoder from unsloth/FLUX.2-dev-ComfyUI and the VAE from
- # unsloth/FLUX.2-VAE.
+ # text-to-image only; sd-cli takes the Mistral encoder from unsloth's Mistral-Small-3.2 GGUF and the VAE from
+ # BFL's own diffusers file.
DiffusionFamily(
name = "flux.2-dev",
label = "FLUX.2-dev",
@@ -569,12 +581,15 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
aliases = ("flux2-dev", "flux2dev"),
trainable = True,
train_base_repos = ("black-forest-labs/FLUX.2-dev",),
- sd_cpp_vae = ("unsloth/FLUX.2-VAE", "split_files/vae/flux2-vae.safetensors"),
+ # BFL's own diffusers VAE file, byte-identical to the single-file repack this used to name.
+ sd_cpp_vae = ("black-forest-labs/FLUX.2-dev", "vae/diffusion_pytorch_model.safetensors"),
sd_cpp_vae_format = "flux2",
+ # FLUX.2-dev's text encoder is Mistral-Small-3.2-24B-Instruct-2506 (byte-identical shards to the unsloth
+ # copy; the BF16 GGUF matches every text tensor), so sd-cli reads unsloth's GGUF of it.
sd_cpp_text_encoders = (
(
- "unsloth/FLUX.2-dev-ComfyUI",
- "split_files/text_encoders/mistral_3_small_flux2_bf16.safetensors",
+ "unsloth/Mistral-Small-3.2-24B-Instruct-2506-GGUF",
+ "Mistral-Small-3.2-24B-Instruct-2506-Q4_K_M.gguf",
"llm",
),
),
@@ -596,10 +611,7 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
edit = True,
# Native: FLUX.1's VAE + CLIP-L / T5-XXL, the source as a reference image (sd.cpp docs/kontext.md).
sd_cpp_vae = ("black-forest-labs/FLUX.1-schnell", "ae.safetensors"),
- sd_cpp_text_encoders = (
- ("unsloth/flux-text-encoders", "clip_l.safetensors", "clip_l"),
- ("unsloth/flux-text-encoders", "t5xxl_fp16.safetensors", "t5xxl"),
- ),
+ sd_cpp_text_encoders = _FLUX1_SD_CPP_TEXT_ENCODERS,
),
DiffusionFamily(
# Qwen instruction editing: the 2511 checkpoint ships as QwenImageEditPlusPipeline. Specific aliases first so
@@ -642,7 +654,8 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
fp16_incompatible = True,
# Native: qwen-image's VAE + Qwen2.5-VL, plus its projector (edits read the source through the VLM; a GGUF
# encoder has no vision weights). 2511 needs no flag: sd.cpp keys zero_cond_t off __index_timestep_zero__.
- sd_cpp_vae = ("unsloth/Qwen-Image-ComfyUI", "split_files/vae/qwen_image_vae.safetensors"),
+ # The official diffusers VAE; sd.cpp maps its names itself, as it does for Layered's.
+ sd_cpp_vae = ("Qwen/Qwen-Image", "vae/diffusion_pytorch_model.safetensors"),
sd_cpp_text_encoders = (
(
"unsloth/Qwen2.5-VL-7B-Instruct-GGUF",
@@ -738,8 +751,8 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
inpaint_pipeline_class = "QwenImageInpaintPipeline",
controlnet_pipeline_class = "QwenImageControlNetPipeline",
controlnet_model_class = "QwenImageControlNetModel",
- # Byte-identical mirror of Comfy-Org/Qwen-Image_ComfyUI.
- sd_cpp_vae = ("unsloth/Qwen-Image-ComfyUI", "split_files/vae/qwen_image_vae.safetensors"),
+ # The official diffusers VAE; sd.cpp maps its names itself, as it does for Layered's.
+ sd_cpp_vae = ("Qwen/Qwen-Image", "vae/diffusion_pytorch_model.safetensors"),
# Qwen2.5-VL as a Q4_K_M GGUF keeps the CPU RAM win (bf16 encoder is ~15 GB). sd-cli --qwen2vl aliases --llm.
sd_cpp_text_encoders = (
(
@@ -952,15 +965,12 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
fp16_guard = "rescale_post_norm",
mlx_model_config = "z-image-turbo",
mlx_model_config_by_base = (("Tongyi-MAI/Z-Image", "z-image"),),
- # Byte-identical mirror of Comfy-Org/z_image_turbo (AE + Qwen3-4B).
- sd_cpp_vae = ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/vae/ae.safetensors"),
- sd_cpp_text_encoders = (
- (
- "unsloth/Z-Image-Turbo-ComfyUI",
- "split_files/text_encoders/qwen_3_4b.safetensors",
- "llm",
- ),
- ),
+ # Z-Image decodes with the FLUX.1 autoencoder: BFL's ae.safetensors, byte-identical to the repack's file.
+ sd_cpp_vae = ("black-forest-labs/FLUX.1-schnell", "ae.safetensors"),
+ # Z-Image's encoder differs from stock Qwen3-4B only in the LAST layer's MLP, which neither diffusers
+ # (hidden_states[-2]) nor sd.cpp (out_layers {35}) reads, so the conditioning is the same. Same Q8_0 file
+ # klein 4B reads, so one download serves both.
+ sd_cpp_text_encoders = (("unsloth/Qwen3-4B-GGUF", "Qwen3-4B-Q8_0.gguf", "llm"),),
),
DiffusionFamily(
name = "krea-2",
@@ -1385,12 +1395,22 @@ _UNGATED_MIRROR_PAIRS: tuple[tuple[str, str], ...] = (
("Qwen/Qwen-Image-2.1", "unsloth/Qwen-Image-2.1"),
("Qwen/Qwen-Image", "unsloth/Qwen-Image"),
("Qwen/Qwen-Image-Edit-2511", "unsloth/Qwen-Image-Edit-2511"),
+ # Variant bases reached only through a GGUF's base_model card tag (Edit, Edit-2509, Z-Image) or a named variant
+ # (2.1 Turbo, also a direct bf16 pick), plus Layered, whose sd-cli VAE is read straight from its base. No separate
+ # mirror repo: the official diffusers folders (model_index.json, transformer/, text_encoder/, tokenizer/,
+ # processor/, scheduler/, vae/) sit byte-identical at their upstream paths inside the model's EXISTING unsloth
+ # repo, its -FP8 repo where one exists, else its -GGUF repo, beside the quantised files that repo already ships.
+ ("Qwen/Qwen-Image-2.1-Turbo", "unsloth/Qwen-Image-2.1-Turbo-FP8"),
+ ("Qwen/Qwen-Image-Edit", "unsloth/Qwen-Image-Edit-GGUF"),
+ ("Qwen/Qwen-Image-Edit-2509", "unsloth/Qwen-Image-Edit-2509-GGUF"),
+ ("Qwen/Qwen-Image-Layered", "unsloth/Qwen-Image-Layered-GGUF"),
("black-forest-labs/FLUX.2-klein-4B", "unsloth/FLUX.2-klein-4B"),
# Lookup is by exact id, so every VARIANT a pick can resolve to needs its own row: the base-4B is what
# `unsloth/FLUX.2-klein-base-4B-GGUF` resolves to from its card tag, and Dev / Fast are offered directly as bf16
# pipeline picks. Without these three the table silently misses them.
("black-forest-labs/FLUX.2-klein-base-4B", "unsloth/FLUX.2-klein-base-4B"),
("Tongyi-MAI/Z-Image-Turbo", "unsloth/Z-Image-Turbo"),
+ ("Tongyi-MAI/Z-Image", "unsloth/Z-Image-GGUF"),
("Alpha-VLLM/Lumina-Image-2.0", "unsloth/Lumina-Image-2.0"),
("HiDream-ai/HiDream-I1-Full", "unsloth/HiDream-I1-Full"),
("HiDream-ai/HiDream-I1-Dev", "unsloth/HiDream-I1-Dev"),
@@ -1399,6 +1419,21 @@ _UNGATED_MIRROR_PAIRS: tuple[tuple[str, str], ...] = (
("stabilityai/sdxl-turbo", "unsloth/sdxl-turbo"),
)
_MIRROR_PAIRS: tuple[tuple[str, str], ...] = _GATED_MIRROR_PAIRS + _UNGATED_MIRROR_PAIRS
+# Mirror targets that are ALSO a model's own artifact repo (its GGUF / prequant checkpoints sit at the root beside the
+# official diffusers folders). A user picks these ids directly, so they are never "just a copy of the upstream": no
+# opt-out may rewrite them to the upstream (which has no such checkpoint), a cached one is its own checkpoint rather
+# than a stand-in for the base, and only the folder part of the snapshot is the pipeline.
+# Listed by hand, never inferred from a -GGUF / -FP8 suffix: unsloth/ideogram-4-fp8 is an ordinary complete copy of
+# ideogram-ai/ideogram-4-fp8 (the FP8 is in the upstream name), so it must keep canonicalising like every full mirror.
+_ARTIFACT_MIRRORS: frozenset[str] = frozenset(
+ {
+ "unsloth/z-image-gguf",
+ "unsloth/qwen-image-2.1-turbo-fp8",
+ "unsloth/qwen-image-edit-gguf",
+ "unsloth/qwen-image-edit-2509-gguf",
+ "unsloth/qwen-image-layered-gguf",
+ }
+)
_GATED_MIRRORS: dict[str, str] = {u.lower(): m for u, m in _MIRROR_PAIRS}
_MIRROR_UPSTREAM: dict[str, str] = {m.lower(): u for u, m in _MIRROR_PAIRS}
_GATED_UPSTREAMS: frozenset[str] = frozenset(u.lower() for u, _m in _GATED_MIRROR_PAIRS)
@@ -1409,6 +1444,11 @@ def mirror_repo(repo_id: Optional[str]) -> Optional[str]:
return _GATED_MIRRORS.get((repo_id or "").strip().lower())
+def mirror_hosts_artifacts(repo_id: Optional[str]) -> bool:
+ """True when ``repo_id`` is a mirror target that also ships the model's own GGUF / prequant checkpoints."""
+ return (repo_id or "").strip().lower() in _ARTIFACT_MIRRORS
+
+
def upstream_is_gated(repo_id: Optional[str]) -> bool:
"""True when ``repo_id`` is a vendor base the Hub refuses without accepted terms. Distinct from
"has a mirror": most of the mirror table is ungated and exists only to keep the fetch inside
@@ -1576,12 +1616,8 @@ def cache_holds_files(repo_id: str, files: Sequence[str]) -> bool:
# keyed by repo id, so re-pointing the table alone would re-download up to tens of GB on upgrade and fail outright
# offline.
_SD_CPP_LEGACY_SOURCES: dict[str, str] = {
- "unsloth/flux-text-encoders": "comfyanonymous/flux_text_encoders",
- "unsloth/qwen-image-comfyui": "Comfy-Org/Qwen-Image_ComfyUI",
- "unsloth/flux.2-vae": "Comfy-Org/flux2-dev",
- "unsloth/flux.2-dev-comfyui": "Comfy-Org/flux2-dev",
- "unsloth/z-image-turbo-comfyui": "Comfy-Org/z_image_turbo",
- "unsloth/flux.2-klein-9b-comfyui": "Comfy-Org/vae-text-encorder-for-flux-klein-9b",
+ # No image entry: every image sd-cli asset is now an official upstream file or an unsloth GGUF, so no image load
+ # reads a Comfy-made repack, not even one already in the cache.
"unsloth/wan2.2-ti2v-5b-gguf": "QuantStack/Wan2.2-TI2V-5B-GGUF",
# MiniMax-H3, where only PART of the mirror came from the repack: the two VAEs now sit beside the denoisers in the
# GGUF repo, and the int8 ConvRot conditioner beside the other prequantized checkpoints. That is why every caller
@@ -1632,6 +1668,7 @@ def prefer_ungated_mirror(
hf_token: Optional[str] = None,
*,
files: Optional[Sequence[str]] = None,
+ other_root: bool = False,
) -> str:
"""``base``, or its ungated unsloth mirror when that is the better repo to FETCH from.
@@ -1655,7 +1692,10 @@ def prefer_ungated_mirror(
"""
del hf_token # noqa: F841 -- signature stability only
if os.environ.get("UNSLOTH_DIFFUSION_NO_MIRROR", "").strip():
- return base if _is_local_path(base) else canonical_base(base)
+ # An artifact repo stays itself: its GGUF / FP8 checkpoint does not exist under the upstream id.
+ if _is_local_path(base) or mirror_hosts_artifacts(base):
+ return base
+ return canonical_base(base)
mirror = mirror_repo(base)
if not mirror:
return base
@@ -1663,7 +1703,14 @@ def prefer_ungated_mirror(
# the copy already downloaded
if _is_local_path(base):
return base
- return base if _upstream_is_cached(base, files) else mirror
+ # ``other_root`` for a fetch that resolves each file through either cache root (``reuse_other_cache_root``):
+ # an upstream copy left in the pre-change root then serves the load, so it must keep the upstream id.
+ cached = (
+ _upstream_is_cached(base, files, other_root = True)
+ if other_root
+ else _upstream_is_cached(base, files)
+ )
+ return base if cached else mirror
# Default (steps, guidance) per model for callers that cannot pass them. Matched by substring, most specific first;
@@ -2606,16 +2653,47 @@ def family_sd_cpp_supported(fam: DiffusionFamily) -> bool:
# FLUX.2-klein 9B pairs with Qwen3-8B, the 4B with the family-default Qwen3-4B (a mismatched encoder fails deep in
-# sd-cli), so pick per variant. Byte-identical mirror of Comfy-Org/vae-text-encorder-for-flux-klein-9b.
-_FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS = (
- (
- "unsloth/FLUX.2-klein-9B-ComfyUI",
- "split_files/text_encoders/qwen_3_8b.safetensors",
- "llm",
- ),
+# sd-cli), so pick per variant. Klein 9B's text encoder is byte-identical to unsloth/Qwen3-8B.
+_FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS = (("unsloth/Qwen3-8B-GGUF", "Qwen3-8B-Q4_K_M.gguf", "llm"),)
+
+
+# sd-cli companion repos released Studio builds fetched and this one no longer reads: the unsloth copies of the
+# ComfyUI-built repacks, each holding only VAE / text-encoder files (no denoiser). Nothing loads from them now, but an
+# upgraded install still holds their bytes (up to ~70 GB), so they stay companion-only: hidden from the model pickers
+# and offered by Free up space once nothing pins them. Never fetched again. The Comfy-Org originals are NOT listed:
+# those repos also ship denoisers a user may load as single files, so they must stay ordinary cached repos.
+_RETIRED_SD_CPP_COMPANION_REPOS: frozenset[str] = frozenset(
+ {
+ "unsloth/flux-text-encoders",
+ "unsloth/qwen-image-comfyui",
+ "unsloth/flux.2-vae",
+ "unsloth/flux.2-dev-comfyui",
+ "unsloth/z-image-turbo-comfyui",
+ "unsloth/flux.2-klein-9b-comfyui",
+ }
)
+# The community repacks those retired copies stood in for. Released builds sent an sd-cli fetch back to one already
+# cached, so a recorded companion link may name it. Ordinary cached repos otherwise (some also ship denoiser files), so
+# this set only drops stale LINKS; it never makes one a companion.
+_RETIRED_SD_CPP_LEGACY_SOURCES: frozenset[str] = frozenset(
+ {
+ "comfyanonymous/flux_text_encoders",
+ "comfy-org/qwen-image_comfyui",
+ "comfy-org/flux2-dev",
+ "comfy-org/z_image_turbo",
+ "comfy-org/vae-text-encorder-for-flux-klein-9b",
+ }
+)
+
+
+def retired_companion_link_ids() -> frozenset[str]:
+ """Lowercased repo ids no load reads any more, so a companion link naming one is stale: released sd.cpp loads
+ recorded these asset repos, and an installed GGUF must not keep pinning them in Free up space forever."""
+ return _RETIRED_SD_CPP_COMPANION_REPOS | _RETIRED_SD_CPP_LEGACY_SOURCES
+
+
def sd_cpp_companion_only_repo_ids() -> frozenset[str]:
"""Lowercased ids of repos that exist ONLY to hand sd.cpp a single-file VAE / text encoder.
@@ -2644,11 +2722,16 @@ def sd_cpp_companion_only_repo_ids() -> frozenset[str]:
loadable.update(repo for _base, _scheme, repo in fam.prequant_variant_repos)
loadable.update(repo for _scheme, _component, repo in fam.te_prequant_repos)
companions.update(repo for repo, _f, _k in _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS)
- return frozenset(r.strip().lower() for r in companions - loadable if r)
+ return (
+ frozenset(r.strip().lower() for r in companions - loadable if r)
+ | _RETIRED_SD_CPP_COMPANION_REPOS
+ )
def prequant_only_repo_ids() -> frozenset[str]:
- """Repos hosting only prequant checkpoints (no model_index.json), never a base or mirror."""
+ """Repos a pick names for their prequant checkpoints, never a base or a full mirror. A prequant repo that also
+ carries the official diffusers folders for its base (``mirror_hosts_artifacts``) stays here: those folders are
+ what a pick of the BASE fetches, and picking the prequant repo itself as a pipeline is still the wrong request."""
hosted: set[str] = set()
bases: set[str] = set()
for fam in _FAMILIES:
@@ -2659,9 +2742,14 @@ def prequant_only_repo_ids() -> frozenset[str]:
bases.update(fam.train_base_repos)
if fam.deploy_base_repo:
bases.add(fam.deploy_base_repo)
- bases.update(rid for pair in _MIRROR_PAIRS for rid in pair)
+ bases.update(rid for pair in _MIRROR_PAIRS for rid in pair if not mirror_hosts_artifacts(rid))
lowered = {b.strip().lower() for b in bases if b}
- return frozenset(r.strip().lower() for r in hosted if r and r.strip().lower() not in lowered)
+ # Every artifact mirror too: the -GGUF ones host no prequant scheme, but their folders are the BASE's pipeline
+ # all the same, and a pipeline pick of the repo id itself is the wrong request.
+ return (
+ frozenset(r.strip().lower() for r in hosted if r and r.strip().lower() not in lowered)
+ | _ARTIFACT_MIRRORS
+ )
def prequant_repo_role(
diff --git a/studio/backend/core/inference/sd_cpp_backend.py b/studio/backend/core/inference/sd_cpp_backend.py
index f2c64f238ed..c8ff29ce151 100644
--- a/studio/backend/core/inference/sd_cpp_backend.py
+++ b/studio/backend/core/inference/sd_cpp_backend.py
@@ -20,9 +20,11 @@ from __future__ import annotations
import base64
import contextlib
+import json
import logging
import os
import re
+import shutil
import sys
import threading
import time
@@ -234,16 +236,21 @@ def _base_sample_sigmas(
elif not explicit_base and named_base:
# Cache-only (e.g. the OpenAI route's auto-switch) reads no card: the pick's own name decides.
base = named_base
- # Cache-only reads try both roots, as the plan's locality check and _fetch_assets do.
+ # Read from the repo the plan staged it under (_grid_fetch_repo: the base's unsloth mirror unless the
+ # upstream already holds it), never the vendor id directly. Cache-only reads try both roots, as the plan's
+ # locality check and _fetch_assets do, and the upstream id too, so an index cached under either still counts.
+ fetch = _grid_fetch_repo(base, hf_token)
+ repos = tuple(dict.fromkeys((fetch, base))) if local_files_only else (fetch,)
roots = (hub_cache_dir(), None) if local_files_only else (hub_cache_dir(),)
- for i, root in enumerate(roots):
+ attempts = [(repo, root) for repo in repos for root in roots]
+ for i, (repo, root) in enumerate(attempts):
try:
index = read_model_index(
- base, hf_token = hf_token, local_files_only = local_files_only, cache_dir = root
+ repo, hf_token = hf_token, local_files_only = local_files_only, cache_dir = root
)
break
except Exception: # noqa: BLE001
- if i == len(roots) - 1:
+ if i == len(attempts) - 1:
raise
except Exception as exc: # noqa: BLE001 - no grid is the pre-grid behaviour
logger.debug("sd_cpp.sample_sigmas_unavailable: %s", exc)
@@ -256,6 +263,14 @@ def _base_sample_sigmas(
return grid, base
+def _grid_fetch_repo(base: str, hf_token: Optional[str]) -> str:
+ """The repo a base's ``model_index.json`` sampling grid is fetched from: the same per-repo swap the assets take, so
+ the plan stages it where the load reads it (a routed base's unsloth mirror, e.g. unsloth/Qwen-Image-2.1-Turbo-FP8
+ for Qwen/Qwen-Image-2.1-Turbo, unless the upstream already holds the file)."""
+ files = ["model_index.json"]
+ return prefer_cached_legacy_source(prefer_ungated_mirror(base, hf_token, files = files), files)
+
+
def _cgroup_cpu_limit(
root: str = "/sys/fs/cgroup", proc_cgroup: str = "/proc/self/cgroup"
) -> Optional[int]:
@@ -2576,6 +2591,74 @@ def _map_guidance(
return cfg, None
+def _assert_shards_beside_index(kind: str, path: str) -> None:
+ """sd-cli resolves a ``*.safetensors.index.json`` encoder's shards relative to the index, so every shard it names
+ must sit in the same snapshot directory. The shards are fetched as their own assets, which normally lands them
+ there; a cache split across two roots could not, and sd-cli would then fail deep in the load. Say so here."""
+ if not str(path).endswith(".safetensors.index.json"):
+ return
+ try:
+ with open(path, encoding = "utf-8") as fh:
+ shards = set((json.load(fh).get("weight_map") or {}).values())
+ except (OSError, ValueError) as exc:
+ raise RuntimeError(f"cannot read the {kind} shard index '{path}': {exc}") from exc
+ missing = sorted(s for s in shards if not (Path(path).parent / s).exists())
+ if missing:
+ raise RuntimeError(
+ f"the {kind} encoder's shards {missing} are not beside its index in '{Path(path).parent}'; "
+ "clear that model from the cache and load it again"
+ )
+
+
+def _colocate_shards(index_path: str, fetched: dict[str, str]) -> None:
+ """Put every shard an encoder index names beside it, when the shard was fetched into the OTHER cache root.
+
+ ``_fetch_assets`` resolves each file through either root, so after a cache-folder change the index can come from
+ the old root while its shards land in the active one. sd-cli only looks beside the index, and an offline user
+ cannot repair that by re-downloading, so each missing shard is hard-linked (else copied) into the index's snapshot
+ directory, under the name the repo itself gives it. ``fetched`` maps a shard's file name to the path it was
+ resolved to. Best-effort: anything left missing is reported by ``_assert_shards_beside_index``."""
+ if not str(index_path).endswith(".safetensors.index.json"):
+ return
+ try:
+ with open(index_path, encoding = "utf-8") as fh:
+ shards = set((json.load(fh).get("weight_map") or {}).values())
+ except (OSError, ValueError):
+ return
+ parent = Path(index_path).parent
+ for shard in sorted(shards):
+ target = parent / shard
+ source = fetched.get(shard)
+ if not source or not Path(source).is_file():
+ continue
+ real = Path(source).resolve()
+ size = real.stat().st_size
+ if target.exists():
+ # A complete shard is left alone; a short one (an earlier copy cut off) is replaced.
+ if target.stat().st_size == size:
+ continue
+ with contextlib.suppress(OSError):
+ target.unlink()
+ # A hard link, else a copy, never a symlink: each cache root is deleted and unmounted on its own, so a link
+ # from one into the other would dangle, or a cache scan would treat the other root's blob as this one's.
+ try:
+ os.link(real, target)
+ continue
+ except OSError:
+ pass
+ # The copy lands under a temporary name and is renamed into place only once complete, so a full disk or an
+ # interrupted copy never leaves a truncated shard that the existence check would accept.
+ partial = target.with_name(f".{target.name}.{os.getpid()}.partial")
+ try:
+ shutil.copyfile(real, partial)
+ if partial.stat().st_size != size:
+ raise OSError(f"short copy of {real}")
+ os.replace(partial, target)
+ except OSError:
+ with contextlib.suppress(OSError):
+ partial.unlink()
+
+
def _fetch_repo_map(assets: list[tuple[str, str, str]], hf_token: Optional[str]) -> dict[str, str]:
"""upstream asset repo -> the repo to actually fetch from (its ungated mirror, or itself).
Decided per REPO over its whole file list, the same input ``download_plan`` uses, so staging
@@ -2587,7 +2670,11 @@ def _fetch_repo_map(assets: list[tuple[str, str, str]], hf_token: Optional[str])
for repo, filename, _kind in assets:
by_repo.setdefault(repo, []).append(filename)
return {
- repo: prefer_cached_legacy_source(prefer_ungated_mirror(repo, hf_token, files = names), names)
+ # Both cache roots: _fetch_assets resolves each file through either, so an upstream copy in the pre-change
+ # root keeps the upstream id instead of re-pulling the mirror.
+ repo: prefer_cached_legacy_source(
+ prefer_ungated_mirror(repo, hf_token, files = names, other_root = True), names
+ )
for repo, names in by_repo.items()
}
@@ -3004,7 +3091,7 @@ class SdCppDiffusionBackend:
)
# Same link the diffusers resolver records, so the delete guard protects a native pick's companions too -- and
# here that means the repos _asset_specs actually FETCHES. The native engine does not read the diffusers base:
- # FLUX.2 takes its VAE from unsloth/FLUX.2-VAE and its encoders from another repo again, so recording only the
+ # FLUX.2 takes its VAE from the FLUX.2 base and its encoder from an unsloth GGUF repo, so recording only the
# base left every repo the pick really depends on outside the guard, and an unloaded model's encoder could be
# deleted while its GGUF stayed installed. Best-effort bookkeeping; never fails a load.
try:
@@ -3636,9 +3723,9 @@ class SdCppDiffusionBackend:
# are gated (the FLUX.1 VAE lives in black-forest-labs/FLUX.1-schnell) and an anonymous user would 401 at
# staging, never reaching the swap. Same per-repo file list on both sides, so both take the same decision.
fetch_repo = _fetch_repo_map(specs, hf_token)
- # MERGED, not reassigned: two upstream repos can share one fetch repo (the FLUX.2 VAE and the dev encoders
- # both come from Comfy-Org/flux2-dev once that repack is cached), and a plain comprehension would drop
- # whichever landed first, leaving its files out of both the staged entry and the footprint.
+ # MERGED, not reassigned: two upstream repos can share one fetch repo (a gated vendor id and its unsloth
+ # mirror both stage under the mirror), and a plain comprehension would drop whichever landed first, leaving
+ # its files out of both the staged entry and the footprint.
merged: dict[str, list[str]] = {}
for repo, names in by_repo.items():
into = merged.setdefault(fetch_repo[repo], [])
@@ -3653,7 +3740,7 @@ class SdCppDiffusionBackend:
else:
grid_base = named_variant_base(fam, repo_id, gguf_filename)
if fam.name in _SAMPLE_SIGMAS_FAMILIES and grid_base:
- names = by_repo.setdefault(grid_base, [])
+ names = by_repo.setdefault(_grid_fetch_repo(grid_base, hf_token), [])
if "model_index.json" not in names:
names.append("model_index.json")
fetch_repo_id = fetch_repo.get(repo_id, repo_id)
@@ -3853,13 +3940,17 @@ class SdCppDiffusionBackend:
total = 0
try:
from huggingface_hub import HfApi
+
api = HfApi(token = hf_token)
+ # Sized where _fetch_assets pulls from: a gated vendor id answers an anonymous user with nothing, which
+ # left CLIP / T5 at 0 bytes and the bar finalizing while they downloaded.
+ fetch_repo = _fetch_repo_map(assets, hf_token)
for repo, fn, kind in assets:
# Only the transformer can be a local path; others are always HF ids.
if kind == "diffusion_model" and Path(repo).expanduser().exists():
continue
try:
- info = api.get_paths_info(repo, paths = [fn], expand = False)
+ info = api.get_paths_info(fetch_repo.get(repo, repo), paths = [fn], expand = False)
for it in info:
total += int(getattr(it, "size", 0) or 0)
except Exception: # noqa: BLE001 -- one missing size is non-fatal
@@ -3889,6 +3980,8 @@ class SdCppDiffusionBackend:
# Callers without a per-load event (tests, direct use) fall back to the current one.
cancel = cancel_event if cancel_event is not None else self._cancel_event
paths: dict[str, str] = {}
+ # Shard file name -> where it resolved: the kind repeats per shard, so ``paths`` keeps only the last one.
+ shard_paths: dict[str, str] = {}
# This backend fetches the ASSET repos, never the base, and some are gated, so the swap goes here. Decided per
# REPO over its whole file list, exactly as download_plan does, so the load pulls from the repo the manager
# already staged.
@@ -3935,12 +4028,17 @@ class SdCppDiffusionBackend:
f"page to fetch it."
) from exc
paths[kind] = path
+ if kind.endswith("_shard"):
+ shard_paths[fn.rsplit("/", 1)[-1]] = path
with self._lock:
if self._loading is not None:
try:
self._loading.downloaded_bytes += os.path.getsize(path)
except OSError:
pass
+ for kind, path in paths.items():
+ _colocate_shards(path, shard_paths)
+ _assert_shards_beside_index(kind, path)
return paths
def load_progress(self) -> dict[str, Any]:
diff --git a/studio/backend/hub/services/models/cache_inventory.py b/studio/backend/hub/services/models/cache_inventory.py
index b5652f4b67d..ef6b71e00c8 100644
--- a/studio/backend/hub/services/models/cache_inventory.py
+++ b/studio/backend/hub/services/models/cache_inventory.py
@@ -688,9 +688,16 @@ def _scan_cached_gguf(
)
except Exception:
pass
+ row_size = max(total_size, variant_state_size)
+ # An artifact mirror's diffusers folders IN THIS ROOT are listed nowhere else (see
+ # _scan_cached_models), and this row's whole-repo delete removes them, so the row counts them. A copy
+ # in another root is that root's own companion row: a delete is scoped to one cache root, so counting
+ # it here would promise bytes this row's delete never frees.
+ if _hosts_artifacts(repo_id):
+ row_size += artifact_folder_bytes(repo_path)
row = {
"repo_id": repo_id,
- "size_bytes": max(total_size, variant_state_size),
+ "size_bytes": row_size,
"cache_path": str(repo_info.repo_path),
"task": row_task,
"audio_type": row_audio_type,
@@ -1180,6 +1187,8 @@ def _scan_cached_models(
variant_states = None
seen_lower: dict[str, dict] = {}
+ # Across EVERY root: the GGUF can sit in one cache root and its mirror's diffusers folders in the other.
+ artifact_gguf_keys = _artifact_gguf_repo_ids(cache_scans)
inspected = 0
skipped_gguf = 0
skipped_no_weights = 0
@@ -1212,6 +1221,22 @@ def _scan_cached_models(
if not payload.has_runnable_weights:
skipped_no_weights += 1
continue
+ # A GGUF repo that also carries the official diffusers folders (it is the base's mirror): the folders,
+ # with or without the bf16 transformer, are part of the GGUF row (its size counts them), never a second
+ # row. Deletes are whole-repo or per-quant, so such a row's delete would wipe the quants, and a
+ # pipeline pick of the -GGUF id is refused anyway.
+ any_root_gguf = has_main_gguf or repo_id.lower() in artifact_gguf_keys
+ if has_main_gguf and _hosts_artifacts(repo_id):
+ skipped_gguf += 1
+ continue
+ # Its GGUF in ANOTHER cache root: this copy holds only the folders that GGUF loads its companions
+ # from. Its own row, so its delete (scoped to this root) frees exactly what it shows, but a companion,
+ # never a pipeline or single-file pick.
+ cross_root_folders = any_root_gguf and _hosts_artifacts(repo_id)
+ # The FP8 artifact mirror (unsloth/Qwen-Image-2.1-Turbo-FP8): its folders are what a pick of the BASE
+ # fetches, and a pipeline pick of the repo itself is refused, so the row stays the root checkpoint row
+ # released builds listed, whatever part of the folders is cached.
+ artifact_checkpoint = not any_root_gguf and _hosts_artifacts(repo_id)
key = repo_id.lower()
existing = seen_lower.get(key)
identity = _resolve_load_identity(
@@ -1247,7 +1272,10 @@ def _scan_cached_models(
),
)
# A companion-only prefetch passes the download check yet cannot from_pretrained, so mark it partial.
- companion_only = hf_cache_scan.snapshot_pipeline_missing_denoiser(load_snapshot)
+ companion_only = (
+ not artifact_checkpoint
+ and hf_cache_scan.snapshot_pipeline_missing_denoiser(load_snapshot)
+ )
snapshot_partial = download_partial or companion_only
# Flags are OR-ed over revisions, so no payload snapshot means no directory serves the row and it would reach for the Hub.
if not payload.payload_snapshots:
@@ -1280,7 +1308,11 @@ def _scan_cached_models(
if not any(tag.lower() == "whisper" for tag in tags):
tags.append("whisper")
local_metadata["tags"] = tags
- pipeline_artifact_kind = _diffusers_pipeline_artifact_kind(load_snapshot)
+ pipeline_artifact_kind = (
+ None
+ if artifact_checkpoint
+ else _diffusers_pipeline_artifact_kind(load_snapshot)
+ )
row = {
"repo_id": repo_id,
"size_bytes": payload.size_bytes,
@@ -1318,10 +1350,14 @@ def _scan_cached_models(
# Diffusion repos with no pipeline index load only via from_single_file, so the task pickers must not offer them as pipeline loads.
"single_file": bool(
row_task is not None
- and not hf_cache_scan.snapshot_has_pipeline_index(load_snapshot)
+ and (
+ artifact_checkpoint
+ or not hf_cache_scan.snapshot_has_pipeline_index(load_snapshot)
+ )
),
# Listed so tens of GB of companion weights stay visible and deletable, but flagged so no picker offers a denoiser-less repo as a load.
- "companion": _cached_row_companion(repo_id, load_snapshot),
+ "companion": cross_root_folders
+ or _cached_row_companion(repo_id, load_snapshot),
"diffusers": _cached_row_is_diffusers(repo_info, load_snapshot),
**local_metadata,
}
@@ -1388,3 +1424,51 @@ async def list_cached_models_response(hf_token: Optional[str] = None):
status_code = 500,
detail = "Failed to read the local model cache.",
) from e
+
+
+def artifact_folder_bytes(*repo_paths: Path) -> int:
+ """Bytes of every non-GGUF file under the repo's snapshots, in every cache root given: the diffusers folders an
+ artifact mirror (``mirror_hosts_artifacts``) holds beside its quants, which only its GGUF row lists. Counted by
+ the physical blob each snapshot entry resolves to, as ``repo_unique_size_bytes`` does: a whole-repo delete frees
+ every revision's blob once, so a file changed under the same name counts twice and one blob behind several paths
+ once. Never raises."""
+ seen: dict[object, int] = {}
+ for repo_path in repo_paths:
+ snapshots = Path(repo_path) / "snapshots"
+ try:
+ for path in snapshots.rglob("*"):
+ if path.name.lower().endswith(".gguf") or not path.is_file():
+ continue
+ st = path.stat()
+ # No inode on this filesystem: the resolved blob path, as _blob_key does.
+ key = (st.st_dev, st.st_ino) if st.st_ino else str(path.resolve())
+ seen[key] = st.st_size
+ except (OSError, ValueError):
+ continue
+ return sum(seen.values())
+
+
+def _artifact_gguf_repo_ids(cache_scans) -> set[str]:
+ """Lowercased ids of artifact mirrors with a main GGUF in ANY cache root."""
+ found: set[str] = set()
+ for hf_cache in cache_scans or ():
+ for repo in getattr(hf_cache, "repos", ()) or ():
+ try:
+ if (
+ str(repo.repo_type) == "model"
+ and _hosts_artifacts(repo.repo_id)
+ and _repo_has_gguf_files(repo)
+ ):
+ found.add(repo.repo_id.lower())
+ except Exception: # noqa: BLE001
+ continue
+ return found
+
+
+def _hosts_artifacts(repo_id: str) -> bool:
+ """``mirror_hosts_artifacts``, False when the family tables are unavailable."""
+ try:
+ from core.inference.diffusion_families import mirror_hosts_artifacts
+ return mirror_hosts_artifacts(repo_id)
+ except Exception: # noqa: BLE001 -- no table means no artifact mirrors
+ return False
diff --git a/studio/backend/hub/services/models/companion_cleanup.py b/studio/backend/hub/services/models/companion_cleanup.py
index ee8cbd99724..71f185d430a 100644
--- a/studio/backend/hub/services/models/companion_cleanup.py
+++ b/studio/backend/hub/services/models/companion_cleanup.py
@@ -374,14 +374,21 @@ def _orphan_companions_blocking() -> dict:
by_id = _repos_by_id(scans)
required = companion_assets.required_companion_bases(scans)
known = companion_assets.known_companion_base_ids()
+ # An artifact mirror with a GGUF in ANY root is an installed model: a folders-only copy of it in another root is
+ # what that GGUF loads its companions from, never an orphan. The per-root denoiser check below cannot see that.
+ artifact_ggufs = cache_inventory._artifact_gguf_repo_ids(scans)
orphans: list[dict] = []
for base_key in sorted(known & set(by_id)):
- if required.get(base_key):
+ if required.get(base_key) or base_key in artifact_ggufs:
continue
repos = by_id[base_key]
- # exclude user-installed copies with denoisers; companion fetches omit transformer/ and orphan rows are per root
- repos = [r for r in repos if not _repo_holds_denoiser(r)]
+ # exclude user-installed copies with denoisers; companion fetches omit transformer/ and orphan rows are per root.
+ # An artifact mirror is judged by its root checkpoints only (an FP8 mirror's checkpoint is installed): a
+ # pipeline load of its id is refused, so with no GGUF left (checked above) transformer/ shards a GGUF speed
+ # load left are no installed checkpoint.
+ folders = not cache_inventory._hosts_artifacts(base_key)
+ repos = [r for r in repos if not _repo_holds_denoiser(r, folders = folders)]
if not repos:
continue
# One row per cache root: a delete is scoped to a single cache, so pooling copies from several would promise bytes one removal cannot deliver.
diff --git a/studio/backend/hub/services/models/local_inventory.py b/studio/backend/hub/services/models/local_inventory.py
index 1b398b7f125..91c3a599b01 100644
--- a/studio/backend/hub/services/models/local_inventory.py
+++ b/studio/backend/hub/services/models/local_inventory.py
@@ -714,10 +714,109 @@ def _scan_hf_cache(
rows, snapshot_partial = True, gguf_partial = gguf_partial
)
]
+ rows = _artifact_mirror_rows(
+ model_id,
+ repo_dir,
+ rows,
+ load_path = load_path,
+ updated_at = updated_at,
+ active_cache = active_cache,
+ )
found.extend(rows)
return found
+def _hosts_artifacts(repo_id: str) -> bool:
+ """``mirror_hosts_artifacts``, False when the family tables are unavailable."""
+ try:
+ from core.inference.diffusion_families import mirror_hosts_artifacts
+ return mirror_hosts_artifacts(repo_id)
+ except Exception: # noqa: BLE001 -- no table means no artifact mirrors
+ return False
+
+
+def _cached_gguf_bytes(repo_dir: Path) -> int:
+ """Bytes of every ``.gguf`` under any cached revision of the repo, each file counted once."""
+ seen: dict[str, int] = {}
+ try:
+ for path in (repo_dir / "snapshots").rglob("*.gguf"):
+ if path.is_file():
+ seen[str(path.resolve())] = path.stat().st_size
+ except OSError:
+ pass
+ return sum(seen.values())
+
+
+def _artifact_mirror_rows(
+ model_id: str,
+ repo_dir: Path,
+ rows: List[LocalModelInfo],
+ *,
+ load_path: Optional[Path] = None,
+ updated_at: Optional[float] = None,
+ active_cache: bool = True,
+) -> List[LocalModelInfo]:
+ """An artifact mirror (a model's own GGUF / FP8 repo that also holds its base's official diffusers folders) never
+ lists those folders as a pipeline row: they are what a pick of the BASE fetches, a pipeline pick of the repo id is
+ refused, and deletes are whole-repo or per-quant, so a separate row's delete would wipe the quants. A GGUF repo's
+ folders fold into its GGUF row's size; the FP8 repo's row stays partial and flagged, so nothing loads or resumes it
+ as a pipeline. A snapshot with no pipeline index is left exactly as released builds listed it."""
+ if not _hosts_artifacts(model_id):
+ return rows
+ snapshot = hf_cache_scan.latest_snapshot_dir(repo_dir)
+ if snapshot is None or not hf_cache_scan.snapshot_has_pipeline_index(snapshot):
+ return rows
+ gguf_rows = [row for row in rows if row.model_format == "gguf"]
+ if not gguf_rows and (gguf_bytes := _cached_gguf_bytes(repo_dir)):
+ # The quants sit in an OLDER revision than the folders a later base pick added, and only the newest snapshot
+ # was classified: recover the GGUF row from every cached revision rather than drop an installed model.
+ gguf_rows = [
+ _local_model_info(
+ scan_path = repo_dir,
+ load_path = load_path or repo_dir,
+ source = "hf_cache",
+ model_format = "gguf",
+ display_name = model_id.split("/")[-1],
+ model_id = model_id,
+ updated_at = updated_at,
+ partial = False,
+ requires_variant = True,
+ size_bytes = gguf_bytes,
+ active_cache = active_cache,
+ )
+ ]
+ if gguf_rows:
+ from hub.services.models.cache_inventory import artifact_folder_bytes
+ folder_bytes = artifact_folder_bytes(repo_dir)
+ return [
+ row.model_copy(update = {"size_bytes": int(row.size_bytes or 0) + folder_bytes})
+ for row in gguf_rows
+ ]
+ return [row.model_copy(update = {"partial": True, "companion_prefetch": True}) for row in rows]
+
+
+def _merge_artifact_mirror_roots(
+ rows_by_root: list[tuple[Path, List[LocalModelInfo]]],
+) -> List[LocalModelInfo]:
+ """The cross-root half of ``_artifact_mirror_rows``, which sees one cache root at a time. When an artifact
+ mirror's GGUF sits in one root and its diffusers folders in another, each root keeps its own row, because a delete
+ is scoped to one root: the GGUF row counts only its own root, and the folders-only row stays partial and flagged as
+ the GGUF's companion prefetch, never a pick. Every other row passes through unchanged."""
+ gguf_ids = {
+ (row.model_id or "").lower()
+ for _root, rows in rows_by_root
+ for row in rows
+ if row.model_format == "gguf" and row.model_id and _hosts_artifacts(row.model_id)
+ }
+ out: List[LocalModelInfo] = []
+ for _root, rows in rows_by_root:
+ for row in rows:
+ if row.model_format != "gguf" and (row.model_id or "").lower() in gguf_ids:
+ row = row.model_copy(update = {"partial": True, "companion_prefetch": True})
+ out.append(row)
+ return out
+
+
def _scan_lmstudio_dir(
lm_dir: Path,
*,
@@ -1085,18 +1184,25 @@ async def _collect_models_from_default_sources(
except Exception as e:
logger.warning("Could not build shared Hub-state index: %s", scrub_paths(e))
variant_states = None
+ hf_rows_by_root: list[tuple[Path, List[LocalModelInfo]]] = []
for label, cache_dir, active_cache, discovered in discovered_sources:
- local_models += await _scan_source(
- label,
- lambda path, rows = discovered, active = active_cache: _scan_hf_cache(
- path,
- active_cache = active,
- discovered = rows,
- variant_states = variant_states,
- active_hub_cache = hf_cache_dir,
- ),
- cache_dir,
+ hf_rows_by_root.append(
+ (
+ cache_dir,
+ await _scan_source(
+ label,
+ lambda path, rows = discovered, active = active_cache: _scan_hf_cache(
+ path,
+ active_cache = active,
+ discovered = rows,
+ variant_states = variant_states,
+ active_hub_cache = hf_cache_dir,
+ ),
+ cache_dir,
+ ),
+ )
)
+ local_models += _merge_artifact_mirror_roots(hf_rows_by_root)
for lm_dir in lm_dirs:
local_models += await _scan_source("LM Studio", _scan_lmstudio_dir, lm_dir)
@@ -1231,18 +1337,24 @@ def _scan_custom_folder(
limit = _MAX_MODELS_PER_CUSTOM_FOLDER,
entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES,
)
- + [
- row
- for cache_dir, discovered in hf_caches
- for row in _scan_hf_cache(
- cache_dir,
- entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES,
- active_cache = False,
- discovered = discovered,
- variant_states = variant_states,
- active_hub_cache = active_hub_cache,
- )
- ]
+ # Several HF caches under one folder are merged like the top-level roots, so an artifact mirror whose
+ # GGUF and diffusers folders sit in different caches is one GGUF row.
+ + _merge_artifact_mirror_roots(
+ [
+ (
+ cache_dir,
+ _scan_hf_cache(
+ cache_dir,
+ entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES,
+ active_cache = False,
+ discovered = discovered,
+ variant_states = variant_states,
+ active_hub_cache = active_hub_cache,
+ ),
+ )
+ for cache_dir, discovered in hf_caches
+ ]
+ )
+ _scan_lmstudio_dir(folder_path, entry_limit = _MAX_CUSTOM_FOLDER_ENTRIES)
)
if _is_supported(m)
diff --git a/studio/backend/hub/tests/test_companion_assets.py b/studio/backend/hub/tests/test_companion_assets.py
index 2554b1007f0..ea66c92bd2b 100644
--- a/studio/backend/hub/tests/test_companion_assets.py
+++ b/studio/backend/hub/tests/test_companion_assets.py
@@ -209,9 +209,15 @@ def test_delete_of_a_companion_base_fails_closed_when_the_cache_cannot_be_read(m
def test_the_guard_leaves_ordinary_repos_alone(monkeypatch):
- """Only a known companion base takes the extra check, so a chat GGUF is untouched by it."""
- assert not companion_assets.is_companion_base("unsloth/Qwen3-8B-GGUF")
+ """Only a known companion base takes the extra check, so a chat GGUF is untouched by it.
+
+ A chat GGUF sd.cpp borrows as a text encoder (unsloth/Qwen3-8B-GGUF for FLUX.2-klein 9B, like
+ unsloth/Qwen2.5-VL-7B-Instruct-GGUF for Qwen-Image) does take it, so an installed image
+ checkpoint that reads it keeps it; one nobody borrows does not."""
+ assert not companion_assets.is_companion_base("unsloth/Qwen3-14B-GGUF")
assert companion_assets.is_companion_base(BASE_REPO)
+ for borrowed in ("unsloth/Qwen2.5-VL-7B-Instruct-GGUF", "unsloth/Qwen3-8B-GGUF"):
+ assert companion_assets.is_companion_base(borrowed), borrowed
# --------------------------------------------------------------------------------------------
@@ -428,12 +434,14 @@ def test_a_cached_community_repack_is_a_companion_identity_too(monkeypatch):
"""prefer_cached_legacy_source deliberately sends the native fetch back to a repack an
upgraded install already holds, so on those machines the bytes protecting an installed GGUF
sit under the OLD repo key. Expanding only the upstream/mirror pair left that copy
- unprotected: deletable after unload, and the GGUF stranded."""
+ unprotected: deletable after unload, and the GGUF stranded.
+
+ Synthetic mirror -> repack row: no image asset is a repack any more, but the mechanism is
+ generic and still serves the video rows."""
from core.inference.diffusion_families import legacy_source_repo
- mirror = "unsloth/Z-Image-Turbo-ComfyUI"
- repack = legacy_source_repo(mirror)
- assert repack, "the mirror table no longer names a legacy repack; pick another for this test"
+ repack, mirror = _synthetic_legacy_row(monkeypatch)
+ assert legacy_source_repo(mirror) == repack
companion_assets.record_companion_link(GGUF_REPO, mirror)
_install(
monkeypatch,
@@ -579,19 +587,57 @@ def test_a_gguf_in_a_subdirectory_still_pins_its_base(monkeypatch):
assert asyncio.run(companion_cleanup.orphan_companions_response())["companions"] == []
+_EXAMPLE_ENCODER = "unsloth/FLUX.2-dev-example-encoder"
+_EXAMPLE_VAE = "unsloth/FLUX.2-dev-example-vae"
+_EXAMPLE_REPACK = "some-org/FLUX.2-dev-example-repack"
+
+
+def _synthetic_legacy_row(
+ monkeypatch,
+ mirror = "unsloth/example-repack-mirror",
+ repack = "some-org/example-repack",
+):
+ """(repack, mirror) after adding a made-up mirror -> community repack row to the legacy table."""
+ from core.inference import diffusion_families
+
+ monkeypatch.setitem(diffusion_families._SD_CPP_LEGACY_SOURCES, mirror.lower(), repack)
+ return repack, mirror
+
+
+def _synthetic_flux2_dev_components(monkeypatch):
+ """Point flux.2-dev's sd-cli VAE and encoder at made-up single-file component repos whose ids
+ carry the family keyword. The real assets now live in a vendor base and an encoder GGUF, neither
+ of which reads as a FLUX.2 checkpoint, so this keeps the keyword trap these tests guard covered."""
+ import dataclasses
+
+ from core.inference import diffusion_families
+
+ families = tuple(
+ dataclasses.replace(
+ fam,
+ sd_cpp_vae = (_EXAMPLE_VAE, "vae.safetensors"),
+ sd_cpp_text_encoders = ((_EXAMPLE_ENCODER, "mistral.safetensors", "llm"),),
+ )
+ if fam.name == "flux.2-dev"
+ else fam
+ for fam in diffusion_families._FAMILIES
+ )
+ monkeypatch.setattr(diffusion_families, "_FAMILIES", families)
+ companions = diffusion_families.sd_cpp_companion_only_repo_ids()
+ assert {_EXAMPLE_ENCODER.lower(), _EXAMPLE_VAE.lower()} <= companions
+
+
def test_orphaned_native_components_do_not_hold_each_other_on_disk(monkeypatch):
"""A component repo is a companion, not a checkpoint. Several of those ids carry a family
keyword of their own, so the derivation read a bare text-encoder fetch as an installed model
and recorded the sibling VAE as still required: the pair survived every cleanup pass until the
user happened to remove one of them by hand."""
- encoder = "unsloth/FLUX.2-dev-ComfyUI"
- vae = "unsloth/FLUX.2-VAE"
+ _synthetic_flux2_dev_components(monkeypatch)
+ encoder, vae = _EXAMPLE_ENCODER, _EXAMPLE_VAE
_install(
monkeypatch,
- _repo(
- encoder, [("split_files/text_encoders/mistral_3_small_flux2_bf16.safetensors", 9_000)]
- ),
- _repo(vae, [("split_files/vae/flux2-vae.safetensors", 300_000)]),
+ _repo(encoder, [("mistral.safetensors", 9_000)]),
+ _repo(vae, [("vae.safetensors", 300_000)]),
)
assert companion_cleanup.companion_dependents(vae) == []
offered = {
@@ -604,13 +650,14 @@ def test_orphaned_native_components_do_not_hold_each_other_on_disk(monkeypatch):
def test_a_component_repo_holding_a_checkpoint_is_still_a_checkpoint(monkeypatch):
"""The exclusion above is denoiser-gated, so a curated component id the user really did
install a GGUF from keeps pinning what it needs."""
- encoder = "unsloth/FLUX.2-dev-ComfyUI"
+ _synthetic_flux2_dev_components(monkeypatch)
+ encoder, vae = _EXAMPLE_ENCODER, _EXAMPLE_VAE
_install(
monkeypatch,
- _repo(encoder, [("split_files/diffusion_models/flux2-dev-Q4_K_M.gguf", 8_000_000)]),
- _repo("unsloth/FLUX.2-VAE", [("split_files/vae/flux2-vae.safetensors", 300_000)]),
+ _repo(encoder, [("flux2-dev-Q4_K_M.gguf", 8_000_000)]),
+ _repo(vae, [("vae.safetensors", 300_000)]),
)
- assert companion_cleanup.companion_dependents("unsloth/FLUX.2-VAE") == [encoder]
+ assert companion_cleanup.companion_dependents(vae) == [encoder]
def test_a_vae_only_prequant_fetch_is_not_a_dependent(monkeypatch):
@@ -801,15 +848,15 @@ def test_a_single_file_safetensors_pick_pins_its_base(monkeypatch):
def test_a_legacy_component_repack_is_not_read_as_a_checkpoint(monkeypatch):
"""An upgraded install holds the component under the repack id the native fetch fell back to.
That id matches its family just as literally, so without expanding the exclusion through the
- same mirror identities the orphaned pair kept holding each other on disk."""
- legacy = "Comfy-Org/flux2-dev"
- vae = "unsloth/FLUX.2-VAE"
+ same mirror identities the orphaned pair kept holding each other on disk. Synthetic component
+ repos and repack row, as above."""
+ _synthetic_flux2_dev_components(monkeypatch)
+ legacy, _mirror = _synthetic_legacy_row(monkeypatch, _EXAMPLE_ENCODER, _EXAMPLE_REPACK)
+ vae = _EXAMPLE_VAE
_install(
monkeypatch,
- _repo(
- legacy, [("split_files/text_encoders/mistral_3_small_flux2_bf16.safetensors", 9_000)]
- ),
- _repo(vae, [("split_files/vae/flux2-vae.safetensors", 300_000)]),
+ _repo(legacy, [("mistral.safetensors", 9_000)]),
+ _repo(vae, [("vae.safetensors", 300_000)]),
)
assert companion_cleanup.companion_dependents(vae) == []
offered = {
@@ -951,3 +998,94 @@ def test_the_curated_bases_carry_the_whole_mirror_table():
curated = companion_assets._curated_base_ids()
missing = [rid for pair in _MIRROR_PAIRS for rid in pair if rid not in curated]
assert missing == []
+
+
+# --------------------------------------------------------------------------------------------
+# Mirror targets that are also a model's own GGUF repo (unsloth/Z-Image-GGUF holds the official Tongyi-MAI/Z-Image
+# diffusers folders beside its quants).
+
+
+def test_a_turbo_checkpoint_does_not_depend_on_the_base_whose_name_it_contains():
+ """ "zimage" is inside "zimageturbo": a substring match made a Turbo GGUF depend on Tongyi-MAI/Z-Image too, whose
+ mirror is now the Z-Image GGUF repo, so deleting that unrelated repo was refused while Turbo was installed."""
+ scans = [
+ SimpleNamespace(
+ repos = [_repo("unsloth/Z-Image-Turbo-GGUF", [("z-image-turbo-Q4_K_M.gguf", 5_000)])]
+ )
+ ]
+ required = companion_assets.required_companion_bases(scans)
+ assert "tongyi-mai/z-image-turbo" in required
+ assert "tongyi-mai/z-image" not in required
+ assert "unsloth/z-image-gguf" not in required
+ scans = [
+ SimpleNamespace(
+ repos = [
+ _repo(
+ "unsloth/Qwen-Image-Edit-2511-GGUF",
+ [("qwen-image-edit-2511-Q4_K_M.gguf", 5_000)],
+ )
+ ]
+ )
+ ]
+ required = companion_assets.required_companion_bases(scans)
+ assert "qwen/qwen-image-edit-2511" in required
+ assert "qwen/qwen-image-edit" not in required
+ assert "unsloth/qwen-image-edit-gguf" not in required
+
+
+def test_an_artifact_mirror_checkpoint_still_protects_its_cached_upstream_base():
+ """The GGUF repo canonicalises to its upstream now, but it is a checkpoint in its own right: a cached upstream
+ base it loads from must keep it as a dependent, not be folded into the GGUF's own identity."""
+ scans = [
+ SimpleNamespace(
+ repos = [
+ _repo("unsloth/Z-Image-GGUF", [("z-image-Q4_K_M.gguf", 5_000)]),
+ _base_repo("Tongyi-MAI/Z-Image"),
+ ]
+ )
+ ]
+ required = companion_assets.required_companion_bases(scans)
+ assert required.get("tongyi-mai/z-image") == {"unsloth/Z-Image-GGUF"}
+
+
+ "retired", ["unsloth/Z-Image-Turbo-ComfyUI", "unsloth/flux-text-encoders", "unsloth/FLUX.2-VAE"]
+)
+def test_a_retired_comfy_companion_left_by_a_released_build_is_offered_for_cleanup(
+ monkeypatch, retired
+):
+ """Released builds fetched the sd-cli VAEs and encoders from ComfyUI-built repacks. This build never reads them
+ again, so on an upgraded install they are pure leftovers: they must stay recognised as companions (hidden from the
+ pickers) and be offered by Free up space, not stranded."""
+ from core.inference.diffusion_families import sd_cpp_companion_only_repo_ids
+
+ assert retired.lower() in sd_cpp_companion_only_repo_ids()
+ assert retired.lower() in companion_assets.known_companion_base_ids()
+ _install(monkeypatch, _repo(retired, [("split_files/vae/ae.safetensors", 900_000)]))
+ offered = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ assert [c["repo_id"].lower() for c in offered] == [retired.lower()]
+
+
+def test_a_link_to_a_retired_sd_cli_repack_no_longer_pins_it(monkeypatch):
+ """A released sd.cpp load recorded the repos it fetched its VAE / encoders from. This build never reads them, so a
+ still-installed GGUF must not keep them required: they are offered by Free up space, and the next write drops
+ them from the file."""
+ gguf = "unsloth/Z-Image-Turbo-GGUF"
+ retired = "unsloth/Z-Image-Turbo-ComfyUI"
+ repack = "Comfy-Org/z_image_turbo"
+ for stale in (retired, repack, "Tongyi-MAI/Z-Image-Turbo"):
+ assert companion_assets.record_companion_link(gguf, stale) is True
+ links = companion_assets.read_companion_links()
+ assert links[gguf.lower()] == ["Tongyi-MAI/Z-Image-Turbo"]
+
+ scans = _install(
+ monkeypatch,
+ _repo(gguf, [("z-image-turbo-Q4_K_M.gguf", 5_000)]),
+ _repo(retired, [("split_files/vae/ae.safetensors", 900_000)]),
+ )
+ required = companion_assets.required_companion_bases(scans)
+ assert retired.lower() not in required
+ assert repack.lower() not in required
+ assert required["tongyi-mai/z-image-turbo"] == {gguf}
+ offered = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ assert retired.lower() in [c["repo_id"].lower() for c in offered]
diff --git a/studio/backend/hub/tests/test_model_services.py b/studio/backend/hub/tests/test_model_services.py
index 839888adff0..18501585dbb 100644
--- a/studio/backend/hub/tests/test_model_services.py
+++ b/studio/backend/hub/tests/test_model_services.py
@@ -2781,12 +2781,21 @@ def test_a_companion_mirror_carries_the_flag_on_the_hub_row(monkeypatch, tmp_pat
into. A mirror that reaches this scan must carry it.
Given a config.json, because the real mirrors have none: see the test below for what that
- means today.
+ means today. A synthetic companion id: no image sd-cli asset is a safetensors-only companion repo any more (the
+ encoders are unsloth GGUFs and the VAEs official diffusers files), but the flag still has to reach this row.
"""
+ import core.inference.diffusion_families as families
+
+ real = families.sd_cpp_companion_only_repo_ids
+ monkeypatch.setattr(
+ families,
+ "sd_cpp_companion_only_repo_ids",
+ lambda: real() | {"unsloth/example-vae-companion"},
+ )
row = _diffusion_scan(
monkeypatch,
tmp_path,
- "unsloth/Z-Image-Turbo-ComfyUI",
+ "unsloth/example-vae-companion",
[_file("config.json", 12), _file("model.safetensors", 300_000_000)],
task = None,
)
@@ -8517,3 +8526,37 @@ def test_every_row_key_the_scanner_emits_survives_the_response_schema():
}
assert CachedModelRepo(**row).model_dump()["diffusers"] is True
assert set(CachedGgufRepo.model_fields), "GGUF schema import is load-bearing above"
+
+
+def test_a_gguf_repo_holding_its_bases_companions_is_not_listed_twice(monkeypatch, tmp_path):
+ """unsloth/Z-Image-GGUF is also Tongyi-MAI/Z-Image's mirror, so a GGUF load caches the official companions inside
+ it. Those companions belong to the GGUF row; a second, companion-only pipeline row with the same id would offer a
+ whole-repo delete that also removes the quants."""
+ repo_id = "unsloth/Z-Image-GGUF"
+ files = [
+ _file("z-image-Q4_K_M.gguf", 5_000_000_000),
+ _file("model_index.json", 900),
+ _file("vae/diffusion_pytorch_model.safetensors", 300_000_000),
+ _file("text_encoder/model-00001-of-00003.safetensors", 3_900_000_000),
+ ]
+ repo_path = tmp_path / f"hub/models--{repo_id.replace('/', '--')}"
+ snapshot = repo_path / "snapshots" / _SNAPSHOT_SHA
+ for f in files:
+ target = snapshot / f.file_name
+ target.parent.mkdir(parents = True, exist_ok = True)
+ target.write_bytes(b"\0" * 64)
+ (repo_path / "refs").mkdir(parents = True, exist_ok = True)
+ (repo_path / "refs" / "main").write_text(_SNAPSHOT_SHA)
+ revision = SimpleNamespace(files = files, snapshot_path = snapshot, commit_hash = _SNAPSHOT_SHA)
+ repo = SimpleNamespace(
+ repo_id = repo_id, repo_type = "model", repo_path = repo_path, revisions = [revision]
+ )
+ monkeypatch.setattr(
+ cache_inventory, "all_hf_cache_scans", lambda: [SimpleNamespace(repos = [repo])]
+ )
+ monkeypatch.setattr(
+ cache_inventory.hf_cache_scan, "is_snapshot_partial", lambda *_a, **_k: False
+ )
+ monkeypatch.setattr(cache_inventory, "_cached_row_task", lambda *_a, **_k: "text-to-image")
+ rows = cache_inventory._scan_cached_models(active_hub_cache = tmp_path / "hub")
+ assert [r for r in rows if (r.get("repo_id") or r.get("id")) == repo_id] == []
diff --git a/studio/backend/hub/utils/companion_assets.py b/studio/backend/hub/utils/companion_assets.py
index ebdc4bcea22..0a87972c883 100644
--- a/studio/backend/hub/utils/companion_assets.py
+++ b/studio/backend/hub/utils/companion_assets.py
@@ -54,16 +54,32 @@ def read_companion_links() -> dict[str, list[str]]:
raw = payload.get("links")
if not isinstance(raw, dict):
return {}
+ retired = _retired_link_ids()
links: dict[str, list[str]] = {}
for checkpoint, bases in raw.items():
if not isinstance(checkpoint, str) or not isinstance(bases, list):
continue
- clean = [b.strip() for b in bases if isinstance(b, str) and b.strip()]
+ # A link to a repo nothing loads from any more is dropped on read (and so from the file on the next write):
+ # it would otherwise pin a retired sd-cli repack for as long as the GGUF that once fetched it stays installed.
+ clean = [
+ b.strip()
+ for b in bases
+ if isinstance(b, str) and b.strip() and _normalise(b) not in retired
+ ]
if clean:
links[_normalise(checkpoint)] = clean
return links
+def _retired_link_ids() -> frozenset[str]:
+ """``retired_companion_link_ids``, empty when the family tables are unavailable (every link then counts)."""
+ try:
+ from core.inference.diffusion_families import retired_companion_link_ids
+ return retired_companion_link_ids()
+ except Exception: # noqa: BLE001 -- no table means nothing is known to be retired
+ return frozenset()
+
+
def _write_companion_links(links: dict[str, list[str]]) -> bool:
path = _links_path(create = True)
if path is None:
@@ -144,10 +160,11 @@ _DENOISER_DIRS = ("transformer/", "unet/")
_WEIGHT_SUFFIXES = (".safetensors", ".bin", ".ckpt", ".pt", ".pth", ".gguf")
-def repo_holds_denoiser(repo) -> bool:
+def repo_holds_denoiser(repo, *, folders: bool = True) -> bool:
"""Whether *repo* holds a runnable checkpoint, i.e. is a model the user installed. Beyond the name-only test: a single_file pick caches its checkpoint as ONE top-level file, ``sd_xl_base_1.0.safetensors`` for a whole-pipeline family and ``flux2-dev-fp8.safetensors`` for a transformer-only one, with no denoiser folder to recognise. Those repos are curated companion bases whose self-dependency is dropped, so without this the orphan listing called an installed checkpoint an unused leftover and Free up space deleted it. A companion-only fetch never lands a weight at the snapshot root, and the two ways to be wrong are not symmetric: an orphan we decline to offer costs disk, a checkpoint we offer costs the model. The one root weight that is NOT a checkpoint is the curated component repos' own asset, which is why they are excluded by id: a single-file VAE or text encoder is the companion, and reading it as an installed model is what kept an orphaned pair pinned to disk."""
names = list(_snapshot_relative_names(repo))
- if any(holds_denoiser(name) for name in names):
+ # ``folders=False``: root checkpoints only, for an artifact mirror, whose transformer/ shards are no install.
+ if folders and any(holds_denoiser(name) for name in names):
return True
repo_id = str(getattr(repo, "repo_id", "") or "")
if _normalise(repo_id) in _component_only_repo_ids():
@@ -272,12 +289,16 @@ def _curated_variant_bases(fam, repo_id: str, gguf_filename: Optional[str]) -> s
if not family:
return set()
identity = f"{_fold(repo_id)} {_fold(gguf_filename or '')}"
- out: set[str] = set()
+ hits: list[tuple[str, str]] = []
for candidate in _curated_base_ids():
name = _fold(candidate.rsplit("/", 1)[-1])
if name and name.startswith(family) and name in identity:
- out.add(candidate)
- return out
+ hits.append((candidate, name))
+ # Most specific spelling only: "zimage" is inside "zimageturbo" and "qwenimageedit" inside "qwenimageedit2511", so
+ # a plain substring test made a Turbo / 2511 checkpoint depend on the Z-Image / Edit base as well, and since those
+ # bases' mirrors are now the Z-Image / Edit GGUF repos, the delete of an unrelated GGUF repo was refused.
+ names = {name for _c, name in hits}
+ return {c for c, name in hits if not any(name != other and name in other for other in names)}
def _fold(text: str) -> str:
@@ -444,7 +465,10 @@ def required_companion_bases(
if recorded:
bases |= _with_mirrors(recorded)
# Canonical, not literal: a cached MIRROR resolves its own family back to the UPSTREAM id, which would make each identity a dependent of the other and leave a cache holding both stuck.
- self_keys = {key, _normalise(_canonical(repo_id))}
+ # Except an artifact-hosting mirror (unsloth/Z-Image-GGUF): it is a checkpoint in its own right, and folding it
+ # onto its upstream would leave a cached upstream base with no dependent, offered for deletion while the GGUF
+ # still loads from it.
+ self_keys = {key} if _hosts_artifacts(repo_id) else {key, _normalise(_canonical(repo_id))}
for base in bases:
base_key = _normalise(base)
if not base_key or base_key in self_keys or _normalise(_canonical(base)) in self_keys:
@@ -453,6 +477,15 @@ def required_companion_bases(
return required
+def _hosts_artifacts(repo_id: str) -> bool:
+ """``mirror_hosts_artifacts``, False when the family tables are unavailable."""
+ try:
+ from core.inference.diffusion_families import mirror_hosts_artifacts
+ return mirror_hosts_artifacts(repo_id)
+ except Exception: # noqa: BLE001 -- no table means no artifact mirrors
+ return False
+
+
def _canonical(repo_id: str) -> str:
"""``canonical_base``, degrading to the id itself when the family tables are unavailable."""
try:
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index b0779d889a5..9b85dd5bd48 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -5498,6 +5498,15 @@ def _repo_model_can_chat(repo_info, selected: Optional[Path] = None) -> Optional
return None
+def _repo_hosts_artifacts(repo_id: str) -> bool:
+ """``mirror_hosts_artifacts``, False when the family tables are unavailable."""
+ try:
+ from core.inference.diffusion_families import mirror_hosts_artifacts
+ return mirror_hosts_artifacts(repo_id)
+ except Exception: # noqa: BLE001 -- no table means no artifact mirrors
+ return False
+
+
def cached_model_rows(cache_scans = None) -> list[dict]:
_WEIGHT_EXTENSIONS = _NON_GGUF_WEIGHT_EXTENSIONS
if cache_scans is None:
@@ -5508,6 +5517,14 @@ def cached_model_rows(cache_scans = None) -> list[dict]:
active_root = None
seen_lower: dict[str, dict] = {}
+ cache_scans = list(cache_scans)
+ # Across EVERY root, as the cached-model scan decides it: an artifact mirror whose GGUF sits in one root and
+ # whose diffusers folders sit in the other is a GGUF repo, so its folders-only copy is no row of this listing.
+ try:
+ from hub.services.models.cache_inventory import _artifact_gguf_repo_ids
+ artifact_gguf_keys = _artifact_gguf_repo_ids(cache_scans)
+ except Exception: # noqa: BLE001 -- no table means no artifact mirrors
+ artifact_gguf_keys = set()
for hf_cache in cache_scans:
for repo_info in hf_cache.repos:
try:
@@ -5519,6 +5536,9 @@ def cached_model_rows(cache_scans = None) -> list[dict]:
continue
if _repo_has_gguf_files(repo_info):
continue
+ # Its GGUF in another root: listed (its delete is scoped to this root and frees what it shows) but as
+ # a companion of that GGUF, never a single-file or pipeline pick.
+ cross_root_folders = repo_id.lower() in artifact_gguf_keys
selected, model_load_id = _repo_model_selection(repo_info, active_root)
if _recovered_repo_is_unusable_by_repo_id(repo_info):
# That guard withheld these because this schema could describe neither a partial nor a path; it now
@@ -5546,9 +5566,12 @@ def cached_model_rows(cache_scans = None) -> list[dict]:
key = repo_id.lower()
existing = seen_lower.get(key)
# A companion-only prefetch (manifest + VAE/TE but no transformer shards) is not a loadable pipeline; treat it as partial.
- is_partial = _cached_repo_partial(
- repo_id, Path(repo_info.repo_path), selected
- ) or _repo_pipeline_missing_denoiser(repo_info, selected)
+ # The FP8 artifact mirror lists as its root checkpoint, as released builds did: its diffusers folders
+ # belong to the BASE pick, and a pipeline pick of the repo itself is refused.
+ artifact_checkpoint = _repo_hosts_artifacts(repo_id) and not cross_root_folders
+ is_partial = _cached_repo_partial(repo_id, Path(repo_info.repo_path), selected) or (
+ not artifact_checkpoint and _repo_pipeline_missing_denoiser(repo_info, selected)
+ )
# Prefer the most COMPLETE snapshot, then largest: a partial copy in one cache root must not shadow a complete copy in another.
if existing is None or (not is_partial, total_size) > (
not bool(existing.get("partial")),
@@ -5556,13 +5579,17 @@ def cached_model_rows(cache_scans = None) -> list[dict]:
):
row_task = _cached_repo_task(repo_info, selected)
is_diffusers = _repo_is_diffusers(repo_info, selected)
- has_pipeline_index = _repo_has_pipeline_index(repo_info, selected)
+ has_pipeline_index = not artifact_checkpoint and _repo_has_pipeline_index(
+ repo_info, selected
+ )
row = {
"repo_id": repo_id,
"size_bytes": total_size,
"task": row_task,
}
- pipeline_artifact_kind = _diffusers_pipeline_artifact_kind(selected)
+ pipeline_artifact_kind = (
+ None if artifact_checkpoint else _diffusers_pipeline_artifact_kind(selected)
+ )
if pipeline_artifact_kind is not None:
row["artifact_kind"] = pipeline_artifact_kind
# Pin a copy its bare id cannot reach, so the pick loads the found snapshot.
@@ -5584,7 +5611,7 @@ def cached_model_rows(cache_scans = None) -> list[dict]:
row["partial"] = True
# Listed, so tens of GB of companion weights stay visible and deletable,
# but flagged, so no picker offers a denoiser-less repo as a load.
- if _is_sd_cpp_companion_repo(repo_id):
+ if _is_sd_cpp_companion_repo(repo_id) or cross_root_folders:
row["companion"] = True
# Flag diffusion repos with no pipeline index: loadable only via from_single_file, so pickers must not offer a pipeline load.
if row["task"] is not None and not has_pipeline_index:
diff --git a/studio/backend/tests/test_artifact_mirrors.py b/studio/backend/tests/test_artifact_mirrors.py
new file mode 100644
index 00000000000..c7892764f64
--- /dev/null
+++ b/studio/backend/tests/test_artifact_mirrors.py
@@ -0,0 +1,927 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Mirror targets that are also a model's own artifact repo (GGUF / FP8 checkpoints at the root, the official
+diffusers folders beside them): the opt-out must not rewrite them, and pipeline sizing must not count the quants."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from core.inference import diffusion_families as df
+from core.inference.diffusion import DiffusionBackend
+
+
+def test_the_new_targets_are_artifact_mirrors_and_the_old_full_mirrors_are_not():
+ for repo in (
+ "unsloth/Z-Image-GGUF",
+ "unsloth/Qwen-Image-Edit-GGUF",
+ "unsloth/Qwen-Image-Edit-2509-GGUF",
+ "unsloth/Qwen-Image-Layered-GGUF",
+ "unsloth/Qwen-Image-2.1-Turbo-FP8",
+ ):
+ assert df.mirror_hosts_artifacts(repo), repo
+ assert df.mirror_hosts_artifacts(repo.lower()), repo
+ for repo in (
+ "unsloth/Z-Image-Turbo",
+ "unsloth/FLUX.1-dev",
+ "unsloth/Qwen-Image",
+ "unsloth/Z-Image-Turbo-GGUF",
+ ):
+ assert not df.mirror_hosts_artifacts(repo), repo
+
+
+def test_the_opt_out_keeps_an_artifact_repo_and_still_unmirrors_a_full_mirror(monkeypatch):
+ """Under UNSLOTH_DIFFUSION_NO_MIRROR a pure mirror maps back to its upstream, but unsloth/Z-Image-GGUF holds the
+ GGUF being loaded, which Tongyi-MAI/Z-Image does not have: rewriting it 404s the denoiser fetch."""
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_NO_MIRROR", "1")
+ assert df.prefer_ungated_mirror("unsloth/Z-Image-GGUF") == "unsloth/Z-Image-GGUF"
+ assert (
+ df.prefer_ungated_mirror("unsloth/Qwen-Image-2.1-Turbo-FP8")
+ == "unsloth/Qwen-Image-2.1-Turbo-FP8"
+ )
+ assert df.prefer_ungated_mirror("unsloth/Z-Image-Turbo") == "Tongyi-MAI/Z-Image-Turbo"
+ assert df.prefer_ungated_mirror("Tongyi-MAI/Z-Image") == "Tongyi-MAI/Z-Image"
+
+
+def _snapshot(root: Path, repo: str, files: dict[str, int]) -> None:
+ repo_dir = root / f"models--{repo.replace('/', '--')}"
+ snap = repo_dir / "snapshots" / "rev1"
+ for name, size in files.items():
+ p = snap / name
+ p.parent.mkdir(parents = True, exist_ok = True)
+ p.write_bytes(b"\0" * size)
+ (repo_dir / "refs").mkdir(parents = True, exist_ok = True)
+ (repo_dir / "refs" / "main").write_text("rev1")
+
+
+def test_pipeline_sizing_of_an_artifact_repo_counts_only_the_diffusers_part(monkeypatch, tmp_path):
+ _snapshot(
+ tmp_path,
+ "unsloth/Z-Image-GGUF",
+ {
+ "z-image-Q4_K_M.gguf": 5000,
+ "z-image-Q8_0.gguf": 8000,
+ "README.md": 10,
+ "model_index.json": 7,
+ "vae/diffusion_pytorch_model.safetensors": 300,
+ "text_encoder/model.safetensors": 600,
+ },
+ )
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_hub_cache_repo_dirs",
+ staticmethod(lambda repo_id: [tmp_path / f"models--{repo_id.replace('/', '--')}"]),
+ )
+ assert DiffusionBackend._cache_bytes("unsloth/Z-Image-GGUF") == 13917
+ assert DiffusionBackend._cache_bytes("unsloth/Z-Image-GGUF", pipeline_only = True) == 907
+
+
+def test_a_direct_pipeline_pick_of_an_artifact_repo_is_still_refused():
+ """The official folders inside unsloth/Qwen-Image-2.1-Turbo-FP8 are what a pick of Qwen/Qwen-Image-2.1-Turbo
+ fetches; naming the FP8 repo itself as a pipeline stays refused, as it was before the folders arrived. The GGUF
+ repos keep their own -GGUF refusal."""
+ assert "unsloth/qwen-image-2.1-turbo-fp8" in df.prequant_only_repo_ids()
+ backend = DiffusionBackend()
+ with pytest.raises(ValueError, match = "pre-quantised"):
+ backend.validate_load_request("unsloth/Qwen-Image-2.1-Turbo-FP8", model_kind = "pipeline")
+ for repo in (
+ "unsloth/Z-Image-GGUF",
+ "unsloth/Qwen-Image-Edit-GGUF",
+ "unsloth/Qwen-Image-Edit-2509-GGUF",
+ "unsloth/Qwen-Image-Layered-GGUF",
+ ):
+ with pytest.raises(ValueError):
+ backend.validate_load_request(repo, model_kind = "pipeline")
+ # and the base pick itself still validates
+ assert (
+ backend.validate_load_request("Qwen/Qwen-Image-2.1-Turbo", model_kind = "pipeline").name
+ == "qwen-image-2.1"
+ )
+
+
+def test_a_full_mirror_whose_upstream_name_ends_in_fp8_is_not_an_artifact_mirror(monkeypatch):
+ """unsloth/ideogram-4-fp8 is a complete copy of ideogram-ai/ideogram-4-fp8 (the suffix is in the upstream name),
+ so the opt-out still maps it back to the upstream, as for every full mirror."""
+ assert not df.mirror_hosts_artifacts("unsloth/ideogram-4-fp8")
+ assert df.mirror_repo("ideogram-ai/ideogram-4-fp8") == "unsloth/ideogram-4-fp8"
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_NO_MIRROR", "1")
+ assert df.prefer_ungated_mirror("unsloth/ideogram-4-fp8") == "ideogram-ai/ideogram-4-fp8"
+ # Every artifact mirror is a mirror target the table actually names.
+ targets = {m.lower() for _u, m in df._MIRROR_PAIRS}
+ assert df._ARTIFACT_MIRRORS <= targets
+
+
+_FP8_REPO = "unsloth/Qwen-Image-2.1-Turbo-FP8"
+_FP8_ROOT = {"qwen-image-2.1-turbo-fp8.safetensors": 4000, "README.md": 10}
+_FOLDERS = {
+ "model_index.json": 1,
+ "vae/config.json": 2,
+ "vae/diffusion_pytorch_model.safetensors": 300,
+ "text_encoder/config.json": 2,
+ "text_encoder/model.safetensors": 600,
+}
+_DENOISER = {
+ "transformer/config.json": 2,
+ "transformer/diffusion_pytorch_model.safetensors": 2000,
+}
+
+
+def _cache_repo(root: Path, repo: str, files: dict[str, int]):
+ from types import SimpleNamespace
+
+ _snapshot(root, repo, files)
+ repo_dir = root / f"models--{repo.replace('/', '--')}"
+ snap = repo_dir / "snapshots" / "rev1"
+ if "model_index.json" in files:
+ (snap / "model_index.json").write_text(
+ '{"_class_name": "QwenImagePipeline", "transformer": ["diffusers", "QwenImageTransformer2DModel"]}'
+ )
+ listed = [
+ SimpleNamespace(
+ file_name = name.rsplit("/", 1)[-1],
+ file_path = snap / name,
+ blob_path = str(snap / name),
+ size_on_disk = size,
+ )
+ for name, size in files.items()
+ ]
+ return SimpleNamespace(
+ repo_id = repo,
+ repo_type = "model",
+ repo_path = repo_dir,
+ revisions = [SimpleNamespace(files = listed, snapshot_path = snap, commit_hash = "rev1")],
+ )
+
+
+def _inventory_row(monkeypatch, tmp_path, repo: str, files: dict[str, int]) -> dict:
+ from types import SimpleNamespace
+
+ from hub.services.models import cache_inventory
+
+ cached = _cache_repo(tmp_path, repo, files)
+ monkeypatch.setattr(
+ cache_inventory, "all_hf_cache_scans", lambda: [SimpleNamespace(repos = [cached])]
+ )
+ monkeypatch.setattr(
+ cache_inventory.hf_cache_scan, "is_snapshot_partial", lambda *_a, **_k: False
+ )
+ monkeypatch.setattr(cache_inventory, "_cached_row_task", lambda *_a, **_k: "text-to-image")
+ rows = [
+ r
+ for r in cache_inventory._scan_cached_models(active_hub_cache = tmp_path)
+ if r["repo_id"] == repo
+ ]
+ assert len(rows) == 1
+ return rows[0]
+
+
+def _route_row(monkeypatch, tmp_path, repo: str, files: dict[str, int]) -> dict:
+ from types import SimpleNamespace
+
+ import routes.models as models_route
+
+ cached = _cache_repo(tmp_path, repo, files)
+ monkeypatch.setattr(models_route, "_resolve_hf_cache_dir", lambda: tmp_path)
+ monkeypatch.setattr(models_route, "_cached_repo_task", lambda *_a, **_k: "text-to-image")
+ monkeypatch.setattr(models_route, "_cached_repo_partial", lambda *_a, **_k: False)
+ monkeypatch.setattr(models_route.account_access, "filter_model_rows", lambda rows: rows)
+ rows = [
+ r
+ for r in models_route.cached_model_rows([SimpleNamespace(repos = [cached])])
+ if r["repo_id"] == repo
+ ]
+ assert len(rows) == 1
+ return rows[0]
+
+
[email protected]("cached", ["companions", "full"])
[email protected]("scan", [_inventory_row, _route_row])
+def test_the_fp8_artifact_mirror_lists_as_its_checkpoint_not_as_a_pipeline(
+ monkeypatch, tmp_path, scan, cached
+):
+ """The Turbo base's folders sit inside unsloth/Qwen-Image-2.1-Turbo-FP8, but a pipeline pick of that id is refused.
+ Whatever part of them is cached, the row is the single-file checkpoint row (the shape the compatibility listing
+ gave the FP8 repo before the folders arrived): visible and deletable, never offered as a pipeline load the backend
+ rejects, never a companion-prefetch partial."""
+ files = {**_FP8_ROOT, **_FOLDERS, **(_DENOISER if cached == "full" else {})}
+ row = scan(monkeypatch, tmp_path, _FP8_REPO, files)
+ assert row["single_file"] is True
+ assert not row.get("partial")
+ assert not row.get("companion_prefetch")
+ assert row.get("artifact_kind") in (None, "unknown")
+ assert row.get("load_id") in (None, row["repo_id"])
+ if scan is _route_row:
+ released = scan(monkeypatch, tmp_path / "released", _FP8_REPO, dict(_FP8_ROOT))
+ assert {
+ k: released.get(k) for k in ("task", "single_file", "partial", "artifact_kind")
+ } == {k: row.get(k) for k in ("task", "single_file", "partial", "artifact_kind")}
+
+
[email protected]("cached", ["companions", "full"])
+def test_a_gguf_artifact_mirror_lists_only_its_gguf_row_which_counts_the_folders(
+ monkeypatch, tmp_path, cached
+):
+ """A bf16 pick of Tongyi-MAI/Z-Image caches the base's folders inside unsloth/Z-Image-GGUF. Deletes are whole-repo
+ or per-quant, so a second, non-GGUF row for those folders would delete the quants with them, and a pipeline pick
+ of the -GGUF id is refused. The folders fold into the GGUF row instead, whose size counts them."""
+ from types import SimpleNamespace
+
+ from hub.services.models import cache_inventory
+
+ repo = "unsloth/Z-Image-GGUF"
+ files = {"z-image-Q4_K_M.gguf": 5000, **_FOLDERS, **(_DENOISER if cached == "full" else {})}
+ cached_repo = _cache_repo(tmp_path, repo, files)
+ monkeypatch.setattr(
+ cache_inventory, "all_hf_cache_scans", lambda: [SimpleNamespace(repos = [cached_repo])]
+ )
+ monkeypatch.setattr(
+ cache_inventory.hf_cache_scan, "is_snapshot_partial", lambda *_a, **_k: False
+ )
+ monkeypatch.setattr(cache_inventory, "_cached_row_task", lambda *_a, **_k: "text-to-image")
+ assert [
+ r
+ for r in cache_inventory._scan_cached_models(active_hub_cache = tmp_path)
+ if r["repo_id"] == repo
+ ] == []
+ gguf_rows = [
+ r
+ for r in cache_inventory._scan_cached_gguf(active_hub_cache = tmp_path)
+ if r["repo_id"] == repo
+ ]
+ assert len(gguf_rows) == 1
+ # model_index.json is rewritten with real JSON, so count every other file exactly and that one as present.
+ assert gguf_rows[0]["size_bytes"] > sum(v for k, v in files.items() if k != "model_index.json")
+
+
[email protected]("cached", ["companions", "full"])
+def test_on_device_lists_an_artifact_mirror_as_its_checkpoint_only(tmp_path, cached):
+ """The On Device scan applies the same rule: the GGUF repo shows only its GGUF row (folders counted), and the FP8
+ repo's row is never a loadable or resumable pipeline. A snapshot with no folders is left as released builds
+ listed it."""
+ from hub.services.models import local_inventory
+
+ extra = {**_FOLDERS, **(_DENOISER if cached == "full" else {})}
+ gguf_files = {"z-image-Q4_K_M.gguf": 5000, **extra}
+ _cache_repo(tmp_path / "gguf", "unsloth/Z-Image-GGUF", gguf_files)
+ rows = local_inventory._scan_hf_cache(tmp_path / "gguf")
+ assert [r.model_format for r in rows] == ["gguf"]
+ assert rows[0].size_bytes > sum(v for k, v in gguf_files.items() if k != "model_index.json")
+
+ _cache_repo(tmp_path / "fp8", _FP8_REPO, {**_FP8_ROOT, **extra})
+ rows = local_inventory._scan_hf_cache(tmp_path / "fp8")
+ assert rows and all(r.partial and r.companion_prefetch for r in rows)
+
+ _cache_repo(tmp_path / "released", _FP8_REPO, dict(_FP8_ROOT))
+ _cache_repo(tmp_path / "released-other", "unsloth/Some-Model-FP8", dict(_FP8_ROOT))
+ released = local_inventory._scan_hf_cache(tmp_path / "released")
+ baseline = local_inventory._scan_hf_cache(tmp_path / "released-other")
+ assert [(r.model_format, r.partial, r.companion_prefetch) for r in released] == [
+ (r.model_format, r.partial, r.companion_prefetch) for r in baseline
+ ]
+
+
+def test_load_progress_through_an_artifact_mirror_counts_only_the_pipeline_part(
+ monkeypatch, tmp_path
+):
+ """A bf16 Turbo load fetches only the diffusers folders of unsloth/Qwen-Image-2.1-Turbo-FP8, so expected_bytes
+ counts only those. FP8 / INT8 checkpoints already cached at the repo root must not count toward progress, while
+ the blob downloading right now must."""
+ from core.inference.diffusion import _LoadingState
+
+ pipeline = {
+ "model_index.json": 7,
+ "vae/diffusion_pytorch_model.safetensors": 300,
+ "text_encoder/model.safetensors": 600,
+ }
+ # Sample renders and the root checkpoint are cached too; neither is a pipeline file the plan counted.
+ _snapshot(
+ tmp_path,
+ _FP8_REPO,
+ {
+ **pipeline,
+ "qwen-image-2.1-turbo-fp8.safetensors": 50_000,
+ "samples/fp8_1.png": 20_000,
+ "assets/preview.png": 20_000,
+ },
+ )
+ blobs = tmp_path / f"models--{_FP8_REPO.replace('/', '--')}" / "blobs"
+ blobs.mkdir(parents = True, exist_ok = True)
+ (blobs / "abc.incomplete").write_bytes(b"\0" * 1_000)
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_hub_cache_repo_dirs",
+ staticmethod(lambda repo_id: [tmp_path / f"models--{repo_id.replace('/', '--')}"]),
+ )
+ backend = DiffusionBackend()
+ base = "Qwen/Qwen-Image-2.1-Turbo"
+ backend._loading = _LoadingState(
+ repo_id = base, base_repo = base, fetch_repo = _FP8_REPO, expected_bytes = 10_000
+ )
+ progress = backend.load_progress()
+ assert progress["phase"] == "downloading"
+ assert progress["bytes_downloaded"] == sum(pipeline.values()) + 1_000
+
+
+def test_on_device_keeps_a_gguf_cached_in_an_older_revision_than_the_folders(tmp_path):
+ """An install that cached a quant before the diffusers folders were added, then a base pick that fetched those
+ folders from the newer revision: the newest snapshot holds only folders, the quant sits in the older one. The GGUF
+ row must survive, with the folders counted, rather than leave only a partial companion row."""
+ from hub.services.models import local_inventory
+
+ repo_dir = tmp_path / "models--unsloth--Z-Image-GGUF"
+ old = repo_dir / "snapshots" / "rev-old"
+ new = repo_dir / "snapshots" / "rev-new"
+ (old).mkdir(parents = True)
+ (old / "z-image-Q4_K_M.gguf").write_bytes(b"\0" * 5_000)
+ for name, size in {**_FOLDERS, **_DENOISER}.items():
+ p = new / name
+ p.parent.mkdir(parents = True, exist_ok = True)
+ p.write_bytes(b"\0" * size)
+ (new / "model_index.json").write_text('{"_class_name": "ZImagePipeline"}')
+ (repo_dir / "refs").mkdir()
+ (repo_dir / "refs" / "main").write_text("rev-new")
+ import os
+
+ os.utime(old, (1, 1))
+
+ rows = local_inventory._scan_hf_cache(tmp_path)
+ assert [r.model_format for r in rows] == ["gguf"]
+ assert rows[0].size_bytes > 5_000 + sum(v for k, v in _DENOISER.items())
+ assert not rows[0].partial
+
+
[email protected]("repo", sorted(df._ARTIFACT_MIRRORS))
+def test_every_artifact_mirror_is_refused_as_a_pipeline_pick(repo):
+ """Its folders are its base's pipeline, reached by picking the base. An explicit pipeline pick of the repo id
+ itself is refused, naming that base, for the -GGUF mirrors as for the FP8 one."""
+ assert repo in df.prequant_only_repo_ids()
+ with pytest.raises(ValueError, match = "pre-quantised") as excinfo:
+ DiffusionBackend().validate_load_request(repo, model_kind = "pipeline")
+ assert df.canonical_base(repo).lower() in str(excinfo.value).lower()
+
+
+def test_progress_of_a_gguf_picked_from_an_artifact_mirror_counts_only_what_it_loads(
+ monkeypatch, tmp_path
+):
+ """unsloth/Z-Image-GGUF is both the pick and its base's companion repo. A sibling quant and the sample renders
+ already cached there are not part of this load; the selected quant, the pipeline folders and the in-flight blob
+ are."""
+ from core.inference.diffusion import _LoadingState
+
+ repo = "unsloth/Z-Image-GGUF"
+ pipeline = {"model_index.json": 7, "vae/diffusion_pytorch_model.safetensors": 300}
+ _snapshot(
+ tmp_path,
+ repo,
+ {
+ **pipeline,
+ "z-image-Q4_K_M.gguf": 5_000,
+ "z-image-Q8_0.gguf": 80_000,
+ "samples/q4.png": 20_000,
+ "assets/preview.png": 20_000,
+ },
+ )
+ blobs = tmp_path / f"models--{repo.replace('/', '--')}" / "blobs"
+ blobs.mkdir(parents = True, exist_ok = True)
+ (blobs / "def.incomplete").write_bytes(b"\0" * 1_000)
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_hub_cache_repo_dirs",
+ staticmethod(lambda repo_id: [tmp_path / f"models--{repo_id.replace('/', '--')}"]),
+ )
+ backend = DiffusionBackend()
+ backend._loading = _LoadingState(
+ repo_id = repo,
+ base_repo = "Tongyi-MAI/Z-Image",
+ fetch_repo = repo,
+ gguf_filename = "z-image-Q4_K_M.gguf",
+ expected_bytes = 50_000,
+ )
+ progress = backend.load_progress()
+ assert progress["phase"] == "downloading"
+ assert progress["bytes_downloaded"] == 5_000 + sum(pipeline.values()) + 1_000
+
+
+def test_a_gguf_and_its_folders_split_across_cache_roots_keep_one_row_per_root(
+ monkeypatch, tmp_path
+):
+ """The quant cached in one root, the base's folders (fetched after a cache-folder change) in the other. A delete
+ is scoped to one cache root, so each root keeps its own row and each row's size is what its delete frees: the
+ GGUF row counts only its own root, and the folders copy is the GGUF's companion, never a pick."""
+ from types import SimpleNamespace
+
+ from hub.services.models import cache_inventory, local_inventory
+
+ repo = "unsloth/Z-Image-GGUF"
+ gguf_root, folder_root = tmp_path / "old", tmp_path / "live"
+ folders = {**_FOLDERS, **_DENOISER}
+ in_gguf_root = _cache_repo(gguf_root, repo, {"z-image-Q4_K_M.gguf": 5_000})
+ in_folder_root = _cache_repo(folder_root, repo, folders)
+ folder_bytes = sum(v for k, v in folders.items() if k != "model_index.json")
+
+ scans = [SimpleNamespace(repos = [in_gguf_root]), SimpleNamespace(repos = [in_folder_root])]
+ monkeypatch.setattr(cache_inventory, "all_hf_cache_scans", lambda: scans)
+ monkeypatch.setattr(
+ cache_inventory.hf_cache_scan, "is_snapshot_partial", lambda *_a, **_k: False
+ )
+ monkeypatch.setattr(cache_inventory, "_cached_row_task", lambda *_a, **_k: "text-to-image")
+ folder_rows = [
+ r
+ for r in cache_inventory._scan_cached_models(active_hub_cache = folder_root)
+ if r["repo_id"] == repo
+ ]
+ assert len(folder_rows) == 1
+ assert folder_rows[0]["companion"] is True and not folder_rows[0]["single_file"]
+ assert folder_rows[0]["cache_path"] == str(in_folder_root.repo_path)
+ assert folder_rows[0]["size_bytes"] > 0
+ gguf_rows = [
+ r
+ for r in cache_inventory._scan_cached_gguf(active_hub_cache = folder_root)
+ if r["repo_id"] == repo
+ ]
+ assert len(gguf_rows) == 1
+ assert gguf_rows[0]["size_bytes"] == 5_000
+ assert gguf_rows[0]["cache_path"] == str(in_gguf_root.repo_path)
+
+ merged = local_inventory._merge_artifact_mirror_roots(
+ [
+ (gguf_root, local_inventory._scan_hf_cache(gguf_root)),
+ (folder_root, local_inventory._scan_hf_cache(folder_root)),
+ ]
+ )
+ rows = [r for r in merged if r.model_id == repo]
+ gguf = [r for r in rows if r.model_format == "gguf"]
+ others = [r for r in rows if r.model_format != "gguf"]
+ assert len(gguf) == 1 and gguf[0].size_bytes == 5_000
+ assert others and all(r.partial and r.companion_prefetch for r in others)
+
+
+def test_a_custom_folder_with_the_gguf_and_folders_in_two_caches_keeps_one_row_per_cache(tmp_path):
+ """A registered custom scan folder can hold several HF caches; the GGUF in one and the mirror's folders in the
+ other are treated like the top-level roots: the GGUF row counts only its own cache, and any folders row is the
+ GGUF's companion prefetch, never a pick."""
+ from hub.services.models import local_inventory
+
+ repo = "unsloth/Z-Image-GGUF"
+ folder = tmp_path / "models"
+ first, second = folder / "a" / "hub", folder / "b" / "hub"
+ folders = {**_FOLDERS, **_DENOISER}
+ _cache_repo(first, repo, {"z-image-Q4_K_M.gguf": 5_000})
+ _cache_repo(second, repo, folders)
+ folder_bytes = sum(v for k, v in folders.items() if k != "model_index.json")
+
+ rows = [
+ r
+ for r in local_inventory._scan_custom_folder(
+ folder, hf_caches = [(first, None), (second, None)]
+ )
+ if r.model_id == repo
+ ]
+ gguf = [r for r in rows if r.model_format == "gguf"]
+ assert len(gguf) == 1 and gguf[0].size_bytes == 5_000
+ assert all(r.partial and r.companion_prefetch for r in rows if r.model_format != "gguf")
+ assert folder_bytes > 0
+
+
+_SHAPES = {
+ # A bf16 pipeline whose files come from the FP8 artifact mirror (root checkpoints + samples cached beside them).
+ "pipeline-through-mirror": dict(
+ repo_id = "Qwen/Qwen-Image-2.1-Turbo",
+ gguf = None,
+ kind = "pipeline",
+ base = "Qwen/Qwen-Image-2.1-Turbo",
+ fetch = _FP8_REPO,
+ base_files = {
+ "model_index.json": 7,
+ "transformer/diffusion_pytorch_model.safetensors": 4_000,
+ "vae/diffusion_pytorch_model.safetensors": 300,
+ },
+ dit = None,
+ extra = {_FP8_REPO: {"Qwen-Image-2.1-Turbo-FP8.safetensors": 7_000, "samples/a.png": 900}},
+ ),
+ # A GGUF picked from the artifact mirror that is also its companion repo (sibling quant + samples cached).
+ "gguf-from-mirror": dict(
+ repo_id = "unsloth/Z-Image-GGUF",
+ gguf = "z-image-Q4_K_M.gguf",
+ gguf_size = 5_000,
+ kind = "gguf",
+ base = "Tongyi-MAI/Z-Image",
+ fetch = "unsloth/Z-Image-GGUF",
+ base_files = {"model_index.json": 7, "vae/diffusion_pytorch_model.safetensors": 300},
+ dit = None,
+ extra = {"unsloth/Z-Image-GGUF": {"z-image-Q8_0.gguf": 9_000, "assets/a.png": 900}},
+ ),
+ # The Turbo pipeline with its hosted FP8 denoiser: companion and denoiser repo are the same mirror.
+ "prequant-in-the-companion-repo": dict(
+ repo_id = "Qwen/Qwen-Image-2.1-Turbo",
+ gguf = None,
+ kind = "pipeline",
+ base = "Qwen/Qwen-Image-2.1-Turbo",
+ fetch = _FP8_REPO,
+ base_files = {
+ "model_index.json": 7,
+ "transformer/config.json": 2,
+ "vae/diffusion_pytorch_model.safetensors": 300,
+ },
+ dit = (_FP8_REPO, "Qwen-Image-2.1-Turbo-FP8.safetensors", 7_000),
+ extra = {_FP8_REPO: {"Qwen-Image-2.1-Turbo-INT8.safetensors": 7_100, "samples/a.png": 900}},
+ ),
+ # A plain GGUF repo with its base on an ordinary full mirror.
+ "plain-gguf": dict(
+ repo_id = "unsloth/FLUX.1-dev-GGUF",
+ gguf = "flux1-dev-Q4_K_M.gguf",
+ gguf_size = 6_000,
+ kind = "gguf",
+ base = "black-forest-labs/FLUX.1-dev",
+ fetch = "unsloth/FLUX.1-dev",
+ base_files = {"model_index.json": 7, "text_encoder/model.safetensors": 2_000},
+ dit = None,
+ extra = {"unsloth/FLUX.1-dev-GGUF": {"flux1-dev-Q8_0.gguf": 11_000}},
+ ),
+}
+
+
[email protected]("shape", sorted(_SHAPES))
+def test_progress_reaches_expected_exactly_when_every_planned_file_is_cached(
+ monkeypatch, tmp_path, shape
+):
+ """expected_bytes and the progress scan come from ONE list of planned files, so whatever else the repos hold
+ (sibling quants, other prequant schemes, sample renders), downloaded equals expected once every planned file is
+ cached, and stays below it while one is still in flight."""
+ from core.inference.diffusion import _LoadingState, _planned_progress_files
+
+ s = _SHAPES[shape]
+ file_sizes = {s["base"]: dict(s["base_files"])}
+ if s["gguf"]:
+ file_sizes[s["repo_id"]] = {s["gguf"]: s["gguf_size"]}
+ planned = _planned_progress_files(
+ s["repo_id"],
+ s["gguf"],
+ kind = s["kind"],
+ base = s["base"],
+ fetch_base = s["fetch"],
+ base_files = list(s["base_files"]),
+ file_sizes = file_sizes,
+ dit_prequant = s["dit"],
+ )
+ on_disk: dict[str, dict[str, int]] = {}
+ for repo, name, size in planned:
+ on_disk.setdefault(repo, {})[name] = size
+ for repo, files in s["extra"].items():
+ on_disk.setdefault(repo, {}).update(files)
+ for repo, files in on_disk.items():
+ _snapshot(tmp_path, repo, files)
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_hub_cache_repo_dirs",
+ staticmethod(lambda repo_id: [tmp_path / f"models--{repo_id.replace('/', '--')}"]),
+ )
+ expected = sum(size for _r, _n, size in planned)
+ backend = DiffusionBackend()
+ backend._loading = _LoadingState(
+ repo_id = s["repo_id"],
+ base_repo = s["base"],
+ fetch_repo = s["fetch"],
+ gguf_filename = s["gguf"],
+ planned_files = planned,
+ expected_bytes = expected,
+ )
+ done = backend.load_progress()
+ assert done["bytes_downloaded"] == expected and done["phase"] == "finalizing"
+
+ # The largest planned file back in flight: half of it written, the snapshot entry not there yet.
+ repo, name, size = max(planned, key = lambda p: p[2])
+ repo_dir = tmp_path / f"models--{repo.replace('/', '--')}"
+ (repo_dir / "snapshots" / "rev1" / name).unlink()
+ (repo_dir / "blobs").mkdir(exist_ok = True)
+ (repo_dir / "blobs" / "x.incomplete").write_bytes(b"\0" * (size // 2))
+ backend._loading = _LoadingState(
+ repo_id = s["repo_id"],
+ base_repo = s["base"],
+ fetch_repo = s["fetch"],
+ gguf_filename = s["gguf"],
+ planned_files = planned,
+ expected_bytes = expected,
+ )
+ partial = backend.load_progress()
+ assert partial["phase"] == "downloading"
+ assert partial["bytes_downloaded"] == expected - size + size // 2
+
+
+def test_run_load_counts_a_prequant_denoiser_hosted_in_the_companion_mirror(monkeypatch):
+ """Qwen-Image-2.1-Turbo as a pipeline with its hosted FP8 denoiser: the companion folders and the denoiser both
+ come from unsloth/Qwen-Image-2.1-Turbo-FP8. The scoped repo scan counted only the folders and the asset loop
+ skipped the companion repo, so the denoiser sat in expected_bytes but never in downloaded."""
+ from core.inference import diffusion as dmod
+ from core.inference.diffusion import _LoadingState
+
+ base = "Qwen/Qwen-Image-2.1-Turbo"
+ dit = (_FP8_REPO, "Qwen-Image-2.1-Turbo-FP8.safetensors", 7_000)
+ base_files = {
+ "model_index.json": 7,
+ "transformer/config.json": 2,
+ "vae/diffusion_pytorch_model.safetensors": 300,
+ }
+
+ def estimate(
+ *_a,
+ file_sizes_out = None,
+ fetch_repos_out = None,
+ **_k,
+ ):
+ if file_sizes_out is not None:
+ file_sizes_out[base] = dict(base_files)
+ if fetch_repos_out is not None:
+ fetch_repos_out[base] = _FP8_REPO
+ return sum(base_files.values()), list(base_files)
+
+ on_disk = {(_FP8_REPO, name): size for name, size in base_files.items()}
+ on_disk[(dit[0], dit[1])] = dit[2]
+ for name, value in {
+ "_te_prequant_plan_files": staticmethod(lambda *a, **k: {}),
+ "_pipeline_planned_denoiser_scheme": lambda self, *a, **k: None,
+ "_dit_prequant_plan_source": lambda self, *a, **k: dit,
+ "declared_footprint_shortfall": lambda self, *a, **k: None,
+ "_estimate_download_bytes": staticmethod(estimate),
+ "_prefetch_files": lambda self, *a, **k: None,
+ "_fetch_denoiser_prequant": lambda self, *a, **k: None,
+ "_cache_file_bytes": staticmethod(lambda repo, f: on_disk.get((repo, f), 0)),
+ "_hub_cache_repo_dirs": staticmethod(lambda repo: []),
+ # What the old scoped scan saw in the mirror: the diffusers folders only.
+ "_cache_bytes": staticmethod(
+ lambda repo, **k: sum(base_files.values()) if repo == _FP8_REPO else 0
+ ),
+ }.items():
+ monkeypatch.setattr(DiffusionBackend, name, value)
+ monkeypatch.setattr(dmod, "_assert_base_repo_accessible", lambda *a, **k: None)
+ monkeypatch.setattr(
+ dmod, "prefer_ungated_mirror", lambda b, *a, **k: _FP8_REPO if b == base else b
+ )
+ monkeypatch.setattr(dmod, "assert_flux2_pick_compatible", lambda *a, **k: None)
+ monkeypatch.setattr(dmod, "assert_pick_is_not_speech", lambda *a, **k: None)
+ seen = []
+ monkeypatch.setattr(
+ DiffusionBackend, "load_pipeline", lambda self, **kw: seen.append(self.load_progress())
+ )
+ backend = DiffusionBackend()
+ backend._loading = _LoadingState(repo_id = base, base_repo = None)
+ backend._load_token = 7
+ backend._run_load(_load_token = 7, repo_id = base, model_kind = "pipeline")
+ expected = sum(base_files.values()) + dit[2]
+ assert (seen[0]["phase"], seen[0]["bytes_downloaded"], seen[0]["bytes_total"]) == (
+ "finalizing",
+ expected,
+ expected,
+ )
+
+
+def test_a_stale_incomplete_blob_from_a_cancelled_sibling_is_not_progress(monkeypatch, tmp_path):
+ """A cancelled download of another quant left a large ``.incomplete`` blob in the same repo before this load
+ started. Only what appears or grows after the load's baseline is this load's progress."""
+ from core.inference.diffusion import _LoadingState
+
+ repo = "unsloth/FLUX.1-dev-GGUF"
+ planned = ((repo, "flux1-dev-Q4_K_M.gguf", 6_000),)
+ _snapshot(tmp_path, repo, {"README.md": 10})
+ blobs = tmp_path / f"models--{repo.replace('/', '--')}" / "blobs"
+ blobs.mkdir(parents = True, exist_ok = True)
+ (blobs / "stale.incomplete").write_bytes(b"\0" * 5_000)
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_hub_cache_repo_dirs",
+ staticmethod(lambda repo_id: [tmp_path / f"models--{repo_id.replace('/', '--')}"]),
+ )
+ backend = DiffusionBackend()
+ backend._loading = _LoadingState(
+ repo_id = repo,
+ base_repo = "black-forest-labs/FLUX.1-dev",
+ gguf_filename = planned[0][1],
+ planned_files = planned,
+ expected_bytes = 6_000,
+ incomplete_baseline = DiffusionBackend._incomplete_blob_sizes({repo}),
+ )
+ assert backend.load_progress()["bytes_downloaded"] == 0
+ (blobs / "mine.incomplete").write_bytes(b"\0" * 1_500)
+ with open(blobs / "stale.incomplete", "ab") as fh: # a resumed blob counts only what it adds
+ fh.write(b"\0" * 500)
+ assert backend.load_progress()["bytes_downloaded"] == 2_000
+
+
+def test_a_folders_only_copy_in_the_other_root_is_a_companion_row_and_no_orphan(
+ monkeypatch, tmp_path
+):
+ """The GGUF in one cache root, the mirror's folders in the other: the compatibility cached-models route lists no
+ single-file row for the folders copy, and Free up space does not offer it, since the installed GGUF loads its
+ companions from it."""
+ import asyncio
+ from types import SimpleNamespace
+
+ import routes.models as models_route
+ from hub.services.models import cache_inventory, companion_cleanup
+
+ repo = "unsloth/Z-Image-GGUF"
+ in_gguf_root = _cache_repo(tmp_path / "old", repo, {"z-image-Q4_K_M.gguf": 5_000})
+ in_folder_root = _cache_repo(tmp_path / "live", repo, dict(_FOLDERS))
+ scans = [SimpleNamespace(repos = [in_gguf_root]), SimpleNamespace(repos = [in_folder_root])]
+
+ monkeypatch.setattr(models_route, "_resolve_hf_cache_dir", lambda: tmp_path / "live")
+ monkeypatch.setattr(models_route, "_cached_repo_task", lambda *_a, **_k: "text-to-image")
+ monkeypatch.setattr(models_route, "_cached_repo_partial", lambda *_a, **_k: False)
+ monkeypatch.setattr(models_route.account_access, "filter_model_rows", lambda rows: rows)
+ rows = [r for r in models_route.cached_model_rows(scans) if r["repo_id"] == repo]
+ # Listed (its delete is scoped to its own root) but as the GGUF's companion, never a single-file pick.
+ assert len(rows) == 1 and rows[0].get("companion") is True and not rows[0].get("single_file")
+
+ monkeypatch.setattr("utils.paths.storage_roots.cache_root", lambda: tmp_path / "app-cache")
+ monkeypatch.setattr(cache_inventory, "all_hf_cache_scans", lambda: scans)
+ monkeypatch.setattr(companion_cleanup.cache_inventory, "all_hf_cache_scans", lambda: scans)
+ offered = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ assert [c for c in offered if c["repo_id"] == repo] == []
+
+
+def test_a_resumed_planned_blob_counts_its_earlier_bytes_and_a_siblings_never_counts(
+ monkeypatch, tmp_path
+):
+ """huggingface_hub writes a file to ``blobs/<blob key>.incomplete``. A planned shard resumed at 90% counts its
+ 90% at once (not 0% until it finishes), while another download's blob in the same repo, new or old, counts
+ nothing."""
+ from core.inference.diffusion import _LoadingState
+
+ repo = "unsloth/FLUX.1-dev-GGUF"
+ planned = ((repo, "flux1-dev-Q4_K_M.gguf", 10_000),)
+ _snapshot(tmp_path, repo, {"README.md": 10})
+ blobs = tmp_path / f"models--{repo.replace('/', '--')}" / "blobs"
+ blobs.mkdir(parents = True, exist_ok = True)
+ (blobs / "a1b2.incomplete").write_bytes(b"\0" * 9_000) # this file, resumed
+ (blobs / "ffff.incomplete").write_bytes(b"\0" * 4_000) # a cancelled sibling quant
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_hub_cache_repo_dirs",
+ staticmethod(lambda repo_id: [tmp_path / f"models--{repo_id.replace('/', '--')}"]),
+ )
+ backend = DiffusionBackend()
+ backend._loading = _LoadingState(
+ repo_id = repo,
+ base_repo = "black-forest-labs/FLUX.1-dev",
+ gguf_filename = planned[0][1],
+ planned_files = planned,
+ expected_bytes = 10_000,
+ incomplete_baseline = DiffusionBackend._incomplete_blob_sizes({repo}),
+ planned_blob_keys = {(repo.lower(), planned[0][1]): "a1b2"},
+ )
+ assert backend.load_progress()["bytes_downloaded"] == 9_000
+ (blobs / "eeee.incomplete").write_bytes(
+ b"\0" * 3_000
+ ) # another download starting after the load
+ assert backend.load_progress()["bytes_downloaded"] == 9_000
+
+
+def test_the_mirror_is_chosen_again_once_the_plan_widens_to_transformer_shards(monkeypatch):
+ """FLUX.1-dev's companions are cached upstream but its transformer is not. An explicit transformer quant widens
+ the plan to the dense shards after the companion-only mirror choice kept the gated upstream; the final list must
+ move the fetch to unsloth/FLUX.1-dev, or the shards 401 for an anonymous user."""
+ from types import SimpleNamespace
+
+ from huggingface_hub import HfApi
+
+ base = "black-forest-labs/FLUX.1-dev"
+ siblings = [
+ SimpleNamespace(rfilename = n, size = s, lfs = None, blob_id = f"b-{n}")
+ for n, s in {
+ "model_index.json": 7,
+ "text_encoder/model.safetensors": 900,
+ "vae/diffusion_pytorch_model.safetensors": 300,
+ "transformer/config.json": 2,
+ "transformer/diffusion_pytorch_model.safetensors": 9_000,
+ }.items()
+ ]
+ asked = []
+
+ def model_info(self, repo_id, *a, **k):
+ asked.append(repo_id)
+ return SimpleNamespace(sha = "0" * 40, siblings = siblings)
+
+ monkeypatch.setattr(HfApi, "model_info", model_info)
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
+ # The upstream cache holds everything but the dense transformer shards.
+ monkeypatch.setattr(
+ df,
+ "_upstream_is_cached",
+ lambda repo_id, files = None, **k: not any(
+ f.startswith("transformer/") and f != "transformer/config.json" for f in (files or ())
+ ),
+ )
+ fetch_repos: dict = {}
+ _total, files = DiffusionBackend._estimate_download_bytes(
+ "unsloth/FLUX.1-dev-GGUF",
+ None,
+ base,
+ None,
+ kind = "gguf",
+ include_transformer = lambda companions, transformer_files: True,
+ fetch_repos_out = fetch_repos,
+ )
+ assert "transformer/diffusion_pytorch_model.safetensors" in files
+ assert fetch_repos[base] == "unsloth/FLUX.1-dev"
+ assert asked[-1] == "unsloth/FLUX.1-dev"
+
+
+def test_artifact_folder_bytes_counts_physical_blobs(tmp_path):
+ from hub.services.models.cache_inventory import artifact_folder_bytes
+
+ repo_dir = tmp_path / "models--unsloth--Z-Image-GGUF"
+ blobs = repo_dir / "blobs"
+ blobs.mkdir(parents = True)
+ old, new, shared = blobs / "old", blobs / "new", blobs / "shared"
+ old.write_bytes(b"\0" * 300)
+ new.write_bytes(b"\0" * 500)
+ shared.write_bytes(b"\0" * 70)
+ for rev, blob in (("rev1", old), ("rev2", new)):
+ vae = repo_dir / "snapshots" / rev / "vae"
+ vae.mkdir(parents = True)
+ try:
+ # The same name, changed between revisions: a whole-repo delete frees both blobs.
+ (vae / "diffusion_pytorch_model.safetensors").symlink_to(blob)
+ # One blob behind two paths is freed once.
+ (vae / "config.json").symlink_to(shared)
+ except OSError:
+ pytest.skip("symlinks need privileges on this host")
+ assert artifact_folder_bytes(repo_dir) == 300 + 500 + 70
+
+
+def test_folders_left_by_a_deleted_gguf_are_offered_even_with_transformer_shards(
+ monkeypatch, tmp_path
+):
+ """No GGUF of the artifact mirror left in any root: its transformer/ shards (a GGUF speed load's dense fetch) are
+ no installed checkpoint, since a pipeline load of the mirror id is refused, so Free up space offers the folders."""
+ import asyncio
+ from types import SimpleNamespace
+
+ from hub.services.models import cache_inventory, companion_cleanup
+
+ repo = "unsloth/Z-Image-GGUF"
+ leftover = _cache_repo(tmp_path / "live", repo, {**_FOLDERS, **_DENOISER})
+ scans = [SimpleNamespace(repos = [leftover])]
+ monkeypatch.setattr("utils.paths.storage_roots.cache_root", lambda: tmp_path / "app-cache")
+ monkeypatch.setattr(cache_inventory, "all_hf_cache_scans", lambda: scans)
+ monkeypatch.setattr(companion_cleanup.cache_inventory, "all_hf_cache_scans", lambda: scans)
+ offered = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ assert [c["repo_id"] for c in offered if c["repo_id"] == repo] == [repo]
+
+
+def test_an_installed_fp8_artifact_mirror_checkpoint_is_never_an_orphan(monkeypatch, tmp_path):
+ import asyncio
+ from types import SimpleNamespace
+
+ from hub.services.models import cache_inventory, companion_cleanup
+ from hub.utils import companion_assets
+
+ repo = "unsloth/Qwen-Image-2.1-Turbo-FP8"
+ assert cache_inventory._hosts_artifacts(repo)
+ assert repo.lower() in {k.lower() for k in companion_assets.known_companion_base_ids()}
+ installed = _cache_repo(
+ tmp_path / "live", repo, {**_FOLDERS, "Qwen-Image-2.1-Turbo-FP8.safetensors": 4_000}
+ )
+ scans = [SimpleNamespace(repos = [installed])]
+ monkeypatch.setattr("utils.paths.storage_roots.cache_root", lambda: tmp_path / "app-cache")
+ monkeypatch.setattr(cache_inventory, "all_hf_cache_scans", lambda: scans)
+ monkeypatch.setattr(companion_cleanup.cache_inventory, "all_hf_cache_scans", lambda: scans)
+ offered = asyncio.run(companion_cleanup.orphan_companions_response())["companions"]
+ # Its root checkpoint is the installed model; only an artifact mirror's transformer/ shards are not.
+ assert [c for c in offered if c["repo_id"] == repo] == []
+
+
+def test_artifact_folder_bytes_without_inodes_keys_by_blob_path(monkeypatch, tmp_path):
+ import os
+
+ from hub.services.models import cache_inventory
+
+ repo_dir = tmp_path / "models--unsloth--Z-Image-GGUF"
+ vae = repo_dir / "snapshots" / "rev1" / "vae"
+ vae.mkdir(parents = True)
+ (vae / "a.safetensors").write_bytes(b"\0" * 300)
+ (vae / "b.safetensors").write_bytes(b"\0" * 500)
+ real_stat = Path.stat
+
+ def no_inode(self, *a, **k):
+ st = real_stat(self, *a, **k)
+ return os.stat_result(
+ (
+ st.st_mode,
+ 0,
+ st.st_dev,
+ st.st_nlink,
+ st.st_uid,
+ st.st_gid,
+ st.st_size,
+ st.st_atime,
+ st.st_mtime,
+ st.st_ctime,
+ )
+ )
+
+ monkeypatch.setattr(Path, "stat", no_inode)
+ assert cache_inventory.artifact_folder_bytes(repo_dir) == 800
diff --git a/studio/backend/tests/test_cached_gguf_routes.py b/studio/backend/tests/test_cached_gguf_routes.py
index 0c983d25e69..e247f2292f7 100644
--- a/studio/backend/tests/test_cached_gguf_routes.py
+++ b/studio/backend/tests/test_cached_gguf_routes.py
@@ -3328,26 +3328,32 @@ def test_cached_repo_task_gates_an_image_pipeline_on_the_load_path_trust_rule(tm
def test_cached_repo_task_never_offers_an_sd_cpp_companion_repo_as_a_model(tmp_path):
- """The single-file VAE / text-encoder repos hold no denoiser, so none of them is a pick.
+ """The sd-cli text-encoder repos hold no denoiser, so none of them is an Images pick.
- Their unsloth mirrors clear the trust gate the old third-party ids never did, and the ids
- resolve to a family, so without the companion check each would list an unloadable Images row.
+ They are unsloth repos, so they clear the trust gate, and an id that resolves to a family
+ would list an unloadable Images row without the companion check. Every image VAE / encoder
+ now comes from a vendor base or an unsloth encoder GGUF, so the set is exactly those GGUFs.
"""
from core.inference.diffusion_families import sd_cpp_companion_only_repo_ids
+ companions = sd_cpp_companion_only_repo_ids()
for repo_id in (
- "unsloth/Z-Image-Turbo-ComfyUI",
- "unsloth/Qwen-Image-ComfyUI",
- "unsloth/FLUX.2-dev-ComfyUI",
- "unsloth/FLUX.2-VAE",
- "unsloth/FLUX.2-klein-9B-ComfyUI",
- "unsloth/flux-text-encoders",
+ "unsloth/Qwen3-4B-GGUF",
+ "unsloth/Qwen3-8B-GGUF",
+ "unsloth/Mistral-Small-3.2-24B-Instruct-2506-GGUF",
+ "unsloth/Qwen2.5-VL-7B-Instruct-GGUF",
):
- assert repo_id.lower() in sd_cpp_companion_only_repo_ids(), repo_id
+ assert repo_id.lower() in companions, repo_id
+ for repo_id in companions:
assert models_route._cached_repo_task(_pipeline_repo(repo_id, tmp_path)) is None, repo_id
- # FLUX.1-schnell also serves a companion VAE, but it is a real base and must stay loadable.
- assert "black-forest-labs/flux.1-schnell" not in sd_cpp_companion_only_repo_ids()
+ # The vendor bases that now serve the VAEs / encoders are real bases and must stay loadable.
+ for base in (
+ "black-forest-labs/FLUX.1-schnell",
+ "black-forest-labs/FLUX.2-dev",
+ "Qwen/Qwen-Image",
+ ):
+ assert base.lower() not in companions, base
assert (
models_route._cached_repo_task(_pipeline_repo("black-forest-labs/FLUX.1-schnell", tmp_path))
== "text-to-image"
@@ -3358,11 +3364,21 @@ def test_a_companion_mirror_is_listed_but_flagged_so_no_picker_offers_it(monkeyp
"""A task of None does NOT drop the row: it is exactly what an unclassified CHAT repo carries,
so the chat picker showed the companion as loadable. Deleting the row instead would hide tens
of GB the user can then never find or remove, so the row stays and carries a flag the pickers
- filter on."""
+ filter on.
+
+ No image companion repo ships .safetensors any more (the remaining ones are encoder GGUFs, which
+ this listing skips), so a synthetic single-file VAE repo is added to the companion set."""
+ import core.inference.diffusion_families as families
+
+ real = families.sd_cpp_companion_only_repo_ids
+ companion_id = "unsloth/example-vae-companion"
+ monkeypatch.setattr(
+ families, "sd_cpp_companion_only_repo_ids", lambda: real() | {companion_id.lower()}
+ )
companion = _repo(
- "unsloth/Z-Image-Turbo-ComfyUI",
- [_file("split_files/vae/ae.safetensors", 300_000)],
- tmp_path / "models--unsloth--Z-Image-Turbo-ComfyUI",
+ companion_id,
+ [_file("vae/ae.safetensors", 300_000)],
+ tmp_path / "models--unsloth--example-vae-companion",
)
chat = _repo(
"unsloth/Qwen3-8B",
@@ -3377,10 +3393,10 @@ def test_a_companion_mirror_is_listed_but_flagged_so_no_picker_offers_it(monkeyp
}
# Listed, so it stays visible and deletable...
- assert "unsloth/Z-Image-Turbo-ComfyUI" in rows
+ assert companion_id in rows
# ...and flagged, which is the part a task of None could never express.
- assert rows["unsloth/Z-Image-Turbo-ComfyUI"]["companion"] is True
- assert rows["unsloth/Z-Image-Turbo-ComfyUI"]["task"] is None
+ assert rows[companion_id]["companion"] is True
+ assert rows[companion_id]["task"] is None
# An ordinary chat repo carries the same task of None and must NOT be flagged.
assert rows["unsloth/Qwen3-8B"].get("companion") is None
assert rows["unsloth/Qwen3-8B"]["task"] is None
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index 0638d9d6691..3de09f54c55 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -229,7 +229,7 @@ def _all_cached(monkeypatch):
def test_gated_mirror_table_round_trips():
"""Both directions, exact case: canonical_base must hand back a real repo id."""
- assert len(_MIRROR_PAIRS) == 27
+ assert len(_MIRROR_PAIRS) == 32
for upstream, mirror in _MIRROR_PAIRS:
assert mirror_repo(upstream) == mirror
assert canonical_base(mirror) == upstream
@@ -252,7 +252,7 @@ def test_only_the_genuinely_gated_half_reads_as_gated():
is mirrored, and which the Hub serves anonymously.
"""
assert len(_GATED_MIRROR_PAIRS) == 14
- assert len(_UNGATED_MIRROR_PAIRS) == 13
+ assert len(_UNGATED_MIRROR_PAIRS) == 18
for upstream, _mirror in _GATED_MIRROR_PAIRS:
assert upstream_is_gated(upstream), upstream
assert upstream_is_gated(upstream.upper()), upstream
@@ -277,12 +277,6 @@ def test_no_mirror_is_a_companion_only_repo():
assert mirror.lower() not in companions, mirror
-# Vendor bases the catalog offers before their unsloth mirror exists on the Hub. A mirror row for a
-# repo that is not there would 404 every fetch it redirects, so the table cannot lead the upload;
-# this names the gap instead of letting the check below go red on every PR until it closes.
-_MIRRORS_NOT_YET_PUBLISHED: frozenset[str] = frozenset({"qwen/qwen-image-2.1-turbo"})
-
-
def test_every_third_party_bf16_pipeline_the_catalog_offers_is_mirrored():
"""Lookup is by exact id, so a variant the catalog offers is silently missed until listed.
@@ -311,18 +305,8 @@ def test_every_third_party_bf16_pipeline_the_catalog_offers_is_mirrored():
if not repo.lower().startswith("unsloth/")
and "hunyuan" not in repo.lower()
and repo.lower() not in mirrored
- and repo.lower() not in _MIRRORS_NOT_YET_PUBLISHED
)
assert not missing, f"catalog offers these vendor bases with no unsloth mirror: {missing}"
- # Each pending entry has to still be pending and still offered, so the exception cannot
- # outlive the gap it names.
- for repo in _MIRRORS_NOT_YET_PUBLISHED:
- assert (
- repo not in mirrored
- ), f"{repo} is in the mirror table now; drop it from _MIRRORS_NOT_YET_PUBLISHED"
- assert repo in {
- o.lower() for o in offered
- }, f"the catalog no longer offers {repo}; drop it from _MIRRORS_NOT_YET_PUBLISHED"
def test_the_qwen_2512_mirror_covers_the_card_tag_route(monkeypatch):
@@ -538,13 +522,18 @@ def test_a_repack_split_across_the_two_cache_roots_still_counts(monkeypatch, tmp
a split pair absent and re-pulls several GB the two roots already have between them (offline,
it fails outright). Reachable with an interrupted download either side of the change: the file
fetched before it stays in the old root, the one fetched after lands in the new one.
+
+ Uses a synthetic mirror -> repack row: the mechanism is generic, and no image asset is a
+ repack any more.
"""
from huggingface_hub import constants
+ from core.inference import diffusion_families
from core.inference.diffusion_families import _upstream_is_cached, prefer_cached_legacy_source
- repack = "Comfy-Org/z_image_turbo"
- mirror = "unsloth/Z-Image-Turbo-ComfyUI"
+ repack = "some-org/example-repack"
+ mirror = "unsloth/example-repack-mirror"
+ monkeypatch.setitem(diffusion_families._SD_CPP_LEGACY_SOURCES, mirror.lower(), repack)
first, second = "split_files/vae/ae.safetensors", "split_files/text_encoders/te.safetensors"
live, other = tmp_path / "live", tmp_path / "other"
@@ -8606,7 +8595,10 @@ def _fake_hf_api(
files_metadata = False,
token = None,
):
- return _FakeInfo(repos[repo_id], (shas or {}).get(repo_id))
+ # The listing now asks a base's unsloth mirror, which carries the same files: answer it from the
+ # upstream's canned listing unless a test describes the mirror itself.
+ key = repo_id if repo_id in repos else canonical_base(repo_id)
+ return _FakeInfo(repos[key], (shas or {}).get(key))
monkeypatch.setattr("huggingface_hub.HfApi", lambda *a, **k: _Api())
# Download-plan tests describe their cache state explicitly. Never let a developer's real
diff --git a/studio/backend/tests/test_diffusion_compat_preflight.py b/studio/backend/tests/test_diffusion_compat_preflight.py
index 4302c9b596a..941c42aed03 100644
--- a/studio/backend/tests/test_diffusion_compat_preflight.py
+++ b/studio/backend/tests/test_diffusion_compat_preflight.py
@@ -796,6 +796,9 @@ def test_the_load_refuses_before_prefetching_or_unloading_anything(monkeypatch,
# ── the sibling hole: the native text-encoder pick ─────────────────────────────
+from core.inference.diffusion_families import _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS # noqa: E402
+
+
def test_the_native_encoder_follows_the_header_over_the_filename():
# A renamed or hand-picked 9B checkpoint says nothing in its id, and the 4B encoder fails deep
# inside sd-cli. The header knows.
@@ -809,7 +812,8 @@ def test_the_native_encoder_follows_the_header_over_the_filename():
assert by_name == fam.sd_cpp_text_encoders # today's answer: the 4B encoder
assert by_header != by_name
- assert any("9B" in repo for repo, _f, _k in by_header)
+ # The 9B checkpoint reads Qwen3-8B.
+ assert by_header == _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS
def test_the_header_also_overrides_a_misleading_9b_filename():
@@ -835,7 +839,7 @@ def test_an_unmapped_or_absent_inner_dim_keeps_the_filename_rule():
)
== nine_b
)
- assert any("9B" in repo for repo, _f, _k in nine_b)
+ assert nine_b == _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS
def test_a_stalled_response_header_cannot_hold_the_picker_open(monkeypatch):
diff --git a/studio/backend/tests/test_diffusion_gated_base.py b/studio/backend/tests/test_diffusion_gated_base.py
index c28fa5b093a..ee8f5e99def 100644
--- a/studio/backend/tests/test_diffusion_gated_base.py
+++ b/studio/backend/tests/test_diffusion_gated_base.py
@@ -463,18 +463,30 @@ def test_the_native_plan_preflights_its_companion_repos_too(monkeypatch):
detail = str(excinfo.value)
assert gated in detail and f"https://huggingface.co/{gated}" in detail
+ # Z-Image decodes with the same FLUX.1 autoencoder, so with the mirror off it hits the same gate.
+ with pytest.raises(ValueError, match = "FLUX.1-schnell"):
+ b.download_plan(
+ "unsloth/Z-Image-Turbo-GGUF",
+ gguf_filename = "z-image-turbo-Q4_K_M.gguf",
+ model_kind = "gguf",
+ )
+
# An open family is untouched: every companion answers, so the plan is built exactly as before.
+ from core.inference.diffusion_families import detect_family
+
+ fam = detect_family("qwen-image")
plan = b.download_plan(
- "unsloth/Z-Image-Turbo-GGUF",
- gguf_filename = "z-image-turbo-Q4_K_M.gguf",
+ "unsloth/Qwen-Image-GGUF",
+ gguf_filename = "qwen-image-Q4_K_M.gguf",
model_kind = "gguf",
)
- # The companion is the unsloth mirror now, not the community repack: this PR repointed the
- # table, and no legacy copy is cached here so prefer_cached_legacy_source keeps the mirror.
+ # Straight from the family table: the official diffusers VAE and the Qwen2.5-VL GGUF encoder.
assert {e["repo_id"] for e in plan["entries"]} == {
- "unsloth/Z-Image-Turbo-GGUF",
- "unsloth/Z-Image-Turbo-ComfyUI",
+ "unsloth/Qwen-Image-GGUF",
+ fam.sd_cpp_vae[0],
+ *(repo for repo, _f, _k in fam.sd_cpp_text_encoders),
}
+ assert fam.sd_cpp_vae[0] == "Qwen/Qwen-Image"
def test_the_native_plan_probes_the_asset_it_stages(monkeypatch):
diff --git a/studio/backend/tests/test_diffusion_more_families.py b/studio/backend/tests/test_diffusion_more_families.py
index 77023434ae1..10e861e243b 100644
--- a/studio/backend/tests/test_diffusion_more_families.py
+++ b/studio/backend/tests/test_diffusion_more_families.py
@@ -625,10 +625,10 @@ def test_flux2_klein_9b_resolves_its_own_base_and_text_encoder():
assert _is_trusted_diffusion_repo(repo), repo
for repo_id, want_te in (
- ("unsloth/FLUX.2-klein-9B-GGUF", "qwen_3_8b"),
- ("unsloth/FLUX.2-klein-base-9B-GGUF", "qwen_3_8b"),
- ("unsloth/FLUX.2-klein-4B-GGUF", "qwen_3_4b"),
- ("unsloth/FLUX.2-klein-base-4B-GGUF", "qwen_3_4b"),
+ ("unsloth/FLUX.2-klein-9B-GGUF", "Qwen3-8B"),
+ ("unsloth/FLUX.2-klein-base-9B-GGUF", "Qwen3-8B"),
+ ("unsloth/FLUX.2-klein-4B-GGUF", "Qwen3-4B"),
+ ("unsloth/FLUX.2-klein-base-4B-GGUF", "Qwen3-4B"),
):
encoders = sd_cpp_text_encoders_for(detect_family(repo_id), repo_id, None)
assert want_te in encoders[0][1], (repo_id, encoders)
diff --git a/studio/backend/tests/test_diffusion_qwen_layered.py b/studio/backend/tests/test_diffusion_qwen_layered.py
index 017c140e55c..d76bce5fc48 100644
--- a/studio/backend/tests/test_diffusion_qwen_layered.py
+++ b/studio/backend/tests/test_diffusion_qwen_layered.py
@@ -100,9 +100,16 @@ def _png(size = (96, 64), color = (120, 30, 30, 77)) -> str:
@pytest.fixture
-def layered(fake_runtime, tmp_path):
+def layered(fake_runtime, tmp_path, monkeypatch):
import diffusers
+ # A fresh install: nothing cached, so the companions come from the unsloth mirror, not this host's cache.
+ monkeypatch.setattr(
+ "core.inference.diffusion_families._upstream_is_cached",
+ lambda repo_id, files = None, **_k: False,
+ )
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
+
diffusers.QwenImageLayeredPipeline = _FakeLayeredPipeline
diffusers.QwenImageTransformer2DModel = _FakeTransformer
_FakeLayeredPipe.calls = []
@@ -176,11 +183,13 @@ def test_layered_family_contract():
def test_gguf_transformer_reads_the_layered_config(layered):
assert layered._state.family.name == "qwen-image-layered"
# The GGUF supplies weights only; the layered transformer config (additional t cond, layer3d RoPE) comes from the
- # base, and so do the RGBA VAE and the pipeline.
- assert _FakeTransformer.last["config"] == "Qwen/Qwen-Image-Layered"
+ # base, and so do the RGBA VAE and the pipeline. Fetched from the official folders inside
+ # unsloth/Qwen-Image-Layered-GGUF; status keeps the upstream id.
+ assert _FakeTransformer.last["config"] == "unsloth/Qwen-Image-Layered-GGUF"
assert _FakeTransformer.last["subfolder"] == "transformer"
assert _FakeTransformer.last["path"].endswith("qwen-image-layered-UD-Q4_K_XL.gguf")
- assert _FakeLayeredPipeline.base == "Qwen/Qwen-Image-Layered"
+ assert _FakeLayeredPipeline.base == "unsloth/Qwen-Image-Layered-GGUF"
+ assert layered.status()["base_repo"] == "Qwen/Qwen-Image-Layered"
assert layered.status()["workflows"] == ["edit"]
diff --git a/studio/backend/tests/test_image_fetch_ids_unsloth.py b/studio/backend/tests/test_image_fetch_ids_unsloth.py
new file mode 100644
index 00000000000..c1991d9f1da
--- /dev/null
+++ b/studio/backend/tests/test_image_fetch_ids_unsloth.py
@@ -0,0 +1,314 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Every Hub repo an IMAGE load can fetch resolves to ``unsloth/*``.
+
+Walks the family table (bases, named variants, prequant / TE checkpoints, sd-cli VAE and text encoders, train and
+deploy bases), the frontend image catalog (every artifact row and the base each GGUF / bnb row takes its companions
+from) and fails on any fetch id outside ``unsloth/*``. Fully offline: the cache probe is forced to "not cached", so the
+answer is what a fresh install fetches, not what this host happens to hold.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from core.inference import diffusion_families as df
+from core.inference.diffusion_families import (
+ _FAMILIES,
+ _UNGATED_MIRROR_PAIRS,
+ canonical_base,
+ detect_family,
+ mirror_repo,
+ prefer_ungated_mirror,
+ sd_cpp_text_encoder_candidates,
+ upstream_is_gated,
+)
+
+# The ONLY vendor repos an image load may still fetch, each with the licence clause that forbids a mirror.
+_LICENCE_BLOCKED: dict[str, str] = {
+ # Tencent Hunyuan Community License: "Territory" means the worldwide territory, excluding the territory of the
+ # European Union, United Kingdom and South Korea. A public Hub mirror cannot honour a territorial limit.
+ "hunyuanvideo-community/hunyuanimage-2.1-diffusers": "territory-restricted licence",
+}
+
+# Third-party DENOISER artifacts the catalog still offers. Not a companion fetch and not licence-blocked: there is
+# simply no unsloth GGUF of FLUX.1 Krea dev yet. Its companions already come from unsloth/FLUX.1-Krea-dev.
+_THIRD_PARTY_DENOISER_ROWS: frozenset[str] = frozenset({"quantstack/flux.1-krea-dev-gguf"})
+
+# The base_model card tag of every quantised image repo Studio offers or supports: the companions (VAE, text
+# encoders, tokenizer, scheduler) of a GGUF / bnb pick come from THIS repo, which no family table names for the
+# card-tag-only variants (Edit, Edit-2509, Z-Image). Read off the Hub cards; the catalog test below fails when the
+# catalog gains a quantised row this map does not cover.
+_CARD_BASES: dict[str, str] = {
+ "unsloth/Z-Image-Turbo-GGUF": "Tongyi-MAI/Z-Image-Turbo",
+ "unsloth/Z-Image-Turbo-unsloth-bnb-4bit": "Tongyi-MAI/Z-Image-Turbo",
+ "unsloth/Z-Image-GGUF": "Tongyi-MAI/Z-Image",
+ "unsloth/Qwen-Image-2.1-GGUF": "Qwen/Qwen-Image-2.1",
+ "unsloth/Qwen-Image-2.1-Turbo-GGUF": "Qwen/Qwen-Image-2.1-Turbo",
+ "unsloth/Qwen-Image-2512-GGUF": "Qwen/Qwen-Image-2512",
+ "unsloth/Qwen-Image-2512-unsloth-bnb-4bit": "Qwen/Qwen-Image-2512",
+ "unsloth/Qwen-Image-GGUF": "Qwen/Qwen-Image",
+ "unsloth/Qwen-Image-Edit-GGUF": "Qwen/Qwen-Image-Edit",
+ "unsloth/Qwen-Image-Edit-2509-GGUF": "Qwen/Qwen-Image-Edit-2509",
+ "unsloth/Qwen-Image-Edit-2511-GGUF": "Qwen/Qwen-Image-Edit-2511",
+ "unsloth/Qwen-Image-Layered-GGUF": "Qwen/Qwen-Image-Layered",
+ "unsloth/FLUX.1-schnell-GGUF": "black-forest-labs/FLUX.1-schnell",
+ "unsloth/FLUX.1-dev-GGUF": "black-forest-labs/FLUX.1-dev",
+ "QuantStack/FLUX.1-Krea-dev-GGUF": "black-forest-labs/FLUX.1-Krea-dev",
+ "unsloth/FLUX.1-Kontext-dev-GGUF": "black-forest-labs/FLUX.1-Kontext-dev",
+ "unsloth/FLUX.2-dev-GGUF": "black-forest-labs/FLUX.2-dev",
+ "unsloth/FLUX.2-klein-4B-GGUF": "black-forest-labs/FLUX.2-klein-4B",
+ "unsloth/FLUX.2-klein-9B-GGUF": "black-forest-labs/FLUX.2-klein-9B",
+ "unsloth/FLUX.2-klein-base-4B-GGUF": "black-forest-labs/FLUX.2-klein-base-4B",
+ "unsloth/FLUX.2-klein-base-9B-GGUF": "black-forest-labs/FLUX.2-klein-base-9B",
+ "unsloth/flux-3-image-klein-GGUF": "black-forest-labs/flux-3-image-klein",
+ "unsloth/flux-3-image-klein-base-GGUF": "black-forest-labs/flux-3-image-klein-base",
+}
+
+# These five have no separate mirror repo: the official diffusers folders live inside the model's existing unsloth
+# repo (-FP8 where one exists, else -GGUF).
+_NEW_PAIRS = (
+ ("Qwen/Qwen-Image-2.1-Turbo", "unsloth/Qwen-Image-2.1-Turbo-FP8"),
+ ("Qwen/Qwen-Image-Edit", "unsloth/Qwen-Image-Edit-GGUF"),
+ ("Qwen/Qwen-Image-Edit-2509", "unsloth/Qwen-Image-Edit-2509-GGUF"),
+ ("Qwen/Qwen-Image-Layered", "unsloth/Qwen-Image-Layered-GGUF"),
+ ("Tongyi-MAI/Z-Image", "unsloth/Z-Image-GGUF"),
+)
+
+# Repacks built by ComfyUI (or its unsloth/* copies). No image load may fetch from one, not even through the
+# legacy-cache fallback.
+_COMFY_MADE: frozenset[str] = frozenset(
+ {
+ "unsloth/flux-text-encoders",
+ "unsloth/qwen-image-comfyui",
+ "unsloth/flux.2-vae",
+ "unsloth/flux.2-dev-comfyui",
+ "unsloth/z-image-turbo-comfyui",
+ "unsloth/flux.2-klein-9b-comfyui",
+ }
+)
+
+
+def _is_comfy(repo: str) -> bool:
+ r = repo.lower()
+ return (
+ r in _COMFY_MADE
+ or r.startswith(("comfy-org/", "comfyanonymous/"))
+ or "comfyui" in r
+ or "comfy" in r.split("/")[0]
+ )
+
+
[email protected](autouse = True)
+def _fresh_install(monkeypatch):
+ """Nothing is cached and the opt-out is off: the fetch id a fresh install uses."""
+ monkeypatch.setattr(df, "_upstream_is_cached", lambda repo_id, files = None, **_k: False)
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
+
+
+def _fetch_id(repo: str) -> str:
+ return prefer_ungated_mirror(repo)
+
+
+def _allowed(repo: str) -> bool:
+ if _is_comfy(repo):
+ return False
+ return repo.lower().startswith("unsloth/") or repo.lower() in _LICENCE_BLOCKED
+
+
+def _family_fetch_ids() -> list[tuple[str, str, str, str]]:
+ """(family, role, table id, fetch id) for every repo the image family table can hand a fetch site."""
+ rows: list[tuple[str, str, str, str]] = []
+
+ def add(fam, role, repo):
+ if repo:
+ rows.append((fam.name, role, repo, _fetch_id(repo)))
+
+ for fam in _FAMILIES:
+ add(fam, "base_repo", fam.base_repo)
+ for repo in fam.named_variant_bases:
+ add(fam, "named_variant", repo)
+ for _scheme, repo in fam.prequant_repos:
+ add(fam, "prequant", repo)
+ for base, _scheme, repo in fam.prequant_variant_repos:
+ add(fam, "prequant_variant_base", base)
+ add(fam, "prequant_variant", repo)
+ for _scheme, _component, repo in fam.te_prequant_repos:
+ add(fam, "te_prequant", repo)
+ for repo in fam.train_base_repos:
+ add(fam, "train_base", repo)
+ add(fam, "deploy_base", fam.deploy_base_repo)
+ for training, inference in fam.deploy_base_repos:
+ add(fam, "deploy_base", training)
+ add(fam, "deploy_base", inference)
+ for base, _config in fam.mlx_model_config_by_base:
+ add(fam, "mlx_base", base)
+ return rows
+
+
+def _sd_cpp_fetch_ids() -> list[tuple[str, str, str, str]]:
+ """The sd-cli VAE and every text-encoder candidate, through the backend's own per-repo fetch map."""
+ from core.inference.sd_cpp_backend import _fetch_repo_map
+
+ rows: list[tuple[str, str, str, str]] = []
+ for fam in _FAMILIES:
+ specs = []
+ if fam.sd_cpp_vae:
+ specs.append((fam.sd_cpp_vae[0], fam.sd_cpp_vae[1], "vae"))
+ specs.extend(sd_cpp_text_encoder_candidates(fam))
+ fetch = _fetch_repo_map(specs, None)
+ rows.extend((fam.name, f"sd_cpp:{kind}", repo, fetch[repo]) for repo, _f, kind in specs)
+ return rows
+
+
+def test_new_mirror_pairs_round_trip():
+ for upstream, mirror in _NEW_PAIRS:
+ assert (upstream, mirror) in _UNGATED_MIRROR_PAIRS
+ assert mirror_repo(upstream) == mirror
+ assert mirror_repo(upstream.lower()) == mirror
+ assert canonical_base(mirror) == upstream
+ # Ungated upstreams: the mirror only keeps the fetch in unsloth/*, it must not override a user's cache.
+ assert not upstream_is_gated(upstream)
+ assert _fetch_id(upstream) == mirror
+
+
+def test_every_image_family_fetch_id_is_unsloth():
+ bad = [row for row in _family_fetch_ids() if not _allowed(row[3])]
+ assert not bad, "image family fetch ids outside unsloth/*:\n" + "\n".join(map(str, bad))
+
+
+def test_every_sd_cpp_asset_fetch_id_is_unsloth():
+ rows = _sd_cpp_fetch_ids()
+ assert rows
+ bad = [row for row in rows if not _allowed(row[3])]
+ assert not bad, "sd-cli asset fetch ids outside unsloth/*:\n" + "\n".join(map(str, bad))
+
+
+def test_layered_sd_cpp_vae_comes_from_the_mirror():
+ """Layered's sd-cli VAE is read from its own base, so the base mirror is what keeps it inside unsloth/*."""
+ fam = detect_family("", override = "qwen-image-layered")
+ assert fam is not None and fam.sd_cpp_vae
+ rows = [r for r in _sd_cpp_fetch_ids() if r[0] == "qwen-image-layered" and r[1] == "sd_cpp:vae"]
+ assert rows and rows[0][3] == "unsloth/Qwen-Image-Layered-GGUF"
+
+
+def _image_catalog() -> str:
+ text = (
+ Path(__file__).resolve().parents[2]
+ / "frontend/src/features/model-picker/components/model-selector/model-catalog.ts"
+ ).read_text(encoding = "utf-8")
+ images = text.split("export const IMAGE_CATALOG", 1)[1].split("export const VIDEO_CATALOG", 1)[
+ 0
+ ]
+ # Comments name withdrawn repos (the old QuantStack HunyuanImage GGUF); only live code counts.
+ return re.sub(r"^\s*//.*$", "", images, flags = re.M)
+
+
+def _catalog_rows() -> list[tuple[str, str]]:
+ images = _image_catalog()
+ rows = []
+ for helper in ("gguf", "bf16Pipeline", "bf16Mirror", "fp8Pipeline", "bnb4bit", "bf16Single"):
+ rows.extend((helper, repo) for repo in re.findall(helper + r'\(\s*"([^"]+)"', images))
+ rows.extend(("prequantRepo", repo) for repo in re.findall(r'prequantRepo:\s*"([^"]+)"', images))
+ assert len(rows) > 20, rows
+ return rows
+
+
+def _catalog_fetch_id(helper: str, repo: str) -> str:
+ # bf16Mirror rows already load the unsloth copy; the rest reach the backend by their own id.
+ if helper == "bf16Mirror":
+ return f"unsloth/{repo.split('/', 1)[1]}"
+ return _fetch_id(repo)
+
+
+def test_every_image_catalog_row_fetches_from_unsloth():
+ bad = []
+ for helper, repo in _catalog_rows():
+ fetch = _catalog_fetch_id(helper, repo)
+ if helper == "bf16Mirror":
+ # The row's id is only usable if the backend maps it back to the upstream it copies.
+ assert mirror_repo(repo) == fetch, repo
+ if _allowed(fetch) or repo.lower() in _THIRD_PARTY_DENOISER_ROWS:
+ continue
+ bad.append((helper, repo, fetch))
+ assert not bad, f"image catalog rows fetching outside unsloth/*: {bad}"
+
+
+def test_every_quantised_catalog_row_takes_its_companions_from_unsloth():
+ quantised = {repo for helper, repo in _catalog_rows() if helper in ("gguf", "bnb4bit")}
+ unmapped = sorted(
+ r for r in quantised if r not in _CARD_BASES and not r.lower().startswith("ideogram-ai/")
+ )
+ assert (
+ not unmapped
+ ), f"add the base_model card tag of these catalog rows to _CARD_BASES: {unmapped}"
+ bad = []
+ for repo, base in _CARD_BASES.items():
+ fam = detect_family(repo)
+ assert fam is not None, repo
+ assert detect_family(base) is fam, (repo, base)
+ fetch = _fetch_id(base)
+ if not _allowed(fetch):
+ bad.append((repo, base, fetch))
+ assert not bad, f"companion bases fetched outside unsloth/*: {bad}"
+
+
+def test_licence_allowlist_is_still_needed():
+ """The allowlist cannot outlive its reason: each entry must still be a fetch id with no mirror."""
+ ids = {row[2].lower() for row in _family_fetch_ids()} | {r.lower() for _h, r in _catalog_rows()}
+ for repo in _LICENCE_BLOCKED:
+ assert repo in ids, f"{repo} is no longer fetched; drop it from _LICENCE_BLOCKED"
+ assert mirror_repo(repo) is None, f"{repo} is mirrored now; drop it from _LICENCE_BLOCKED"
+ rows = {r.lower() for _h, r in _catalog_rows()}
+ for repo in _THIRD_PARTY_DENOISER_ROWS:
+ assert (
+ repo in rows
+ ), f"the catalog no longer offers {repo}; drop it from _THIRD_PARTY_DENOISER_ROWS"
+
+
+def test_no_image_asset_names_a_comfy_repack():
+ """Neither the tables nor the fetch map may name a ComfyUI-built file, and the legacy-cache fallback must not be
+ able to turn an image asset back into one."""
+ rows = _family_fetch_ids() + _sd_cpp_fetch_ids()
+ bad = [r for r in rows if _is_comfy(r[2]) or _is_comfy(r[3])]
+ assert not bad, bad
+ image_assets = {r[2].lower() for r in rows} | {r[3].lower() for r in rows}
+ for key, legacy in df._SD_CPP_LEGACY_SOURCES.items():
+ assert key not in image_assets, (key, legacy)
+ assert key not in _COMFY_MADE, key
+
+
+def test_sd_cpp_text_encoders_are_unsloth_ggufs_or_official_files():
+ """Every sd-cli text encoder is an unsloth GGUF or an official upstream file (through its unsloth mirror)."""
+ for fam, role, repo, fetch in _sd_cpp_fetch_ids():
+ if role == "sd_cpp:vae":
+ continue
+ assert fetch.lower().startswith("unsloth/") and not _is_comfy(fetch), (
+ fam,
+ role,
+ repo,
+ fetch,
+ )
+
+
+def test_every_sampling_grid_index_is_read_from_an_unsloth_repo(monkeypatch):
+ """The native route reads a variant base's model_index.json for its sample_sigmas grid outside the asset table,
+ so it needs its own walk: every base a grid family can name must resolve to an unsloth repo on a fresh install."""
+ from core.inference import diffusion_families as families
+ from core.inference import sd_cpp_backend as bk
+
+ monkeypatch.setattr(families, "_upstream_is_cached", lambda *a, **k: False)
+ bases = {
+ b
+ for fam in families._FAMILIES
+ if fam.name in bk._SAMPLE_SIGMAS_FAMILIES
+ for b in (fam.base_repo, *(getattr(fam, "named_variant_bases", ()) or ()))
+ if b
+ }
+ assert bases
+ for base in sorted(bases):
+ assert bk._grid_fetch_repo(base, None).lower().startswith("unsloth/"), base
diff --git a/studio/backend/tests/test_image_hub_metadata_unsloth.py b/studio/backend/tests/test_image_hub_metadata_unsloth.py
new file mode 100644
index 00000000000..ee27d159337
--- /dev/null
+++ b/studio/backend/tests/test_image_hub_metadata_unsloth.py
@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Every Hub METADATA call an image plan makes (listings, sizes, manifests, access probes) asks an ``unsloth/*`` repo.
+
+Walks the diffusers plan for every quantised catalog row and every mirrored base picked as a bf16 pipeline, and the
+sd.cpp plan for every GGUF row, with the Hub client replaced by a recorder that answers from a synthetic listing and
+refuses any HTTP that slips past it. A fresh install: nothing cached, so every byte and every listing comes from a
+mirror. (A base whose upstream copy is already cached keeps reading that copy's metadata, as released builds do: the
+cache probe pins the vendor commit, and the load itself revalidates against the vendor id.)
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from core.inference import diffusion_families as df
+from core.inference import sd_cpp_backend as bk
+from core.inference.diffusion import DiffusionBackend
+
+from .test_image_fetch_ids_unsloth import _CARD_BASES
+
+# Third-party DENOISER rows the catalog still offers (no unsloth GGUF exists): the pick's own repo, never a companion.
+_PICK_ONLY_EXCEPTIONS = frozenset({"quantstack/flux.1-krea-dev-gguf"})
+
+_PIPELINE_FILES = {
+ "model_index.json": 400,
+ "scheduler/scheduler_config.json": 300,
+ "text_encoder/config.json": 300,
+ "text_encoder/model.safetensors": 9_000,
+ "tokenizer/tokenizer.json": 500,
+ "transformer/config.json": 300,
+ "transformer/diffusion_pytorch_model.safetensors": 20_000,
+ "vae/config.json": 300,
+ "vae/diffusion_pytorch_model.safetensors": 3_000,
+}
+_MODEL_INDEX = {
+ "_class_name": "DiffusionPipeline",
+ **{
+ c: ["diffusers", "Component"]
+ for c in ("scheduler", "text_encoder", "tokenizer", "transformer", "vae")
+ },
+}
+# What an artifact mirror ships beside the upstream folders: root checkpoints and sample renders.
+_ARTIFACT_EXTRAS = {"Model-FP8.safetensors": 7_000, "samples/fp8_1.png": 1_000}
+_GGUFS = {r: f"{r.split('/')[1].lower()}-Q4_K_M.gguf" for r in _CARD_BASES if r.endswith("-GGUF")}
+
+
+def _record_hub(monkeypatch, tmp_path) -> list[tuple[str, str]]:
+ import httpx
+ import huggingface_hub
+ from huggingface_hub import HfApi
+
+ asked: list[tuple[str, str]] = []
+
+ def _siblings(repo):
+ files = dict(_PIPELINE_FILES)
+ if repo in _GGUFS:
+ files[_GGUFS[repo]] = 5_000
+ if df.mirror_hosts_artifacts(repo):
+ files.update(_ARTIFACT_EXTRAS)
+ return [
+ SimpleNamespace(rfilename = n, size = s, lfs = None, blob_id = f"b-{n}")
+ for n, s in files.items()
+ ]
+
+ def _info(repo):
+ base = _CARD_BASES.get(repo)
+ card = {"base_model": base} if base else {}
+ return SimpleNamespace(
+ id = repo,
+ sha = "0" * 40,
+ gated = False,
+ private = False,
+ siblings = _siblings(repo),
+ cardData = card,
+ card_data = card,
+ tags = [],
+ library_name = "diffusers",
+ pipeline_tag = "text-to-image",
+ )
+
+ def _api(kind, answer):
+ def call(self, repo_id, *args, **kwargs):
+ asked.append((kind, repo_id))
+ return answer(repo_id, *args, **kwargs)
+
+ return call
+
+ for name, answer in {
+ "model_info": lambda r, *a, **k: _info(r),
+ "repo_info": lambda r, *a, **k: _info(r),
+ "list_repo_files": lambda r, *a, **k: [s.rfilename for s in _siblings(r)],
+ "list_repo_tree": lambda r, *a, **k: [
+ SimpleNamespace(path = s.rfilename, size = s.size) for s in _siblings(r)
+ ],
+ "get_paths_info": lambda r, paths = (), *a, **k: [
+ SimpleNamespace(path = p, size = 100, lfs = None) for p in (k.get("paths") or paths)
+ ],
+ "file_exists": lambda r, *a, **k: True,
+ }.items():
+ monkeypatch.setattr(HfApi, name, _api(name, answer))
+
+ def hf_hub_download(repo_id, filename, *args, **kwargs):
+ asked.append(("hf_hub_download", repo_id))
+ if kwargs.get("local_files_only"):
+ from huggingface_hub.errors import LocalEntryNotFoundError
+ raise LocalEntryNotFoundError(f"{repo_id}/{filename}")
+ out = tmp_path / "dl" / repo_id.replace("/", "--") / filename
+ out.parent.mkdir(parents = True, exist_ok = True)
+ out.write_text(json.dumps(_MODEL_INDEX) if filename == "model_index.json" else "{}")
+ return str(out)
+
+ monkeypatch.setattr(huggingface_hub, "hf_hub_download", hf_hub_download)
+ monkeypatch.setattr(huggingface_hub.file_download, "hf_hub_download", hf_hub_download)
+
+ def _refuse(request):
+ asked.append(("http", f"{request.url.host}{request.url.path}"))
+ return httpx.Response(503)
+
+ monkeypatch.setattr(
+ huggingface_hub.utils._http,
+ "get_session",
+ lambda: httpx.Client(transport = httpx.MockTransport(_refuse)),
+ )
+ return asked
+
+
+def _vendor_calls(asked: list[tuple[str, str]], pick: str) -> list[tuple[str, str]]:
+ def allowed(target: str) -> bool:
+ t = target.lower()
+ if t.startswith("huggingface.co/"):
+ t = t.split("/", 1)[1]
+ if t.startswith("api/models/"):
+ t = t.split("/", 2)[2]
+ if t.startswith("unsloth/"):
+ return True
+ return pick.lower() in _PICK_ONLY_EXCEPTIONS and t.startswith(pick.lower())
+
+ return sorted({(kind, target) for kind, target in asked if not allowed(target)})
+
+
+def hub(monkeypatch, tmp_path):
+ monkeypatch.setattr(df, "_upstream_is_cached", lambda *a, **k: False)
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
+ monkeypatch.setattr(
+ DiffusionBackend, "_hub_file_is_loadable", staticmethod(lambda *a, **k: False)
+ )
+ return _record_hub(monkeypatch, tmp_path)
+
+
+def _picks():
+ return [(repo, gguf, "gguf") for repo, gguf in _GGUFS.items()] + [
+ (upstream, None, "pipeline") for upstream, _mirror in df._MIRROR_PAIRS
+ ]
+
+
+def test_the_picks_cover_every_mirrored_base():
+ picked = {r.lower() for r, _g, _k in _picks()} | {b.lower() for b in _CARD_BASES.values()}
+ assert {u.lower() for u, _m in df._MIRROR_PAIRS} <= picked
+
+
+def test_every_diffusers_plan_asks_only_unsloth_repos(hub):
+ backend = DiffusionBackend()
+ leaks = {}
+ for repo, gguf, kind in _picks():
+ hub.clear()
+ backend.download_plan(
+ repo,
+ gguf_filename = gguf,
+ model_kind = kind,
+ allow_device_probe = False,
+ memory_verdict = False,
+ discover_text_encoders = False,
+ )
+ assert hub, repo # the plan really asked the Hub something
+ if calls := _vendor_calls(hub, repo):
+ leaks[repo] = calls
+ assert leaks == {}
+
+
+def test_every_native_plan_asks_only_unsloth_repos(hub, monkeypatch):
+ backend = bk.SdCppDiffusionBackend()
+ monkeypatch.setattr(backend, "_flux2_inner_dim", lambda *a, **k: None)
+ leaks = {}
+ for repo, gguf in _GGUFS.items():
+ hub.clear()
+ backend.download_plan(repo, gguf_filename = gguf, model_kind = "gguf")
+ if calls := _vendor_calls(hub, repo):
+ leaks[repo] = calls
+ assert leaks == {}
+
+
[email protected]("kind", ["pipeline", "gguf"])
+def test_an_artifact_mirror_listing_stages_only_the_upstream_folders(hub, kind):
+ """Listing unsloth/Qwen-Image-2.1-Turbo-FP8 for the Turbo base must not stage its root checkpoints or sample
+ renders: neither is part of the pipeline, and the vendor listing it replaces never had them."""
+ base = "Qwen/Qwen-Image-2.1-Turbo"
+ repo, gguf = (base, None) if kind == "pipeline" else ("unsloth/Qwen-Image-2.1-Turbo-GGUF", None)
+ _total, files = DiffusionBackend._estimate_download_bytes(
+ repo, "x-Q4_K_M.gguf" if kind == "gguf" else gguf, base, None, kind = kind
+ )
+ assert files and "model_index.json" in files
+ assert not [f for f in files if f in _ARTIFACT_EXTRAS]
diff --git a/studio/backend/tests/test_sd_cpp_backend.py b/studio/backend/tests/test_sd_cpp_backend.py
index e4a7c9e85b8..cdc03ad1086 100644
--- a/studio/backend/tests/test_sd_cpp_backend.py
+++ b/studio/backend/tests/test_sd_cpp_backend.py
@@ -138,7 +138,7 @@ def test_loaded_repo_ids_includes_native_companions():
assert fam.base_repo in ids
assert fam.sd_cpp_vae[0] in ids # black-forest-labs/FLUX.1-schnell (VAE)
for terepo, _f, _k in fam.sd_cpp_text_encoders:
- assert terepo in ids # unsloth/flux-text-encoders
+ assert terepo in ids # black-forest-labs/FLUX.1-schnell (CLIP-L + sharded T5-XXL)
b._state = None
assert b.loaded_repo_ids() == ()
@@ -176,9 +176,12 @@ def test_loaded_repo_ids_tracks_variant_encoder_by_gguf_filename():
gguf_filename = "FLUX.2-klein-9B-Q4_K_M.gguf",
)
ids = set(b.loaded_repo_ids())
- assert "unsloth/FLUX.2-klein-9B-ComfyUI" in ids # the 8B encoder this load pulled
+ nine_b = _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS[0][0]
+ four_b = fam.sd_cpp_text_encoders[0][0]
+ assert nine_b != four_b
+ assert nine_b in ids # the 8B encoder this load pulled (unsloth/Qwen3-8B-GGUF)
# The 4B default must not be protected instead.
- assert "unsloth/Z-Image-Turbo-ComfyUI" not in ids
+ assert four_b not in ids
class _FakeServer:
@@ -256,7 +259,8 @@ class _FakeServer:
@pytest.mark.parametrize(
"fam_name,expect_kinds",
[
- ("flux.1", {"diffusion_model", "vae", "clip_l", "t5xxl"}),
+ # The T5-XXL is sharded: the index is the t5xxl input, its shards ride along as t5xxl_shard.
+ ("flux.1", {"diffusion_model", "vae", "clip_l", "t5xxl", "t5xxl_shard"}),
("z-image", {"diffusion_model", "vae", "llm"}),
("qwen-image", {"diffusion_model", "vae", "qwen2vl"}),
("flux.2-klein", {"diffusion_model", "vae", "llm"}),
@@ -286,25 +290,35 @@ def _plan_sees_an_empty_cache(monkeypatch):
)
+_Z_IMAGE_KIND_BYTES = {"diffusion_model": 4_000, "vae": 300, "llm": 8_000}
+
+
+def _z_image_native_assets(monkeypatch, b):
+ """kind -> (fetch repo, file) and (fetch repo, file) -> size for a z-image GGUF pick, read off the family table
+ and the same fetch map the plan uses, so the test follows the table instead of naming its repos."""
+ monkeypatch.setattr(
+ "core.inference.diffusion_families._upstream_is_cached",
+ lambda repo_id, files = None, **kwargs: False,
+ )
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
+ specs = b._asset_specs(
+ "unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf", detect_family("z-image")
+ )
+ fetch = bk._fetch_repo_map(specs, None)
+ by_kind = {k: (fetch[r], f) for r, f, k in specs}
+ assert set(by_kind) == set(_Z_IMAGE_KIND_BYTES)
+ return by_kind, {by_kind[k]: n for k, n in _Z_IMAGE_KIND_BYTES.items()}
+
+
def test_download_plan_skips_assets_already_in_the_cache(monkeypatch):
# _fetch_assets resolves either cache root, so staging a file it can already open re-downloads
# it for nothing and fails offline. required_bytes stays the full footprint regardless.
from core.inference.diffusion import DiffusionBackend
b = SdCppDiffusionBackend(engine = _FakeEngine())
+ by_kind, sizes = _z_image_native_assets(monkeypatch, b)
monkeypatch.setattr(
- SdCppDiffusionBackend,
- "_plan_file_sizes",
- staticmethod(
- lambda by_repo, token: {
- ("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf"): 4_000,
- ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/vae/ae.safetensors"): 300,
- (
- "unsloth/Z-Image-Turbo-ComfyUI",
- "split_files/text_encoders/qwen_3_4b.safetensors",
- ): 8_000,
- }
- ),
+ SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
)
cached = {"z-image-turbo-Q4_K_M.gguf"}
@@ -323,15 +337,19 @@ def test_download_plan_skips_assets_already_in_the_cache(monkeypatch):
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
model_kind = "gguf",
)
- cached.add("split_files/vae/ae.safetensors")
+ cached.add(by_kind["vae"][1])
warming = b.download_plan(
"unsloth/Z-Image-Turbo-GGUF",
gguf_filename = "z-image-turbo-Q4_K_M.gguf",
model_kind = "gguf",
)
- assert [e["repo_id"] for e in plan["entries"]] == ["unsloth/Z-Image-Turbo-ComfyUI"]
- assert plan["entries"][0]["files"] == warming["entries"][0]["files"]
+ vae_repo, llm_repo = by_kind["vae"][0], by_kind["llm"][0]
+ assert vae_repo != llm_repo # the VAE and the encoder now come from separate repos
+ assert [e["repo_id"] for e in plan["entries"]] == [vae_repo, llm_repo]
+ # Once the VAE is cached its repo has nothing left to stage; the encoder entry is unchanged.
+ assert [e["repo_id"] for e in warming["entries"]] == [llm_repo]
+ assert plan["entries"][1]["files"] == warming["entries"][0]["files"]
assert plan["total_bytes"] == 8_300
assert warming["total_bytes"] == 8_000
assert plan["required_bytes"] == 12_300
@@ -410,19 +428,9 @@ def test_download_plan_restages_a_native_asset_that_changed_size(monkeypatch):
b = SdCppDiffusionBackend(engine = _FakeEngine())
seen = {}
+ by_kind, sizes = _z_image_native_assets(monkeypatch, b)
monkeypatch.setattr(
- SdCppDiffusionBackend,
- "_plan_file_sizes",
- staticmethod(
- lambda by_repo, token: {
- ("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf"): 4_000,
- ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/vae/ae.safetensors"): 300,
- (
- "unsloth/Z-Image-Turbo-ComfyUI",
- "split_files/text_encoders/qwen_3_4b.safetensors",
- ): 8_000,
- }
- ),
+ SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
)
def probe(
@@ -444,7 +452,8 @@ def test_download_plan_restages_a_native_asset_that_changed_size(monkeypatch):
)
assert seen["z-image-turbo-Q4_K_M.gguf"] == 4_000
- assert seen["split_files/vae/ae.safetensors"] == 300
+ assert seen[by_kind["vae"][1]] == 300
+ assert seen[by_kind["llm"][1]] == 8_000
assert all(size for size in seen.values()), "an unsized probe trusts the local ref alone"
@@ -470,11 +479,7 @@ def test_download_plan_is_empty_when_every_native_asset_is_cached(monkeypatch):
def test_download_plan_stages_exactly_what_sd_cli_opens(monkeypatch):
# The plan feeds the Hub download manager. Native reads single-file assets, so a native-routed pick must be staged from the asset specs.
b = SdCppDiffusionBackend(engine = _FakeEngine())
- sizes = {
- ("unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf"): 4_000,
- ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/vae/ae.safetensors"): 300,
- ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/text_encoders/qwen_3_4b.safetensors"): 8_000,
- }
+ by_kind, sizes = _z_image_native_assets(monkeypatch, b)
monkeypatch.setattr(
SdCppDiffusionBackend,
"_plan_file_sizes",
@@ -490,36 +495,31 @@ def test_download_plan_stages_exactly_what_sd_cli_opens(monkeypatch):
memory_mode = "low_vram",
)
- fam = detect_family("z-image")
- expected = {
- (r, f)
- for r, f, _k in b._asset_specs(
- "unsloth/Z-Image-Turbo-GGUF", "z-image-turbo-Q4_K_M.gguf", fam
- )
- }
+ expected = set(by_kind.values()) # every asset spec, under the repo the fetch pulls it from
listed = {(e["repo_id"], f) for e in plan["entries"] for f in e["files"]}
assert listed == expected
assert plan["total_bytes"] == 12_300
assert plan["required_bytes"] == 12_300
assert plan["checkpoint_bytes"] == 4_000
- # The transformer entry is the only one carrying the GGUF filename; the VAE + encoder share one repo entry.
+ # The transformer entry is the only one carrying the GGUF filename; the VAE and the encoder get one entry each.
tr = [e for e in plan["entries"] if e["gguf_filename"]]
assert len(tr) == 1 and tr[0]["repo_id"] == "unsloth/Z-Image-Turbo-GGUF"
- assert len([e for e in plan["entries"] if e["repo_id"] == "unsloth/Z-Image-Turbo-ComfyUI"]) == 1
+ for kind in ("vae", "llm"):
+ assert len([e for e in plan["entries"] if e["repo_id"] == by_kind[kind][0]]) == 1, kind
def test_download_plan_merges_asset_repos_that_share_one_fetch_repo(monkeypatch):
- # Two upstream repos can resolve to ONE fetch repo: on an install that already holds the
- # Comfy-Org/flux2-dev repack, both unsloth/FLUX.2-VAE and unsloth/FLUX.2-dev-ComfyUI are
- # served from it. Keying the swapped map by fetch repo therefore drops whichever landed
- # first, taking its files out of the staged entry AND out of the footprint.
+ # Two upstream repos can resolve to ONE fetch repo (e.g. two mirrors of the same cached
+ # community repack). Synthetic repos: the mechanism is generic, and no image asset is a repack
+ # any more. Keying the swapped map by fetch repo therefore drops whichever landed first,
+ # taking its files out of the staged entry AND out of the footprint.
import core.inference.sd_cpp_backend as S
b = SdCppDiffusionBackend(engine = _FakeEngine())
specs = [
("unsloth/FLUX.2-dev-GGUF", "flux2-dev-Q4_K_M.gguf", "transformer"),
- ("unsloth/FLUX.2-VAE", "vae/ae.safetensors", "vae"),
- ("unsloth/FLUX.2-dev-ComfyUI", "text_encoders/mistral.safetensors", "text_encoder"),
+ ("unsloth/example-vae-mirror", "vae/ae.safetensors", "vae"),
+ ("unsloth/example-encoder-mirror", "text_encoders/mistral.safetensors", "text_encoder"),
]
monkeypatch.setattr(SdCppDiffusionBackend, "_asset_specs", lambda *a, **k: specs)
monkeypatch.setattr(
@@ -527,15 +527,15 @@ def test_download_plan_merges_asset_repos_that_share_one_fetch_repo(monkeypatch)
"_fetch_repo_map",
lambda assets, token: {
"unsloth/FLUX.2-dev-GGUF": "unsloth/FLUX.2-dev-GGUF",
- "unsloth/FLUX.2-VAE": "Comfy-Org/flux2-dev",
- "unsloth/FLUX.2-dev-ComfyUI": "Comfy-Org/flux2-dev",
+ "unsloth/example-vae-mirror": "some-org/example-repack",
+ "unsloth/example-encoder-mirror": "some-org/example-repack",
},
)
monkeypatch.setattr(SdCppDiffusionBackend, "_preflight_companion_repos", lambda *a, **k: None)
sizes = {
("unsloth/FLUX.2-dev-GGUF", "flux2-dev-Q4_K_M.gguf"): 4_000,
- ("Comfy-Org/flux2-dev", "vae/ae.safetensors"): 300,
- ("Comfy-Org/flux2-dev", "text_encoders/mistral.safetensors"): 8_000,
+ ("some-org/example-repack", "vae/ae.safetensors"): 300,
+ ("some-org/example-repack", "text_encoders/mistral.safetensors"): 8_000,
}
monkeypatch.setattr(
SdCppDiffusionBackend, "_plan_file_sizes", staticmethod(lambda by_repo, token: sizes)
@@ -552,7 +552,7 @@ def test_download_plan_merges_asset_repos_that_share_one_fetch_repo(monkeypatch)
"unsloth/FLUX.2-dev-GGUF", gguf_filename = "flux2-dev-Q4_K_M.gguf", model_kind = "gguf"
)
- shared = next(e for e in plan["entries"] if e["repo_id"] == "Comfy-Org/flux2-dev")
+ shared = next(e for e in plan["entries"] if e["repo_id"] == "some-org/example-repack")
assert sorted(shared["files"]) == [
"text_encoders/mistral.safetensors",
"vae/ae.safetensors",
@@ -572,8 +572,9 @@ def test_download_plan_skips_a_local_transformer_but_still_stages_the_assets(mon
str(tmp_path), gguf_filename = "z-image-turbo-Q4_K_M.gguf", model_kind = "gguf"
)
+ by_kind, _sizes = _z_image_native_assets(monkeypatch, b)
assert str(tmp_path) not in {e["repo_id"] for e in plan["entries"]}
- assert {e["repo_id"] for e in plan["entries"]} == {"unsloth/Z-Image-Turbo-ComfyUI"}
+ assert {e["repo_id"] for e in plan["entries"]} == {by_kind["vae"][0], by_kind["llm"][0]}
# An unreadable size understates the total; it must never fail the plan.
assert plan["total_bytes"] == 0
@@ -605,16 +606,28 @@ def test_download_plan_stages_the_mirrored_asset_repo(monkeypatch):
assert len(tr) == 1 and tr[0]["repo_id"] == "unsloth/FLUX.1-dev-GGUF"
-def test_download_plan_and_fetch_assets_pick_the_same_repo(monkeypatch):
+def test_download_plan_and_fetch_assets_pick_the_same_repo(monkeypatch, tmp_path):
"""Staging one repo and then downloading from the other is the failure this feature removes,
so both sides take the decision from the same per-repo file list."""
+ import json
+
_no_cache(monkeypatch)
b = _shared_setup_4(monkeypatch)
pulled: list = []
- monkeypatch.setattr(
- "utils.hf_xet_fallback.hf_hub_download_with_xet_fallback",
- lambda repo, fn, tok, **k: (pulled.append((repo, fn)), f"/cache/{fn}")[1],
- )
+
+ def fake_download(repo, fn, tok, **k):
+ # Real files in one snapshot dir per repo: the load checks the T5-XXL index's shards sit beside it.
+ pulled.append((repo, fn))
+ path = tmp_path / repo.replace("/", "--") / fn
+ path.parent.mkdir(parents = True, exist_ok = True)
+ if fn.endswith(".safetensors.index.json"):
+ shards = [f.rsplit("/", 1)[-1] for _r, f, kind in specs if kind == "t5xxl_shard"]
+ path.write_text(json.dumps({"weight_map": {str(i): n for i, n in enumerate(shards)}}))
+ else:
+ path.write_bytes(b"x")
+ return str(path)
+
+ monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", fake_download)
fam = detect_family("flux.1")
specs = b._asset_specs("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", fam)
@@ -662,18 +675,14 @@ def test_asset_specs_flux2_klein_selects_encoder_by_variant():
specs_4b = b._asset_specs("unsloth/FLUX.2-klein-4B-GGUF", "FLUX.2-klein-4B-Q4_K_M.gguf", fam)
te_4b = [(r, f) for r, f, k in specs_4b if k == "llm"]
- assert te_4b == [
- ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/text_encoders/qwen_3_4b.safetensors")
- ]
+ assert te_4b == [(r, f) for r, f, _k in fam.sd_cpp_text_encoders]
+ assert te_4b[0][0] == "unsloth/Qwen3-4B-GGUF"
specs_9b = b._asset_specs("unsloth/FLUX.2-klein-9B-GGUF", "FLUX.2-klein-9B-Q4_K_M.gguf", fam)
te_9b = [(r, f) for r, f, k in specs_9b if k == "llm"]
- assert te_9b == [
- (
- "unsloth/FLUX.2-klein-9B-ComfyUI",
- "split_files/text_encoders/qwen_3_8b.safetensors",
- )
- ]
+ assert te_9b == [(r, f) for r, f, _k in _FLUX2_KLEIN_9B_SD_CPP_TEXT_ENCODERS]
+ assert te_9b[0][0] == "unsloth/Qwen3-8B-GGUF"
+ assert te_4b != te_9b
# A rename or takedown in a community repack breaks every no-GPU load needing the file, so each
@@ -700,44 +709,61 @@ def test_no_sd_cpp_asset_comes_from_a_community_repack():
def test_the_moved_sd_cpp_assets_keep_their_upstream_relative_paths():
- # The mirrors kept the upstream paths, so the swap is an id change only; a reorganised mirror
- # would 404 sd-cli at load time.
- want = {
- "flux.1": [
- ("unsloth/flux-text-encoders", "clip_l.safetensors"),
- ("unsloth/flux-text-encoders", "t5xxl_fp16.safetensors"),
- ],
- "flux.2-klein": [
- ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/text_encoders/qwen_3_4b.safetensors"),
- ],
- "flux.2-dev": [
- (
- "unsloth/FLUX.2-dev-ComfyUI",
- "split_files/text_encoders/mistral_3_small_flux2_bf16.safetensors",
- ),
- ],
- "z-image": [
- ("unsloth/Z-Image-Turbo-ComfyUI", "split_files/text_encoders/qwen_3_4b.safetensors"),
- ],
- }
- for name, encoders in want.items():
- fam = detect_family(name)
- assert [(r, f) for r, f, _k in fam.sd_cpp_text_encoders] == encoders, name
- assert detect_family("qwen-image").sd_cpp_vae == (
- "unsloth/Qwen-Image-ComfyUI",
- "split_files/vae/qwen_image_vae.safetensors",
- )
+ # Every image sd-cli asset is an official upstream file at its upstream path (fetched through the
+ # ungated mirror, which keeps the same path, so the swap is an id change only) or an unsloth GGUF
+ # of the encoder model. A reorganised mirror would 404 sd-cli at load time.
+ from core.inference.diffusion_families import _FLUX1_SD_CPP_TEXT_ENCODERS, mirror_repo
+
+ flux1 = [(r, f) for r, f, _k in _FLUX1_SD_CPP_TEXT_ENCODERS]
+ assert flux1 == [
+ ("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors"),
+ ("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model.safetensors.index.json"),
+ ("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model-00001-of-00002.safetensors"),
+ ("black-forest-labs/FLUX.1-schnell", "text_encoder_2/model-00002-of-00002.safetensors"),
+ ]
+ assert [k for _r, _f, k in _FLUX1_SD_CPP_TEXT_ENCODERS] == [
+ "clip_l",
+ "t5xxl",
+ "t5xxl_shard",
+ "t5xxl_shard",
+ ]
+ for name in ("flux.1", "flux.1-kontext"):
+ assert detect_family(name).sd_cpp_text_encoders == _FLUX1_SD_CPP_TEXT_ENCODERS, name
+ assert detect_family(name).sd_cpp_vae == (
+ "black-forest-labs/FLUX.1-schnell",
+ "ae.safetensors",
+ )
+ # Klein 4B and Z-Image share one Qwen3-4B GGUF; FLUX.2-dev reads the Mistral-Small-3.2 GGUF.
+ for name in ("flux.2-klein", "z-image"):
+ [(repo, fn, kind)] = detect_family(name).sd_cpp_text_encoders
+ assert (repo, kind) == ("unsloth/Qwen3-4B-GGUF", "llm"), name
+ assert fn.startswith("Qwen3-4B-") and fn.endswith(".gguf"), name
+ [(repo, fn, kind)] = detect_family("flux.2-dev").sd_cpp_text_encoders
+ assert (repo, kind) == ("unsloth/Mistral-Small-3.2-24B-Instruct-2506-GGUF", "llm")
+ assert fn.startswith("Mistral-Small-3.2-24B-Instruct-2506-") and fn.endswith(".gguf")
+
+ for name in ("qwen-image", "qwen-image-edit"):
+ assert detect_family(name).sd_cpp_vae == (
+ "Qwen/Qwen-Image",
+ "vae/diffusion_pytorch_model.safetensors",
+ ), name
+ # Z-Image decodes with the FLUX.1 autoencoder.
assert detect_family("z-image").sd_cpp_vae == (
- "unsloth/Z-Image-Turbo-ComfyUI",
- "split_files/vae/ae.safetensors",
+ "black-forest-labs/FLUX.1-schnell",
+ "ae.safetensors",
)
- # The FLUX.2 autoencoder is Apache-2.0 while the conditioner beside it in the source repack is
- # not, so it is mirrored on its own.
for name in ("flux.2-klein", "flux.2-dev"):
assert detect_family(name).sd_cpp_vae == (
- "unsloth/FLUX.2-VAE",
- "split_files/vae/flux2-vae.safetensors",
+ "black-forest-labs/FLUX.2-dev",
+ "vae/diffusion_pytorch_model.safetensors",
), name
+ # Each vendor VAE / encoder repo is reached through an unsloth mirror holding the same path.
+ for upstream in (
+ "black-forest-labs/FLUX.1-schnell",
+ "black-forest-labs/FLUX.2-dev",
+ "Qwen/Qwen-Image",
+ ):
+ assert (mirror_repo(upstream) or "").startswith("unsloth/"), upstream
# ── guidance mapping ──────────────────────────────────────────────────────────
@@ -2245,14 +2271,25 @@ def test_native_negative_prompt_reaches_sd_cli_only_when_cfg_runs():
assert out["negative_prompt"] is None
+def _synthetic_legacy_row(monkeypatch):
+ """(repack, mirror) after adding a made-up mirror -> community repack row to the legacy table."""
+ from core.inference import diffusion_families
+
+ repack, mirror = "some-org/example-repack", "unsloth/example-repack-mirror"
+ monkeypatch.setitem(diffusion_families._SD_CPP_LEGACY_SOURCES, mirror.lower(), repack)
+ return repack, mirror
+
+
def test_a_cached_community_repack_is_reused_instead_of_re_downloading_the_mirror(
monkeypatch, tmp_path
):
- """reuse repo-id-keyed legacy caches to avoid redownloads and keep offline loads working."""
+ """reuse repo-id-keyed legacy caches to avoid redownloads and keep offline loads working.
+
+ Synthetic mirror -> repack row: the mechanism is generic, and only video assets still have one."""
from core.inference.diffusion_families import prefer_cached_legacy_source
from core.inference.sd_cpp_backend import _fetch_repo_map
- repack = "Comfy-Org/z_image_turbo"
+ repack, mirror = _synthetic_legacy_row(monkeypatch)
root = tmp_path / f"models--{repack.replace('/', '--')}"
snapshot = root / "snapshots" / ("d" * 40)
(snapshot / "split_files" / "vae").mkdir(parents = True)
@@ -2263,8 +2300,8 @@ def test_a_cached_community_repack_is_reused_instead_of_re_downloading_the_mirro
"utils.hf_cache_settings.active_hf_hub_cache", lambda: str(tmp_path), raising = False
)
- assets = [("unsloth/Z-Image-Turbo-ComfyUI", "split_files/vae/ae.safetensors", "vae")]
- assert _fetch_repo_map(assets, None)["unsloth/Z-Image-Turbo-ComfyUI"] == repack
+ assets = [(mirror, "split_files/vae/ae.safetensors", "vae")]
+ assert _fetch_repo_map(assets, None)[mirror] == repack
# A fresh install has no repack, so the mirror stays the source.
monkeypatch.setattr(
@@ -2272,9 +2309,7 @@ def test_a_cached_community_repack_is_reused_instead_of_re_downloading_the_mirro
lambda: str(tmp_path / "empty"),
raising = False,
)
- assert _fetch_repo_map(assets, None)["unsloth/Z-Image-Turbo-ComfyUI"] == (
- "unsloth/Z-Image-Turbo-ComfyUI"
- )
+ assert _fetch_repo_map(assets, None)[mirror] == mirror
# And a repo that mirrors nothing is returned unchanged.
assert prefer_cached_legacy_source("unsloth/Qwen-Image", ["x"]) == "unsloth/Qwen-Image"
@@ -2287,10 +2322,10 @@ def test_a_repack_left_in_the_pre_change_cache_root_still_wins_over_the_mirror(
The fetch passes reuse_other_cache_root, so a file cached only under huggingface_hub's
import-time root resolves through that root -- but only under the repo id it was filed as.
Picking the mirror because the LIVE root looks empty makes those bytes unreachable: several GB
- re-download online, and offline the load fails."""
+ re-download online, and offline the load fails. Synthetic mirror -> repack row, as above."""
from core.inference.sd_cpp_backend import _fetch_repo_map
- repack = "Comfy-Org/z_image_turbo"
+ repack, mirror = _synthetic_legacy_row(monkeypatch)
other = tmp_path / "before_the_move"
root = other / f"models--{repack.replace('/', '--')}"
snapshot = root / "snapshots" / ("d" * 40)
@@ -2306,8 +2341,8 @@ def test_a_repack_left_in_the_pre_change_cache_root_still_wins_over_the_mirror(
)
monkeypatch.setattr("huggingface_hub.constants.HF_HUB_CACHE", str(other))
- assets = [("unsloth/Z-Image-Turbo-ComfyUI", "split_files/vae/ae.safetensors", "vae")]
- assert _fetch_repo_map(assets, None)["unsloth/Z-Image-Turbo-ComfyUI"] == repack
+ assets = [(mirror, "split_files/vae/ae.safetensors", "vae")]
+ assert _fetch_repo_map(assets, None)[mirror] == repack
def test_the_delete_guard_names_the_repack_as_well_as_the_mirror(monkeypatch):
@@ -2315,9 +2350,13 @@ def test_the_delete_guard_names_the_repack_as_well_as_the_mirror(monkeypatch):
a guard naming only one of them can delete a repo the next load needs."""
from core.inference.sd_cpp_backend import _with_mirrors
- protected = _with_mirrors(["unsloth/Z-Image-Turbo-ComfyUI"])
- assert "unsloth/Z-Image-Turbo-ComfyUI" in protected
- assert "Comfy-Org/z_image_turbo" in protected
+ repack, mirror = _synthetic_legacy_row(monkeypatch)
+ protected = _with_mirrors([mirror])
+ assert mirror in protected
+ assert repack in protected
+ # The remaining real (video) row is covered the same way.
+ protected = _with_mirrors(["unsloth/Wan2.2-TI2V-5B-GGUF"])
+ assert "QuantStack/Wan2.2-TI2V-5B-GGUF" in protected
def test_begin_load_answers_without_waiting_on_the_header_probe(monkeypatch):
@@ -2875,3 +2914,129 @@ def test_only_managed_cpu_binaries_count_as_cpu_only(monkeypatch):
monkeypatch.setattr(bk, "find_sd_server_binary", lambda: None)
monkeypatch.setattr(bk, "find_sd_cpp_binary", lambda: None)
assert bk.sd_cpp_binaries_all_cpu() is False
+
+
+def test_a_t5_index_from_the_old_cache_root_gets_its_shards_beside_it(monkeypatch, tmp_path):
+ """After a cache-folder change the T5 index resolves from the old root while its shards land in the active one.
+ sd-cli reads the shards beside the index, so the load links them there instead of refusing a cache that holds
+ every file (an offline user could not repair it by re-downloading)."""
+ import json
+ from pathlib import Path
+
+ _no_cache(monkeypatch)
+ b = _shared_setup_4(monkeypatch)
+ old_root, live_root = tmp_path / "old", tmp_path / "live"
+
+ def fake_download(repo, fn, tok, **k):
+ root = old_root if fn.endswith(".safetensors.index.json") else live_root
+ path = root / repo.replace("/", "--") / fn
+ path.parent.mkdir(parents = True, exist_ok = True)
+ if fn.endswith(".safetensors.index.json"):
+ shards = [f.rsplit("/", 1)[-1] for _r, f, kind in specs if kind == "t5xxl_shard"]
+ path.write_text(json.dumps({"weight_map": {str(i): n for i, n in enumerate(shards)}}))
+ else:
+ path.write_bytes(b"shard:" + fn.encode())
+ return str(path)
+
+ monkeypatch.setattr("utils.hf_xet_fallback.hf_hub_download_with_xet_fallback", fake_download)
+ fam = detect_family("flux.1")
+ specs = b._asset_specs("unsloth/FLUX.1-dev-GGUF", "flux1-dev-Q4_K_M.gguf", fam)
+ shard_files = [f for _r, f, kind in specs if kind == "t5xxl_shard"]
+ assert len(shard_files) == 2
+
+ paths = b._fetch_assets(specs, None, local_files_only = True)
+
+ index = Path(paths["t5xxl"])
+ assert index.is_relative_to(old_root)
+ for fn in shard_files:
+ beside = index.parent / fn.rsplit("/", 1)[-1]
+ assert beside.read_bytes() == b"shard:" + fn.encode()
+ # Never a symlink into the other root: deleting or unmounting either root must not break the other.
+ assert not beside.is_symlink()
+
+
+def test_a_cross_device_shard_copy_never_leaves_a_truncated_shard(monkeypatch, tmp_path):
+ """Across filesystems the hard link fails and the shard is copied. A copy cut off (full disk) must not leave a
+ file at the final name, since the existence check would accept it, and a short file left by an earlier copy is
+ replaced on the next load."""
+ import json
+ import os
+ import shutil
+
+ from core.inference import sd_cpp_backend as mod
+
+ src = tmp_path / "live" / "model-00001-of-00001.safetensors"
+ src.parent.mkdir(parents = True)
+ src.write_bytes(b"x" * 4096)
+ index = tmp_path / "old" / "model.safetensors.index.json"
+ index.parent.mkdir(parents = True)
+ index.write_text(json.dumps({"weight_map": {"a": src.name}}))
+ target = index.parent / src.name
+
+ def no_link(*_a, **_k):
+ raise OSError("cross-device link")
+
+ def full_disk(a, b):
+ with open(b, "wb") as fh:
+ fh.write(b"x" * 100)
+ raise OSError("No space left on device")
+
+ real_copyfile = shutil.copyfile
+ monkeypatch.setattr(mod.os, "link", no_link)
+ monkeypatch.setattr(mod.shutil, "copyfile", full_disk)
+ mod._colocate_shards(str(index), {src.name: str(src)})
+ assert not target.exists()
+ assert os.listdir(index.parent) == [index.name]
+
+ # A short shard from an earlier, cut-off copy is replaced by a complete one.
+ target.write_bytes(b"x" * 100)
+ monkeypatch.setattr(mod.shutil, "copyfile", real_copyfile)
+ mod._colocate_shards(str(index), {src.name: str(src)})
+ assert target.read_bytes() == src.read_bytes()
+ assert sorted(os.listdir(index.parent)) == sorted([index.name, src.name])
+
+
+def test_the_native_fetch_keeps_an_upstream_cached_only_in_the_pre_change_root(monkeypatch):
+ """_fetch_assets resolves each file through either cache root, so FLUX.1's CLIP / T5 left in the previous root
+ serve the load. Deciding the mirror swap off the live root alone rewrote them to unsloth/FLUX.1-schnell, which a
+ cache-only load then could not find and an online one re-pulled (~10 GB)."""
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_NO_MIRROR", raising = False)
+ monkeypatch.setattr(
+ "core.inference.diffusion_families._upstream_is_cached",
+ lambda repo_id, files = None, *, other_root = False: other_root,
+ )
+ assets = [
+ ("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors", "clip_l"),
+ ("black-forest-labs/FLUX.1-schnell", "ae.safetensors", "vae"),
+ ]
+ assert bk._fetch_repo_map(assets, None) == {
+ "black-forest-labs/FLUX.1-schnell": "black-forest-labs/FLUX.1-schnell"
+ }
+
+
+def test_the_native_progress_total_is_sized_where_the_assets_are_fetched(monkeypatch):
+ """An anonymous user gets nothing back from a gated vendor id, so sizing FLUX.1's CLIP / T5 there left them at 0
+ bytes and the bar finalizing while they downloaded. The total asks the repo _fetch_assets pulls from."""
+ from types import SimpleNamespace
+
+ from huggingface_hub import HfApi
+
+ _no_cache(monkeypatch)
+ asked = []
+
+ def get_paths_info(self, repo_id, paths, **kwargs):
+ asked.append(repo_id)
+ if not repo_id.startswith("unsloth/"):
+ raise PermissionError("gated")
+ return [SimpleNamespace(path = p, size = 1_000) for p in paths]
+
+ monkeypatch.setattr(HfApi, "get_paths_info", get_paths_info)
+ b = SdCppDiffusionBackend(engine = _FakeEngine())
+ b._loading = SimpleNamespace(expected_bytes = 0)
+ assets = [
+ ("black-forest-labs/FLUX.1-schnell", "text_encoder/model.safetensors", "clip_l"),
+ ("black-forest-labs/FLUX.1-schnell", "ae.safetensors", "vae"),
+ ]
+ b._set_expected_bytes(assets, None)
+ assert asked == ["unsloth/FLUX.1-schnell", "unsloth/FLUX.1-schnell"]
+ assert b._loading.expected_bytes == 2_000
diff --git a/studio/backend/tests/test_sd_cpp_edit_families.py b/studio/backend/tests/test_sd_cpp_edit_families.py
index 968fd642b5d..5d1cd884b20 100644
--- a/studio/backend/tests/test_sd_cpp_edit_families.py
+++ b/studio/backend/tests/test_sd_cpp_edit_families.py
@@ -95,7 +95,8 @@ def test_every_qwen_edit_checkpoint_maps_to_vae_encoder_and_projector(repo, file
specs = SdCppDiffusionBackend(engine = _FakeEngine())._asset_specs(repo, filename, fam)
assert specs == [
(repo, filename, "diffusion_model"),
- ("unsloth/Qwen-Image-ComfyUI", "split_files/vae/qwen_image_vae.safetensors", "vae"),
+ # qwen-image's official diffusers VAE, the same one the base family reads.
+ ("Qwen/Qwen-Image", "vae/diffusion_pytorch_model.safetensors", "vae"),
(
"unsloth/Qwen2.5-VL-7B-Instruct-GGUF",
"Qwen2.5-VL-7B-Instruct-Q4_K_M.gguf",
@@ -103,6 +104,7 @@ def test_every_qwen_edit_checkpoint_maps_to_vae_encoder_and_projector(repo, file
),
("unsloth/Qwen2.5-VL-7B-Instruct-GGUF", "mmproj-F16.gguf", "llm_vision"),
]
+ assert fam.sd_cpp_vae == detect_family("qwen-image").sd_cpp_vae
assert (fam.sd_cpp_sampling_method, fam.sd_cpp_flow_shift) == ("euler", 3.0)
assert text_encoder_flags_for_family(fam.name) == ("--qwen2vl",)
@@ -116,15 +118,24 @@ def test_kontext_maps_to_the_flux1_assets():
specs = SdCppDiffusionBackend(engine = _FakeEngine())._asset_specs(
"unsloth/FLUX.1-Kontext-dev-GGUF", "flux1-kontext-dev-Q4_K_M.gguf", fam
)
- assert [k for _r, _f, k in specs] == ["diffusion_model", "vae", "clip_l", "t5xxl"]
+ # The T5-XXL is BFL's sharded file: the index is the --t5xxl input, its two shards are fetched beside it.
+ assert [k for _r, _f, k in specs] == [
+ "diffusion_model",
+ "vae",
+ "clip_l",
+ "t5xxl",
+ "t5xxl_shard",
+ "t5xxl_shard",
+ ]
assert text_encoder_flags_for_family(fam.name) == ("--clip_l", "--t5xxl")
def test_the_new_companions_stay_fetch_only_and_bases_stay_loadable():
companions = sd_cpp_companion_only_repo_ids()
- assert "unsloth/qwen-image-comfyui" in companions
assert "unsloth/qwen2.5-vl-7b-instruct-gguf" in companions
- # The FLUX.1 VAE lives in a real base; mapping Kontext onto it must not hide that base.
+ # The Qwen edit VAE and the FLUX.1 VAE / encoders live in real bases; mapping the edit families
+ # onto them must not hide those bases.
+ assert "qwen/qwen-image" not in companions
assert "black-forest-labs/flux.1-schnell" not in companions
diff --git a/studio/backend/tests/test_sd_cpp_sample_sigmas.py b/studio/backend/tests/test_sd_cpp_sample_sigmas.py
index 320ab4d81fa..2a13b6e22f2 100644
--- a/studio/backend/tests/test_sd_cpp_sample_sigmas.py
+++ b/studio/backend/tests/test_sd_cpp_sample_sigmas.py
@@ -109,17 +109,25 @@ def test_other_step_counts_resample_along_the_grid(steps):
def _patch_hub(monkeypatch, *, card_base, indexes):
- calls = {"card": 0, "index": []}
+ """``indexes`` is keyed by the UPSTREAM base; the read lands on whichever id the fetch swap picks (its unsloth
+ mirror while the upstream is uncached, pinned here), so ``index`` records the base it stands for and ``read`` the
+ id actually read."""
+ from core.inference import diffusion_families as families
+
+ calls = {"card": 0, "index": [], "read": []}
+ monkeypatch.setattr(families, "_upstream_is_cached", lambda *a, **k: False)
def _card(repo_id, token):
calls["card"] += 1
return card_base
def _index(base, **kw):
- calls["index"].append((base, kw.get("local_files_only")))
- if base not in indexes:
+ upstream = families.canonical_base(base)
+ calls["read"].append(base)
+ calls["index"].append((upstream, kw.get("local_files_only")))
+ if upstream not in indexes:
raise FileNotFoundError(base)
- return indexes[base]
+ return indexes[upstream]
monkeypatch.setattr(diffusion_mod, "_hf_base_model", _card)
monkeypatch.setattr(comfy_components, "read_model_index", _index)
@@ -245,6 +253,24 @@ def test_a_local_turbo_gguf_without_a_card_takes_the_named_grid(monkeypatch):
assert calls["index"][-1][0] == "Qwen/Qwen-Image-2.1-Turbo"
[email protected]("local_files_only", [False, True])
+def test_the_grid_is_read_from_the_bases_unsloth_mirror(monkeypatch, local_files_only):
+ """Qwen/Qwen-Image-2.1-Turbo's index ships inside unsloth/Qwen-Image-2.1-Turbo-FP8, which is where the plan stages
+ it. Reading the vendor id instead fetched it from Qwen, and a cache holding only the mirror lost Turbo's grid."""
+ calls = _patch_hub(monkeypatch, card_base = None, indexes = INDEXES)
+ grid, base = bk._base_sample_sigmas(
+ REPO,
+ FAM.base_repo,
+ None,
+ family = FAM.name,
+ explicit_base = False,
+ local_files_only = local_files_only,
+ named_base = "Qwen/Qwen-Image-2.1-Turbo",
+ )
+ assert grid == TURBO_GRID and base == "Qwen/Qwen-Image-2.1-Turbo"
+ assert calls["read"] and all(r == "unsloth/Qwen-Image-2.1-Turbo-FP8" for r in calls["read"])
+
+
@pytest.mark.parametrize(
"gguf, base_repo, staged",
[
@@ -257,8 +283,10 @@ def test_a_local_turbo_gguf_without_a_card_takes_the_named_grid(monkeypatch):
)
def test_the_native_plan_stages_a_named_variants_index(monkeypatch, gguf, base_repo, staged):
# Locality approves a cache-only load from this plan, so the index the load reads for its grid is in it.
+ from core.inference import diffusion_families as families
from core.inference.diffusion import DiffusionBackend
+ monkeypatch.setattr(families, "_upstream_is_cached", lambda *a, **k: False)
repo = "someone/Qwen-Image-2.1-GGUF"
b = SdCppDiffusionBackend(engine = _FakeEngine())
monkeypatch.setattr(b, "_asset_specs", lambda *a, **k: [(repo, gguf, "diffusion_model")])
@@ -271,7 +299,11 @@ def test_the_native_plan_stages_a_named_variants_index(monkeypatch, gguf, base_r
DiffusionBackend, "_hub_file_is_loadable", staticmethod(lambda *a, **k: False)
)
plan = b.download_plan(repo, gguf_filename = gguf, base_repo = base_repo, model_kind = "gguf")
- index = [e for e in plan["entries"] if e["repo_id"].lower() == "qwen/qwen-image-2.1-turbo"]
+ # Staged under the mirror the load reads it from, never the vendor id.
+ assert not [e for e in plan["entries"] if e["repo_id"].lower().startswith("qwen/")]
+ index = [
+ e for e in plan["entries"] if e["repo_id"].lower() == "unsloth/qwen-image-2.1-turbo-fp8"
+ ]
assert (
(index == [{**index[0], "files": ["model_index.json"], "checkpoint": False}])
if staged
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
index d810ac3aa20..b2595dc4064 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
@@ -256,7 +256,8 @@ export const IMAGE_CATALOG: CatalogGroup[] = [
],
},
{
- // A different denoiser with its own FP8/INT8 checkpoints; no unsloth mirror, so the vendor pipeline is the row.
+ // A different denoiser with its own FP8/INT8 checkpoints. The bf16 row keeps the vendor id; the backend fetches
+ // it from unsloth/Qwen-Image-2.1-Turbo-FP8, which carries the official diffusers folders byte-identical.
canonicalId: "Qwen/Qwen-Image-2.1-Turbo",
displayName: "Qwen-Image 2.1 Turbo",
description: "Text-to-image and image editing in 8 steps",