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
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Safetensors is preferred, but a cached .pt whose sha256 matches the Hub's record is reused rather than
re-downloading its safetensors twin; an unverified one (mismatch, no record, offline) keeps safetensors first."""
from __future__ import annotations
import hashlib
import types
import huggingface_hub
import pytest
from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError
import core.inference.cached_weight_sha as cws
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 = []
# sha256 the Hub records per name; None = no LFS record. Default: the bytes cache() writes.
self.hub_sha: dict = {}
self.sha_calls: 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]
@pytest.fixture
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)
def hub_sha256s(repo_id, filenames, **_):
fake.sha_calls.append(tuple(filenames))
out = {}
for name in filenames:
sha = fake.hub_sha.get(name, hashlib.sha256(b"x").hexdigest())
if sha:
out[name] = sha
return out
monkeypatch.setattr(cws, "hub_sha256s", hub_sha256s)
monkeypatch.setattr(cws, "_store_path", lambda: tmp_path / "weight_sha256.json")
monkeypatch.setattr(cws, "_persisted", None)
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)
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")]
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)
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"]
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"]
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
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):
"""A cached INT8 .pt is not free while a declared ConvRot build is ahead of it online."""
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
_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):
"""Once the resolver has seen a 404 for an unhosted ConvRot build, the probe must stop blocking."""
hub.cache("Model-INT8.pt")
src = _convrot_dit()
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
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()
(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
# ---- ComfyUI-format twin: the default download, never a re-download of a cached artifact ----
COMFY = "Model-INT8-ComfyUI.safetensors"
def _comfy_dit():
return _dit(COMFY, "Model-INT8.safetensors", "Model-INT8.pt", "transformer_int8.pt")
def test_new_user_downloads_the_comfy_twin(hub):
assert _resolve(_comfy_dit()) == hub.cached[(REPO, COMFY)]
assert hub.fetched == [COMFY]
def test_cached_own_safetensors_is_kept_over_the_comfy_twin(hub, caplog):
hub.cache("Model-INT8.safetensors")
caplog.set_level("INFO")
assert _resolve(_comfy_dit()) == hub.cached[(REPO, "Model-INT8.safetensors")]
assert COMFY not in hub.fetched
assert "its ComfyUI-format twin" in caplog.text
def test_cached_own_pickle_is_kept_over_both_twins(hub):
hub.cache("Model-INT8.pt")
assert pq.prefer_cached_pickle_twins(REPO, _comfy_dit().candidate_filenames) == [
"Model-INT8.pt",
"Model-INT8.safetensors",
COMFY,
"transformer_int8.pt",
]
assert _resolve(_comfy_dit()) == hub.cached[(REPO, "Model-INT8.pt")]
assert hub.fetched == ["Model-INT8.pt"]
def test_cached_own_pickle_offline_never_asks_for_the_twin(hub):
hub.cache("Model-INT8.pt")
assert _resolve(_comfy_dit(), local_files_only = True) == hub.cached[(REPO, "Model-INT8.pt")]
assert hub.downloads == [("Model-INT8.pt", True)]
@pytest.mark.parametrize("why", ["sha_mismatch", "no_lfs_record", "reuse_off", "prefer_st"])
def test_unverified_cached_pickle_does_not_demote_the_hosted_twin(hub, monkeypatch, why):
"""Only the own safetensors 404s: the hosted twin loads, never the cached pickle the Hub does not vouch for."""
hub.cache("Model-INT8.pt")
hub.hosted = {COMFY, "Model-INT8.pt"}
if why == "sha_mismatch":
hub.hub_sha["Model-INT8.pt"] = hashlib.sha256(b"other").hexdigest()
elif why == "no_lfs_record":
hub.hub_sha["Model-INT8.pt"] = None
elif why == "reuse_off":
monkeypatch.setenv(cws.ENV_DISABLE, "0")
else:
monkeypatch.setenv(KILL_SWITCH, "1")
assert pq.prefer_cached_pickle_twins(REPO, _comfy_dit().candidate_filenames)[0] == COMFY
assert _resolve(_comfy_dit()) == hub.cached[(REPO, COMFY)]
assert hub.fetched == [COMFY]
def test_cached_comfy_twin_stays_first(hub):
hub.cache(COMFY)
hub.cache("Model-INT8.pt")
assert _resolve(_comfy_dit()) == hub.cached[(REPO, COMFY)]
assert hub.fetched == [COMFY]
def test_repo_without_the_twin_falls_back_to_the_old_names(hub):
"""A repo that does not host the twin yet (or an older publish): one 404, then today's artifact."""
hub.hosted = {"Model-INT8.safetensors", "Model-INT8.pt"}
assert _resolve(_comfy_dit()) == hub.cached[(REPO, "Model-INT8.safetensors")]
assert hub.fetched == [COMFY, "Model-INT8.safetensors"]
def test_a_cached_other_artifact_does_not_demote_the_twin(hub):
"""INT8 cached does not stand in for the INT8-ConvRot twin (different weights); only its own twin moves."""
hub.cache("Model-INT8.safetensors")
names = (
"Model-INT8-ConvRot-ComfyUI.safetensors",
"Model-INT8-ConvRot.safetensors",
COMFY,
"Model-INT8.safetensors",
)
assert pq.prefer_cached_pickle_twins(REPO, names) == [
"Model-INT8-ConvRot-ComfyUI.safetensors",
"Model-INT8-ConvRot.safetensors",
"Model-INT8.safetensors",
COMFY,
]
def test_cache_probe_reads_a_cached_own_file_as_free_online(hub):
"""The planner's no-download answer: the cached own file, not 'must fetch the twin'."""
hub.cache("Model-INT8.safetensors")
src = _comfy_dit()
assert pq.cached_checkpoint_path(src) == hub.cached[(REPO, "Model-INT8.safetensors")]
assert pq.cached_checkpoint_path(src) == _resolve(src)
def test_dit_planner_stages_the_twin_only_when_nothing_is_cached(hub, monkeypatch):
from core.inference.diffusion import DiffusionBackend
api = _Api([COMFY, "Model-INT8.safetensors", "Model-INT8.pt"])
monkeypatch.setattr(huggingface_hub, "HfApi", lambda token = None: api)
assert DiffusionBackend._prequant_source_hub_entry(_comfy_dit(), None, scheme = "int8") == (
REPO,
COMFY,
100,
)
hub.cache("Model-INT8.safetensors")
assert DiffusionBackend._prequant_source_hub_entry(_comfy_dit(), None, scheme = "int8") == (
REPO,
"Model-INT8.safetensors",
101,
)
# a repo listing without the twin stages today's artifact
hub.cached.clear()
api.names = ["Model-INT8.safetensors", "Model-INT8.pt"]
assert DiffusionBackend._prequant_source_hub_entry(_comfy_dit(), None, scheme = "int8") == (
REPO,
"Model-INT8.safetensors",
100,
)
def test_a_cached_trailing_fp8_twin_is_used_before_an_uncached_own_file(hub):
"""fp8 twins trail Studio's own artifact; one that is already cached still wins over downloading the other."""
fp8 = _dit(
"Model-FP8.safetensors",
"Model-FP8.pt",
"Model-FP8-ComfyUI.safetensors",
"transformer_fp8.pt",
)
hub.cache("Model-FP8-ComfyUI.safetensors")
assert _resolve(fp8) == hub.cached[(REPO, "Model-FP8-ComfyUI.safetensors")]
assert hub.fetched == ["Model-FP8-ComfyUI.safetensors"]
# nothing cached: Studio's own per-row fp8 is the download
hub.cached.clear()
hub.downloads.clear()
assert _resolve(fp8) == hub.cached[(REPO, "Model-FP8.safetensors")]
assert hub.fetched == ["Model-FP8.safetensors"]
# nvfp4 is the exception: its hosted repos hold only the .safetensors, and a .pt is never resolved, cached or opened.
NV_REPO = "unsloth/Z-Image-Turbo-NVFP4"
NV_ST, NV_PT = "Z-Image-Turbo-NVFP4.safetensors", "Z-Image-Turbo-NVFP4.pt"
# Captured before any fixture stubs it: the nvfp4 cases ask the install's real readability question.
_REAL_LOAD_SUPPORTED = pq.restricted_prequant_load_supported
@pytest.fixture
def nv_hub(hub, monkeypatch):
from core.inference import diffusion_nvfp4_flag
monkeypatch.setenv(diffusion_nvfp4_flag.NVFP4_DIFFUSION_ENV, "1")
monkeypatch.setattr(pq, "restricted_prequant_load_supported", _REAL_LOAD_SUPPORTED)
hub.hosted = {NV_ST, NV_PT}
return hub
def _nv_source():
"""The chain Studio resolves for Z-Image's hosted NVFP4 repo, not a hand-written one."""
from core.inference.diffusion_families import detect_family
fam = detect_family("Tongyi-MAI/Z-Image-Turbo")
source = pq.resolve_prequant_source(fam, "nvfp4")
assert source.location == NV_REPO
chain = pq.candidate_filenames_of(source)
# the hosted safetensors leads; no .pt / .pth name anywhere (a ComfyUI-format twin may trail)
assert chain[0] == NV_ST and all(n.endswith(".safetensors") for n in chain), chain
assert source.declared_filenames == (NV_ST,)
return source
def _nv_resolve(source, **kw):
return pq._resolve_checkpoint_path(source, None, None, scheme = "nvfp4", **kw)
def _needs_nvfp4_safetensors():
if not _REAL_LOAD_SUPPORTED("nvfp4", NV_ST):
pytest.skip("this install cannot read nvfp4 safetensors checkpoints")
def test_nvfp4_pickle_is_never_readable():
assert _REAL_LOAD_SUPPORTED("nvfp4", NV_PT) is False
assert _REAL_LOAD_SUPPORTED("nvfp4", "Model-NVFP4.pth") is False
assert _REAL_LOAD_SUPPORTED("nvfp4", "transformer_nvfp4.pt") is False
def test_nvfp4_cached_pickle_is_ignored(nv_hub):
_needs_nvfp4_safetensors()
nv_hub.cache(NV_PT, NV_REPO)
assert _nv_resolve(_nv_source()) == nv_hub.cached[(NV_REPO, NV_ST)]
assert nv_hub.fetched == [NV_ST]
def test_nvfp4_cached_pickle_offline_is_not_used(nv_hub):
_needs_nvfp4_safetensors()
nv_hub.cache(NV_PT, NV_REPO)
with pytest.raises(LocalEntryNotFoundError):
_nv_resolve(_nv_source(), local_files_only = True)
assert NV_PT not in nv_hub.fetched
def test_nvfp4_cached_pickle_is_not_preferred_even_when_offered(nv_hub):
"""A stale chain naming the .pt (an older caller) still never moves the cached pickle ahead."""
nv_hub.cache(NV_PT, NV_REPO)
names = [NV_ST, NV_PT]
assert pq.prefer_cached_pickle_twins(NV_REPO, names, readable = None)[0] == NV_PT
out = pq.prefer_cached_pickle_twins(
NV_REPO, names, readable = lambda n: _REAL_LOAD_SUPPORTED("nvfp4", n)
)
assert out.index(NV_ST) < out.index(NV_PT)
assert pq.without_nvfp4_pickles("nvfp4", out) == [NV_ST]
def test_nvfp4_stale_pickle_chain_is_filtered_at_download(nv_hub):
"""Even a source that still lists the .pt (built by older code) never downloads it."""
_needs_nvfp4_safetensors()
nv_hub.cache(NV_PT, NV_REPO)
stale = pq.PrequantSource(
kind = "repo", location = NV_REPO, filename = NV_ST, fallback_filenames = (NV_PT,)
)
assert _nv_resolve(stale) == nv_hub.cached[(NV_REPO, NV_ST)]
nv_hub.hosted = {NV_PT}
nv_hub.cached.clear()
nv_hub.downloads.clear()
with pytest.raises(EntryNotFoundError):
_nv_resolve(stale)
assert nv_hub.fetched == [NV_ST]
def test_nvfp4_new_user_downloads_only_the_safetensors(nv_hub):
_needs_nvfp4_safetensors()
assert _nv_resolve(_nv_source()) == nv_hub.cached[(NV_REPO, NV_ST)]
assert nv_hub.fetched == [NV_ST]
def test_nvfp4_pickle_only_repo_is_not_loaded(nv_hub):
_needs_nvfp4_safetensors()
nv_hub.hosted = {NV_PT}
with pytest.raises(EntryNotFoundError):
_nv_resolve(_nv_source())
assert nv_hub.fetched[0] == NV_ST and NV_PT not in nv_hub.fetched
def test_nvfp4_torchao_without_nvfp4_unflatten_is_refused(nv_hub, monkeypatch):
"""torchao 0.16 cannot rebuild the NVFP4 safetensors: a clear refusal, never the hosted .pt."""
utils = pytest.importorskip("torchao.prototype.safetensors.safetensors_utils")
monkeypatch.setattr(
utils,
"ALLOWED_TENSORS_SUBCLASSES",
[n for n in utils.ALLOWED_TENSORS_SUBCLASSES if n not in ("NVFP4Tensor", "MXTensor")],
)
with pytest.raises(ValueError, match = "torchao >= 0.17"):
_nv_resolve(_nv_source())
assert nv_hub.fetched == []