Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: keep using an already-downloaded prequant .pt; new users get the .safetensors twin (#12711)
Daniel Hanbdf45e91da1e
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.pyindex b130e3988d7..36a40ebbacc 100644--- a/studio/backend/core/inference/diffusion.py+++ b/studio/backend/core/inference/diffusion.py@@ -276,6 +276,7 @@ from .diffusion_prequant import (prequant_checkpoint_cached,prequant_unreadable_reason,resolve_prequant_source,+ scoped_local_files_only,usable_prequant_source,)from .diffusion_auto_policy import (@@ -1524,6 +1525,7 @@ def _uncached_prequant_repo(*,base_repo: Optional[str],prequant_path: Optional[str],+ online: Optional[bool] = None,) -> Optional[str]:"""The hosted pre-quant repo an AUTO-derived quant would have to DOWNLOAD for this pick, or Nonewhen it costs no extra bytes (no hosted source, a local override, or already cached).@@ -1541,7 +1543,7 @@ def _uncached_prequant_repo()if source is None or source.kind != "repo":return None- if prequant_checkpoint_cached(source, cache_dir = hub_cache_dir()):+ if prequant_checkpoint_cached(source, cache_dir = hub_cache_dir(), online = online):return Nonereturn source.locationexcept Exception: # noqa: BLE001 - a probe that cannot answer keeps the prequant shortcut@@ -2633,7 +2635,11 @@ class DiffusionBackend:)if source is None or getattr(source, "kind", None) != "repo":return True- if prequant_checkpoint_cached(source, cache_dir = hub_cache_dir()):+ if prequant_checkpoint_cached(+ source,+ cache_dir = hub_cache_dir(),+ online = False if kwargs.get("local_files_only") else None,+ ):return Trueif kwargs.get("local_files_only"):return False@@ -3120,6 +3126,7 @@ class DiffusionBackend:).start()return self.status()+ @scoped_local_files_onlydef _run_load(self, **kwargs: Any) -> None:token = kwargs.get("_load_token")# This load's own event: a later load replaces self._cancel_event rather than clearing it.@@ -3897,9 +3904,19 @@ class DiffusionBackend:sizes = {s.rfilename: int(getattr(s, "size", 0) or 0) for s in (info.siblings or [])}# Every candidate, in the order the loader tries them: safetensors first, then the pickle# spellings. Reading only two of them would miss the artifact on a repo that hosts the third.- from .diffusion_prequant import candidate_filenames_of, restricted_prequant_load_supported+ from .diffusion_prequant import (+ candidate_filenames_of,+ prefer_cached_pickle_twins,+ restricted_prequant_load_supported,+ )- for name in candidate_filenames_of(source):+ # The resolver's order, so a cached .pt is priced and staged instead of its uncached twin.+ ordered = prefer_cached_pickle_twins(+ source.location,+ candidate_filenames_of(source),+ readable = lambda n: restricted_prequant_load_supported(scheme, n),+ )+ for name in ordered:if name and name in sizes and restricted_prequant_load_supported(scheme, name):return (source.location, name, int(sizes[name]))# The repo answered and holds NEITHER name. Not "no prequant is used": this pick is configured to@@ -3936,7 +3953,9 @@ class DiffusionBackend:return Falseif getattr(source, "kind", None) != "repo":return True- if prequant_checkpoint_cached(source, cache_dir = hub_cache_dir()):+ if prequant_checkpoint_cached(+ source, cache_dir = hub_cache_dir(), online = False if local_files_only else None+ ):return Trueif local_files_only:return False@@ -5088,6 +5107,7 @@ class DiffusionBackend:TE_PREQUANT_BUDGET_SCALE,TE_PREQUANT_COMPONENTS,te_candidate_filenames,+ te_candidate_is_readable,te_prequant_sources_for_base,)@@ -5113,19 +5133,45 @@ class DiffusionBackend:except OSError:size = 0elif kind == "repo":- names = te_candidate_filenames(source)+ from .diffusion_prequant import (+ first_cached_as_resolved,+ prefer_cached_pickle_twins,+ )- def _sizes(d: Path, names = names) -> dict[str, int]:- for name in names:+ repo = str(source.location)+ sized: dict[str, int] = {}++ def _size_of(name: str) -> int:+ def _sizes(d: Path) -> dict[str, int]:f = d / nameif f.is_file():try:return {"precast": f.stat().st_size}except OSError:return {}- return {}+ return {}++ if name not in sized:+ sized[name] = DiffusionBackend._union_over_cached_revs(repo, _sizes)+ return sized[name]- size = DiffusionBackend._union_over_cached_revs(str(source.location), _sizes)+ # The file the load opens: a cached older encoder does not make an uncached one ahead free.+ names = [+ n for n in te_candidate_filenames(source) if te_candidate_is_readable(n)+ ]+ hit = first_cached_as_resolved(+ repo,+ prefer_cached_pickle_twins(+ repo,+ names,+ readable = te_candidate_is_readable,+ cache_dir = hub_cache_dir(),+ log = False,+ ),+ is_cached = lambda n: _size_of(n) > 0,+ cache_dir = hub_cache_dir(),+ )+ size = _size_of(hit) if hit else 0if size > 0:total += int(size)continue@@ -5191,6 +5237,7 @@ class DiffusionBackend:@_invalidates_gpu_memory("diffusion load")@_account_owned_load@_plans_at_requested_speed+ @scoped_local_files_onlydef load_pipeline(self,repo_id: str,@@ -5624,6 +5671,7 @@ class DiffusionBackend:transformer_quant,base_repo = base,prequant_path = transformer_prequant_path,+ online = False if local_files_only else None,)if uncached_prequant is not None:logger.info(diff --git a/studio/backend/core/inference/diffusion_denoiser_prequant.py b/studio/backend/core/inference/diffusion_denoiser_prequant.pyindex 0f9f604d821..9866ba2fe01 100644--- a/studio/backend/core/inference/diffusion_denoiser_prequant.py+++ b/studio/backend/core/inference/diffusion_denoiser_prequant.py@@ -68,7 +68,9 @@ def denoiser_prequant_cached(return Truetry:from .diffusion_prequant import prequant_checkpoint_cached- return prequant_checkpoint_cached(source, cache_dir = cache_dir)++ # Offline: the load walks to the first cached name, so any cached readable name is what it opens.+ return prequant_checkpoint_cached(source, cache_dir = cache_dir, online = False)except Exception: # noqa: BLE001 -- an unreadable cache is not proof the artifact is therereturn Falsediff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.pyindex 4b590c4f90b..72ef5bd291a 100644--- a/studio/backend/core/inference/diffusion_prequant.py+++ b/studio/backend/core/inference/diffusion_prequant.py@@ -29,6 +29,8 @@ caller falls back to dense-quantise (then GGUF). Inert with nothing configured.from __future__ import annotations+import contextvars+import functoolsimport re as _reimport threading as _threadingfrom dataclasses import dataclass@@ -492,6 +494,250 @@ def _first_mirrored(repo_id: Optional[str], names: Sequence[str], readable: Any)return None+# Set to 1 to always download the safetensors container even when its pickle twin is already cached.+PREFER_SAFETENSORS_ENV = "UNSLOTH_PREQUANT_PREFER_SAFETENSORS"++_PICKLE_SUFFIXES = (".pt", ".pth")+_logged_twin_choices: set = set()+++def _hub_name_cached(+ repo_id: Optional[str], name: Optional[str], root: Optional[str]+) -> Optional[str]:+ """``repo_id/name``'s path in ONE Hub cache root (None = huggingface_hub's own), else None. Never raises."""+ if not repo_id or not name:+ return None+ try:+ import os++ from huggingface_hub import try_to_load_from_cache+ except Exception: # noqa: BLE001 - no cache API to ask: treat as not cached+ return None+ try:+ hit = try_to_load_from_cache(repo_id, name, cache_dir = root)+ except Exception: # noqa: BLE001 - a malformed cache entry is not a hit+ return None+ # a str is the cached path; a miss is None and a known-absent file is a sentinel object+ return hit if isinstance(hit, str) and os.path.isfile(hit) else None+++def _twin_cache_roots(cache_dir: Optional[str]) -> tuple:+ """Every cache root a download could reuse: the caller's, the live setting, huggingface_hub's own."""+ roots: list = []+ live = None+ try:+ from utils.hf_cache_settings import active_hf_hub_cache+ live = active_hf_hub_cache()+ except Exception: # noqa: BLE001 - outside the Studio backend there is no live setting+ live = None+ for root in (cache_dir, live, None):+ if root not in roots:+ roots.append(root)+ return tuple(roots)+++def explain_container_choice(+ repo_id: Optional[str],+ chosen: Optional[str],+ candidates: Sequence[str],+ order: Sequence[str],+ readable: Any = None,+ logger: Any = None,+) -> Optional[str]:+ """Log once per file why a ``.pt`` was resolved although the chain names its safetensors twin+ (cached twin, twin not hosted yet, or safetensors unreadable here). Returns the reason. Never raises."""+ try:+ if not repo_id or not chosen or not chosen.lower().endswith(_PICKLE_SUFFIXES):+ return None+ stem = chosen[: chosen.rfind(".")]+ twin = stem + ".safetensors"+ if twin not in candidates:+ return None+ try:+ twin_ok = readable is None or bool(readable(twin))+ except Exception: # noqa: BLE001+ twin_ok = False+ if not twin_ok:+ reason = "this install cannot read the .safetensors container"+ elif twin in order and chosen in order and order.index(chosen) < order.index(twin):+ return "cached"+ else:+ reason = "the repo does not host the .safetensors twin yet"+ key = (repo_id, chosen, reason)+ if key not in _logged_twin_choices:+ _logged_twin_choices.add(key)+ log = logger+ if log is None:+ import logging+ log = logging.getLogger(__name__)+ log.info(+ "diffusion.prequant_pickle: %s: using %s instead of %s because %s",+ repo_id,+ chosen,+ twin,+ reason,+ )+ return reason+ except Exception: # noqa: BLE001 - a log line, never a failure+ return None+++def prefer_cached_pickle_twins(+ repo_id: Optional[str],+ names: Sequence[str],+ *,+ readable: Any = None,+ cache_dir: Optional[str] = None,+ logger: Any = None,+ log: bool = True,+ roots: Optional[Sequence[Optional[str]]] = None,+) -> list:+ """``names`` with a cached, readable ``<stem>.pt``/``.pth`` moved ahead of its uncached+ ``<stem>.safetensors`` twin, so an existing user does not re-download the same weights.++ Same stem only: a different artifact never jumps the queue. The safetensors name stays right+ behind, so a twin since removed from the Hub 404s onto it. ``PREFER_SAFETENSORS_ENV`` disables.+ Pure cache lookups, never raises."""+ import os++ out = [n for n in names if n]+ if not repo_id or len(out) < 2:+ return out+ if (os.environ.get(PREFER_SAFETENSORS_ENV) or "").strip().lower() in ("1", "true", "yes", "on"):+ return out+ try:+ # only the roots the caller's download will reuse, else it re-fetches the pickle it was promised+ roots = tuple(roots) if roots is not None else _twin_cache_roots(cache_dir)++ def _cached(name: str) -> bool:+ return any(_hub_name_cached(repo_id, name, root) is not None for root in roots)++ def _ok(name: str) -> bool:+ try:+ return readable is None or bool(readable(name))+ except Exception: # noqa: BLE001 - an unanswerable question is a no+ return False++ for st in [n for n in out if n.lower().endswith(".safetensors")]:+ stem = st[: -len(".safetensors")]+ twin = next(+ (+ stem + suffix+ for suffix in _PICKLE_SUFFIXES+ if stem + suffix in out and _ok(stem + suffix) and _cached(stem + suffix)+ ),+ None,+ )+ if twin is None or _cached(st):+ continue+ out.remove(twin)+ out.insert(out.index(st), twin)+ key = (repo_id, twin)+ if log and key not in _logged_twin_choices:+ _logged_twin_choices.add(key)+ sink = logger+ if sink is None:+ import logging+ sink = logging.getLogger(__name__)+ sink.info(+ "diffusion.prequant_cached_pickle: %s: using the cached %s; the %s twin is not "+ "downloaded (set %s=1 to fetch it instead)",+ repo_id,+ twin,+ st,+ PREFER_SAFETENSORS_ENV,+ )+ except Exception: # noqa: BLE001 - a preference, never a new failure+ return [n for n in names if n]+ return out+++_LOCAL_FILES_ONLY = contextvars.ContextVar("unsloth_prequant_local_files_only", default = False)+++def scoped_local_files_only(fn: Any) -> Any:+ """Run ``fn`` with its ``local_files_only`` kwarg visible to every cache probe it reaches, so a+ load that may not download plans like an offline one. Nested calls keep an outer True."""++ @functools.wraps(fn)+ def _wrapper(*args: Any, **kwargs: Any) -> Any:+ token = _LOCAL_FILES_ONLY.set(+ bool(kwargs.get("local_files_only")) or _LOCAL_FILES_ONLY.get()+ )+ try:+ return fn(*args, **kwargs)+ finally:+ _LOCAL_FILES_ONLY.reset(token)++ return _wrapper+++def hub_offline() -> bool:+ """huggingface_hub's offline switch. Never raises."""+ try:+ from huggingface_hub import constants+ return bool(constants.HF_HUB_OFFLINE)+ except Exception: # noqa: BLE001 - no hub library: nothing can be downloaded either+ return True+++def hub_name_known_absent(+ repo_id: Optional[str],+ name: Optional[str],+ cache_dir: Optional[str] = None,+) -> bool:+ """True when a Hub cache root holds a ``.no_exist`` marker (a recorded 404) for ``name``. Never raises."""+ if not repo_id or not name:+ return False+ try:+ from huggingface_hub import try_to_load_from_cache+ except Exception: # noqa: BLE001 - no cache API: nothing is known+ return False+ for root in _twin_cache_roots(cache_dir):+ try:+ hit = try_to_load_from_cache(repo_id, name, cache_dir = root)+ except Exception: # noqa: BLE001 - a malformed cache entry says nothing+ continue+ # str = cached path, None = never asked, anything else = the .no_exist sentinel+ if hit is not None and not isinstance(hit, str):+ return True+ return False+++def first_cached_as_resolved(+ repo_id: Optional[str],+ names: Sequence[str],+ *,+ is_cached: Any,+ online: Optional[bool] = None,+ cache_dir: Optional[str] = None,+) -> Optional[str]:+ """The first cached name in ``names`` (resolver order) the load opens without downloading anything+ first, else None. Offline that is the first cached name. Online an uncached name ahead of it blocks+ (the resolver would fetch it) unless the cache recorded its 404; otherwise a cached INT8 ``.pt``+ reads as free while the load fetches an uncached INT8-ConvRot. A twin still ahead of the hit was+ not reordered (kill switch, unreadable pickle), so the load fetches it too.+ ``online=None`` reads huggingface_hub's offline switch and the load's ``local_files_only``. Never raises."""+ try:+ if online is None:+ online = not hub_offline() and not _LOCAL_FILES_ONLY.get()+ ahead: list = []+ for name in names:+ if not name:+ continue+ if not is_cached(name):+ ahead.append(name)+ continue+ if online:+ for other in ahead:+ if not hub_name_known_absent(repo_id, other, cache_dir):+ return None+ return name+ except Exception: # noqa: BLE001 - a planning aid: unanswerable reads as not cached+ return None+ return None++@dataclass(frozen = True)class PrequantSource:"""Where a pre-quantized checkpoint lives. ``kind`` is "path" (a local file) or "repo" (Hub repo@@ -1142,7 +1388,7 @@ def usable_prequant_source(# the dense shards, then resolve neither file.if (not any(n in declared for n in readable)- and cached_checkpoint_path(src, names = readable) is None+ and cached_checkpoint_path(src, names = readable, online = False) is None):return Noneif src.kind == "path":@@ -1158,6 +1404,7 @@ def cached_checkpoint_path(*,cache_dir: Optional[str] = None,names: Optional[Sequence[str]] = None,+ online: Optional[bool] = None,) -> Optional[str]:"""The path of a hosted (``kind == "repo"``) checkpoint ALREADY in the local Hub cache. A purelookup (a refs read plus a stat, no network), so memory planning can ask on every pick.@@ -1177,6 +1424,9 @@ def cached_checkpoint_path(cache hit was about and finds the other name uncached. Asked per NAME rather than per scheme,because the container is what decides it.+ Online the answer is the file the load opens (``first_cached_as_resolved``); ``online=False`` asks+ whether ANY readable name is cached.+``names`` narrows the chain further, to a caller's own subset.Both cache roots are searched: Unsloth pins the LIVE cache setting while an unpinned@@ -1195,16 +1445,36 @@ def cached_checkpoint_path(for n in candidate_filenames_of(source)if (wanted is None or n in wanted) and _readable(n)]+ location = getattr(source, "location", None)if getattr(source, "kind", None) == "repo":- mirrored = _first_mirrored(getattr(source, "location", None), candidates, _readable)+ mirrored = _first_mirrored(location, candidates, _readable)if mirrored is not None:return mirrored- for name in candidates:- for root in roots:- hit = _cached_in_root(source, root, name)- if hit is not None:- return hit- return None+ hits: dict = {}++ def _hit(name: str) -> Optional[str]:+ if name not in hits:+ hits[name] = next(+ (+ h+ for h in (_cached_in_root(source, root, name) for root in roots)+ if h is not None+ ),+ None,+ )+ return hits[name]++ ordered = prefer_cached_pickle_twins(+ location, candidates, readable = _readable, cache_dir = cache_dir, log = False+ )+ name = first_cached_as_resolved(+ location,+ ordered,+ is_cached = lambda n: _hit(n) is not None,+ online = online,+ cache_dir = cache_dir,+ )+ return _hit(name) if name else Nonedef _cached_in_root(@@ -1233,9 +1503,14 @@ def _cached_in_root(return hit if isinstance(hit, str) and os.path.isfile(hit) else None-def prequant_checkpoint_cached(source: Any, *, cache_dir: Optional[str] = None) -> bool:+def prequant_checkpoint_cached(+ source: Any,+ *,+ cache_dir: Optional[str] = None,+ online: Optional[bool] = None,+) -> bool:"""True when ``source`` resolves from the cache, i.e. enabling prequant costs no download."""- return cached_checkpoint_path(source, cache_dir = cache_dir) is not None+ return cached_checkpoint_path(source, cache_dir = cache_dir, online = online) is not Nonedef _pin_kernel_preference(state_dict: Any, logger: Any = None) -> int:@@ -1323,7 +1598,12 @@ def load_prequantized_transformer(return Nonepath = _resolve_checkpoint_path(- source, hf_token, cache_dir, local_files_only = local_files_only, scheme = scheme+ source,+ hf_token,+ cache_dir,+ local_files_only = local_files_only,+ scheme = scheme,+ logger = logger,)if path is None:return None@@ -1552,6 +1832,7 @@ def _resolve_checkpoint_path(*,local_files_only: bool = False,scheme: Optional[str] = None,+ logger: Any = None,) -> Optional[str]:"""The local file path for ``source``, downloading from the Hub if needed; None if absent.``local_files_only`` is the caller's promise that this load may not fetch anything, so a@@ -1573,6 +1854,7 @@ def _resolve_checkpoint_path(if source.kind == "repo":EntryNotFoundError, LocalEntryNotFoundError = _entry_not_found_errors()names = list(candidate_filenames_of(source))+ all_names = list(names)if scheme is not None:readable = [n for n in names if restricted_prequant_load_supported(scheme, n)]# Only when it leaves something. An empty filter means the source should never have@@ -1587,10 +1869,18 @@ def _resolve_checkpoint_path()if mirrored is not None:return mirrored+ names = prefer_cached_pickle_twins(+ source.location,+ names,+ readable = lambda n: restricted_prequant_load_supported(scheme, n),+ cache_dir = cache_dir,+ logger = logger,+ roots = tuple(dict.fromkeys((cache_dir, None))), # what _download_checkpoint_name reuses+ )for index, name in enumerate(names):last = index == len(names) - 1try:- return _download_checkpoint_name(+ path = _download_checkpoint_name(source,name,hf_token,@@ -1601,6 +1891,15 @@ def _resolve_checkpoint_path(propagate_missing = not last,local_files_only = local_files_only,)+ explain_container_choice(+ source.location,+ name,+ all_names,+ names,+ readable = lambda n: restricted_prequant_load_supported(scheme, n),+ logger = logger,+ )+ return pathexcept LocalEntryNotFoundError:# Caught BEFORE the base it subclasses, because the two mean different things and# only the mode says which. huggingface_hub documents this one as "not on the disk@@ -1615,7 +1914,7 @@ def _resolve_checkpoint_path(Noneif lastelse cached_checkpoint_path(- source, cache_dir = cache_dir, names = names[index + 1 :]+ source, cache_dir = cache_dir, names = names[index + 1 :], online = False))if cached is None:@@ -2448,7 +2747,7 @@ def prequant_unreadable_reason(declared = set(getattr(src, "declared_filenames", ()) or ())if (not declared.intersection(readable)- and cached_checkpoint_path(src, names = readable) is None+ and cached_checkpoint_path(src, names = readable, online = False) is None):readable = []if readable:diff --git a/studio/backend/core/inference/diffusion_te_prequant.py b/studio/backend/core/inference/diffusion_te_prequant.pyindex 2b585d49e6d..1f31b3eb0c5 100644--- a/studio/backend/core/inference/diffusion_te_prequant.py+++ b/studio/backend/core/inference/diffusion_te_prequant.py@@ -414,6 +414,7 @@ def load_prequant_text_encoder(hf_token,cache_dir = cache_dir,local_files_only = local_files_only,+ logger = logger,)if path is None:return None@@ -612,6 +613,7 @@ def _resolve_checkpoint_path(*,cache_dir: str,local_files_only: bool = False,+ logger: Any = None,) -> Optional[str]:"""The local file path for ``source``, downloading from the Hub if needed; None if absent."""if source.kind == "path":@@ -619,7 +621,6 @@ def _resolve_checkpoint_path(expanded = os.path.expanduser(source.location)return expanded if os.path.isfile(expanded) else Noneif source.kind == "repo":- from huggingface_hub import hf_hub_downloadfrom huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError# Which exception means "this NAME is absent" depends on the mode, and the two are not@@ -642,15 +643,37 @@ def _resolve_checkpoint_path(mirrored = _first_mirrored(source.location, names, te_candidate_is_readable)if mirrored is not None:return mirrored- for name in names:+ from .diffusion_prequant import prefer_cached_pickle_twins++ names = prefer_cached_pickle_twins(+ source.location,+ names,+ readable = te_candidate_is_readable,+ cache_dir = cache_dir,+ logger = logger,+ roots = tuple(dict.fromkeys((cache_dir, None))), # what _download_checkpoint_name reuses+ )+ from .diffusion_prequant import _download_checkpoint_name, explain_container_choice++ for index, name in enumerate(names):try:- return hf_hub_download(- repo_id = source.location,- filename = name,- token = hf_token,- cache_dir = cache_dir,+ path = _download_checkpoint_name(+ source,+ name,+ hf_token,+ cache_dir,+ propagate_missing = index < len(names) - 1,local_files_only = local_files_only,)+ explain_container_choice(+ source.location,+ name,+ te_candidate_filenames(source),+ names,+ readable = te_candidate_is_readable,+ logger = logger,+ )+ return pathexcept LocalEntryNotFoundError:# Online this is the Hub being unreachable, not a missing name: re-raise as itself# rather than blaming the next candidate for it.@@ -737,7 +760,12 @@ def te_prequant_hub_files(# order, so the bytes counted here are the bytes that will actually be fetched. Matching# the primary name alone reported every .pt repo as having no pre-cast encoder at all the# moment safetensors became the preferred spelling.- for name in te_candidate_filenames(source):+ from .diffusion_prequant import prefer_cached_pickle_twins++ ordered = prefer_cached_pickle_twins(+ source.location, te_candidate_filenames(source), readable = te_candidate_is_readable+ )+ for name in ordered:if name in sizes and te_candidate_is_readable(name):found[component] = [(name, sizes[name])]breakdiff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex ddbe119c299..2ff5a9b3c60 100644--- a/studio/backend/core/inference/video.py+++ b/studio/backend/core/inference/video.py@@ -56,6 +56,7 @@ from .diffusion_attention import (select_attention_backend,)from .diffusion_flow_shift import apply_comfy_flow_shift+from .diffusion_prequant import scoped_local_files_onlyfrom .diffusion_cache import (FBCACHE_MIN_STEPS,TC_AUTO,@@ -2852,6 +2853,7 @@ class VideoBackend:).start()return self.status()+ @scoped_local_files_onlydef _run_load(self, **kwargs: Any) -> None:token = kwargs.get("_load_token")# This load's own event: a later load replaces self._cancel_event rather than clearing it.@@ -3122,6 +3124,7 @@ class VideoBackend:kwargs.get("hf_token"),cancel_event = cancel_event,local_files_only = local_files_only,+ scheme = TQ_FP8,)# The denoiser artifact too: the injection that would fetch it has no cancel event.if skip_transformer_weights:@@ -3135,6 +3138,7 @@ class VideoBackend:kwargs.get("hf_token"),cancel_event = cancel_event,local_files_only = local_files_only,+ scheme = h3_auto_denoiser or video_auto_denoiser or requested_denoiser,)base_local = self._predownload_base(base,@@ -3918,7 +3922,9 @@ class VideoBackend:)return Falseif local_files_only:- repo = self._denoiser_prequant_cached_repo(fam, transformer_quant, base, h3_task)+ repo = self._denoiser_prequant_cached_repo(+ fam, transformer_quant, base, h3_task, online = False+ )else:try:from huggingface_hub import HfApi@@ -3977,7 +3983,12 @@ class VideoBackend:if not restricted_prequant_load_supported("nvfp4"):return False- if self._denoiser_prequant_cached_repo(fam, "nvfp4", base, task) is not None:+ if (+ self._denoiser_prequant_cached_repo(+ fam, "nvfp4", base, task, online = False if local_files_only else None+ )+ is not None+ ):return Trueif local_files_only:return False@@ -4256,16 +4267,29 @@ class VideoBackend:*,cancel_event: Optional[threading.Event] = None,local_files_only: bool = False,+ scheme: Optional[str] = None,) -> None:"""Pre-fetch the hosted denoiser checkpoint(s) under the load's cancel event; best effort except cancellation."""cancel = cancel_event if cancel_event is not None else self._cancel_event- from core.inference.diffusion_prequant import candidate_filenames_of+ from core.inference.diffusion_prequant import (+ candidate_filenames_of,+ prefer_cached_pickle_twins,+ restricted_prequant_load_supported,+ )from utils.hf_xet_fallback import hf_hub_download_with_xet_fallbackfor source in sources:if getattr(source, "kind", None) != "repo":continuenames = list(dict.fromkeys(candidate_filenames_of(source)))+ # the resolver's filter: readable names, unless that leaves none+ names = [n for n in names if restricted_prequant_load_supported(scheme, n)] or names+ names = prefer_cached_pickle_twins(+ source.location,+ names,+ readable = lambda n: restricted_prequant_load_supported(scheme, n),+ cache_dir = hub_cache_dir(),+ )for index, name in enumerate(names):try:hf_hub_download_with_xet_fallback(@@ -4383,12 +4407,26 @@ class VideoBackend:except Exception as exc: # noqa: BLE001 -- unavailable prequant means the dense DiTlogger.warning("video.denoiser_prequant_unavailable: %s: %s", location, exc)return None, []- from core.inference.diffusion_prequant import candidate_filenames_of+ from core.inference.diffusion_prequant import (+ candidate_filenames_of,+ prefer_cached_pickle_twins,+ restricted_prequant_load_supported,+ )by_name = {s.rfilename: int(s.size or 0) for s in (info.siblings or [])}files: list[tuple[str, int]] = []for src in sources:- wanted = list(candidate_filenames_of(src))+ names = list(candidate_filenames_of(src))+ # the resolver's filter: readable names, unless that leaves none+ names = [+ n for n in names if restricted_prequant_load_supported(transformer_quant, n)+ ] or names+ wanted = prefer_cached_pickle_twins(+ src.location,+ names,+ readable = lambda n: restricted_prequant_load_supported(transformer_quant, n),+ cache_dir = hub_cache_dir(),+ )found = next((n for n in wanted if n in by_name), None)if found is None:return None, []@@ -4401,24 +4439,49 @@ class VideoBackend:transformer_quant: Optional[str],base: Optional[str],h3_task: Optional[str] = None,+ online: Optional[bool] = None,) -> Optional[str]:"""The hosted pre-quantized denoiser repo when its checkpoint is ALREADY cached, else None.- Offline twin of ``_denoiser_prequant_hub_files``; a cached name is taken at face value."""+ Offline twin of ``_denoiser_prequant_hub_files``; online semantics per ``first_cached_as_resolved``."""sources = VideoBackend._denoiser_prequant_source_list(fam, transformer_quant, base, h3_task)# A local override is on disk by definition; only a hosted checkpoint has a cache to probeif not sources or any(getattr(src, "kind", None) != "repo" for src in sources):return Nonefrom core.inference.diffusion import DiffusionBackend- from core.inference.diffusion_prequant import candidate_filenames_of+ from core.inference.diffusion_prequant import (+ candidate_filenames_of,+ first_cached_as_resolved,+ prefer_cached_pickle_twins,+ restricted_prequant_load_supported,+ )cached: list[str] = []for src in sources:- for name in candidate_filenames_of(src):- if DiffusionBackend._hub_file_is_cached(src.location, name):- cached.append(src.location)- break+ # only names the loader can open: a cached unreadable file must not drop the dense shards+ ordered = prefer_cached_pickle_twins(+ src.location,+ [+ n+ for n in candidate_filenames_of(src)+ if restricted_prequant_load_supported(transformer_quant, n)+ ],+ readable = lambda n: restricted_prequant_load_supported(transformer_quant, n),+ cache_dir = hub_cache_dir(),+ log = False,+ )+ hit = first_cached_as_resolved(+ src.location,+ ordered,+ is_cached = lambda n, repo = src.location: DiffusionBackend._hub_file_is_cached(+ repo, n+ ),+ online = online,+ cache_dir = hub_cache_dir(),+ )+ if hit is not None:+ cached.append(src.location)if len(cached) == len(sources):return cached[0]# No log here: the caller reports the same "keeping its dense denoiser shards" outcome for a miss, and logging@@ -5155,7 +5218,13 @@ class VideoBackend:# no skippable component, which is the dense encoder downloaded twice over.from .diffusion_te_prequant import te_candidate_filenames, te_candidate_is_readable- names = [n for n in te_candidate_filenames(source) if te_candidate_is_readable(n)]+ from .diffusion_prequant import prefer_cached_pickle_twins++ names = prefer_cached_pickle_twins(+ source.location,+ [n for n in te_candidate_filenames(source) if te_candidate_is_readable(n)],+ readable = te_candidate_is_readable,+ )got = Falsefor name in names:try:@@ -5378,6 +5447,7 @@ class VideoBackend:# ── the load itself ──────────────────────────────────────────────────────@_invalidates_gpu_memory("video load")+ @scoped_local_files_onlydef load_pipeline(self,repo_id: str,diff --git a/studio/backend/tests/test_diffusion_prequant.py b/studio/backend/tests/test_diffusion_prequant.pyindex 6ea55c086cb..b13e9508fcb 100644--- a/studio/backend/tests/test_diffusion_prequant.py+++ b/studio/backend/tests/test_diffusion_prequant.py@@ -1581,6 +1581,8 @@ def test_prequant_checkpoint_cached_reads_only_the_cache(monkeypatch, tmp_path):legacy.write_bytes(b"weights")source = _prequant_source()asked: list = []+ absent: set = set()+ no_exist = object() # huggingface_hub's sentinel for a recorded 404def _cache(repo_id,@@ -1588,6 +1590,8 @@ def test_prequant_checkpoint_cached_reads_only_the_cache(monkeypatch, tmp_path):cache_dir = None,):asked.append((repo_id, filename, cache_dir))+ if filename in absent:+ return no_existreturn str(tmp_path / filename) if (tmp_path / filename).is_file() else Nonemonkeypatch.setattr("huggingface_hub.try_to_load_from_cache", _cache)@@ -1596,7 +1600,7 @@ def test_prequant_checkpoint_cached_reads_only_the_cache(monkeypatch, tmp_path):lambda *a, **k: pytest.fail("the cache probe must never download"),)- assert prequant_checkpoint_cached(source, cache_dir = "/models/hub") is True+ assert prequant_checkpoint_cached(source, cache_dir = "/models/hub", online = True) is True# The live root is asked first, and the model-name file resolves, so no legacy lookup.assert asked == [("unsloth/Z-Image-Turbo-FP8", "Z-Image-Turbo-FP8.pt", "/models/hub")]@@ -1605,11 +1609,20 @@ def test_prequant_checkpoint_cached_reads_only_the_cache(monkeypatch, tmp_path):# most repos do not have yet, primary-only would report every existing .pt repo as "would# download several GB" and hand the pick to GGUF while its checkpoint sat in the cache. The# preference is unaffected: the downloader still asks for the better name first.+ # It loads, though, only when the names ahead of it are absent from the Hub. Online and never+ # asked about the model-name file, the load would download that one first, so this is a miss.ckpt.unlink()- assert prequant_checkpoint_cached(source) is True+ assert prequant_checkpoint_cached(source, online = True) is False+ # The resolver's own 404 on it left a .no_exist marker: now the legacy name is what loads.+ absent.add("Z-Image-Turbo-FP8.pt")+ assert prequant_checkpoint_cached(source, online = True) is True+ # Offline the load walks to the cached legacy name whatever the Hub holds.+ absent.clear()+ assert prequant_checkpoint_cached(source, online = False) is True# Neither name cached -> same answer, for the ordinary reason.legacy.unlink()- assert prequant_checkpoint_cached(source) is False+ assert prequant_checkpoint_cached(source, online = True) is False+ assert prequant_checkpoint_cached(source, online = False) is Falsedef test_a_live_root_hit_still_goes_through_the_hub_so_it_revalidates(monkeypatch, tmp_path):@@ -2535,7 +2548,7 @@ def test_a_cached_pickle_is_not_evidence_for_a_safetensors_artifact(monkeypatch)monkeypatch.setattr(pq,"cached_checkpoint_path",- lambda source, cache_dir = None, names = None: next(+ lambda source, cache_dir = None, names = None, **kw: next((v for k, v in cached.items() if names is None or k in names), None),)diff --git a/studio/backend/tests/test_prequant_prefer_cached_pickle.py b/studio/backend/tests/test_prequant_prefer_cached_pickle.pynew file mode 100644index 00000000000..d17df14d708--- /dev/null+++ b/studio/backend/tests/test_prequant_prefer_cached_pickle.py@@ -0,0 +1,669 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""A user who already holds a hosted ``.pt`` checkpoint must not download its ``.safetensors`` twin.++The candidate chain prefers safetensors, so once a repo publishes the twin every path that walks+the chain in order (the transformer resolver, the text-encoder resolver, the download planners and+the video prefetch) would fetch it again next to the multi-GB pickle already in the cache. These+tests drive a fake Hub cache through ``try_to_load_from_cache`` / ``hf_hub_download``."""++from __future__ import annotations++import types++import huggingface_hub+import pytest+from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError++import core.inference.diffusion_prequant as pq+import core.inference.diffusion_te_prequant as tpq++REPO = "unsloth/Model-FP8"+KILL_SWITCH = "UNSLOTH_PREQUANT_PREFER_SAFETENSORS"+NO_EXIST = object() # stands in for huggingface_hub's recorded-404 sentinel+++class FakeHub:+ """A Hub cache keyed by (repo, name) plus a Hub listing; records every download."""++ def __init__(+ self,+ tmp_path,+ cached = (),+ hosted = None,+ ):+ self.tmp = tmp_path+ self.cached: dict = {}+ self.hosted = set(hosted) if hosted is not None else None+ # names a 404 was recorded for, as huggingface_hub's .no_exist markers+ self.absent: set = set()+ self.downloads: list = []+ for name in cached:+ self.cache(name)++ def cache(+ self,+ name,+ repo = REPO,+ ):+ path = self.tmp / "cache" / repo.replace("/", "--") / name+ path.parent.mkdir(parents = True, exist_ok = True)+ path.write_bytes(b"x")+ self.cached[(repo, name)] = str(path)++ def try_to_load_from_cache(+ self,+ repo_id,+ filename,+ cache_dir = None,+ **_,+ ):+ if (repo_id, filename) in self.absent:+ return NO_EXIST+ return self.cached.get((repo_id, filename))++ def hf_hub_download(+ self,+ repo_id,+ filename,+ token = None,+ cache_dir = None,+ local_files_only = False,+ **_,+ ):+ self.downloads.append((filename, bool(local_files_only)))+ hit = self.cached.get((repo_id, filename))+ if local_files_only:+ if hit is None:+ raise LocalEntryNotFoundError(f"{filename} not cached")+ return hit+ if self.hosted is not None and filename not in self.hosted:+ self.absent.add((repo_id, filename))+ raise EntryNotFoundError(f"404 {filename}")+ if hit is None:+ self.cache(filename, repo_id)+ return self.cached[(repo_id, filename)]++ @property+ def fetched(self):+ return [n for n, _ in self.downloads]+++def hub(tmp_path, monkeypatch):+ fake = FakeHub(tmp_path)+ monkeypatch.setattr(huggingface_hub, "try_to_load_from_cache", fake.try_to_load_from_cache)+ monkeypatch.setattr(huggingface_hub, "hf_hub_download", fake.hf_hub_download)+ monkeypatch.setattr(+ pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True+ )+ monkeypatch.setattr(tpq, "te_candidate_is_readable", lambda name: bool(name))+ monkeypatch.delenv(pq.PREQUANT_MIRROR_ENV, raising = False)+ monkeypatch.delenv(KILL_SWITCH, raising = False)+ getattr(pq, "_logged_twin_choices", set()).clear()+ return fake+++def _dit(*names):+ names = names or ("Model-INT8.safetensors", "Model-INT8.pt", "transformer_int8.pt")+ return pq.PrequantSource(+ kind = "repo", location = REPO, filename = names[0], fallback_filenames = tuple(names[1:])+ )+++def _te(*names):+ names = names or ("Model-text_encoder-FP8.safetensors", "Model-text_encoder-FP8.pt")+ return tpq.TePrequantSource(+ kind = "repo", location = REPO, filename = names[0], fallback_filenames = tuple(names[1:])+ )+++def _resolve(source, **kw):+ return pq._resolve_checkpoint_path(source, None, None, scheme = "int8", **kw)+++# ---- transformer resolver ----+++def test_cached_pickle_is_used_and_revalidated_online(hub, caplog):+ hub.cache("Model-INT8.pt")+ caplog.set_level("INFO")+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.pt")]+ # Revalidated through hf_hub_download for the PICKLE name; the safetensors twin is never asked.+ assert hub.downloads == [("Model-INT8.pt", False)]+ assert "Model-INT8.safetensors" not in hub.fetched+ assert "using the cached Model-INT8.pt" in caplog.text+++def test_cached_pickle_offline_uses_cache_without_a_network_call(hub):+ hub.cache("Model-INT8.pt")+ assert _resolve(_dit(), local_files_only = True) == hub.cached[(REPO, "Model-INT8.pt")]+ assert hub.downloads == [("Model-INT8.pt", True)]+++def test_new_user_downloads_safetensors(hub):+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.safetensors")]+ assert hub.fetched == ["Model-INT8.safetensors"]+++def test_both_cached_safetensors_wins(hub):+ hub.cache("Model-INT8.pt")+ hub.cache("Model-INT8.safetensors")+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.safetensors")]+ assert hub.fetched == ["Model-INT8.safetensors"]+++def test_kill_switch_forces_safetensors(hub, monkeypatch):+ hub.cache("Model-INT8.pt")+ monkeypatch.setenv(KILL_SWITCH, "1")+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.safetensors")]+ assert hub.fetched == ["Model-INT8.safetensors"]+++def test_twin_removed_from_hub_falls_back_to_the_chain(hub):+ hub.cache("Model-INT8.pt")+ hub.hosted = {"Model-INT8.safetensors"}+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.safetensors")]+ assert hub.fetched == ["Model-INT8.pt", "Model-INT8.safetensors"]+++def test_a_cached_different_artifact_does_not_preempt_a_better_one(hub):+ """INT8-ConvRot is a different artifact than INT8: a cached INT8 pickle must not win."""+ hub.cache("Model-INT8.pt")+ src = _dit(+ "Model-INT8-ConvRot.safetensors",+ "Model-INT8-ConvRot.pt",+ "Model-INT8.safetensors",+ "Model-INT8.pt",+ )+ assert _resolve(src) == hub.cached[(REPO, "Model-INT8-ConvRot.safetensors")]+ assert hub.fetched == ["Model-INT8-ConvRot.safetensors"]+++def test_unreadable_twin_is_not_preferred(hub, monkeypatch):+ hub.cache("Model-INT8.pt")+ monkeypatch.setattr(+ pq,+ "restricted_prequant_load_supported",+ lambda scheme = None, filename = None: not str(filename).endswith(".pt"),+ )+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.safetensors")]+ assert hub.fetched == ["Model-INT8.safetensors"]+++def test_mirror_still_answers_first(hub, tmp_path, monkeypatch):+ hub.cache("Model-INT8.pt")+ mirrored = tmp_path / "mirror" / "unsloth" / "Model-FP8" / "Model-INT8.safetensors"+ mirrored.parent.mkdir(parents = True)+ mirrored.write_bytes(b"x")+ monkeypatch.setenv(pq.PREQUANT_MIRROR_ENV, str(tmp_path / "mirror"))+ assert _resolve(_dit()) == str(mirrored.resolve())+ assert hub.downloads == []+++def test_cache_probe_agrees_with_the_resolver(hub):+ hub.cache("Model-INT8.pt")+ src = _dit()+ assert pq.cached_checkpoint_path(src) == _resolve(src)+++# ---- text encoder resolver ----+++def test_te_cached_pickle_is_used(hub):+ hub.cache("Model-text_encoder-FP8.pt")+ got = tpq._resolve_checkpoint_path(_te(), None, cache_dir = "/live")+ assert got == hub.cached[(REPO, "Model-text_encoder-FP8.pt")]+ assert hub.downloads == [("Model-text_encoder-FP8.pt", False)]+++def test_te_offline_cached_pickle(hub):+ hub.cache("Model-text_encoder-FP8.pt")+ got = tpq._resolve_checkpoint_path(_te(), None, cache_dir = "/live", local_files_only = True)+ assert got == hub.cached[(REPO, "Model-text_encoder-FP8.pt")]+ assert hub.downloads == [("Model-text_encoder-FP8.pt", True)]+++def test_te_new_user_downloads_safetensors(hub):+ tpq._resolve_checkpoint_path(_te(), None, cache_dir = "/live")+ assert hub.fetched == ["Model-text_encoder-FP8.safetensors"]+++def test_te_cached_fp8_does_not_preempt_int8_convrot(hub):+ hub.cache("Model-text_encoder-FP8.pt")+ src = _te(+ "Model-text_encoder-INT8-ConvRot.safetensors",+ "Model-text_encoder-INT8-ConvRot.pt",+ "Model-text_encoder-FP8.safetensors",+ "Model-text_encoder-FP8.pt",+ )+ tpq._resolve_checkpoint_path(src, None, cache_dir = "/live")+ assert hub.fetched == ["Model-text_encoder-INT8-ConvRot.safetensors"]+++def test_te_twin_removed_from_hub_falls_back(hub):+ hub.cache("Model-text_encoder-FP8.pt")+ hub.hosted = {"Model-text_encoder-FP8.safetensors"}+ got = tpq._resolve_checkpoint_path(_te(), None, cache_dir = "/live")+ assert got == hub.cached[(REPO, "Model-text_encoder-FP8.safetensors")]+ assert hub.fetched == ["Model-text_encoder-FP8.pt", "Model-text_encoder-FP8.safetensors"]+++# ---- planners: price / stage the same name the resolver uses ----+++class _Api:+ def __init__(self, names):+ self.names = names++ def model_info(+ self,+ repo_id,+ files_metadata = False,+ ):+ return types.SimpleNamespace(+ siblings = [+ types.SimpleNamespace(rfilename = n, size = 100 + i) for i, n in enumerate(self.names)+ ]+ )+++def test_te_hub_files_planner_prices_the_cached_pickle(hub):+ hub.cache("Model-text_encoder-FP8.pt")+ api = _Api(["Model-text_encoder-FP8.safetensors", "Model-text_encoder-FP8.pt"])+ files = tpq.te_prequant_hub_files({"text_encoder": _te()}, api, None)+ assert files == {"text_encoder": [("Model-text_encoder-FP8.pt", 101)]}+ hub.cached.clear()+ files = tpq.te_prequant_hub_files({"text_encoder": _te()}, api, None)+ assert files == {"text_encoder": [("Model-text_encoder-FP8.safetensors", 100)]}+++def test_dit_planner_stages_the_cached_pickle(hub, monkeypatch):+ from core.inference.diffusion import DiffusionBackend++ api = _Api(["Model-INT8.safetensors", "Model-INT8.pt"])+ monkeypatch.setattr(huggingface_hub, "HfApi", lambda token = None: api)+ hub.cache("Model-INT8.pt")+ entry = DiffusionBackend._prequant_source_hub_entry(_dit(), None, scheme = "int8")+ assert entry == (REPO, "Model-INT8.pt", 101)+ assert entry[1] == _resolve(_dit()).rsplit("/", 1)[-1]+ hub.cached.clear()+ entry = DiffusionBackend._prequant_source_hub_entry(_dit(), None, scheme = "int8")+ assert entry == (REPO, "Model-INT8.safetensors", 100)+++def test_video_denoiser_prefetch_fetches_the_cached_pickle(hub, monkeypatch):+ import utils.hf_xet_fallback as xet+ from core.inference.video import VideoBackend++ hub.cache("Model-INT8.pt")+ fetched = []++ def _dl(repo, name, token, **kw):+ fetched.append(name)+ return hub.cached.get((repo, name)) or "/new/" + name++ monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _dl)+ backend = VideoBackend.__new__(VideoBackend)+ import threading++ VideoBackend._fetch_denoiser_prequant(backend, [_dit()], None, cancel_event = threading.Event())+ assert fetched == ["Model-INT8.pt"]+++def test_video_denoiser_prefetch_skips_an_unreadable_cached_pickle(hub, monkeypatch):+ import threading++ import utils.hf_xet_fallback as xet+ from core.inference.video import VideoBackend++ hub.cache("Model-INT8.pt")+ monkeypatch.setattr(+ pq,+ "restricted_prequant_load_supported",+ lambda scheme = None, filename = None: not str(filename).endswith(".pt"),+ )+ fetched = []++ def _dl(repo, name, token, **kw):+ fetched.append(name)+ return hub.cached.get((repo, name)) or "/new/" + name++ monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _dl)+ backend = VideoBackend.__new__(VideoBackend)+ VideoBackend._fetch_denoiser_prequant(+ backend, [_dit()], None, cancel_event = threading.Event(), scheme = "int8"+ )+ # the loader cannot open the cached .pt, so the prefetch stages the safetensors it will open+ assert fetched == ["Model-INT8.safetensors"]+++def test_video_te_prefetch_fetches_the_cached_pickle(hub, monkeypatch):+ import threading++ import utils.hf_xet_fallback as xet+ from core.inference.video import VideoBackend++ hub.cache("Model-text_encoder-FP8.pt")+ fetched = []++ def _dl(repo, name, token, **kw):+ fetched.append(name)+ return hub.cached.get((repo, name)) or "/new/" + name++ monkeypatch.setattr(xet, "hf_hub_download_with_xet_fallback", _dl)+ backend = VideoBackend.__new__(VideoBackend)+ got = VideoBackend._fetch_te_prequant(+ backend, {"text_encoder": _te()}, None, cancel_event = threading.Event()+ )+ assert got == ("text_encoder",) and fetched == ["Model-text_encoder-FP8.pt"]+++# ---- policy: new users only ever get the safetensors container ----+++def test_new_user_never_requests_the_pickle_when_the_twin_is_hosted(hub, monkeypatch):+ """Both containers on the Hub, nothing cached: only the .safetensors is fetched, on every path."""+ import threading++ import utils.hf_xet_fallback as xet+ from core.inference.diffusion import DiffusionBackend+ from core.inference.video import VideoBackend++ hub.hosted = {+ "Model-INT8.safetensors",+ "Model-INT8.pt",+ "Model-text_encoder-FP8.safetensors",+ "Model-text_encoder-FP8.pt",+ }+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.safetensors")]+ tpq._resolve_checkpoint_path(_te(), None, cache_dir = "/live")+ assert hub.fetched == ["Model-INT8.safetensors", "Model-text_encoder-FP8.safetensors"]+ hub.cached.clear()++ api = _Api(sorted(hub.hosted))+ monkeypatch.setattr(huggingface_hub, "HfApi", lambda token = None: api)+ assert DiffusionBackend._prequant_source_hub_entry(_dit(), None, scheme = "int8")[1] == (+ "Model-INT8.safetensors"+ )+ assert tpq.te_prequant_hub_files({"text_encoder": _te()}, api, None)["text_encoder"][0][0] == (+ "Model-text_encoder-FP8.safetensors"+ )+ fetched = []+ monkeypatch.setattr(+ xet, "hf_hub_download_with_xet_fallback", lambda repo, name, tok, **kw: fetched.append(name)+ )+ backend = VideoBackend.__new__(VideoBackend)+ VideoBackend._fetch_denoiser_prequant(backend, [_dit()], None, cancel_event = threading.Event())+ VideoBackend._fetch_te_prequant(+ backend, {"text_encoder": _te()}, None, cancel_event = threading.Event()+ )+ assert fetched == ["Model-INT8.safetensors", "Model-text_encoder-FP8.safetensors"]+ assert not any(n.endswith(".pt") for n in hub.fetched + fetched)+++def test_pickle_only_repo_downloads_the_pickle_and_says_why(hub, caplog):+ hub.hosted = {"Model-INT8.pt"}+ caplog.set_level("INFO")+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.pt")]+ assert hub.fetched == ["Model-INT8.safetensors", "Model-INT8.pt"]+ assert "does not host the .safetensors twin yet" in caplog.text+++def test_install_without_safetensors_support_downloads_the_pickle_and_says_why(+ hub, monkeypatch, caplog+):+ monkeypatch.setattr(+ pq,+ "restricted_prequant_load_supported",+ lambda scheme = None, filename = None: not str(filename).endswith(".safetensors"),+ )+ caplog.set_level("INFO")+ assert _resolve(_dit()) == hub.cached[(REPO, "Model-INT8.pt")]+ assert hub.fetched == ["Model-INT8.pt"]+ assert "cannot read the .safetensors container" in caplog.text+++# ---- cache probes: "nothing to download" must mean the file the load will open ----++CONVROT = ("Model-INT8-ConvRot.safetensors",)+PLAIN = ("Model-INT8.safetensors", "Model-INT8.pt", "transformer_int8.pt")+++def _convrot_dit(declared = True):+ names = CONVROT + PLAIN+ return pq.PrequantSource(+ kind = "repo",+ location = REPO,+ filename = names[0],+ fallback_filenames = names[1:],+ declared_filenames = CONVROT if declared else (),+ )+++def test_cached_int8_is_not_free_when_a_declared_convrot_is_ahead(hub):+ """An existing user's INT8 .pt is cached and the family now declares an INT8-ConvRot build.+ Online the load downloads the ConvRot file first, so the planner and the disk gate must not be+ told this costs nothing."""+ hub.cache("Model-INT8.pt")+ src = _convrot_dit()+ assert pq.cached_checkpoint_path(src, online = True) is None+ assert pq.prequant_checkpoint_cached(src, online = True) is False+ # and that is what the load really does+ _resolve(src)+ assert hub.fetched == ["Model-INT8-ConvRot.safetensors"]+++def test_offline_the_cached_int8_is_what_loads(hub):+ hub.cache("Model-INT8.pt")+ src = _convrot_dit()+ assert pq.cached_checkpoint_path(src, online = False) == hub.cached[(REPO, "Model-INT8.pt")]+ assert _resolve(src, local_files_only = True) == hub.cached[(REPO, "Model-INT8.pt")]+++def test_an_unpublished_convrot_stops_blocking_once_the_resolver_saw_its_404(hub):+ """The code names a ConvRot build the repo does not host yet (merged before the upload). The+ first load asks, gets a 404, and opens the cached INT8 .pt; from then on the probe agrees with+ the resolver instead of planning a download that never happens on every load."""+ hub.cache("Model-INT8.pt")+ src = _convrot_dit()+ # never asked: online, it may be hosted, so a download is planned+ assert pq.cached_checkpoint_path(src, online = True) is None+ hub.hosted = set(PLAIN)+ got = _resolve(src)+ assert got == hub.cached[(REPO, "Model-INT8.pt")]+ assert hub.fetched == ["Model-INT8-ConvRot.safetensors", "Model-INT8.pt"]+ assert pq.cached_checkpoint_path(src, online = True) == got+ assert pq.prequant_checkpoint_cached(src, online = True) is True+++def test_a_derived_name_is_cleared_by_the_resolvers_own_404(hub):+ """Same rule for a name derived from the repo id rather than declared by the family."""+ hub.cache("Model-INT8.pt")+ src = _convrot_dit(declared = False)+ assert pq.cached_checkpoint_path(src, online = True) is None+ hub.hosted = {"Model-INT8.pt"}+ got = _resolve(src)+ assert got == hub.cached[(REPO, "Model-INT8.pt")]+ assert pq.cached_checkpoint_path(src, online = True) == got+++def test_the_cached_pickle_twin_still_counts_online(hub):+ """The safetensors twin of a cached .pt never blocks it: the resolver opens the .pt."""+ hub.cache("Model-INT8.pt")+ src = _dit()+ assert pq.cached_checkpoint_path(src, online = True) == hub.cached[(REPO, "Model-INT8.pt")]+ assert pq.cached_checkpoint_path(src, online = True) == _resolve(src)+ assert hub.fetched == ["Model-INT8.pt"]+++def test_a_cached_convrot_is_free(hub):+ hub.cache("Model-INT8.pt")+ hub.cache("Model-INT8-ConvRot.safetensors")+ got = pq.cached_checkpoint_path(_convrot_dit(), online = True)+ assert got == hub.cached[(REPO, "Model-INT8-ConvRot.safetensors")]+++def test_video_cached_repo_probe_follows_the_same_rule(hub, monkeypatch):+ from core.inference.diffusion import DiffusionBackend+ from core.inference.video import VideoBackend++ hub.cache("Model-INT8.pt")+ monkeypatch.setattr(+ VideoBackend,+ "_denoiser_prequant_source_list",+ staticmethod(lambda *a, **k: [_convrot_dit()]),+ )+ monkeypatch.setattr(+ DiffusionBackend,+ "_hub_file_is_cached",+ staticmethod(lambda repo, name, *a, **k: (repo, name) in hub.cached),+ )+ probe = VideoBackend._denoiser_prequant_cached_repo+ assert probe(None, "int8", "base/Model", online = True) is None+ assert probe(None, "int8", "base/Model", online = False) == REPO+++def test_video_cached_repo_probe_ignores_a_cached_unreadable_file(hub, monkeypatch):+ """Offline, a cached safetensors this install cannot read is not what the loader opens."""+ from core.inference.diffusion import DiffusionBackend+ from core.inference.video import VideoBackend++ hub.cache("Model-INT8.safetensors")+ monkeypatch.setattr(+ pq,+ "restricted_prequant_load_supported",+ lambda scheme = None, filename = None: not str(filename).endswith(".safetensors"),+ )+ monkeypatch.setattr(+ VideoBackend, "_denoiser_prequant_source_list", staticmethod(lambda *a, **k: [_dit()])+ )+ monkeypatch.setattr(+ DiffusionBackend,+ "_hub_file_is_cached",+ staticmethod(lambda repo, name, *a, **k: (repo, name) in hub.cached),+ )+ assert VideoBackend._denoiser_prequant_cached_repo(None, "int8", "b", online = False) is None+ hub.cache("Model-INT8.pt")+ assert VideoBackend._denoiser_prequant_cached_repo(None, "int8", "b", online = False) == REPO+++def test_te_pricing_does_not_call_a_cached_fp8_encoder_free(hub, monkeypatch, tmp_path):+ """The text-encoder size estimate: a cached FP8 encoder is not what loads when an uncached+ INT8-ConvRot encoder is ahead of it and no 404 for it is recorded, so the size is not exact."""+ import core.inference.diffusion as diffusion+ from core.inference.diffusion import DiffusionBackend++ snap = tmp_path / "snap"+ snap.mkdir()+ (snap / "Model-text_encoder-FP8.pt").write_bytes(b"x" * 4096)+ hub.cache("Model-text_encoder-FP8.pt")+ convrot = ("Model-text_encoder-INT8-ConvRot.safetensors",)++ def _sources(*a, **k):+ names = convrot + ("Model-text_encoder-FP8.safetensors", "Model-text_encoder-FP8.pt")+ return {+ "text_encoder": tpq.TePrequantSource(+ kind = "repo",+ location = REPO,+ filename = names[0],+ fallback_filenames = names[1:],+ )+ }++ monkeypatch.setattr(tpq, "te_prequant_sources_for_base", _sources)+ monkeypatch.setattr(+ DiffusionBackend,+ "_union_over_cached_revs",+ staticmethod(lambda base, fn, staged_dir = None: sum(fn(snap).values())),+ )+ monkeypatch.setattr(diffusion, "family_bf16_components_gb", lambda fam, base: (10.0, 16.0))+ monkeypatch.setattr(pq, "hub_offline", lambda: False)+ fam = types.SimpleNamespace(name = "probe")+ mib, components, exact = DiffusionBackend._precast_text_encoder_mib(+ fam, "base/Model", None, "int8"+ )+ assert components == ("text_encoder",)+ assert exact is False+ # Not hosted yet: once the resolver's 404 for it is recorded, the cached fp8 file is what loads.+ hub.absent.add((REPO, convrot[0]))+ mib, components, exact = DiffusionBackend._precast_text_encoder_mib(+ fam, "base/Model", None, "int8"+ )+ assert exact is True and mib == 1+ hub.absent.clear()+ # Once the ConvRot encoder is cached it is what loads, and the size is the file's own.+ (snap / "Model-text_encoder-INT8-ConvRot.safetensors").write_bytes(b"x" * (3 << 20))+ mib, components, exact = DiffusionBackend._precast_text_encoder_mib(+ fam, "base/Model", None, "int8"+ )+ assert exact is True and mib == 3+++def test_kill_switch_probe_plans_the_safetensors_download(hub, monkeypatch):+ """With the kill switch the resolver fetches the uncached safetensors, so the probe must not call it free."""+ hub.cache("Model-INT8.pt")+ monkeypatch.setenv(KILL_SWITCH, "1")+ assert pq.cached_checkpoint_path(_dit(), online = True) is None+ assert pq.cached_checkpoint_path(_dit(), online = False) == hub.cached[(REPO, "Model-INT8.pt")]+++def test_te_pickle_in_the_default_root_is_reused_through_that_root(hub, monkeypatch):+ """A pickle cached only under huggingface_hub's default root is what the planner and the video+ prefetch count, so the TE resolver reuses it through that root instead of fetching the twin."""+ hub.cache("Model-text_encoder-FP8.pt")+ real = hub.try_to_load_from_cache+ real_dl = hub.hf_hub_download+ roots = []++ def _default_root_only(+ repo_id,+ filename,+ cache_dir = None,+ **kw,+ ):+ return real(repo_id, filename) if cache_dir is None else None++ def _dl(+ repo_id,+ filename,+ cache_dir = None,+ **kw,+ ):+ roots.append(cache_dir)+ return real_dl(repo_id, filename, cache_dir = cache_dir, **kw)++ monkeypatch.setattr(huggingface_hub, "try_to_load_from_cache", _default_root_only)+ monkeypatch.setattr(huggingface_hub, "hf_hub_download", _dl)+ got = tpq._resolve_checkpoint_path(_te(), None, cache_dir = "/live")+ assert got == hub.cached[(REPO, "Model-text_encoder-FP8.pt")]+ assert hub.fetched == ["Model-text_encoder-FP8.pt"] and roots == [None]+++def test_local_files_only_reachability_uses_the_cached_fallback(hub, monkeypatch):+ """local_files_only skips the uncached ConvRot and opens the cached INT8, so the prequant is reachable."""+ import core.inference.diffusion as dmod++ hub.cache("Model-INT8.pt")+ monkeypatch.setattr(dmod, "usable_prequant_source", lambda *a, **k: _convrot_dit())+ backend = dmod.DiffusionBackend.__new__(dmod.DiffusionBackend)+ assert backend._hosted_prequant_reachable(None, "int8", {"local_files_only": True}) is True+ assert _resolve(_convrot_dit(), local_files_only = True) == hub.cached[(REPO, "Model-INT8.pt")]+++def test_a_local_files_only_load_probes_like_an_offline_one(hub, monkeypatch):+ """Inside a local_files_only load every default probe (auto policy, retry rung, plan source) opens+ the cached fallback, as the resolver will; outside it the uncached ConvRot still plans a download."""+ monkeypatch.setattr(pq, "hub_offline", lambda: False)+ hub.cache("Model-INT8.pt")+ seen = {}++ @pq.scoped_local_files_only+ def _load(*, local_files_only = False):+ seen["inner"] = pq.prequant_checkpoint_cached(_convrot_dit())+ return pq.prequant_checkpoint_cached(_convrot_dit())++ assert _load(local_files_only = True) is True and seen["inner"] is True+ assert _load(local_files_only = False) is False+ assert pq.prequant_checkpoint_cached(_convrot_dit()) is Falsediff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.pyindex 3bdede35194..b34d29722c1 100644--- a/studio/backend/tests/test_video_backend.py+++ b/studio/backend/tests/test_video_backend.py@@ -12476,6 +12476,7 @@ def test_the_ltx23_fp8_load_prefetches_the_hosted_dit_under_its_cancel_event(tmp*,cancel_event = None,local_files_only = False,+ scheme = None,):fetched.append(([src.location for src in sources], cancel_event, local_files_only))