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
"""A hosted pre-quant checkpoint is judged from its header BEFORE its weights are downloaded, and its
packed-weight fingerprint verifies whichever torchao generation built or loads it.
The Hub side is a real HTTP server on localhost serving real ``torch.save`` / safetensors files with
Range support, so the probe's range requests, zip directory walk and inert unpickle all run for real;
only the two huggingface_hub URL / HEAD helpers are pointed at it.
"""
from __future__ import annotations
from pathlib import Path
import http.server
import json
import os
import threading
import types
import pytest
torch = pytest.importorskip("torch")
import core.inference.diffusion_prequant as pq # noqa: E402
from core.inference.diffusion_prequant import PREQUANT_FORMAT, PrequantSource # noqa: E402
_STALE_INT8_EXCLUDES = [
"norm",
"_mod",
"modulation",
"timestep_embed",
"guidance_embed",
"time_text_embed",
"pooled",
"time_embed",
]
@pytest.fixture(autouse = True)
def _fresh_probe(monkeypatch):
monkeypatch.delenv(
getattr(pq, "HEADER_PROBE_ENV", "UNSLOTH_PREQUANT_HEADER_PROBE"), raising = False
)
monkeypatch.setattr(pq, "_HEADER_PROBE_MEMO", {}, raising = False)
monkeypatch.setattr(pq, "_HEADER_PROBE_SAID", {}, raising = False)
monkeypatch.setattr(pq, "hub_offline", lambda: False)
monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda scheme, name = None: True)
def _qwen_int8_meta(excludes):
return {
"scheme": "int8",
"family": "qwen-image",
"base_model_id": "Qwen/Qwen-Image-2512",
"min_features": 512,
"exclude_name_tokens": list(excludes),
"torch_version": torch.__version__, # a TorchVersion, as the builder records it
}
def _write_pt(
path,
meta,
*,
mb = 8,
):
"""A real torch.save checkpoint whose weight bytes dwarf its metadata."""
state_dict = {
f"blocks.{i}.weight": torch.zeros(256, 1024, dtype = torch.int8) for i in range(mb * 4)
}
torch.save({"format": PREQUANT_FORMAT, "metadata": meta, "state_dict": state_dict}, path)
return path
def _write_safetensors(
path,
meta,
*,
mb = 8,
):
from safetensors.torch import save_file
from core.inference.prequant_safetensors import UNSLOTH_FORMAT_KEY, UNSLOTH_METADATA_KEY
tensors = {
f"blocks.{i}.weight": torch.zeros(256, 1024, dtype = torch.int8) for i in range(mb * 4)
}
save_file(
tensors,
str(path),
metadata = {
UNSLOTH_FORMAT_KEY: PREQUANT_FORMAT,
UNSLOTH_METADATA_KEY: json.dumps(meta, default = str),
},
)
return path
class _RangeServer:
"""Serves files from a directory with HTTP Range support and counts every byte sent."""
def __init__(self, root):
self.root = root
self.sent = 0
self.full_gets = 0
owner = self
class Handler(http.server.BaseHTTPRequestHandler):
def log_message(self, *args):
pass
def do_GET(self):
path = os.path.join(owner.root, self.path.lstrip("/").split("?")[0])
if not os.path.isfile(path):
self.send_response(404)
self.end_headers()
return
size = os.path.getsize(path)
spec = self.headers.get("Range")
if not spec:
owner.full_gets += 1
start, end, code = 0, size - 1, 200
else:
a, _, b = spec.replace("bytes=", "").partition("-")
if a == "":
start, end = max(0, size - int(b)), size - 1
else:
start, end = int(a), min(size - 1, int(b) if b else size - 1)
code = 206
with open(path, "rb") as handle:
handle.seek(start)
body = handle.read(end - start + 1)
self.send_response(code)
self.send_header("Content-Length", str(len(body)))
if code == 206:
self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
self.end_headers()
self.wfile.write(body)
owner.sent += len(body)
self.httpd = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
self.thread = threading.Thread(target = self.httpd.serve_forever, daemon = True)
self.thread.start()
self.url = f"http://127.0.0.1:{self.httpd.server_address[1]}"
def close(self):
self.httpd.shutdown()
self.httpd.server_close()
@pytest.fixture
def hub(tmp_path, monkeypatch):
"""A fake Hub: ``<repo>/<file>`` under tmp_path served over real HTTP; downloads are recorded."""
import huggingface_hub
root = tmp_path / "hub"
root.mkdir()
server = _RangeServer(str(root))
def hf_hub_url(
repo_id,
filename,
revision = None,
**_,
):
return f"{server.url}/{repo_id}/{filename}"
def get_hf_file_metadata(
url,
token = None,
timeout = None,
**_,
):
path = os.path.join(str(root), url[len(server.url) + 1 :])
if not os.path.isfile(path):
err = Exception("404")
err.response = types.SimpleNamespace(status_code = 404)
raise err
return types.SimpleNamespace(size = os.path.getsize(path), commit_hash = None)
downloads: list = []
def hf_hub_download(
repo_id = None,
filename = None,
**kwargs,
):
downloads.append(filename)
raise RuntimeError("weight download attempted")
monkeypatch.setattr(huggingface_hub, "hf_hub_url", hf_hub_url)
monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", get_hf_file_metadata)
monkeypatch.setattr(huggingface_hub, "hf_hub_download", hf_hub_download)
monkeypatch.setattr(pq, "cached_checkpoint_path", lambda *a, **k: None)
yield types.SimpleNamespace(root = root, server = server, downloads = downloads)
server.close()
def _repo_file(hub, repo, name):
folder = hub.root / repo
folder.mkdir(parents = True, exist_ok = True)
return folder / name
def _source(repo, *names):
return PrequantSource(
kind = "repo", location = repo, filename = names[0], fallback_filenames = tuple(names[1:])
)
def _load(source, logger = None):
return pq.load_prequantized_transformer(
object,
"Qwen/Qwen-Image-2512",
source,
device = "cpu",
dtype = None,
scheme = "int8",
min_features = 512,
logger = logger,
)
class _Lines:
def __init__(self):
self.lines: list = []
def _say(self, msg, *args):
self.lines.append(msg % args if args else msg)
debug = info = warning = error = _say
def test_a_stale_hosted_checkpoint_is_refused_before_any_weight_download(hub):
container = "safetensors"
repo = "unsloth/Qwen-Image-2512-FP8"
name = f"Qwen-Image-2512-INT8.{container}"
path = _repo_file(hub, repo, name)
writer = _write_safetensors
writer(path, _qwen_int8_meta(_STALE_INT8_EXCLUDES), mb = 16)
logger = _Lines()
source = _source(repo, "Qwen-Image-2512-INT8-ComfyUI.safetensors", name)
assert _load(source, logger) is None
assert hub.downloads == [] # the multi-GB hf_hub_download never started
assert hub.server.full_gets == 0
assert hub.server.sent < path.stat().st_size // 4, (hub.server.sent, path.stat().st_size)
said = [line for line in logger.lines if "skipping hosted int8 checkpoint" in line]
assert len(said) == 1 and "txt_in" in said[0] and name in said[0]
assert "txt_in" in (pq.last_prequant_failure() or "")
def test_a_pickle_checkpoint_is_never_read_and_never_refused_early(hub):
"""The probe reads safetensors headers only. A ``.pt`` that comes first in the resolver's order is
"unknown": no range read of it at all, and the load goes on to download and validate it as before."""
repo = "unsloth/Qwen-Image-2512-FP8"
name = "Qwen-Image-2512-INT8.pt"
_write_pt(_repo_file(hub, repo, name), _qwen_int8_meta(_STALE_INT8_EXCLUDES))
assert pq.hosted_prequant_refusal(_source(repo, name), "int8") is None
assert hub.server.sent == 0
_load(_source(repo, name))
assert hub.downloads == [name]
def test_the_first_existing_name_decides_like_the_resolver(hub):
"""Safetensors ahead of the pickle, as the resolver orders them: a stale .safetensors is refused even
with a .pt behind it, and a missing .safetensors leaves the .pt to the loader."""
repo = "unsloth/Qwen-Image-2512-FP8"
_write_pt(_repo_file(hub, repo, "q-INT8.pt"), _qwen_int8_meta(_STALE_INT8_EXCLUDES))
assert (
pq.hosted_prequant_refusal(_source(repo, "q-INT8.safetensors", "q-INT8.pt"), "int8") is None
)
_write_safetensors(
_repo_file(hub, repo, "q-INT8.safetensors"), _qwen_int8_meta(_STALE_INT8_EXCLUDES)
)
pq._HEADER_PROBE_MEMO.clear()
assert pq.hosted_prequant_refusal(_source(repo, "q-INT8.safetensors", "q-INT8.pt"), "int8")
def test_a_current_hosted_checkpoint_still_goes_to_the_download(hub):
from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
repo = "unsloth/Qwen-Image-FP8"
path = _repo_file(hub, repo, "Qwen-Image-INT8.pt")
_write_pt(path, _qwen_int8_meta(exclude_tokens_for_scheme("int8", "qwen-image")))
source = _source(repo, "Qwen-Image-INT8.pt")
_load(source)
assert hub.downloads == ["Qwen-Image-INT8.pt"]
def test_planning_sees_a_stale_hosted_checkpoint_as_no_source(hub):
"""``usable_prequant_source`` is what the download plan and auto policy ask, so a stale file is
never staged: the dense path is budgeted up front instead of after a wasted download."""
from core.inference.diffusion_families import detect_family
fam = detect_family("Qwen/Qwen-Image-2512")
src = pq.resolve_prequant_source(fam, "int8", base_repo = "Qwen/Qwen-Image-2512")
assert src is not None and src.kind == "repo"
stale = next(n for n in pq.candidate_filenames_of(src) if n.endswith("INT8.safetensors"))
_write_safetensors(_repo_file(hub, src.location, stale), _qwen_int8_meta(_STALE_INT8_EXCLUDES))
assert pq.usable_prequant_source(fam, "int8", base_repo = "Qwen/Qwen-Image-2512") is None
assert hub.downloads == []
def test_an_unreadable_or_foreign_header_is_never_a_refusal(hub):
repo = "org/odd"
_repo_file(hub, repo, "odd-INT8.pt").write_bytes(b"not a zip at all" * 1000)
from safetensors.torch import save_file
save_file({"a.weight": torch.zeros(4, 4)}, str(_repo_file(hub, repo, "odd-INT8.safetensors")))
for name in ("odd-INT8.pt", "odd-INT8.safetensors", "absent-INT8.pt"):
assert pq.hosted_prequant_refusal(_source(repo, name), "int8") is None
def test_offline_with_nothing_cached_asks_nothing(hub, monkeypatch):
monkeypatch.setattr(pq, "hub_offline", lambda: True)
repo = "unsloth/Qwen-Image-2512-FP8"
_write_pt(_repo_file(hub, repo, "x-INT8.pt"), _qwen_int8_meta(_STALE_INT8_EXCLUDES))
assert pq.hosted_prequant_refusal(_source(repo, "x-INT8.pt"), "int8") is None
assert (
pq.hosted_prequant_refusal(_source(repo, "x-INT8.pt"), "int8", local_files_only = True)
is None
)
assert hub.server.sent == 0
def test_a_cached_checkpoint_is_judged_locally_without_the_network(hub, monkeypatch, tmp_path):
cached = _write_safetensors(
tmp_path / "cached-INT8.safetensors", _qwen_int8_meta(_STALE_INT8_EXCLUDES)
)
monkeypatch.setattr(pq, "cached_checkpoint_path", lambda *a, **k: str(cached))
monkeypatch.setattr(pq, "hub_offline", lambda: True)
reason = pq.hosted_prequant_refusal(_source("unsloth/x", "cached-INT8.safetensors"), "int8")
assert reason is not None and "txt_in" in reason
assert hub.server.sent == 0
def test_the_kill_switch_turns_the_probe_off(hub, monkeypatch):
repo = "unsloth/Qwen-Image-2512-FP8"
_write_safetensors(
_repo_file(hub, repo, "y-INT8.safetensors"), _qwen_int8_meta(_STALE_INT8_EXCLUDES)
)
monkeypatch.setenv(pq.HEADER_PROBE_ENV, "0")
assert pq.hosted_prequant_refusal(_source(repo, "y-INT8.safetensors"), "int8") is None
assert hub.server.sent == 0
class PlainAQTTensorImpl:
def __init__(self, q, scale):
self.int_data, self.scale, self.zero_point = q, scale, None
class AffineQuantizedTensor:
def __init__(self, impl):
self.tensor_impl = impl
class LinearActivationQuantizedTensor:
def __init__(self, aqt):
self.original_weight_tensor = aqt
class Int8Tensor:
def __init__(
self,
q,
scale,
zero_point = None,
):
self.qdata, self.scale, self.zero_point = q, scale, zero_point
self.act_quant_scale = self.act_quant_zero_point = self.act_pre_scale = None
def _int8_values(
seed,
n = 8,
k = 32,
):
g = torch.Generator().manual_seed(seed)
q = torch.randint(-127, 128, (n, k), generator = g, dtype = torch.int8)
scale = (torch.rand(n, generator = g) / 100 + 1e-4).to(torch.bfloat16)
return q, scale
def _as_017(q, scale):
return LinearActivationQuantizedTensor(AffineQuantizedTensor(PlainAQTTensorImpl(q, scale)))
def _as_018(
q,
scale,
*,
zero_point = True,
):
n = q.shape[0]
zp = torch.zeros(n, 1, dtype = torch.int8) if zero_point else None
return Int8Tensor(q, scale.float().reshape(n, 1), zp)
def _state(layout, values):
return {f"blocks.{i}.weight": layout(*v) for i, v in enumerate(values)}
_GENERATIONS = {
"0.17": _as_017,
"0.18": _as_018,
"0.18-legacy-decode": lambda q, s: Int8Tensor(q, s.reshape(-1, 1)), # prequant_legacy_int8
"0.16": lambda q, s: _as_018(q, s, zero_point = False),
}
@pytest.mark.parametrize("built", sorted(_GENERATIONS))
@pytest.mark.parametrize("loaded", sorted(_GENERATIONS))
def test_a_legacy_v1_fingerprint_verifies_on_another_torchao_generation(built, loaded):
values = [_int8_values(i) for i in range(4)]
recorded = pq.packed_weight_fingerprint(_state(_GENERATIONS[built], values))
assert recorded["count"] == 4
assert pq._verify_packed_fingerprint(
_state(_GENERATIONS[loaded], values), {"fingerprint": recorded}
)
@pytest.mark.parametrize("built", sorted(_GENERATIONS))
@pytest.mark.parametrize("loaded", sorted(_GENERATIONS))
def test_the_canonical_fingerprint_is_the_same_on_every_generation(built, loaded):
values = [_int8_values(i) for i in range(4)]
recorded = pq.canonical_weight_fingerprint(_state(_GENERATIONS[built], values))
assert "modules" not in recorded # an older loader skips the check instead of refusing
assert recorded["count"] == 4 and recorded["algo"] == pq.CANONICAL_FINGERPRINT_ALGO
assert recorded == pq.canonical_weight_fingerprint(_state(_GENERATIONS[loaded], values))
assert pq._verify_packed_fingerprint(
_state(_GENERATIONS[loaded], values), {"fingerprint": recorded}
)
@pytest.mark.parametrize("algo", ["v1", "canonical"])
@pytest.mark.parametrize("what", ["q", "scale"])
def test_a_changed_value_is_still_refused_across_generations(algo, what):
values = [_int8_values(i) for i in range(4)]
fingerprint = pq.packed_weight_fingerprint if algo == "v1" else pq.canonical_weight_fingerprint
recorded = fingerprint(_state(_as_017, values))
q, scale = values[2]
if what == "q":
q = q.clone()
q[0, 0] ^= 1
else:
scale = scale.clone()
scale[0] = scale[0] * 2
values[2] = (q, scale)
logger = _Lines()
assert not pq._verify_packed_fingerprint(
_state(_as_018, values), {"fingerprint": recorded}, logger = logger
)
assert "blocks.2.weight" in "\n".join(logger.lines)
assert "blocks.1.weight" not in "\n".join(logger.lines)
def test_fp8_fingerprints_are_unchanged_by_the_canonical_form():
if not hasattr(torch, "float8_e4m3fn"):
pytest.skip("this torch has no float8")
class Float8Tensor:
def __init__(self, q, scale):
self.qdata, self.scale = q, scale
g = torch.Generator().manual_seed(0)
q = torch.randn(8, 32, generator = g).to(torch.float8_e4m3fn)
scale = torch.rand(8, 1, generator = g)
sd = {"a.weight": Float8Tensor(q, scale)}
assert pq._verify_packed_fingerprint(sd, {"fingerprint": pq.packed_weight_fingerprint(sd)})
assert pq._verify_packed_fingerprint(sd, {"fingerprint": pq.canonical_weight_fingerprint(sd)})
def test_real_torchao_int8_weight_matches_the_other_generations_layout():
"""The weight the INSTALLED torchao quantizes, re-laid out as the other generation stores it."""
pytest.importorskip("torchao")
from torchao.quantization import quantize_
from core.inference.diffusion_transformer_quant import _make_quant_config
torch.manual_seed(0)
model = torch.nn.Sequential(torch.nn.Linear(64, 32, bias = False)).to(torch.bfloat16)
quantize_(model, _make_quant_config("int8"))
real = model.state_dict()
parts = pq._canonical_parts(real["0.weight"])
q, scale = parts["q"], parts["scale"]
native = type(real["0.weight"]).__name__
other = (
_as_018(q, scale.reshape(-1).to(torch.bfloat16))
if native == "LinearActivationQuantizedTensor"
else _as_017(q, scale.reshape(-1).to(torch.bfloat16))
)
if not torch.equal(scale.reshape(-1).to(torch.bfloat16).float(), scale.reshape(-1).float()):
pytest.skip("this torchao's scale is not bf16-representable; no 0.17 twin exists")
assert pq._verify_packed_fingerprint(
{"0.weight": other}, {"fingerprint": pq.packed_weight_fingerprint(real)}
)
assert pq._verify_packed_fingerprint(
{"0.weight": other}, {"fingerprint": pq.canonical_weight_fingerprint(real)}
)
def _counting_hub(hub, monkeypatch):
"""Counts every Hub HEAD the probe makes, on top of the byte count the range server keeps."""
import huggingface_hub
calls: list = []
real = huggingface_hub.get_hf_file_metadata
def counted(url, *args, **kwargs):
calls.append(url)
return real(url, *args, **kwargs)
monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", counted)
return calls
def _hosted_qwen_int8(hub, meta):
"""Serve ``meta`` under the name planning probes for Qwen-Image-2512 int8; returns ``(fam, base)``."""
from core.inference.diffusion_families import detect_family
base = "Qwen/Qwen-Image-2512"
fam = detect_family(base)
src = pq.resolve_prequant_source(fam, "int8", base_repo = base)
name = next(n for n in pq.candidate_filenames_of(src) if n.endswith("INT8.safetensors"))
_write_safetensors(_repo_file(hub, src.location, name), meta)
return fam, base
def _current_int8_meta(**overrides):
from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
meta = _qwen_int8_meta(exclude_tokens_for_scheme("int8", "qwen-image"))
meta.update(overrides)
return {k: v for k, v in meta.items() if v is not None}
def test_an_offline_load_plans_without_any_hub_request(hub, monkeypatch):
"""``local_files_only`` reaches the planning probe, explicitly or from the load's scope: a cache miss
is "unknown" (usable, today's answer) and costs no HEAD, no range read and no probe timeout."""
calls = _counting_hub(hub, monkeypatch)
fam, base = _hosted_qwen_int8(hub, _qwen_int8_meta(_STALE_INT8_EXCLUDES))
assert pq.usable_prequant_source(fam, "int8", base_repo = base, local_files_only = True) is not None
@pq.scoped_local_files_only
def offline_load(**kwargs):
return pq.usable_prequant_source(fam, "int8", base_repo = base)
assert offline_load(local_files_only = True) is not None
assert calls == [] and hub.server.sent == 0
assert pq.usable_prequant_source(fam, "int8", base_repo = base) is None
assert calls and hub.server.sent > 0
assert hub.downloads == []
def test_an_offline_denoiser_seed_cache_check_makes_no_hub_request(hub, monkeypatch):
from core.inference.diffusion_denoiser_prequant import denoiser_prequant_cached
calls = _counting_hub(hub, monkeypatch)
fam, base = _hosted_qwen_int8(hub, _qwen_int8_meta(_STALE_INT8_EXCLUDES))
assert denoiser_prequant_cached(fam, "int8", base_repo = base) is False
assert calls == [] and hub.server.sent == 0
def test_the_hub_token_and_cache_root_reach_the_planning_probe(hub, monkeypatch):
import huggingface_hub
seen: dict = {}
real = huggingface_hub.get_hf_file_metadata
def spy(
url,
token = None,
**kwargs,
):
seen["token"] = token
return real(url, token = token, **kwargs)
def cached(source, **kwargs):
seen["cache_dir"] = kwargs.get("cache_dir")
return None
monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", spy)
monkeypatch.setattr(pq, "cached_checkpoint_path", cached)
fam, base = _hosted_qwen_int8(hub, _current_int8_meta())
src = pq.usable_prequant_source(
fam, "int8", base_repo = base, hf_token = "hf_secret", cache_dir = "/live/cache"
)
assert src is not None
assert seen == {"token": "hf_secret", "cache_dir": "/live/cache"}
@pytest.mark.parametrize(
"recorded, usable",
[
("Qwen/Qwen-Image-2512", True), # the requested base
("unsloth/Qwen-Image-2512", True), # a mirror of it: same tail, as the loader accepts
("Qwen/Qwen-Image", False), # a different base
(None, False), # no base_model_id at all: the loader refuses it for a requested base
],
)
def test_planning_checks_the_requested_base_like_the_loader(hub, recorded, usable):
fam, base = _hosted_qwen_int8(hub, _current_int8_meta(base_model_id = recorded))
src = pq.usable_prequant_source(fam, "int8", base_repo = base)
assert (src is not None) is usable
hosted = src or pq.resolve_prequant_source(fam, "int8", base_repo = base)
assert (pq.hosted_prequant_refusal(hosted, "int8", base = base) is None) is usable
assert hub.downloads == []
def test_no_requested_base_skips_the_base_check(hub):
fam, _ = _hosted_qwen_int8(hub, _current_int8_meta(base_model_id = "Qwen/Qwen-Image"))
src = pq.resolve_prequant_source(fam, "int8", base_repo = "Qwen/Qwen-Image-2512")
assert pq.hosted_prequant_refusal(src, "int8") is None
assert pq.hosted_prequant_refusal(src, "int8", base = None) is None
def _raw_safetensors(
path,
header: dict,
pad: bytes = b"",
):
"""A safetensors file whose JSON header is ``header`` (plus raw ``pad`` spliced into it), no tensors."""
import struct
text = json.dumps(header).encode()
if pad:
text = text[:-1] + b', "pad": ' + pad + b"}"
with open(path, "wb") as handle:
handle.write(struct.pack("<Q", len(text)) + text + b"\0" * 64)
return path
def _unsloth_extra(meta):
from core.inference.prequant_safetensors import UNSLOTH_FORMAT_KEY, UNSLOTH_METADATA_KEY
return {
UNSLOTH_FORMAT_KEY: PREQUANT_FORMAT,
UNSLOTH_METADATA_KEY: json.dumps(meta, default = str),
}
def _traced(fn):
import time
import tracemalloc
tracemalloc.start()
started = time.monotonic()
try:
out = fn()
_, peak = tracemalloc.get_traced_memory()
finally:
tracemalloc.stop()
return out, peak, time.monotonic() - started
def test_a_safetensors_header_with_millions_of_entries_is_unknown_fast_and_small(tmp_path):
from core.inference.prequant_header_probe import read_local_checkpoint_header
meta = _qwen_int8_meta(["norm"])
bomb = _raw_safetensors(
tmp_path / "bomb-INT8.safetensors",
{"__metadata__": _unsloth_extra(meta)},
pad = b"[" + b"{}," * 2_000_000 + b"{}]",
)
header, peak, took = _traced(lambda: read_local_checkpoint_header(str(bomb)))
assert header is None
# The header is ~6 MB of text; parsing it would build 2M dicts (hundreds of MB).
assert peak < 32 * 1024 * 1024, peak
assert took < 30
def test_a_nested_metadata_string_with_millions_of_entries_is_unknown(tmp_path):
from core.inference.prequant_header_probe import read_local_checkpoint_header
meta = _qwen_int8_meta(["norm"])
meta["pad"] = [0] * 1_200_000
bomb = _raw_safetensors(
tmp_path / "nested-INT8.safetensors", {"__metadata__": _unsloth_extra(meta)}
)
assert read_local_checkpoint_header(str(bomb)) is None
def test_a_real_sized_safetensors_header_still_reads(tmp_path):
"""~3 MB of header (the largest hosted pre-quant headers) with real per-tensor entries."""
from safetensors.torch import save_file
from core.inference.prequant_header_probe import read_local_checkpoint_header
meta = _qwen_int8_meta(["norm"])
tensors = {
f"transformer_blocks.{i // 64}.attn.to_q.{i % 64}.weight_scale_inverse_long": torch.zeros(1)
for i in range(24_000)
}
path = tmp_path / "big-INT8.safetensors"
save_file(tensors, str(path), metadata = {k: v for k, v in _unsloth_extra(meta).items()})
import struct
with open(path, "rb") as handle:
(length,) = struct.unpack("<Q", handle.read(8))
assert length > 2_500_000, length
header = read_local_checkpoint_header(str(path))
assert header is not None and header["metadata"]["exclude_name_tokens"] == ["norm"]
def _hf_cache_file(tmp_path, name, commit, etag, writer, meta):
"""``<root>/snapshots/<commit>/<name>`` symlinked to ``blobs/<etag>``, as huggingface_hub lays it out."""
root = tmp_path / "models--unsloth--Qwen-Image-2512-FP8"
blob = root / "blobs" / etag
blob.parent.mkdir(parents = True, exist_ok = True)
writer(blob, meta)
snap = root / "snapshots" / commit / name
snap.parent.mkdir(parents = True, exist_ok = True)
snap.symlink_to(os.path.relpath(blob, snap.parent))
return snap
@pytest.fixture
def replaced(hub, tmp_path, monkeypatch):
"""A stale checkpoint in the cache; the Hub file under the same name is set per test."""
import huggingface_hub
from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
repo, name = "unsloth/Qwen-Image-2512-FP8", "Qwen-Image-2512-INT8.safetensors"
cached = _hf_cache_file(
tmp_path,
name,
"c0ffee01",
"etag-stale",
_write_safetensors,
_qwen_int8_meta(_STALE_INT8_EXCLUDES),
)
monkeypatch.setattr(pq, "cached_checkpoint_path", lambda *a, **k: str(cached))
served = {"etag": "etag-stale", "commit": "c0ffee01"}
heads: list = []
real = huggingface_hub.get_hf_file_metadata
def get_hf_file_metadata(url, *args, **kwargs):
heads.append(url)
meta = real(url, *args, **kwargs)
return types.SimpleNamespace(
size = meta.size, commit_hash = served["commit"], etag = served["etag"]
)
monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", get_hf_file_metadata)
def publish(fixed: bool, etag: str, commit: str):
meta = _qwen_int8_meta(
exclude_tokens_for_scheme("int8", "qwen-image") if fixed else _STALE_INT8_EXCLUDES
)
_write_safetensors(_repo_file(hub, repo, name), meta)
served.update(etag = etag, commit = commit)
return types.SimpleNamespace(source = _source(repo, name), publish = publish, heads = heads)
def test_a_fixed_reupload_replaces_a_stale_cached_verdict_online(hub, replaced):
replaced.publish(True, "etag-fixed", "c0ffee02")
assert pq.hosted_prequant_refusal(replaced.source, "int8") is None
assert hub.server.sent > 0 and hub.downloads == []
def test_an_unchanged_cached_file_costs_one_head_and_no_range_read(hub, replaced):
replaced.publish(False, "etag-stale", "c0ffee03")
reason = pq.hosted_prequant_refusal(replaced.source, "int8")
assert reason is not None and "txt_in" in reason
assert len(replaced.heads) == 1 and hub.server.sent == 0
def test_offline_keeps_the_cached_verdict_without_any_request(hub, replaced, monkeypatch):
replaced.publish(True, "etag-fixed", "c0ffee02")
assert pq.hosted_prequant_refusal(replaced.source, "int8", local_files_only = True) is not None
monkeypatch.setattr(pq, "hub_offline", lambda: True)
assert pq.hosted_prequant_refusal(replaced.source, "int8") is not None
assert replaced.heads == [] and hub.server.sent == 0
def test_an_online_cached_verdict_expires(hub, replaced, monkeypatch):
replaced.publish(False, "etag-stale", "c0ffee01")
assert pq.hosted_prequant_refusal(replaced.source, "int8") is not None
replaced.publish(True, "etag-fixed", "c0ffee02")
assert pq.hosted_prequant_refusal(replaced.source, "int8") is not None # memoised
monkeypatch.setattr(pq, "_HEADER_PROBE_TTL_S", 0.0)
assert pq.hosted_prequant_refusal(replaced.source, "int8") is None
def test_a_cached_name_the_hub_no_longer_serves_moves_on_to_the_next_name(
hub, tmp_path, monkeypatch
):
# The stale cached name 404s on the Hub, so planning must judge the next name.
from core.inference.diffusion_transformer_quant import exclude_tokens_for_scheme
repo = "unsloth/Qwen-Image-2512-FP8"
gone, current = "Qwen-Image-2512-INT8-ComfyUI.safetensors", "Qwen-Image-2512-INT8.safetensors"
cached = _hf_cache_file(
tmp_path,
gone,
"c0ffee01",
"etag-stale",
_write_safetensors,
_qwen_int8_meta(_STALE_INT8_EXCLUDES),
)
monkeypatch.setattr(pq, "cached_checkpoint_path", lambda *a, **k: str(cached))
_write_safetensors(
_repo_file(hub, repo, current),
_qwen_int8_meta(exclude_tokens_for_scheme("int8", "qwen-image")),
)
assert pq.hosted_prequant_refusal(_source(repo, gone, current), "int8") is None
assert hub.downloads == []
def test_unsloth_metadata_that_is_not_an_object_is_refused_before_download(hub):
from safetensors.torch import save_file
from core.inference.prequant_safetensors import UNSLOTH_FORMAT_KEY, UNSLOTH_METADATA_KEY
repo, name = "unsloth/Qwen-Image-2512-FP8", "Qwen-Image-2512-INT8.safetensors"
save_file(
{"blocks.0.weight": torch.zeros(256, 1024, dtype = torch.int8)},
str(_repo_file(hub, repo, name)),
metadata = {UNSLOTH_FORMAT_KEY: PREQUANT_FORMAT, UNSLOTH_METADATA_KEY: "[]"},
)
reason = pq.hosted_prequant_refusal(_source(repo, name), "int8")
assert reason is not None and "malformed" in reason
assert hub.downloads == []
def test_the_probe_memo_and_said_set_are_bounded():
cap = pq._HEADER_PROBE_MAX
with pq._HEADER_PROBE_LOCK:
for i in range(cap * 4):
pq._memo_put(
("hub", "r", ("n",), ("int8", f"base{i}", None, None, "")), (0.0, None), 0.0
)
pq._said_first(("r", "n", f"reason {i}"))
assert len(pq._HEADER_PROBE_MEMO) <= cap
assert len(pq._HEADER_PROBE_SAID) <= cap
assert (
"hub",
"r",
("n",),
("int8", f"base{cap * 4 - 1}", None, None, ""),
) in pq._HEADER_PROBE_MEMO
def test_an_expired_memo_entry_is_dropped():
ttl = pq._HEADER_PROBE_TTL_S
with pq._HEADER_PROBE_LOCK:
pq._memo_put(("hub", "a"), (0.0, "old"), 0.0)
pq._memo_put(("local", "b"), (0.0, "kept"), 0.0)
assert pq._memo_get(("hub", "a"), ttl + 1) is None
assert ("hub", "a") not in pq._HEADER_PROBE_MEMO
pq._memo_put(("hub", "c"), (0.0, "old"), 0.0)
pq._memo_put(("hub", "d"), (ttl + 1, None), ttl + 1) # an insert sweeps the expired
assert ("hub", "c") not in pq._HEADER_PROBE_MEMO
assert pq._memo_get(("local", "b"), ttl * 10) == (0.0, "kept")
def test_many_requested_bases_keep_the_memo_bounded(hub, monkeypatch, tmp_path):
cached = _write_safetensors(
tmp_path / "c-INT8.safetensors", _qwen_int8_meta(_STALE_INT8_EXCLUDES)
)
monkeypatch.setattr(pq, "cached_checkpoint_path", lambda *a, **k: str(cached))
monkeypatch.setattr(pq, "hub_offline", lambda: True)
for i in range(pq._HEADER_PROBE_MAX + 50):
pq.hosted_prequant_refusal(
_source("unsloth/x", "c-INT8.safetensors"), "int8", base = f"org/b{i}"
)
assert len(pq._HEADER_PROBE_MEMO) <= pq._HEADER_PROBE_MAX
def test_an_anonymous_401_does_not_answer_for_a_token_probe(hub, monkeypatch):
import huggingface_hub
real = huggingface_hub.get_hf_file_metadata
def gated(
url,
token = None,
**kwargs,
):
if not token:
err = Exception("401")
err.response = types.SimpleNamespace(status_code = 401)
raise err
return real(url, token = token, **kwargs)
monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", gated)
repo = "unsloth/Qwen-Image-2512-FP8"
_write_safetensors(
_repo_file(hub, repo, "g-INT8.safetensors"), _qwen_int8_meta(_STALE_INT8_EXCLUDES)
)
source = _source(repo, "g-INT8.safetensors")
assert pq.hosted_prequant_refusal(source, "int8") is None # unknown: never a refusal
reason = pq.hosted_prequant_refusal(source, "int8", hf_token = "hf_secret")
assert reason is not None and "txt_in" in reason
assert all("hf_secret" not in repr(key) for key in pq._HEADER_PROBE_MEMO)
_WAN_TI2V = "Wan-AI/Wan2.2-TI2V-5B-Diffusers"
def _wan_int8(hub, base_model_id):
from core.inference.diffusion_transformer_quant import (
DEFAULT_MIN_LINEAR_FEATURES,
exclude_tokens_for_scheme,
)
from core.inference.video_families import detect_video_family
fam = detect_video_family(_WAN_TI2V)
src = pq.resolve_prequant_source(fam, "int8", base_repo = _WAN_TI2V)
meta = {
"scheme": "int8",
"family": fam.name,
"base_model_id": base_model_id,
"min_features": DEFAULT_MIN_LINEAR_FEATURES,
"exclude_name_tokens": list(exclude_tokens_for_scheme("int8", fam.name)),
"component": "transformer",
}
_write_safetensors(_repo_file(hub, src.location, pq.candidate_filenames_of(src)[0]), meta)
return fam
@pytest.mark.parametrize("base_model_id, usable", [(_WAN_TI2V, True), ("Other/Model", False)])
def test_a_video_plan_drops_a_hosted_denoiser_its_loader_would_refuse(hub, base_model_id, usable):
from core.inference.video import VideoBackend
from core.inference.video_denoiser_prequant import denoiser_prequant_sources
fam = _wan_int8(hub, base_model_id)
assert (denoiser_prequant_sources(fam, "int8", _WAN_TI2V) is not None) is usable
staged = VideoBackend._denoiser_prequant_source_list(fam, "int8", _WAN_TI2V)
assert bool(staged) is usable
assert VideoBackend._denoiser_prequant_covered(fam, "int8", _WAN_TI2V) is usable
assert hub.downloads == [] and hub.server.full_gets == 0
def _gated_hub(monkeypatch):
"""The fake Hub answers 401 to any HEAD without a token, as a gated repo does."""
import huggingface_hub
real = huggingface_hub.get_hf_file_metadata
def gated(
url,
token = None,
**kwargs,
):
if not token:
err = Exception("401")
err.response = types.SimpleNamespace(status_code = 401)
raise err
return real(url, token = token, **kwargs)
monkeypatch.setattr(huggingface_hub, "get_hf_file_metadata", gated)
def test_a_gated_stale_video_denoiser_is_refused_with_the_plan_token(hub, monkeypatch):
from core.inference.video import VideoBackend
_gated_hub(monkeypatch)
fam = _wan_int8(hub, "Other/Model")
assert VideoBackend._denoiser_prequant_source_list(fam, "int8", _WAN_TI2V)
assert (
VideoBackend._denoiser_prequant_source_list(fam, "int8", _WAN_TI2V, hf_token = "hf_x") == []
)
assert not VideoBackend._denoiser_prequant_covered(fam, "int8", _WAN_TI2V, hf_token = "hf_x")
listed: list = []
api = types.SimpleNamespace(
token = "hf_x",
model_info = lambda *a, **k: listed.append(a) or types.SimpleNamespace(siblings = []),
)
assert VideoBackend._denoiser_prequant_hub_files(fam, "int8", _WAN_TI2V, api) == (None, [])
assert listed == [] and hub.downloads == []
def test_planning_refuses_a_header_baked_under_another_linear_filter(hub):
fam, base = _hosted_qwen_int8(hub, _current_int8_meta(min_features = 256))
assert pq.usable_prequant_source(fam, "int8", base_repo = base) is None
assert hub.downloads == []
def test_planning_keeps_a_header_with_the_runtime_linear_filter(hub):
fam, base = _hosted_qwen_int8(hub, _current_int8_meta(min_features = 512))
assert pq.usable_prequant_source(fam, "int8", base_repo = base) is not None
@pytest.mark.parametrize(
"field, value", [("min_features", "bad"), ("require_divisible", "not-a-number")]
)
def test_a_parsed_header_with_a_malformed_field_is_refused_at_planning(hub, field, value):
fam, base = _hosted_qwen_int8(hub, _current_int8_meta(**{field: value}))
assert pq.usable_prequant_source(fam, "int8", base_repo = base) is None
src = pq.resolve_prequant_source(fam, "int8", base_repo = base)
pq._HEADER_PROBE_MEMO.clear()
reason = pq.hosted_prequant_refusal(src, "int8", base = base, min_features = 512)
assert reason is not None
assert hub.downloads == []
def test_the_safetensors_evidence_check_looks_in_the_requested_cache(hub, monkeypatch):
"""An install that reads only safetensors needs evidence a derived safetensors name is really there;
a checkpoint cached under a non-default root is that evidence."""
from core.inference.diffusion_families import detect_family
fam = detect_family("Qwen/Qwen-Image-2512")
monkeypatch.setattr(
pq,
"restricted_prequant_load_supported",
lambda scheme, name = None: name is None or str(name).endswith(".safetensors"),
)
asked: list = []
def cached(
source,
*,
cache_dir = None,
names = None,
online = None,
):
asked.append(cache_dir)
return "/live/cache/hit.safetensors" if cache_dir == "/live/cache" else None
monkeypatch.setattr(pq, "cached_checkpoint_path", cached)
src = pq.usable_prequant_source(
fam,
"int8",
base_repo = "Qwen/Qwen-Image-2512",
cache_dir = "/live/cache",
local_files_only = True,
)
assert src is not None
assert "/live/cache" in asked
def test_a_token_refusal_makes_the_hosted_prequant_unreachable(hub, monkeypatch):
"""The dense-quant prefetch counts on a prequant its anonymous candidate probe could not read; asked with
the load's token the loader would refuse it, so it is NOT reachable and the dense shards get staged."""
from core.inference.diffusion import DiffusionBackend
_gated_hub(monkeypatch)
fam, base = _hosted_qwen_int8(hub, _qwen_int8_meta(_STALE_INT8_EXCLUDES))
assert pq.usable_prequant_source(fam, "int8", base_repo = base) is not None # anonymous: unknown
kwargs = {"base_repo": base, "hf_token": "hf_x"}
assert DiffusionBackend._hosted_prequant_reachable(None, fam, "int8", kwargs) is False
assert hub.downloads == []