Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: keep 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.py
index 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 None
when 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 None
return source.location
except 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 True
if kwargs.get("local_files_only"):
return False
@@ -3120,6 +3126,7 @@ class DiffusionBackend:
).start()
return self.status()
+ @scoped_local_files_only
def _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 False
if 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 True
if 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 = 0
elif 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 / name
if 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 0
if 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_only
def 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.py
index 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 True
try:
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 there
return False
diff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.py
index 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 functools
import re as _re
import threading as _threading
from 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 None
if 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 pure
lookup (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 None
def _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 None
def _pin_kernel_preference(state_dict: Any, logger: Any = None) -> int:
@@ -1323,7 +1598,12 @@ def load_prequantized_transformer(
return None
path = _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) - 1
try:
- 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 path
except 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(
None
if last
else 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.py
index 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 None
if source.kind == "repo":
- from huggingface_hub import hf_hub_download
from 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 path
except 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])]
break
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 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_only
from .diffusion_cache import (
FBCACHE_MIN_STEPS,
TC_AUTO,
@@ -2852,6 +2853,7 @@ class VideoBackend:
).start()
return self.status()
+ @scoped_local_files_only
def _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 False
if 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 True
if 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_fallback
for source in sources:
if getattr(source, "kind", None) != "repo":
continue
names = 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 DiT
logger.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 probe
if not sources or any(getattr(src, "kind", None) != "repo" for src in sources):
return None
from 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 = False
for name in names:
try:
@@ -5378,6 +5447,7 @@ class VideoBackend:
# ── the load itself ──────────────────────────────────────────────────────
@_invalidates_gpu_memory("video load")
+ @scoped_local_files_only
def load_pipeline(
self,
repo_id: str,
diff --git a/studio/backend/tests/test_diffusion_prequant.py b/studio/backend/tests/test_diffusion_prequant.py
index 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 404
def _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_exist
return str(tmp_path / filename) if (tmp_path / filename).is_file() else None
monkeypatch.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 False
def 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.py
new file mode 100644
index 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 False
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 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))