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: judge hosted pre-quant checkpoints before downloading them, and make the int8 fingerprint torchao-version-neutral (#13339)

Daniel Han27626031e65d
diff --git a/scripts/build_prequant_checkpoint.py b/scripts/build_prequant_checkpoint.py
index 3906130f3a3..cd70badd2ff 100644
--- a/scripts/build_prequant_checkpoint.py
+++ b/scripts/build_prequant_checkpoint.py
@@ -417,9 +417,10 @@ def main(argv = None) -> int:
"torchao_version": getattr(torchao, "__version__", "?"),
"diffusers_version": diffusers.__version__,
}
- from core.inference.diffusion_prequant import packed_weight_fingerprint
+ from core.inference.diffusion_prequant import canonical_weight_fingerprint
- metadata["fingerprint"] = packed_weight_fingerprint(state_dict)
+ # Version-neutral, so a file built on one torchao generation verifies on every other.
+ metadata["fingerprint"] = canonical_weight_fingerprint(state_dict)
# fp8 granularity: lets the loader reject a stale per-tensor checkpoint (runtime needs per-row).
if scheme == TQ_FP8:
metadata["fp8_granularity"] = FP8_GRANULARITY
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 7babce3cf48..70f6cb8708e 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -2921,8 +2921,22 @@ class DiffusionBackend:
scheme,
path_override = kwargs.get("transformer_prequant_path"),
base_repo = kwargs.get("base_repo"),
+ local_files_only = bool(kwargs.get("local_files_only")),
+ hf_token = kwargs.get("hf_token"),
+ cache_dir = hub_cache_dir(),
)
- if source is None or getattr(source, "kind", None) != "repo":
+ if source is None:
+ # With the load's token the loader would refuse it, so stage dense; only if a source resolves at all.
+ return (
+ resolve_prequant_source(
+ fam,
+ scheme,
+ path_override = kwargs.get("transformer_prequant_path"),
+ base_repo = kwargs.get("base_repo"),
+ )
+ is None
+ )
+ if getattr(source, "kind", None) != "repo":
return True
if prequant_checkpoint_cached(
source,
@@ -4292,6 +4306,8 @@ class DiffusionBackend:
rung,
base_repo = base,
path_override = transformer_prequant_path,
+ local_files_only = local_files_only,
+ cache_dir = hub_cache_dir(),
)
if source is None:
continue
@@ -4382,6 +4398,9 @@ class DiffusionBackend:
planned,
base_repo = kwargs.get("base_repo"),
path_override = kwargs.get("transformer_prequant_path"),
+ local_files_only = bool(kwargs.get("local_files_only")),
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
)
return self._prequant_source_hub_entry(source, hf_token, scheme = planned)
raw = kwargs.get("transformer_quant")
@@ -4437,6 +4456,9 @@ class DiffusionBackend:
scheme,
path_override = kwargs.get("transformer_prequant_path"),
base_repo = kwargs.get("base_repo"),
+ local_files_only = bool(kwargs.get("local_files_only")),
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
)
if source is None and auto:
@@ -4455,6 +4477,9 @@ class DiffusionBackend:
retry,
path_override = kwargs.get("transformer_prequant_path"),
base_repo = kwargs.get("base_repo"),
+ local_files_only = bool(kwargs.get("local_files_only")),
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
)
# The retry REPLACED the pick, so the readability question below is about
# the rung actually being planned, not the one the ladder started on.
@@ -4552,7 +4577,13 @@ class DiffusionBackend:
if _has_active_lora(loras):
return False
source = usable_prequant_source(
- fam, TQ_NVFP4, path_override = path_override, base_repo = base
+ fam,
+ TQ_NVFP4,
+ path_override = path_override,
+ base_repo = base,
+ local_files_only = local_files_only,
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
)
if source is None:
return False
@@ -6377,6 +6408,9 @@ class DiffusionBackend:
TQ_NVFP4,
path_override = transformer_prequant_path,
base_repo = base,
+ local_files_only = local_files_only,
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
)
is None,
)
@@ -6712,6 +6746,9 @@ class DiffusionBackend:
scheme,
path_override = transformer_prequant_path,
base_repo = base,
+ local_files_only = local_files_only,
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
)
if scheme is not None
else None
@@ -7229,6 +7266,9 @@ class DiffusionBackend:
pipeline_seed_scheme,
base_repo = base,
path_override = transformer_prequant_path,
+ local_files_only = local_files_only,
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
),
next(iter(seeded.values()), None),
)
diff --git a/studio/backend/core/inference/diffusion_denoiser_prequant.py b/studio/backend/core/inference/diffusion_denoiser_prequant.py
index cbda6b57ce3..4462e6f343b 100644
--- a/studio/backend/core/inference/diffusion_denoiser_prequant.py
+++ b/studio/backend/core/inference/diffusion_denoiser_prequant.py
@@ -35,16 +35,28 @@ def denoiser_prequant_source(
*,
base_repo: Optional[str],
path_override: Optional[str] = None,
+ local_files_only: bool = False,
+ hf_token: Optional[str] = None,
+ cache_dir: Optional[str] = None,
) -> Optional[Any]:
"""The ``PrequantSource`` a pipeline pick would seed its denoiser from, or None.
``usable_prequant_source``, not ``resolve_prequant_source``: an override the loader would refuse
- must read as no source here. Never raises."""
+ must read as no source here. ``local_files_only`` / ``hf_token`` / ``cache_dir`` reach its hosted
+ header probe. Never raises."""
wanted = (scheme or "").strip().lower()
if wanted in ("", "auto", "off", "none") or wanted == PIPELINE_SEED_DECLINED:
return None
try:
from .diffusion_prequant import usable_prequant_source
- return usable_prequant_source(fam, wanted, path_override = path_override, base_repo = base_repo)
+ return usable_prequant_source(
+ fam,
+ wanted,
+ path_override = path_override,
+ base_repo = base_repo,
+ local_files_only = local_files_only,
+ hf_token = hf_token,
+ cache_dir = cache_dir,
+ )
except Exception: # noqa: BLE001 -- an unanswerable registry keeps the released bf16 denoiser
return None
@@ -60,7 +72,14 @@ def denoiser_prequant_cached(
"""Whether the artifact this seed would open is ALREADY on disk, answered without a Hub call.
The offline twin of the ``model_info`` probe the online plan makes, so a load that may not
download can still seed from the cache an earlier load built. Never raises."""
- source = denoiser_prequant_source(fam, scheme, base_repo = base_repo, path_override = path_override)
+ source = denoiser_prequant_source(
+ fam,
+ scheme,
+ base_repo = base_repo,
+ path_override = path_override,
+ local_files_only = True,
+ cache_dir = cache_dir,
+ )
if source is None:
return False
if getattr(source, "kind", None) != "repo":
@@ -98,7 +117,13 @@ def denoiser_prequant_pipe_kwargs(
if not pipeline_seed_supported(fam):
return {}
source = denoiser_prequant_source(
- fam, scheme, base_repo = base_repo, path_override = path_override
+ fam,
+ scheme,
+ base_repo = base_repo,
+ path_override = path_override,
+ local_files_only = local_files_only,
+ hf_token = hf_token,
+ cache_dir = cache_dir,
)
if source is None:
return {}
diff --git a/studio/backend/core/inference/diffusion_fast_load.py b/studio/backend/core/inference/diffusion_fast_load.py
index f6cf8577e68..8df29698729 100644
--- a/studio/backend/core/inference/diffusion_fast_load.py
+++ b/studio/backend/core/inference/diffusion_fast_load.py
@@ -320,6 +320,9 @@ def start_load_prefetch(
prequant_scheme,
base_repo = prequant_base_repo or base,
path_override = prequant_path_override,
+ # Only a cached file is prefetched, so its header is judged from the cache, never the Hub.
+ local_files_only = True,
+ cache_dir = cache_dir,
)
if source is not None:
location = None
diff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.py
index 7158bb2dde3..d91b71d9b26 100644
--- a/studio/backend/core/inference/diffusion_prequant.py
+++ b/studio/backend/core/inference/diffusion_prequant.py
@@ -1262,7 +1262,11 @@ def declares_nvfp4_checkpoint(model_path: Optional[str]) -> bool:
return raw.rstrip("/\\").lower().endswith("-nvfp4")
+# Legacy (read-only): hashes torchao internals, so v1 only matches the torchao generation that wrote it.
FINGERPRINT_ALGO = "md5-packed-v1"
+# Stored under ``canonical_modules``, not ``modules``: older loaders would refuse it as a v1 mismatch.
+CANONICAL_FINGERPRINT_ALGO = "md5-canonical-v2"
+CANONICAL_FINGERPRINT_KEY = "canonical_modules"
# Payload attrs per torchao class NAME, hash order; unlisted reads "not covered", never "equal".
_FINGERPRINT_PAYLOAD: dict = {
@@ -1345,6 +1349,187 @@ def packed_weight_fingerprint(state_dict: Any, *, select: Any = None) -> dict:
}
+# torchao class name -> (role, attr); ("inner", attr) unwraps. Roles are version neutral (``q`` = int_data / qdata).
+_CANONICAL_PARTS: dict = {
+ "LinearActivationQuantizedTensor": (("inner", "original_weight_tensor"),),
+ "AffineQuantizedTensor": (("inner", "tensor_impl"),),
+ "PlainAQTTensorImpl": (("q", "int_data"), ("scale", "scale"), ("zero_point", "zero_point")),
+ "Int8Tensor": (
+ ("q", "qdata"),
+ ("scale", "scale"),
+ ("zero_point", "zero_point"),
+ ("act_quant_scale", "act_quant_scale"),
+ ("act_quant_zero_point", "act_quant_zero_point"),
+ ("act_pre_scale", "act_pre_scale"),
+ ),
+ "Float8Tensor": (("q", "qdata"), ("scale", "scale")),
+ "NVFP4Tensor": (("q", "qdata"), ("scale", "scale"), ("per_tensor_scale", "per_tensor_scale")),
+ "MXTensor": (("q", "qdata"), ("scale", "scale")),
+}
+_CANONICAL_ROLE_ORDER = (
+ "q",
+ "scale",
+ "zero_point",
+ "per_tensor_scale",
+ "act_quant_scale",
+ "act_quant_zero_point",
+ "act_pre_scale",
+)
+_ZERO_POINT_ROLES = ("zero_point", "act_quant_zero_point")
+
+
+def _canonical_parts(tensor: Any, depth: int = 0) -> Optional[dict]:
+ spec = _CANONICAL_PARTS.get(type(tensor).__name__)
+ if spec is None or depth > 4:
+ return None
+ parts: dict = {}
+ for role, attr in spec:
+ value = getattr(tensor, attr, None)
+ if value is None:
+ continue
+ if role == "inner":
+ inner = _canonical_parts(value, depth + 1)
+ if inner is None:
+ return None
+ parts.update(inner)
+ else:
+ parts[role] = value
+ return parts if "q" in parts else None
+
+
+def _all_zero(value: Any, torch: Any) -> bool:
+ try:
+ return not bool(torch.any(value.detach() != 0))
+ except Exception: # noqa: BLE001 - unknown: hash it
+ return False
+
+
+def _canonical_bytes(role: str, value: Any, torch: Any) -> bytes:
+ """Version-stable bytes: ``q`` as stored; others flattened to float32 (exact for stored scales) / int64 zero point."""
+ t = value.detach()
+ if role == "q":
+ head = f"q:{str(t.dtype).replace('torch.', '')}:{tuple(t.shape)}".encode("utf-8")
+ return head + _packed_bytes(t, torch)
+ t = t.reshape(-1)
+ if role in _ZERO_POINT_ROLES:
+ t = t.to(torch.int64)
+ elif t.is_floating_point() and t.dtype is not torch.float64:
+ t = t.to(torch.float32)
+ head = f"{role}:{str(t.dtype).replace('torch.', '')}:{t.numel()}".encode("utf-8")
+ return head + _packed_bytes(t, torch)
+
+
+def canonical_weight_digest(tensor: Any) -> Optional[str]:
+ """Version-neutral md5 of one quantized weight (None if unmodelled); an all-zero zero point equals none."""
+ import hashlib
+
+ import torch
+
+ parts = _canonical_parts(tensor)
+ if parts is None:
+ return None
+ digest = hashlib.md5()
+ for role in _CANONICAL_ROLE_ORDER:
+ value = parts.get(role)
+ if value is None or (role in _ZERO_POINT_ROLES and _all_zero(value, torch)):
+ continue
+ digest.update(_canonical_bytes(role, value, torch))
+ return digest.hexdigest()
+
+
+def canonical_weight_fingerprint(state_dict: Any, *, select: Any = None) -> dict:
+ modules: dict = {}
+ skipped: list = []
+ items = state_dict.items() if hasattr(state_dict, "items") else ()
+ for key, tensor in items:
+ if key != "weight" and not str(key).endswith(".weight"):
+ continue
+ if select is not None and not select(str(key)):
+ continue
+ try:
+ value = canonical_weight_digest(tensor)
+ except Exception: # noqa: BLE001 -- an unreadable payload is uncovered, never a raise
+ value = None
+ if value is None:
+ skipped.append(key)
+ else:
+ modules[key] = value
+ return {
+ "algo": CANONICAL_FINGERPRINT_ALGO,
+ "count": len(modules),
+ CANONICAL_FINGERPRINT_KEY: modules,
+ "skipped": skipped,
+ }
+
+
+_V1_INT8_PREFIXES = (
+ ("original_weight_tensor", "tensor_impl", "int_data"), # torchao <= 0.17
+ ("qdata",), # torchao >= 0.18 Int8Tensor
+)
+
+
+def _v1_cross_generation_match(
+ tensor: Any,
+ recorded: str,
+ hint: Optional[list] = None,
+) -> bool:
+ """Whether v1 digest ``recorded`` matches this int8 weight in any torchao generation's layout.
+
+ Every variant hashes the full ``q`` and scale bytes, so changed values still fail. ``hint`` caches
+ the last matching layout to try first."""
+ import hashlib
+
+ import torch
+
+ parts = _canonical_parts(tensor)
+ if parts is None or set(parts) - {"q", "scale", "zero_point"} or "scale" not in parts:
+ return False
+ q, scale = parts["q"], parts["scale"].detach()
+ if q.dtype is not torch.int8 or q.dim() != 2:
+ return False
+ zp = parts.get("zero_point")
+ if zp is not None and not _all_zero(zp, torch):
+ return False
+ n = q.shape[0]
+ scales = {"stored": scale}
+ for dtype in (torch.float32, torch.bfloat16):
+ if scale.dtype is not dtype:
+ cast = scale.to(dtype)
+ if torch.equal(cast.to(scale.dtype), scale):
+ scales[str(dtype)] = cast
+ zero_points = {"none": None, "int8_zeros": torch.zeros(n, 1, dtype = torch.int8)}
+ if zp is not None:
+ zero_points["stored"] = zp
+ layouts = [
+ (p, sk, zk) for p in range(len(_V1_INT8_PREFIXES)) for sk in scales for zk in zero_points
+ ]
+ if hint and hint[0] in layouts:
+ layouts.remove(hint[0])
+ layouts.insert(0, hint[0])
+ q_bytes = _packed_bytes(q, torch)
+ bases: dict = {}
+ for layout in layouts:
+ prefix, sk, zk = layout
+ if prefix not in bases:
+ base = hashlib.md5()
+ for name in _V1_INT8_PREFIXES[prefix]:
+ base.update(name.encode("utf-8"))
+ base.update(q_bytes)
+ bases[prefix] = base
+ digest = bases[prefix].copy()
+ digest.update(b"scale")
+ digest.update(_packed_bytes(scales[sk], torch))
+ z = zero_points[zk]
+ if z is not None:
+ digest.update(b"zero_point")
+ digest.update(_packed_bytes(z, torch))
+ if digest.hexdigest() == recorded:
+ if hint is not None:
+ hint[:] = [layout]
+ return True
+ return False
+
+
FINGERPRINT_MODE_ENV = "UNSLOTH_PREQUANT_FINGERPRINT"
FINGERPRINT_MODES = ("full", "sample", "off")
FINGERPRINT_SAMPLE_RATE = 8
@@ -1426,8 +1611,10 @@ def _verify_packed_fingerprint(
A full pass is remembered per file (real path, size, mtime, recorded fingerprint) in the Studio cache, so later
loads of the same unchanged file skip the md5 of every weight; any change to the file checks in full again."""
block = (metadata or {}).get("fingerprint")
- expected = (block or {}).get("modules") if isinstance(block, dict) else None
- if not expected:
+ block = block if isinstance(block, dict) else {}
+ canonical = bool(block.get(CANONICAL_FINGERPRINT_KEY))
+ expected = block.get(CANONICAL_FINGERPRINT_KEY) if canonical else block.get("modules")
+ if not expected or not isinstance(expected, dict):
return True
mode = _fingerprint_mode()
marker = _verified_marker(path, expected) if path is not None and mode == "full" else None
@@ -1445,13 +1632,16 @@ def _verify_packed_fingerprint(
)
return True
try:
- actual = (
- packed_weight_fingerprint(
- state_dict,
- select = _fingerprint_sampled if mode == "sample" else None,
- ).get("modules")
- or {}
- )
+ select = _fingerprint_sampled if mode == "sample" else None
+ if canonical:
+ actual = (
+ canonical_weight_fingerprint(state_dict, select = select).get(
+ CANONICAL_FINGERPRINT_KEY
+ )
+ or {}
+ )
+ else:
+ actual = packed_weight_fingerprint(state_dict, select = select).get("modules") or {}
except Exception as exc: # noqa: BLE001 -- an uncomputable fingerprint checks nothing
_warn(logger, "fingerprint", exc)
return True
@@ -1467,14 +1657,31 @@ def _verify_packed_fingerprint(
return True
checked = [k for k in expected if mode != "sample" or _fingerprint_sampled(k)]
differing = sorted(k for k in checked if actual.get(k) != expected[k])
+ reencoded = 0
+ if differing and not canonical and hasattr(state_dict, "get"):
+ still = []
+ hint: list = []
+ for key in differing:
+ try:
+ crossed = _v1_cross_generation_match(state_dict.get(key), expected[key], hint)
+ except Exception: # noqa: BLE001 -- not re-encodable: a real mismatch
+ crossed = False
+ if not crossed:
+ still.append(key)
+ reencoded = len(differing) - len(still)
+ differing = still
counted = mode != "sample" and len(actual) != len(expected)
if not differing and not counted:
if logger is not None:
logger.info(
- "diffusion.prequant: fingerprint verified (%d of %d quantized weights, %s)",
+ "diffusion.prequant: fingerprint verified (%d of %d quantized weights, %s, %s%s)",
len(checked),
len(expected),
mode,
+ CANONICAL_FINGERPRINT_ALGO if canonical else FINGERPRINT_ALGO,
+ f"; {reencoded} matched in another torchao generation's layout"
+ if reencoded
+ else "",
)
_remember_verified(marker)
return True
@@ -1492,12 +1699,281 @@ def _verify_packed_fingerprint(
return False
+HEADER_PROBE_ENV = "UNSLOTH_PREQUANT_HEADER_PROBE"
+_HEADER_PROBE_TTL_S = 600.0
+# Keyed by request values, so bounded: memo drops expired then LRU entries, the said-set its oldest.
+_HEADER_PROBE_MAX = 256
+_HEADER_PROBE_MEMO: dict = {}
+_HEADER_PROBE_SAID: dict = {}
+_HEADER_PROBE_LOCK = _threading.Lock()
+
+
+def _memo_get(key: Any, now: float) -> Any:
+ """The live memo entry for ``key`` (refreshed as most recent), or None; an expired one is dropped.
+ Offline-cache verdicts (``key[0] == "local"``) never expire: the file under them cannot change
+ without changing the key. Caller holds the lock."""
+ hit = _HEADER_PROBE_MEMO.pop(key, None)
+ if hit is None:
+ return None
+ if key[0] != "local" and now - hit[0] >= _HEADER_PROBE_TTL_S:
+ return None
+ _HEADER_PROBE_MEMO[key] = hit
+ return hit
+
+
+def _memo_put(key: Any, value: Any, now: float) -> None:
+ """Insert ``key``, then trim expired entries and the oldest beyond ``_HEADER_PROBE_MAX``. Caller holds the lock."""
+ _HEADER_PROBE_MEMO.pop(key, None)
+ _HEADER_PROBE_MEMO[key] = value
+ for old in [
+ k
+ for k, (at, _) in _HEADER_PROBE_MEMO.items()
+ if k[0] != "local" and now - at >= _HEADER_PROBE_TTL_S
+ ]:
+ del _HEADER_PROBE_MEMO[old]
+ while len(_HEADER_PROBE_MEMO) > _HEADER_PROBE_MAX:
+ del _HEADER_PROBE_MEMO[next(iter(_HEADER_PROBE_MEMO))]
+
+
+def _token_fingerprint(token: Optional[str]) -> str:
+ """A short one-way tag for ``token`` (empty when none), so memo keys never hold the secret."""
+ if not token:
+ return ""
+ import hashlib
+
+ return hashlib.sha256(str(token).encode("utf-8", "replace")).hexdigest()[:16]
+
+
+def _said_first(said: Any) -> bool:
+ """Whether ``said`` is new (warn) rather than a repeat (info); remembers at most ``_HEADER_PROBE_MAX``.
+ Caller holds the lock."""
+ first = said not in _HEADER_PROBE_SAID
+ _HEADER_PROBE_SAID.pop(said, None)
+ _HEADER_PROBE_SAID[said] = True
+ while len(_HEADER_PROBE_SAID) > _HEADER_PROBE_MAX:
+ del _HEADER_PROBE_SAID[next(iter(_HEADER_PROBE_SAID))]
+ return first
+
+
+def _cached_snapshot_current(repo_id: str, local: str, token: Optional[str]) -> Optional[bool]:
+ """Whether the Hub still serves the cached ``local`` snapshot of its file: True / False, or None when
+ unanswerable (not a Hub-cache path, no network, no etag nor commit), which keeps the cached verdict.
+ One HEAD, no range read. The blob name is the file's etag and the snapshot directory its commit, so
+ either matching proves the cache is what ``hf_hub_download`` would open; an unrelated commit to the
+ repo leaves the etag equal and costs no re-read."""
+ import os
+
+ parts = os.path.normpath(local).split(os.sep)
+ if len(parts) < 3 or parts[-3] != "snapshots":
+ return None
+ commit, name = parts[-2], parts[-1]
+ blob = os.path.basename(os.path.realpath(local))
+ from .prequant_header_probe import hub_file_revision
+
+ current = hub_file_revision(repo_id, name, token = token)
+ if current is None or current == "missing":
+ return None if current is None else False
+ etag, hub_commit = current
+ if (etag and etag == blob) or (hub_commit and hub_commit == commit):
+ return True
+ if etag or hub_commit:
+ return False
+ return None
+
+
+class _CollectWarnings:
+ def __init__(self) -> None:
+ self.lines: list = []
+
+ def warning(self, fmt: str, *args: Any) -> None:
+ self.lines.append(fmt % args if args else fmt)
+
+ def info(self, *args: Any, **kwargs: Any) -> None:
+ pass
+
+ debug = info
+
+
+def _probe_logger(logger: Any) -> Any:
+ if logger is not None:
+ return logger
+ try:
+ from loggers import get_logger
+ return get_logger(__name__)
+ except Exception: # noqa: BLE001 - no Studio logger: the stdlib one
+ import logging
+ return logging.getLogger(__name__)
+
+
+def hosted_prequant_refusal(
+ source: Any,
+ scheme: str,
+ *,
+ base: Optional[str] = None,
+ min_features: Optional[int] = None,
+ fast_accum: Optional[bool] = None,
+ component: Optional[str] = None,
+ hf_token: Optional[str] = None,
+ cache_dir: Optional[str] = None,
+ local_files_only: bool = False,
+ logger: Any = None,
+) -> Optional[str]:
+ """Why hosted ``source`` would be refused, from its header alone (no weight download).
+
+ Only a ``.safetensors`` checkpoint has a header this reads. The candidate names are walked in the
+ resolver's order (safetensors ahead of the pickle), and when the first one that exists is a
+ ``.pt`` the answer is None: a pickle is never opened here, so it is judged by the loader after its
+ download, as before. A parsed header whose typed fields cannot be validated IS a refusal, since
+ the loader would refuse it too.
+
+ None when usable or unreadable: unknown is never a refusal. Never raises."""
+ import os
+ import time
+
+ if (os.environ.get(HEADER_PROBE_ENV) or "").strip().lower() in ("0", "false", "no", "off"):
+ return None
+ if getattr(source, "kind", None) != "repo" or not scheme:
+ return None
+ saved_failure = getattr(_LAST_FAILURE, "text", None)
+ try:
+ names = [
+ n
+ for n in candidate_filenames_of(source)
+ if restricted_prequant_load_supported(scheme, n)
+ ]
+ if not names:
+ return None
+ local = cached_checkpoint_path(source, cache_dir = cache_dir, names = names)
+ # A ``scoped_local_files_only`` load is offline too: a cache miss must not become Hub requests.
+ offline = bool(local_files_only or _LOCAL_FILES_ONLY.get() or hub_offline())
+ if local is None and offline:
+ return None
+ request = (scheme, base or "", min_features, fast_accum, component or "")
+ # Keyed by credentials: an anonymous 401 (unknown) must not stand in for the authenticated probe.
+ auth = _token_fingerprint(hf_token)
+ if local is not None:
+ try:
+ st = os.stat(local)
+ # Offline the cached file is what loads; online it may have been re-uploaded, so revalidate.
+ key = (
+ "local" if offline else "cached",
+ os.path.realpath(local),
+ st.st_size,
+ st.st_mtime_ns,
+ request,
+ "" if offline else auth,
+ )
+ except OSError:
+ return None
+ else:
+ key = ("hub", source.location, tuple(names), request, auth)
+ now = time.monotonic()
+ with _HEADER_PROBE_LOCK:
+ hit = _memo_get(key, now)
+ if hit is not None:
+ return hit[1]
+
+ from .prequant_header_probe import read_hub_checkpoint_header, read_local_checkpoint_header
+
+ header, name = None, None
+ # False when the Hub could not answer (401/403, network): not memoised, so the next probe retries.
+ answered = True
+ hub_names = names
+ from .prequant_safetensors import is_safetensors_checkpoint
+
+ # Only a safetensors header is ever read, so a cached pickle is "unknown" and not worth a HEAD.
+ if local is not None and not offline and is_safetensors_checkpoint(local):
+ if _cached_snapshot_current(source.location, local, hf_token) is False:
+ # Judge what the download would fetch; a name now 404ing falls through to the next one.
+ cached_name = os.path.basename(local)
+ at = names.index(cached_name) if cached_name in names else -1
+ hub_names, local = (names[at:] if at >= 0 else [cached_name]), None
+ if local is not None:
+ header, name = read_local_checkpoint_header(local), os.path.basename(local)
+ else:
+ for candidate in hub_names:
+ header, exists = read_hub_checkpoint_header(
+ source.location, candidate, token = hf_token
+ )
+ if exists is False:
+ continue
+ answered = exists is not None
+ name = candidate
+ break
+ reason = None
+ if header is not None:
+ collect = _CollectWarnings()
+ try:
+ if not isinstance(header["metadata"], dict):
+ raise ValueError("metadata is not a JSON object")
+ ok = _validate_checkpoint(
+ {"format": header["format"], "metadata": header["metadata"]},
+ scheme,
+ base or "",
+ collect,
+ min_features = min_features,
+ fast_accum = fast_accum,
+ component = component,
+ metadata_only = True,
+ )
+ except Exception as exc: # noqa: BLE001 - a PARSED header the loader cannot validate
+ # The loader raises on it too, so this is a refusal, not "unknown".
+ ok = False
+ collect.lines.insert(
+ 0, f"malformed checkpoint metadata ({type(exc).__name__}: {exc})"[:300]
+ )
+ if not ok:
+ reason = (collect.lines[0] if collect.lines else "incompatible metadata").replace(
+ "diffusion.prequant: ", ""
+ )
+ said = (source.location, name, reason)
+ with _HEADER_PROBE_LOCK:
+ first = _said_first(said)
+ where = (
+ "cached file"
+ if local is not None
+ else f"{(header.get('size') or 0) / 1e9:.1f} GB file, not downloaded"
+ )
+ (_probe_logger(logger).warning if first else _probe_logger(logger).info)(
+ "diffusion.prequant: skipping hosted %s checkpoint %s/%s (%s; read %d header "
+ "bytes): %s; using the fallback path instead",
+ scheme,
+ source.location,
+ name,
+ where,
+ int(header.get("bytes_read") or 0),
+ reason,
+ )
+ with _HEADER_PROBE_LOCK:
+ if answered:
+ _memo_put(key, (now, reason), now)
+ return reason
+ except Exception: # noqa: BLE001 - a probe that cannot answer leaves today's behaviour
+ return None
+ finally:
+ _LAST_FAILURE.text = saved_failure
+
+
+def _planning_min_features(min_features: Optional[int]) -> Optional[int]:
+ if min_features is not None:
+ return min_features
+ try:
+ from .diffusion_transformer_quant import DEFAULT_MIN_LINEAR_FEATURES
+ return DEFAULT_MIN_LINEAR_FEATURES
+ except Exception: # noqa: BLE001 - no quant module: skip the check, as before
+ return None
+
+
def usable_prequant_source(
fam: Any,
scheme: str,
*,
path_override: Optional[str] = None,
base_repo: Optional[str] = None,
+ local_files_only: bool = False,
+ hf_token: Optional[str] = None,
+ cache_dir: Optional[str] = None,
+ min_features: Optional[int] = None,
) -> Optional[PrequantSource]:
"""``resolve_prequant_source``, but a local path counts only when the loader would accept it:
inside the allowlist AND present on disk AND baked for THIS scheme. Otherwise resolves to None
@@ -1517,6 +1993,13 @@ def usable_prequant_source(
primary artifact is safetensors is usable on an install that could not open a pickle at all, and
resolving first is what lets the source say so. Any one loadable name is enough, since the
resolver tries them in order and the first that exists wins.
+
+ ``local_files_only`` / ``hf_token`` / ``cache_dir`` are the load's own, handed to the hosted header
+ probe so planning asks exactly what the loader will: an offline load makes no Hub request here
+ either, and a gated repo is read with the caller's token. ``base_repo`` doubles as the base the
+ probe checks ``base_model_id`` against, as ``load_prequantized_transformer`` does. ``min_features``
+ defaults to ``DEFAULT_MIN_LINEAR_FEATURES``, the Linear filter every loader of these checkpoints
+ enforces, so a header baked under another filter is refused here rather than after its download.
"""
src = resolve_prequant_source(fam, scheme, path_override = path_override, base_repo = base_repo)
if src is None:
@@ -1548,7 +2031,8 @@ 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, online = False) is None
+ and cached_checkpoint_path(src, cache_dir = cache_dir, names = readable, online = False)
+ is None
):
return None
if src.kind == "path":
@@ -1566,6 +2050,21 @@ def usable_prequant_source(
return None
except Exception: # noqa: BLE001 -- unreadable: the scheme check above already decided
pass
+ # Refused metadata = no source, judged with the loader's base and fetch rules, so planning stages dense.
+ if (
+ src.kind == "repo"
+ and hosted_prequant_refusal(
+ src,
+ scheme,
+ base = base_repo,
+ min_features = _planning_min_features(min_features),
+ hf_token = hf_token,
+ cache_dir = cache_dir,
+ local_files_only = local_files_only,
+ )
+ is not None
+ ):
+ return None
return src
@@ -1771,6 +2270,23 @@ def load_prequantized_transformer(
)
return None
+ if source.kind == "repo":
+ refusal = hosted_prequant_refusal(
+ source,
+ scheme,
+ base = base,
+ min_features = min_features,
+ fast_accum = fast_accum,
+ component = component,
+ hf_token = hf_token,
+ cache_dir = cache_dir,
+ local_files_only = local_files_only,
+ logger = logger,
+ )
+ if refusal is not None:
+ _LAST_FAILURE.text = _ABS_PATH.sub("", f"ValueError: {refusal}")[:300]
+ return None
+
path = _resolve_checkpoint_path(
source,
hf_token,
@@ -2436,12 +2952,14 @@ def _validate_checkpoint(
min_features: Optional[int] = None,
fast_accum: Optional[bool] = None,
component: Optional[str] = None,
+ metadata_only: bool = False,
) -> bool:
- """Reject a wrong format / scheme / base / filter / denoiser; absent ``min_features`` / ``fast_accum`` pass."""
+ """Reject a wrong format / scheme / base / filter / denoiser; absent ``min_features`` / ``fast_accum`` pass.
+ ``metadata_only`` skips the checks that need tensors."""
if not isinstance(ckpt, dict) or ckpt.get("format") not in PREQUANT_FORMATS:
_warn(logger, scheme, ValueError("unrecognised pre-quant checkpoint format"))
return False
- if "state_dict" not in ckpt:
+ if "state_dict" not in ckpt and not metadata_only:
_warn(logger, scheme, ValueError("pre-quant checkpoint has no state_dict"))
return False
meta = ckpt.get("metadata") or {}
@@ -2475,7 +2993,11 @@ def _validate_checkpoint(
# predates any metadata field we could stamp -- and "absent is accepted for back-compat", the convention every
# check above follows, is exactly wrong here. Reading the tensors is fail-closed and needs no format bump.
# Unless the floor is the only difference: it is not weight data, so ``_repair_legacy_checkpoint`` writes it in.
- if holds_fp8 and not _fp8_activation_floor_present(ckpt.get("state_dict"), logger, warn = False):
+ if (
+ holds_fp8
+ and not metadata_only
+ and not _fp8_activation_floor_present(ckpt.get("state_dict"), logger, warn = False)
+ ):
if not _fp8_activation_floor_restorable(ckpt.get("state_dict")):
_fp8_activation_floor_present(ckpt.get("state_dict"), logger)
return False
@@ -2525,7 +3047,9 @@ def _validate_checkpoint(
logger,
scheme,
ValueError(
- f"checkpoint exclude_name_tokens {ckpt_excludes!r} do not cover the runtime {expected!r}"
+ "checkpoint built under an older exclusion list (missing "
+ f"{sorted(set(expected) - set(ckpt_excludes or ())) if isinstance(ckpt_excludes, (list, tuple)) else ckpt_excludes!r}"
+ f"): checkpoint exclude_name_tokens {ckpt_excludes!r} do not cover the runtime {expected!r}"
),
)
return False
diff --git a/studio/backend/core/inference/prequant_header_probe.py b/studio/backend/core/inference/prequant_header_probe.py
new file mode 100644
index 00000000000..195722bc297
--- /dev/null
+++ b/studio/backend/core/inference/prequant_header_probe.py
@@ -0,0 +1,228 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Read a SAFETENSORS pre-quant checkpoint's ``format`` + ``metadata`` without reading its weights.
+
+A ``.pt`` (pickle) is never opened. Readers never raise and fail open (None = unknown).
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+import threading
+import time
+from typing import Any, Callable, Optional
+
+# Above this many bytes read, the probe gives up (answers None) rather than turn into a download.
+MAX_PROBE_BYTES = 64 * 1024 * 1024
+TIMEOUT_SECONDS = 20.0
+
+ReadRange = Callable[[int, int], bytes]
+
+
+class _ProbeBudgetExceeded(Exception):
+ pass
+
+
+# Bounded by bytes AND structure before ``json.loads``; real headers are <= 2.9 MB, so >= 4x headroom.
+MAX_SAFETENSORS_HEADER_BYTES = 16 * 1024 * 1024
+MAX_JSON_STRUCTURE = 1_000_000
+
+
+def _json_within(raw: Any) -> bool:
+ """Whether ``raw`` (bytes or str) is small enough in bytes and structure to hand to ``json.loads``.
+ Counted on the raw text, so a nested JSON string inside it is counted too, before either parse."""
+ if isinstance(raw, str):
+ raw = raw.encode("utf-8", "surrogatepass")
+ if len(raw) > MAX_SAFETENSORS_HEADER_BYTES:
+ return False
+ total = 0
+ for mark in (b"{", b"[", b",", b":"):
+ total += raw.count(mark)
+ if total > MAX_JSON_STRUCTURE:
+ return False
+ return True
+
+
+def _from_safetensors(read_range: ReadRange, size: int) -> Optional[dict]:
+ if size < 8:
+ return None
+ (length,) = struct.unpack("<Q", read_range(0, 7))
+ if length <= 0 or length > MAX_SAFETENSORS_HEADER_BYTES or 8 + length > size:
+ return None
+ raw = read_range(8, 8 + length - 1)
+ if not _json_within(raw):
+ return None
+ header = json.loads(raw.decode("utf-8"))
+ extra = header.get("__metadata__") if isinstance(header, dict) else None
+ if not isinstance(extra, dict):
+ return None
+ from .prequant_safetensors import UNSLOTH_FORMAT_KEY, UNSLOTH_METADATA_KEY
+
+ fmt = extra.get(UNSLOTH_FORMAT_KEY)
+ inner = extra.get(UNSLOTH_METADATA_KEY) or "null"
+ if not isinstance(inner, str) or not _json_within(inner):
+ return None
+ meta = json.loads(inner)
+ if not isinstance(fmt, str):
+ return None
+ # An Unsloth header whose metadata is not an object is malformed, not unreadable: the loader refuses it.
+ return {"format": fmt, "metadata": meta, "container": "safetensors"}
+
+
+def read_checkpoint_header(name: str, read_range: ReadRange, size: int) -> Optional[dict]:
+ """``{"format", "metadata", "container", "bytes_read"}`` of a checkpoint named ``name``, or None.
+
+ Only a ``.safetensors`` name is read; any other is None with nothing read. Never raises; reads at
+ most ``MAX_PROBE_BYTES``."""
+ counted = [0]
+
+ def _counted(start: int, end: int) -> bytes:
+ if counted[0] + (end - start + 1) > MAX_PROBE_BYTES:
+ raise _ProbeBudgetExceeded("probe budget exceeded")
+ data = read_range(start, end)
+ counted[0] += len(data)
+ return data
+
+ if not str(name).lower().endswith(".safetensors"):
+ # A pickle checkpoint is never read here: unknown, without a single byte fetched.
+ return None
+ try:
+ out = _from_safetensors(_counted, size)
+ except Exception: # noqa: BLE001 - unreadable is "unknown", never "incompatible"
+ return None
+ if out is not None:
+ out["bytes_read"] = counted[0]
+ return out
+
+
+def read_local_checkpoint_header(path: str) -> Optional[dict]:
+ import os
+ try:
+ size = os.path.getsize(path)
+ handle = open(path, "rb")
+ except (OSError, ValueError):
+ return None
+ try:
+
+ def _read(start: int, end: int) -> bytes:
+ handle.seek(start)
+ return handle.read(end - start + 1)
+
+ return read_checkpoint_header(path, _read, size)
+ finally:
+ handle.close()
+
+
+def _hub_range_reader(url: str, headers: dict, deadline: float) -> ReadRange:
+ """Ranged GETs against ``url``; anything but a 206 of exactly the asked length raises."""
+ from huggingface_hub.utils import get_session
+
+ from .diffusion_compat import _interrupt_read, _iter_body, _ranged_stream
+
+ def _read(start: int, end: int) -> bytes:
+ want = end - start + 1
+ buffer = bytearray()
+ holder: list = [None]
+ failure: list = []
+
+ def _fetch() -> None:
+ try:
+ ranged = dict(headers)
+ ranged["Range"] = f"bytes={start}-{end}"
+ with _ranged_stream(get_session(), url, ranged) as response:
+ holder[0] = response
+ # A server ignoring Range answers 200 with the WHOLE checkpoint: never drain it.
+ if response.status_code != 206:
+ failure.append(f"HTTP {response.status_code}")
+ return
+ for chunk in _iter_body(response, 65536):
+ buffer.extend(chunk)
+ if len(buffer) >= want or time.monotonic() > deadline:
+ break
+ except Exception as exc: # noqa: BLE001
+ failure.append(repr(exc))
+
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ raise TimeoutError("header probe deadline")
+ worker = threading.Thread(target = _fetch, name = "prequant-header-read", daemon = True)
+ worker.start()
+ worker.join(remaining)
+ if worker.is_alive():
+ _interrupt_read(holder[0])
+ raise TimeoutError("header probe deadline")
+ if failure or len(buffer) < want:
+ raise OSError(failure[0] if failure else "short read")
+ return bytes(buffer[:want])
+
+ return _read
+
+
+MISSING = "missing"
+
+
+def _is_not_found(exc: BaseException) -> bool:
+ status = getattr(getattr(exc, "response", None), "status_code", None)
+ return status == 404 or type(exc).__name__ in ("EntryNotFoundError", "RemoteEntryNotFoundError")
+
+
+def hub_file_revision(
+ repo_id: str,
+ filename: str,
+ *,
+ token: Optional[str] = None,
+ revision: Optional[str] = None,
+ timeout_seconds: float = TIMEOUT_SECONDS,
+) -> Optional[tuple]:
+ """``(etag, commit)`` the Hub serves for ``filename`` now (one HEAD, no body), ``MISSING`` on a definite
+ 404, or None if unanswerable."""
+ try:
+ from huggingface_hub import get_hf_file_metadata, hf_hub_url
+ meta = get_hf_file_metadata(
+ hf_hub_url(repo_id, filename, revision = revision),
+ token = token,
+ timeout = timeout_seconds,
+ )
+ except Exception as exc: # noqa: BLE001 - offline or refused: the caller keeps what it has
+ return MISSING if _is_not_found(exc) else None
+ return getattr(meta, "etag", None), getattr(meta, "commit_hash", None)
+
+
+def read_hub_checkpoint_header(
+ repo_id: str,
+ filename: str,
+ *,
+ token: Optional[str] = None,
+ revision: Optional[str] = None,
+ timeout_seconds: float = TIMEOUT_SECONDS,
+) -> tuple:
+ """``(header or None, exists)`` via HTTP range requests; ``exists`` is False only on a definite 404."""
+ try:
+ from huggingface_hub import get_hf_file_metadata, hf_hub_url
+ from huggingface_hub.utils import build_hf_headers
+ except Exception: # noqa: BLE001
+ return None, None
+ deadline = time.monotonic() + timeout_seconds
+ try:
+ meta = get_hf_file_metadata(
+ hf_hub_url(repo_id, filename, revision = revision),
+ token = token,
+ timeout = timeout_seconds,
+ )
+ except Exception as exc: # noqa: BLE001
+ return None, (False if _is_not_found(exc) else None)
+ size = getattr(meta, "size", None)
+ if not size:
+ return None, True
+ url = hf_hub_url(repo_id, filename, revision = getattr(meta, "commit_hash", None) or revision)
+ try:
+ headers = dict(build_hf_headers(token = token))
+ except Exception: # noqa: BLE001
+ return None, True
+ out = read_checkpoint_header(filename, _hub_range_reader(url, headers, deadline), int(size))
+ if out is not None:
+ out["size"] = int(size)
+ out["commit"] = getattr(meta, "commit_hash", None)
+ return out, True
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index e5db1063545..bfbb7b34362 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -1709,8 +1709,10 @@ def _video_auto_denoiser_scheme(
requested: Optional[str],
base_repo: Optional[str],
speed_mode: Optional[str] = None,
+ hf_token: Optional[str] = None,
) -> Optional[str]:
- """The scheme a CONVENTIONAL video load would seed from a hosted checkpoint, or None."""
+ """The scheme a CONVENTIONAL video load would seed from a hosted checkpoint, or None. ``hf_token``
+ reaches the hosted header probe, so a gated artifact is judged, not read as unknown."""
# Only an AUTO precision becomes "off" under Speed="off"; an EXPLICIT scheme is honored, so it keeps its seed.
auto = requested is None or str(requested).strip().lower() in ("", "auto")
if auto and speed_mode is not None and str(speed_mode).strip().lower() == SPEED_OFF:
@@ -1724,7 +1726,7 @@ def _video_auto_denoiser_scheme(
hosted = tuple(
s
for s in video_family_prequant_schemes(fam)
- if denoiser_prequant_sources(fam, s, base_repo) is not None
+ if denoiser_prequant_sources(fam, s, base_repo, hf_token = hf_token) is not None
)
if not hosted or (not auto and normalize_transformer_quant(requested) not in hosted):
return None
@@ -1735,13 +1737,13 @@ def _video_auto_denoiser_scheme(
family = getattr(fam, "name", None),
base_repo = base_repo,
has_prequant = lambda candidate: (
- denoiser_prequant_sources(fam, candidate, base_repo) is not None
+ denoiser_prequant_sources(fam, candidate, base_repo, hf_token = hf_token) is not None
),
)
if scheme is None or scheme == TQ_AUTO:
return None
# EVERY component or none: partial coverage drops shards the dense fallback then has to open.
- if denoiser_prequant_sources(fam, scheme, base_repo) is None:
+ if denoiser_prequant_sources(fam, scheme, base_repo, hf_token = hf_token) is None:
return None
from .diffusion_prequant import restricted_prequant_load_supported
@@ -3173,6 +3175,7 @@ class VideoBackend:
memory_mode = kwargs.get("memory_mode"),
text_encoder_quant = kwargs.get("text_encoder_quant"),
gpu_ordinal = kwargs.get("gpu_ordinal"),
+ hf_token = kwargs.get("hf_token"),
)
video_seed_declined = video_auto_denoiser == DENOISER_SEED_DECLINED
if video_seed_declined:
@@ -3355,7 +3358,7 @@ class VideoBackend:
from .video_ltx2 import LTX23_PREQUANT_BASE
ltx23_sources = self._denoiser_prequant_source_list(
- fam, TQ_FP8, LTX23_PREQUANT_BASE
+ fam, TQ_FP8, LTX23_PREQUANT_BASE, hf_token = kwargs.get("hf_token")
)
with self._lock:
if self._load_token == token and self._loading is not None:
@@ -3380,6 +3383,7 @@ class VideoBackend:
h3_auto_denoiser or video_auto_denoiser or requested_denoiser,
base,
kwargs.get("h3_task"),
+ hf_token = kwargs.get("hf_token"),
),
kwargs.get("hf_token"),
cancel_event = cancel_event,
@@ -4156,7 +4160,9 @@ class VideoBackend:
The pure probe answers from the registry, which is right where it must not raise or touch
the network, but a renamed / gated task artifact still reads covered there. Unanswerable
keeps the dense shards; ``local_files_only`` answers from the cache."""
- if not self._denoiser_prequant_covered(fam, transformer_quant, base, h3_task, kind = kind):
+ if not self._denoiser_prequant_covered(
+ fam, transformer_quant, base, h3_task, kind = kind, hf_token = hf_token
+ ):
return False
from .diffusion_prequant import restricted_prequant_load_supported
@@ -4172,7 +4178,7 @@ class VideoBackend:
return False
if local_files_only:
repo = self._denoiser_prequant_cached_repo(
- fam, transformer_quant, base, h3_task, online = False
+ fam, transformer_quant, base, h3_task, online = False, hf_token = hf_token
)
else:
try:
@@ -4226,7 +4232,9 @@ class VideoBackend:
if planned == DENOISER_SEED_DECLINED and not modular:
return False
task = (h3_task or getattr(fam, "modular_workflow", None)) if modular else h3_task
- if not self._denoiser_prequant_covered(fam, "nvfp4", base, task, kind = kind):
+ if not self._denoiser_prequant_covered(
+ fam, "nvfp4", base, task, kind = kind, hf_token = hf_token
+ ):
return False
from .diffusion_prequant import restricted_prequant_load_supported
@@ -4234,7 +4242,12 @@ class VideoBackend:
return False
if (
self._denoiser_prequant_cached_repo(
- fam, "nvfp4", base, task, online = False if local_files_only else None
+ fam,
+ "nvfp4",
+ base,
+ task,
+ online = False if local_files_only else None,
+ hf_token = hf_token,
)
is not None
):
@@ -4323,6 +4336,7 @@ class VideoBackend:
memory_mode: Optional[str] = None,
text_encoder_quant: Optional[str] = None,
gpu_ordinal: Optional[int] = None,
+ hf_token: Optional[str] = None,
) -> Optional[str]:
"""The pre-download auto denoiser scheme, None, or ``DENOISER_SEED_DECLINED`` if the plan would offload."""
try:
@@ -4346,6 +4360,7 @@ class VideoBackend:
requested = transformer_quant,
base_repo = base,
speed_mode = speed_mode,
+ hf_token = hf_token,
)
if scheme is None:
return None
@@ -4587,20 +4602,31 @@ class VideoBackend:
h3_task: Optional[str] = None,
*,
kind: str = "pipeline",
+ hf_token: Optional[str] = None,
) -> bool:
- """True when hosted pre-quantized checkpoints replace ALL the family's dense DiT shards; offline, never raises."""
+ """True when hosted pre-quantized checkpoints replace ALL the family's dense DiT shards; never raises.
+ Registry plus the hosted header probe (cache-only offline); ``hf_token`` lets it read a gated header."""
try:
scheme = normalize_transformer_quant(transformer_quant)
# An unresolved "auto" must NOT drop dense shards; the backend settles it first.
if scheme is None or scheme == TQ_AUTO:
return False
if getattr(fam, "modular_workflow", None):
- return video_family_prequant_available(fam, scheme, task = h3_task, base_repo = base)
+ if not video_family_prequant_available(fam, scheme, task = h3_task, base_repo = base):
+ return False
+ # Covered only by a checkpoint the loader will accept: a stale header keeps the dense shards.
+ from .diffusion_prequant import resolve_prequant_source
+ from .video_denoiser_prequant import hosted_denoiser_refused
+
+ source = resolve_prequant_source(fam, scheme, base_repo = base, task = h3_task)
+ return source is None or not hosted_denoiser_refused(
+ source, scheme, base, hf_token = hf_token
+ )
if kind != "pipeline":
return False
from .video_denoiser_prequant import denoiser_prequant_sources
- return denoiser_prequant_sources(fam, scheme, base) is not None
+ return denoiser_prequant_sources(fam, scheme, base, hf_token = hf_token) is not None
except Exception: # noqa: BLE001 -- an unanswerable probe keeps the dense shards
return False
@@ -4610,19 +4636,27 @@ class VideoBackend:
transformer_quant: Optional[str],
base: Optional[str],
h3_task: Optional[str] = None,
+ *,
+ hf_token: Optional[str] = None,
) -> list[Any]:
- """Every ``PrequantSource`` a seeded load would open, or ``[]``; registry only, never raises."""
+ """Every ``PrequantSource`` a seeded load would open, or ``[]``; never raises. A hosted source the
+ loader would refuse from its header is dropped; ``hf_token`` lets that probe read a gated repo."""
scheme = (transformer_quant or "").strip().lower()
if scheme in ("", "auto", "off", "none"):
return []
try:
from .diffusion_prequant import resolve_prequant_source
- from .video_denoiser_prequant import denoiser_prequant_sources
+ from .video_denoiser_prequant import denoiser_prequant_sources, hosted_denoiser_refused
if getattr(fam, "modular_workflow", None):
source = resolve_prequant_source(fam, scheme, base_repo = base, task = h3_task)
- return [source] if source is not None else []
- resolved = denoiser_prequant_sources(fam, scheme, base)
+ # The modular loader checks no component; a header it would refuse is never staged.
+ if source is None or hosted_denoiser_refused(
+ source, scheme, base, hf_token = hf_token
+ ):
+ return []
+ return [source]
+ resolved = denoiser_prequant_sources(fam, scheme, base, hf_token = hf_token)
return list(resolved.values()) if resolved else []
except Exception as exc: # noqa: BLE001 -- a bad registry entry must not sink the plan
logger.warning("video.denoiser_prequant_unresolved: %s", exc)
@@ -4655,8 +4689,16 @@ class VideoBackend:
h3_task: Optional[str] = None,
) -> tuple[Optional[str], list[tuple[str, int]]]:
"""``(repo_id, [(rfilename, size)])`` for every hosted denoiser artifact, or ``(None, [])``, so preflight
- counts the checkpoint that replaces the dropped dense shards."""
- sources = VideoBackend._denoiser_prequant_source_list(fam, transformer_quant, base, h3_task)
+ counts the checkpoint that replaces the dropped dense shards. The header probe asks with ``api``'s own
+ token, so a gated artifact is judged by the same credentials that would stage it."""
+ token = getattr(api, "token", None)
+ sources = VideoBackend._denoiser_prequant_source_list(
+ fam,
+ transformer_quant,
+ base,
+ h3_task,
+ hf_token = token if isinstance(token, str) and token else None,
+ )
if not sources or any(getattr(src, "kind", None) != "repo" for src in sources):
return None, []
locations = {src.location for src in sources}
@@ -4706,11 +4748,14 @@ class VideoBackend:
base: Optional[str],
h3_task: Optional[str] = None,
online: Optional[bool] = None,
+ hf_token: Optional[str] = None,
) -> Optional[str]:
"""The hosted pre-quantized denoiser repo when its checkpoint is ALREADY cached, else None.
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)
+ sources = VideoBackend._denoiser_prequant_source_list(
+ fam, transformer_quant, base, h3_task, hf_token = hf_token
+ )
# 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
@@ -5059,6 +5104,7 @@ class VideoBackend:
memory_mode = load_kwargs.get("memory_mode"),
text_encoder_quant = text_encoder_quant,
gpu_ordinal = load_kwargs.get("gpu_ordinal"),
+ hf_token = hf_token,
)
if video_planned == DENOISER_SEED_DECLINED:
video_planned = None
@@ -5243,7 +5289,7 @@ class VideoBackend:
skip_transformer_weights = (
dq_repo is not None
and self._denoiser_prequant_covered(
- fam, transformer_quant, base, h3_task, kind = kind
+ fam, transformer_quant, base, h3_task, kind = kind, hf_token = hf_token
)
),
skip_transformer_components = _planned_denoiser_components(fam, kind),
@@ -6234,11 +6280,14 @@ class VideoBackend:
requested = transformer_quant,
base_repo = base,
speed_mode = speed_mode,
+ hf_token = hf_token,
)
denoiser_seed_sources: dict[str, Any] = {}
if denoiser_seed_scheme is not None:
from .video_denoiser_prequant import denoiser_prequant_sources
- denoiser_seed_sources = denoiser_prequant_sources(fam, denoiser_seed_scheme, base) or {}
+ denoiser_seed_sources = (
+ denoiser_prequant_sources(fam, denoiser_seed_scheme, base, hf_token = hf_token) or {}
+ )
if not denoiser_seed_sources:
denoiser_seed_scheme = None
denoiser_seed_gb: Optional[float] = None
diff --git a/studio/backend/core/inference/video_denoiser_prequant.py b/studio/backend/core/inference/video_denoiser_prequant.py
index 744d3b4f700..4acf4314d30 100644
--- a/studio/backend/core/inference/video_denoiser_prequant.py
+++ b/studio/backend/core/inference/video_denoiser_prequant.py
@@ -13,6 +13,41 @@ from typing import Any, Optional
MOE_SECOND_DENOISER = "transformer_2"
+def hosted_denoiser_refused(
+ source: Any,
+ scheme: Optional[str],
+ base_repo: Optional[str],
+ *,
+ component: Optional[str] = None,
+ hf_token: Optional[str] = None,
+) -> bool:
+ """Whether the loader would refuse hosted ``source`` from its header, asked BEFORE anything is staged:
+ the same base / min_features / component the loader checks, so a stale artifact is neither fetched nor
+ allowed to drop the dense shards. Offline (``HF_HUB_OFFLINE`` or a ``local_files_only`` load scope)
+ only a cached file is read. Unknown is never a refusal. Never raises."""
+ if getattr(source, "kind", None) != "repo":
+ return False
+ try:
+ from .diffusion import hub_cache_dir
+ from .diffusion_prequant import hosted_prequant_refusal
+ from .diffusion_transformer_quant import DEFAULT_MIN_LINEAR_FEATURES
+
+ return (
+ hosted_prequant_refusal(
+ source,
+ str(scheme or "").strip().lower(),
+ base = base_repo,
+ min_features = DEFAULT_MIN_LINEAR_FEATURES,
+ component = component,
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
+ )
+ is not None
+ )
+ except Exception: # noqa: BLE001 -- an unanswerable probe keeps today's plan
+ return False
+
+
def denoiser_components(fam: Any) -> tuple[str, ...]:
if getattr(fam, "is_moe", False):
return ("transformer", MOE_SECOND_DENOISER)
@@ -20,9 +55,15 @@ def denoiser_components(fam: Any) -> tuple[str, ...]:
def denoiser_prequant_sources(
- fam: Any, scheme: Optional[str], base_repo: Optional[str]
+ fam: Any,
+ scheme: Optional[str],
+ base_repo: Optional[str],
+ *,
+ hf_token: Optional[str] = None,
) -> Optional[dict[str, Any]]:
- """``{component: PrequantSource}`` for EVERY denoiser, or None (never partial). Never raises."""
+ """``{component: PrequantSource}`` for EVERY denoiser, or None (never partial). A hosted source whose
+ header the loader would refuse (``hosted_denoiser_refused``) counts as none, so planning keeps the
+ dense shards and never fetches it. Never raises."""
wanted = (scheme or "").strip().lower()
if wanted in ("", "auto", "off", "none"):
return None
@@ -48,6 +89,11 @@ def denoiser_prequant_sources(
)
if sources[component] is None:
return None
+ for component, source in sources.items():
+ if hosted_denoiser_refused(
+ source, wanted, base_repo, component = component, hf_token = hf_token
+ ):
+ return None
return sources or None
except Exception: # noqa: BLE001 -- an unanswerable registry keeps the dense denoiser
return None
@@ -70,7 +116,7 @@ def denoiser_prequant_pipe_kwargs(
try:
import gc
- sources = denoiser_prequant_sources(fam, scheme, base_repo)
+ sources = denoiser_prequant_sources(fam, scheme, base_repo, hf_token = hf_token)
if not sources:
return {}
if target is not None:
diff --git a/studio/backend/tests/test_prequant_header_probe.py b/studio/backend/tests/test_prequant_header_probe.py
new file mode 100644
index 00000000000..7fd9cb08953
--- /dev/null
+++ b/studio/backend/tests/test_prequant_header_probe.py
@@ -0,0 +1,1048 @@
+# 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",
+]
+
+
[email protected](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()
+
+
+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),
+}
+
+
[email protected]("built", sorted(_GENERATIONS))
[email protected]("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}
+ )
+
+
[email protected]("built", sorted(_GENERATIONS))
[email protected]("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}
+ )
+
+
[email protected]("algo", ["v1", "canonical"])
[email protected]("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"}
+
+
+ "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
+
+
+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
+
+
[email protected]("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
+
+
+ "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 == []
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index b4d1b3a5b5a..914e92cb8f8 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -9920,7 +9920,7 @@ def _stub_denoiser_seed(
kind = "repo", location = repo, filename = "x.pt", fallback_filename = None
)
monkeypatch.setattr(
- dq, "denoiser_prequant_sources", lambda fam, s, base: {c: source for c in components}
+ dq, "denoiser_prequant_sources", lambda fam, s, base, **_: {c: source for c in components}
)
modules = {c: object() for c in components}
calls = []
@@ -10318,7 +10318,7 @@ def test_the_download_plan_stages_both_experts_artifacts(monkeypatch):
fallback_filename = None,
),
}
- monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base: sources)
+ monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base, **_: sources)
monkeypatch.setattr(video_mod, "_video_auto_denoiser_scheme", lambda fam, **kw: "nvfp4")
monkeypatch.setattr(video_mod, "_video_seed_stays_resident", lambda fam, **kw: True)
@@ -10379,7 +10379,7 @@ def test_an_explicit_scheme_under_speed_off_stages_the_hosted_experts(monkeypatc
fallback_filename = None,
),
}
- monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base: sources)
+ monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base, **_: sources)
monkeypatch.setattr(
video_mod, "select_transformer_quant_scheme", lambda target, requested, **kw: requested
)
@@ -10477,7 +10477,7 @@ def _a14b_plan(monkeypatch):
fallback_filename = None,
),
}
- monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base: sources)
+ monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base, **_: sources)
def test_a_plan_that_still_offloads_at_artifact_size_stages_the_dense_experts(monkeypatch):
@@ -11402,7 +11402,7 @@ def test_an_nvfp4_video_family_with_no_hosted_checkpoint_installs_no_flashinfer(
import core.inference.video_denoiser_prequant as dq
installs, listed, _ = _video_install_probe(monkeypatch)
- monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base: None)
+ monkeypatch.setattr(dq, "denoiser_prequant_sources", lambda fam, scheme, base, **_: None)
_video_load_to_the_install_gate()
assert installs == []
assert listed == []