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.

Let a pre-quant checkpoint be safetensors instead of a pickle (#11394)

Daniel Han0275f7ee31df
diff --git a/scripts/build_prequant_checkpoint.py b/scripts/build_prequant_checkpoint.py
index bc5761c6c61..83b919e436c 100644
--- a/scripts/build_prequant_checkpoint.py
+++ b/scripts/build_prequant_checkpoint.py
@@ -52,7 +52,9 @@ def upload_destination(
scheme: str,
*,
rotated: bool,
+ safetensors: bool = False,
override: Optional[str] = None,
+ upload_repo: Optional[str] = None,
) -> str:
"""The repo-root filename this build should publish under.
@@ -61,22 +63,69 @@ def upload_destination(
``transformer_<scheme>.pt`` is either never resolved at all, or resolved as the fallback by a
build too old to honour the rotation, which then refuses the v2 tag and drops to the dense
download. A rotated build therefore goes to the declared name or nowhere. Plain builds keep
- the legacy name they have always used."""
+ the legacy name they have always used.
+
+ A SAFETENSORS build is in the same position for a different reason: both derived names end in
+ ``.pt``, so no build ever asks the Hub for a safetensors artifact unless the family names it.
+ Uploading one under a derived name produces a file that is reachable by nothing and a repo that
+ looks like it has a checkpoint when it does not, so it is refused here rather than discovered
+ as a silent dense fallback later.
+
+ An ``override`` skips the family table, because naming the artifact by hand is the escape hatch
+ for a repo the table does not describe yet. It does NOT skip the container check: every loader
+ dispatches on the extension alone, so a safetensors build published as ``.pt`` is read as a
+ pickle and a pickle published as ``.safetensors`` is read from a header it does not have. Either
+ way the upload succeeds and the artifact is unopenable, after the hours the quantization took.
+ """
if override:
+ wanted = ".safetensors" if safetensors else ".pt"
+ if not override.lower().endswith(wanted):
+ container = "safetensors" if safetensors else "torch.save"
+ raise ValueError(
+ f"--upload-filename {override!r} does not end in {wanted!r}, but --out writes the "
+ f"{container} container. The loader dispatches on the extension alone, so this "
+ "would publish an artifact nothing can open. Rename the upload, or change --out."
+ )
return override
from core.inference.diffusion_prequant import prequant_filename
- if not rotated:
+ if not rotated and not safetensors:
return prequant_filename(scheme)
from core.inference.diffusion_families import family_prequant_filename
preferred = family_prequant_filename(fam, scheme)
+ why = "a rotated checkpoint" if rotated else "a safetensors checkpoint"
if not preferred:
+ # A PLAIN safetensors build now has a derived name, and only because
+ # ``derived_prequant_filenames`` asks for ``<Model>-<SCHEME>.safetensors`` FIRST. The
+ # reachability this refusal protects is exactly what that chain supplies, so refusing here
+ # would make every family without a declared entry pass an override it could compute
+ # itself. Rotation keeps needing a declared name: no derived spelling carries the marker.
+ if safetensors and not rotated and upload_repo:
+ from core.inference.diffusion_prequant import prequant_repo_filename
+ return prequant_repo_filename(upload_repo, scheme, ".safetensors")
raise ValueError(
f"family {getattr(fam, 'name', fam)!r} declares no prequant_filenames entry for "
- f"{scheme!r}, so a rotated checkpoint has no name the loader would ask for. Add the "
+ f"{scheme!r}, so {why} has no name the loader would ask for. Add the "
"entry to the family table, or pass --upload-filename."
)
+ # Both directions, not just one. The declared name and the container have to agree, and a
+ # family that has moved its entry to a .safetensors artifact makes the REVERSE mismatch the
+ # reachable one: a rotated pickle build then publishes torch.save bytes under a safetensors
+ # name, every loader dispatches on the extension and hands them to safe_open, and the artifact
+ # is unopenable after the hours the quantization took. Same failure as the guarded direction,
+ # so it gets the same refusal.
+ wanted = ".safetensors" if safetensors else ".pt"
+ if not preferred.lower().endswith(wanted):
+ reads_as = "a pickle" if safetensors else "safetensors"
+ writes = "safetensors" if safetensors else "torch.save"
+ raise ValueError(
+ f"family {getattr(fam, 'name', fam)!r} declares {preferred!r} for {scheme!r}, which "
+ f"does not end in {wanted!r}, but --out writes the {writes} container. The loader "
+ f"dispatches on the extension alone, so this would be published under a name it reads "
+ f"as {reads_as}. Point the prequant_filenames entry at the matching artifact, or pass "
+ "--upload-filename."
+ )
return preferred
@@ -87,7 +136,12 @@ def main(argv = None) -> int:
)
p.add_argument("--family", required = True, help = "diffusion family name/alias (e.g. z-image)")
p.add_argument("--scheme", required = True, help = "quant scheme: int8 | fp8 | nvfp4 | mxfp8")
- p.add_argument("--out", required = True, help = "output .pt path for the checkpoint")
+ p.add_argument(
+ "--out",
+ required = True,
+ help = "output path; a .safetensors extension writes the safetensors container, anything "
+ "else writes the torch.save one",
+ )
p.add_argument("--min-features", type = int, default = 512)
p.add_argument("--dtype", default = "bfloat16", choices = ["bfloat16"])
p.add_argument("--hf-token", default = None)
@@ -144,6 +198,38 @@ def main(argv = None) -> int:
print(f"error: unknown family '{args.family}'", flush = True)
return 2
transformer_cls = getattr(diffusers, fam.transformer_class)
+ # The CONTAINER is chosen by the --out extension, so one flag picks the on-disk format, the reachable upload name
+ # and the writer, and they cannot be set to disagree.
+ is_safetensors_out = str(args.out).lower().endswith(".safetensors")
+ if is_safetensors_out:
+ from core.inference.prequant_safetensors import (
+ safetensors_prequant_supported,
+ scheme_is_flattenable,
+ )
+
+ if not safetensors_prequant_supported():
+ print(
+ "error: --out names a .safetensors checkpoint but this install cannot write one "
+ "(needs torchao >= 0.16 for torchao.prototype.safetensors.safetensors_support, "
+ "plus the safetensors package)",
+ flush = True,
+ )
+ return 2
+ # The helpers importing is not the same question as this scheme producing something they can
+ # flatten, and for int8 the two disagree through torchao 0.17. Probed here, on one tiny CPU
+ # Linear, so the answer arrives in a second instead of after the download and the hours of
+ # GPU quantization. None means the probe could not run, which is not evidence: proceed.
+ from core.inference.diffusion_transformer_quant import _make_quant_config
+
+ if scheme_is_flattenable(_make_quant_config(scheme)) is False:
+ print(
+ f"error: --out names a .safetensors checkpoint but this torchao quantises "
+ f"{scheme!r} to a legacy tensor subclass that cannot be written to safetensors. "
+ "torchao >= 0.18 produces the flattenable subclasses for every scheme Unsloth "
+ "ships. Upgrade torchao, or write this build as a .pt checkpoint.",
+ flush = True,
+ )
+ return 2
# Resolved BEFORE the load, so a rotated build with nowhere resolvable to publish fails in a second rather than
# after the quantise and the multi-gigabyte save.
upload_dest = None
@@ -153,7 +239,9 @@ def main(argv = None) -> int:
fam,
scheme,
rotated = bool(args.convrot_groupsize),
+ safetensors = is_safetensors_out,
override = args.upload_filename,
+ upload_repo = args.upload_repo,
)
except ValueError as exc:
print(f"error: {exc}", flush = True)
@@ -240,7 +328,16 @@ def main(argv = None) -> int:
out = Path(args.out)
out.parent.mkdir(parents = True, exist_ok = True)
- torch.save(ckpt, out)
+ if is_safetensors_out:
+ from core.inference.prequant_safetensors import save_prequant_safetensors
+ save_prequant_safetensors(
+ str(out),
+ fmt = ckpt["format"],
+ state_dict = state_dict,
+ metadata = metadata,
+ )
+ else:
+ torch.save(ckpt, out)
size_gb = out.stat().st_size / 1e9
print(f" saved {out} ({size_gb:.2f} GB) in {time.time() - t0:.0f}s", flush = True)
print(f" metadata: {ckpt['metadata']}", flush = True)
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 16e410cf2bf..2631f02d4e7 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -2921,7 +2921,7 @@ class DiffusionBackend:
base_repo = kwargs.get("base_repo"),
path_override = kwargs.get("transformer_prequant_path"),
)
- return self._prequant_source_hub_entry(source, hf_token)
+ return self._prequant_source_hub_entry(source, hf_token, scheme = planned)
raw = kwargs.get("transformer_quant")
auto = raw is None or str(raw).strip().lower() in ("", "auto")
# An AUTO quant under an explicit Speed="off" is forced to "off" by load_pipeline, which normalizes to
@@ -2990,7 +2990,12 @@ class DiffusionBackend:
path_override = kwargs.get("transformer_prequant_path"),
base_repo = kwargs.get("base_repo"),
)
- return self._prequant_source_hub_entry(source, hf_token, failures_out)
+ # The retry REPLACED the pick, so the readability question below is about
+ # the rung actually being planned, not the one the ladder started on.
+ scheme = retry
+ return self._prequant_source_hub_entry(
+ source, hf_token, failures_out, scheme = scheme
+ )
except Exception as exc: # noqa: BLE001 -- an unsizable prequant must not fail the plan
logger.warning("diffusion.dit_prequant_plan_failed: %s", exc)
# Best-effort for the UI, but NOT for a caller that must not download afterwards: the
@@ -3006,17 +3011,30 @@ class DiffusionBackend:
source: Any,
hf_token: Optional[str],
failures_out: Optional[list] = None,
+ scheme: Optional[str] = None,
) -> Optional[tuple[str, str, int]]:
- """``(repo, filename, declared_size)`` for a hosted checkpoint that exists, else None."""
+ """``(repo, filename, declared_size)`` for a hosted checkpoint that exists AND that this
+ install can open, else None.
+
+ Both halves matter, and only the first is obvious. This is the call that drops the released
+ dense shards from the pull, and the candidate chain now spans two containers, so the name
+ that EXISTS and the name that is READABLE are no longer the same question: a repo still
+ serving only the legacy pickle is answered by an install whose torch or torchao cannot
+ restrict that load, and committing to it here would spend the download and then refuse it
+ with no dense weights left to fall back to. Skipping an unreadable name lets a later
+ candidate answer, and skipping them all reports the miss, which keeps the shards."""
if source is None or getattr(source, "kind", None) != "repo":
return None
from huggingface_hub import HfApi
info = HfApi(token = hf_token or None).model_info(source.location, files_metadata = True)
sizes = {s.rfilename: int(getattr(s, "size", 0) or 0) for s in (info.siblings or [])}
- # Primary name first, then the legacy one, in the order the loader tries them.
- for name in (source.filename, source.fallback_filename):
- if name and name in sizes:
+ # Every candidate, in the order the loader tries them: safetensors first, then the pickle
+ # spellings. Reading only two of them would miss the artifact on a repo that hosts the third.
+ from .diffusion_prequant import candidate_filenames_of, restricted_prequant_load_supported
+
+ for name in candidate_filenames_of(source):
+ if name and name in sizes and restricted_prequant_load_supported(scheme, name):
return (source.location, name, int(sizes[name]))
# The repo answered and holds NEITHER name. Not "no prequant is used": this pick is configured to
# use one and its dense shards are already excluded, so the plan has no transformer and is partial.
@@ -3024,7 +3042,7 @@ class DiffusionBackend:
failures_out.append(
RuntimeError(
f"prequant artifact missing from {source.location}: "
- f"{source.filename!r} / {source.fallback_filename!r}"
+ f"tried {list(candidate_filenames_of(source))}"
)
)
return None
diff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.py
index 3701c1ca6d7..61c369603dc 100644
--- a/studio/backend/core/inference/diffusion_prequant.py
+++ b/studio/backend/core/inference/diffusion_prequant.py
@@ -13,10 +13,15 @@ to device. Measured (B200, Z-Image fp8): GPU load peak 12.9 -> 6.3 GB, download
output bit-identical (LPIPS 0.0). The checkpoint carries the same scheme + ``min_features`` as the
runtime path, so the result matches quantising on the fly.
-torchao's weight subclasses are not safetensors-serializable, so the artifact is a torch.save pickle
--- read under ``weights_only`` plus the constructor ALLOWLIST below, never as a free one. It is a
+Two containers, one dict. Historically the artifact could only be a ``torch.save`` pickle, because
+torchao's weight subclasses are wrapper tensors and safetensors stores flat ones; that pickle is read
+under ``weights_only`` plus the constructor ALLOWLIST below, never as a free one, since it is a
mutable remote file reached by loads that never asked for a scheme (auto resolves an unset precision
-to a hosted checkpoint), so "first-party repo" cannot stand in for that restriction.
+to a hosted checkpoint) and "first-party repo" cannot stand in for that restriction. torchao >= 0.16
+can flatten those subclasses, so an artifact may now also be ``.safetensors`` (see
+``prequant_safetensors``), which needs no allowlist at all and answers the validation questions from
+its header. ``_load_prequant_checkpoint`` returns the same ``{"format", "state_dict", "metadata"}``
+for both, so every check in this module applies to them identically and the two cannot drift apart.
Best-effort and lazily imported: a missing / mismatched / unreadable checkpoint returns None and the
caller falls back to dense-quantise (then GGUF). Inert with nothing configured.
@@ -26,6 +31,7 @@ from __future__ import annotations
import threading as _threading
from dataclasses import dataclass
+from collections.abc import Sequence
from typing import Any, Optional
# torch.save dict layout tag; bump on an on-disk change so old/foreign artifacts are rejected
@@ -233,7 +239,9 @@ def _register_prequant_safe_globals() -> bool:
return ok
-def restricted_prequant_load_supported(scheme: Optional[str] = None) -> bool:
+def restricted_prequant_load_supported(
+ scheme: Optional[str] = None, filename: Optional[str] = None
+) -> bool:
"""Whether this install can read a pre-quant checkpoint, for ``scheme`` when one is named.
Without the allowlist there is no safe way to open a pre-quant pickle and the loader refuses.
@@ -247,7 +255,18 @@ def restricted_prequant_load_supported(scheme: Optional[str] = None) -> bool:
deprecated upstream (pytorch/ao#2752), so a release that drops them while keeping
``Float8Tensor`` leaves fp8 loadable and int8 not. An unknown or unnamed scheme gets the floor
answer the registration itself already checked.
+
+ ``filename`` is the artifact the question is actually about, when the caller knows it. A
+ safetensors checkpoint names no constructors, so there is nothing to allowlist and none of the
+ above applies: it needs torchao's flatten/unflatten helpers and nothing else. Answering the
+ pickle's question for a safetensors artifact would refuse a perfectly loadable file on exactly
+ the installs the new container exists to unblock (a torch too old for ``add_safe_globals``, a
+ torchao missing a scheme's constructors, the stubbed torchao on Windows ROCm).
"""
+ from .prequant_safetensors import is_safetensors_checkpoint, safetensors_prequant_supported
+
+ if is_safetensors_checkpoint(filename):
+ return safetensors_prequant_supported()
if not _register_prequant_safe_globals():
return False
required = _SCHEME_REQUIRED_GLOBALS.get((scheme or "").strip().lower())
@@ -273,6 +292,21 @@ def _torch_load_prequant(path: str, **kwargs: Any) -> Any:
return torch.load(path, weights_only = True, **kwargs)
+def _load_prequant_checkpoint(path: str, **kwargs: Any) -> Any:
+ """Read a pre-quant checkpoint of EITHER container, as the same ``{"format", "state_dict",
+ "metadata"}`` dict.
+
+ Dispatched on the file extension rather than on content sniffing: the extension is what the
+ resolver asked the Hub for, so a repo hosting both containers cannot serve one and be parsed as
+ the other. ``kwargs`` are the pickle path's (``map_location``, ``mmap``); safetensors has no
+ equivalent knobs and reads to CPU, which is where the pickle path maps too."""
+ from .prequant_safetensors import is_safetensors_checkpoint, load_prequant_safetensors
+
+ if is_safetensors_checkpoint(path):
+ return load_prequant_safetensors(path)
+ return _torch_load_prequant(path, **kwargs)
+
+
_PREQUANT_TOGGLE_TOKENS = {"1", "true", "yes", "on", "0", "false", "no", "off"}
@@ -327,13 +361,46 @@ def local_prequant_path_ready(path: str) -> bool:
@dataclass(frozen = True)
class PrequantSource:
"""Where a pre-quantized checkpoint lives. ``kind`` is "path" (a local file) or "repo" (Hub repo
- id in ``location`` + ``filename``; ``fallback_filename`` is tried when the primary name is
- absent, covering repos still on the legacy transformer_<scheme>.pt)."""
+ id in ``location`` + ``filename``; ``fallback_filenames`` are tried IN ORDER when the primary
+ name is absent, covering the ``.pt`` container and repos still on the legacy
+ transformer_<scheme>.pt)."""
kind: str
location: str
filename: Optional[str] = None
- fallback_filename: Optional[str] = None
+ fallback_filenames: tuple[str, ...] = ()
+ # Names the FAMILY declared, as opposed to ones derived from the repo id. A declared name is
+ # evidence the repo really hosts that file; a derived one is a guess that costs a 404. Planning
+ # needs to tell them apart, see ``usable_prequant_source``.
+ declared_filenames: tuple[str, ...] = ()
+
+ @property
+ def fallback_filename(self) -> Optional[str]:
+ """The first fallback. Kept because callers outside this module read it by name, and
+ because it is what "the one other name to try" meant before the chain existed."""
+ return self.fallback_filenames[0] if self.fallback_filenames else None
+
+ @property
+ def candidate_filenames(self) -> tuple[str, ...]:
+ """Every name this source may resolve, best first. The single place that ordering lives, so
+ the downloader, the cache probe and the planner cannot disagree about which file wins."""
+ return tuple(n for n in (self.filename, *self.fallback_filenames) if n)
+
+
+def candidate_filenames_of(source: Any) -> tuple[str, ...]:
+ """``source``'s names, best first, for anything SHAPED like a source.
+
+ Planning passes lightweight stand-ins that carry ``filename`` / ``fallback_filename`` and
+ nothing else, so reading the property directly turns one of those into an AttributeError that
+ is swallowed into "no prequant plan" and a silent dense fallback. Falling back to the two older
+ attributes keeps every such caller working while the real dataclass answers the full chain."""
+ names = getattr(source, "candidate_filenames", None)
+ if names is None:
+ names = (
+ getattr(source, "filename", None),
+ getattr(source, "fallback_filename", None),
+ )
+ return tuple(n for n in names if n)
def prequant_filename(scheme: str) -> str:
@@ -341,16 +408,41 @@ def prequant_filename(scheme: str) -> str:
return f"transformer_{scheme}.pt"
-def prequant_repo_filename(repo_id: str, scheme: str) -> str:
+def prequant_repo_filename(
+ repo_id: str,
+ scheme: str,
+ suffix: str = ".pt",
+) -> str:
"""The model-name checkpoint filename for ``scheme`` in ``repo_id``: the hosted repos are named
<Model>-FP8 (or -INT8 / -quantized) and carry <Model>-<SCHEME>.pt files, e.g.
- unsloth/Z-Image-Turbo-FP8 -> Z-Image-Turbo-INT8.pt / Z-Image-Turbo-FP8.pt."""
+ unsloth/Z-Image-Turbo-FP8 -> Z-Image-Turbo-INT8.pt / Z-Image-Turbo-FP8.pt.
+
+ ``suffix`` picks the container. It defaults to ``.pt`` so every existing caller keeps naming the
+ artifact it already names; ``derived_prequant_filenames`` is what puts the safetensors spelling
+ of the same name ahead of it."""
model = repo_id.rsplit("/", 1)[-1]
- for suffix in ("-fp8", "-int8", "-quantized"):
- if model.lower().endswith(suffix):
- model = model[: -len(suffix)]
+ for drop in ("-fp8", "-int8", "-quantized"):
+ if model.lower().endswith(drop):
+ model = model[: -len(drop)]
break
- return f"{model}-{scheme.upper()}.pt"
+ return f"{model}-{scheme.upper()}{suffix}"
+
+
+def derived_prequant_filenames(repo_id: str, scheme: str) -> tuple[str, ...]:
+ """The names to try for ``(repo_id, scheme)``, best first, safetensors AHEAD of the pickle.
+
+ Preferring safetensors is a policy decision rather than a detail: it needs no constructor
+ allowlist (so it loads on installs where the pickle is refused outright), it validates from its
+ header before a weight is read, and it cannot carry pickle opcodes at all. Deriving the
+ preference here rather than per family means a repo that gains a ``.safetensors`` sibling is
+ picked up with no code change, and a repo that never does keeps resolving exactly what it
+ resolves today, because the ``.pt`` names stay in the chain behind it.
+ """
+ return (
+ prequant_repo_filename(repo_id, scheme, ".safetensors"),
+ prequant_repo_filename(repo_id, scheme, ".pt"),
+ prequant_filename(scheme),
+ )
def resolve_prequant_source(
@@ -392,7 +484,7 @@ def resolve_prequant_source(
except Exception: # noqa: BLE001 - a bad family object must not break the load
repo_id = None
if repo_id:
- derived = prequant_repo_filename(repo_id, scheme)
+ derived = derived_prequant_filenames(repo_id, scheme)
# A family may name a SECOND artifact for the same repo and scheme (today: MiniMax-H3's rotated INT8
# denoiser). It becomes the primary and the derived name becomes the fallback, so a build that knows the new
# name gets it and every older build keeps resolving the artifact it already understands. Without an override
@@ -403,13 +495,26 @@ def resolve_prequant_source(
# artifact per task prevents. Absent is better than wrong here: no artifact means the released bfloat16
# denoiser.
task_specific = preferred is not None and preferred != agnostic
+ if task_specific:
+ return PrequantSource(
+ kind = "repo",
+ location = repo_id,
+ filename = preferred,
+ declared_filenames = (preferred,),
+ )
+ # Family-declared name first when there is one, then the derived chain, which puts the
+ # safetensors spelling ahead of the pickle. Order-preserving dedup so a family that declares
+ # exactly what the chain would derive does not make the downloader ask twice for it.
+ names: list[str] = []
+ for name in ((preferred,) if preferred else ()) + derived:
+ if name and name not in names:
+ names.append(name)
return PrequantSource(
kind = "repo",
location = repo_id,
- filename = preferred or derived,
- fallback_filename = (
- None if task_specific else (derived if preferred else prequant_filename(scheme))
- ),
+ filename = names[0],
+ fallback_filenames = tuple(names[1:]),
+ declared_filenames = (preferred,) if preferred else (),
)
return None
@@ -432,6 +537,9 @@ def local_prequant_scheme(path: str) -> Optional[str]:
(path, mtime, size) because the auto ladder asks once per candidate scheme. Read under the same
allowlisted ``weights_only`` load the loader uses, so probing a file that turns out not to be a
checkpoint cannot execute anything either.
+
+ A safetensors artifact answers from its HEADER, so the probe reads a few KB of JSON and no
+ tensor at all, and needs neither the allowlist nor a torchao that can rebuild the subclasses.
"""
import os
@@ -446,9 +554,14 @@ def local_prequant_scheme(path: str) -> Optional[str]:
return None
if key in _LOCAL_PREQUANT_SCHEME:
return _LOCAL_PREQUANT_SCHEME[key]
+ from .prequant_safetensors import is_safetensors_checkpoint, read_prequant_header
+
scheme: Optional[str] = None
try:
- obj = _torch_load_prequant(real, map_location = "meta", mmap = True)
+ if is_safetensors_checkpoint(real):
+ obj = read_prequant_header(real)
+ else:
+ obj = _torch_load_prequant(real, map_location = "meta", mmap = True)
if isinstance(obj, dict) and obj.get("format") in PREQUANT_FORMATS:
recorded = (obj.get("metadata") or {}).get("scheme")
scheme = str(recorded) if recorded else None
@@ -478,12 +591,46 @@ def usable_prequant_source(
An install that cannot restrict the load has no usable source AT ALL, hosted included: the
loader refuses every checkpoint there, and a plan that had already dropped the dense shards for
- one would find that out after the eviction.
+ one would find that out after the eviction. That question is asked of the RESOLVED names rather
+ than of the scheme alone, because it has different answers for the two containers: a repo whose
+ 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.
"""
- if not restricted_prequant_load_supported(scheme):
- return None
src = resolve_prequant_source(fam, scheme, path_override = path_override, base_repo = base_repo)
- if src is not None and src.kind == "path":
+ if src is None:
+ return None
+ # getattr, because a source here is anything shaped like one (the planners hand round lightweight stand-ins) and a
+ # missing attribute must not turn a usable prequant into a silent dense fallback. No name at all asks the
+ # scheme-only question, which is what this did before either container existed.
+ candidates = (
+ [src.location]
+ if getattr(src, "kind", None) == "path"
+ else list(candidate_filenames_of(src))
+ ) or [None]
+ readable = [n for n in candidates if restricted_prequant_load_supported(scheme, n)]
+ if not readable:
+ return None
+ # A DERIVED safetensors name is a guess: most repos do not host one yet, and a guess must not be
+ # what planning bets the dense shards on. So when the only readable candidates are safetensors
+ # names, require evidence that one is really there -- the family declared it, or it is already
+ # in the cache. Without that, an install that cannot open a pickle would plan a 6 GB artifact
+ # for a .pt-only repo, get a 404 then a refusal, and fall back to dense under a plan that never
+ # budgeted for it, which is the evict-then-OOM this function exists to prevent.
+ from .prequant_safetensors import is_safetensors_checkpoint
+
+ if src.kind == "repo" and all(is_safetensors_checkpoint(n) for n in readable):
+ declared = set(getattr(src, "declared_filenames", ()) or ())
+ # The cache probe is scoped to the READABLE names for the same reason the list above is: a
+ # cached legacy pickle is not evidence for a safetensors artifact nobody has published, and
+ # an install that cannot open that pickle would take the cache hit as proof, plan without
+ # the dense shards, then resolve neither file.
+ if (
+ not any(n in declared for n in readable)
+ and cached_checkpoint_path(src, names = readable) is None
+ ):
+ return None
+ if src.kind == "path":
if not local_prequant_path_ready(src.location):
return None
if local_prequant_scheme(src.location) != scheme:
@@ -491,18 +638,49 @@ def usable_prequant_source(
return src
-def cached_checkpoint_path(source: Any, *, cache_dir: Optional[str] = None) -> Optional[str]:
+def cached_checkpoint_path(
+ source: Any,
+ *,
+ cache_dir: Optional[str] = None,
+ names: Optional[Sequence[str]] = None,
+) -> Optional[str]:
"""The path of a hosted (``kind == "repo"``) checkpoint ALREADY in the local Hub cache. A pure
- lookup (a refs read plus a stat, no network), so memory planning can ask on every pick. Only
- the PRIMARY ``filename`` counts: a cached ``fallback_filename`` (the legacy artifact) must
- not short-circuit it, or a stale name stays pinned once the repo ships the real one, so a
- fallback-only cache reads as "this would have to download" and the GGUF simply runs. Both
- cache roots are searched: Unsloth pins the LIVE cache setting while an unpinned
+ lookup (a refs read plus a stat, no network), so memory planning can ask on every pick.
+
+ Every candidate name counts, IN PREFERENCE ORDER, not just the primary. Primary-only was right
+ while the primary was the only name a repo could realistically host; it is wrong the moment the
+ chain leads with a safetensors name that most repos do not have yet, because then every existing
+ ``.pt`` repo reads as "this would have to download several GB" and loses to the GGUF even though
+ its checkpoint is sitting in the cache. Walking the chain in order keeps the anti-staleness
+ property that motivated primary-only: the better name still wins whenever it is present.
+
+ A name this install cannot OPEN is never a hit, in either direction. The obvious direction is a
+ cached ``.pt`` on a host whose torch or torchao cannot restrict that load; the inverse is a
+ cached ``.safetensors`` on a host without torchao's flatten helpers, which reads the pickle
+ perfectly well. Both end the same way if this answers yes: the planner commits to the prequant,
+ drops the dense shards, and ``_resolve_checkpoint_path`` then filters out the very file the
+ cache hit was about and finds the other name uncached. Asked per NAME rather than per scheme,
+ because the container is what decides it.
+
+ ``names`` narrows the chain further, to a caller's own subset.
+
+ Both cache roots are searched: Unsloth pins the LIVE cache setting while an unpinned
``hf_hub_download`` falls back to huggingface_hub's import-time constant. Never raises."""
- for root in (cache_dir, None) if cache_dir else (None,):
- hit = _cached_in_root(source, root)
- if hit is not None:
- return hit
+ roots = (cache_dir, None) if cache_dir else (None,)
+ wanted = set(names) if names is not None else None
+ for name in candidate_filenames_of(source):
+ if wanted is not None and name not in wanted:
+ continue
+ try:
+ readable = restricted_prequant_load_supported(None, name)
+ except Exception: # noqa: BLE001 - a pure lookup that never raises, as documented above
+ readable = True
+ if not readable:
+ continue
+ for root in roots:
+ hit = _cached_in_root(source, root, name)
+ if hit is not None:
+ return hit
return None
@@ -632,16 +810,17 @@ def load_prequantized_transformer(
return None
path = _resolve_checkpoint_path(
- source, hf_token, cache_dir, local_files_only = local_files_only
+ source, hf_token, cache_dir, local_files_only = local_files_only, scheme = scheme
)
if path is None:
return None
- # A torch.save pickle, deserialized under the constructor ALLOWLIST above and never as a free-running one.
- # First-party hosting is no reason to execute whatever bytes arrive: the artifact is mutable, fetched over the
- # network, and reached by loads that never asked for one (auto resolves an unset precision to a hosted
- # checkpoint), so a mutated file must fail to load rather than run.
- ckpt = _torch_load_prequant(path, map_location = "cpu")
+ # A safetensors artifact, or a torch.save pickle deserialized under the constructor ALLOWLIST above and never
+ # as a free-running one. First-party hosting is no reason to execute whatever bytes arrive: the artifact is
+ # mutable, fetched over the network, and reached by loads that never asked for one (auto resolves an unset
+ # precision to a hosted checkpoint), so a mutated file must fail to load rather than run. Both containers
+ # hand back the same dict, so every check below applies to them equally.
+ ckpt = _load_prequant_checkpoint(path, map_location = "cpu")
if not _validate_checkpoint(
ckpt, scheme, base, logger, min_features = min_features, fast_accum = fast_accum
):
@@ -807,11 +986,19 @@ def _resolve_checkpoint_path(
cache_dir: Optional[str] = None,
*,
local_files_only: bool = False,
+ scheme: Optional[str] = None,
) -> Optional[str]:
"""The local file path for ``source``, downloading from the Hub if needed; None if absent.
``local_files_only`` is the caller's promise that this load may not fetch anything, so a
cache miss answers None and the build falls back rather than pulling several GB nobody asked
- for."""
+ for.
+
+ ``scheme`` drops the names this install could not deserialize anyway, which is the SAME filter
+ the download plan applies. It has to be the same one: with only the plan filtering, a repo
+ hosting both containers would have the plan stage the readable one while this fetched the
+ other, downloading a second artifact to fail on it and then falling back to dense weights the
+ plan had already left out. Unset keeps the whole chain, for the callers that have no scheme to
+ offer."""
if source.kind == "path":
import os
@@ -819,30 +1006,44 @@ def _resolve_checkpoint_path(
expanded = os.path.expanduser(source.location)
return expanded if os.path.isfile(expanded) else None
if source.kind == "repo":
- EntryNotFoundError, _ = _entry_not_found_errors()
- has_fallback = (
- bool(source.fallback_filename) and source.fallback_filename != source.filename
- )
- try:
- return _download_checkpoint_name(
- source,
- source.filename,
- hf_token,
- cache_dir,
- propagate_missing = has_fallback,
- local_files_only = local_files_only,
- )
- except EntryNotFoundError:
- if not has_fallback:
- raise
- return _download_checkpoint_name(
- source,
- source.fallback_filename,
- hf_token,
- cache_dir,
- propagate_missing = False,
- local_files_only = local_files_only,
- )
+ EntryNotFoundError, LocalEntryNotFoundError = _entry_not_found_errors()
+ names = list(candidate_filenames_of(source))
+ if scheme is not None:
+ readable = [n for n in names if restricted_prequant_load_supported(scheme, n)]
+ # Only when it leaves something. An empty filter means the source should never have
+ # been offered, and resolving nothing here would turn that into a silent None rather
+ # than the refusal the loader reports.
+ names = readable or names
+ if not names:
+ return None
+ for index, name in enumerate(names):
+ last = index == len(names) - 1
+ try:
+ return _download_checkpoint_name(
+ source,
+ name,
+ hf_token,
+ cache_dir,
+ # Only the LAST name may swallow its own 404. Any earlier one has to let the
+ # error reach here so the next candidate is tried, which is what makes the
+ # safetensors-then-pickle preference work on a repo hosting only one of them.
+ propagate_missing = not last,
+ local_files_only = local_files_only,
+ )
+ except LocalEntryNotFoundError:
+ # Caught BEFORE the base it subclasses, because the two mean different things and
+ # only the mode says which. huggingface_hub documents this one as "not on the disk
+ # when network is disabled OR UNAVAILABLE (connection issue). The entry may exist
+ # on the Hub", so online it is the Hub being unreachable, not this name being
+ # absent: advancing would spend a full attempt on every remaining candidate and
+ # then report the LAST one's error instead of the connection failure that actually
+ # happened. Offline, a cache miss is the only verdict there is, so the chain is
+ # walked exactly as for a 404.
+ if not local_files_only or last:
+ raise
+ except EntryNotFoundError:
+ if last:
+ raise
return None
diff --git a/studio/backend/core/inference/diffusion_te_prequant.py b/studio/backend/core/inference/diffusion_te_prequant.py
index 2d86e9ab487..c74235533a9 100644
--- a/studio/backend/core/inference/diffusion_te_prequant.py
+++ b/studio/backend/core/inference/diffusion_te_prequant.py
@@ -351,9 +351,17 @@ def load_prequant_text_encoder(
import torch
+ from .prequant_safetensors import is_safetensors_checkpoint, load_prequant_safetensors
+
# The layerwise-fp8 state dict is plain tensors, so weights_only=True suffices and no pickle code runs even for
# a local path. A future torchao-subclass scheme needs a format bump AND the DiT module's allowlist.
- ckpt = torch.load(path, weights_only = True, map_location = "cpu")
+ # A ``.safetensors`` artifact is read through the shared reader instead, which returns the same dict shape, so
+ # ``_validate_checkpoint`` and everything after it are unchanged. Dispatch is on the extension the resolver
+ # asked the Hub for, never on sniffing the bytes.
+ if is_safetensors_checkpoint(path):
+ ckpt = load_prequant_safetensors(path)
+ else:
+ ckpt = torch.load(path, weights_only = True, map_location = "cpu")
if not _validate_checkpoint(ckpt, scheme, component, base, logger):
return None
state_dict = ckpt["state_dict"]
diff --git a/studio/backend/core/inference/prequant_safetensors.py b/studio/backend/core/inference/prequant_safetensors.py
new file mode 100644
index 00000000000..1cd5e613f6c
--- /dev/null
+++ b/studio/backend/core/inference/prequant_safetensors.py
@@ -0,0 +1,312 @@
+# 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 and write a pre-quantized checkpoint as ``.safetensors`` instead of a ``torch.save`` pickle.
+
+torchao's weight subclasses (``Float8Tensor``, ``Int8Tensor``, ``NVFP4Tensor``, ...) are wrapper
+tensors: several plain tensors plus reconstruction metadata behind one logical weight. safetensors
+stores flat tensors only, which is why every pre-quant artifact Unsloth has published so far is a
+pickle. torchao >= 0.16 closes that gap with ``flatten_tensor_state_dict`` /
+``unflatten_tensor_state_dict``, the same pair ``transformers`` and ``diffusers`` use for their own
+torchao checkpoints, so the subclass is split into ``<fqn>._weight_qdata`` / ``._weight_scale`` and a
+JSON description of how to put it back.
+
+Why bother, given the pickle is already read under ``weights_only`` plus a constructor allowlist:
+
+- That allowlist is a real gate, not a formality. ``restricted_prequant_load_supported`` returns
+ False when torch cannot express it or when torchao does not ship a scheme's constructors, and the
+ callers in ``video.py`` then refuse the checkpoint outright and fall back to dense. A safetensors
+ artifact has no constructors to allowlist, so that whole failure mode does not apply to it.
+- A pickle has to be parsed before anything about it is known. A safetensors header is a JSON blob at
+ the front of the file, so the scheme / base model / filter checks run off a few KB, before a single
+ weight byte is read, and a mismatched artifact costs a header read rather than a full parse.
+- mmap, lazy per-tensor reads, the Hub's file viewer and cross-framework reads all come for free.
+
+**On-disk layout.** Tensors are exactly what ``flatten_tensor_state_dict`` produces. The header is
+torchao's own metadata (``tensor_names`` plus one JSON entry per weight, which is what makes the file
+readable by anything that understands torchao checkpoints) with two namespaced keys added:
+
+ "unsloth_format" -> the same format tag the pickle carries in ckpt["format"]
+ "unsloth_metadata" -> JSON of the same dict the pickle carries in ckpt["metadata"]
+
+``is_metadata_torchao`` walks ``tensor_names`` only, so the extra keys do not disturb it.
+
+**Writing needs a newer torchao than reading does.** Only the new-style subclasses can be flattened,
+and through torchao 0.17 the int8 config still produces the legacy
+``LinearActivationQuantizedTensor`` over an ``AffineQuantizedTensor``; 0.18 produces ``Int8Tensor``,
+which flattens. Both versions RECONSTRUCT an ``Int8Tensor`` file happily, so this binds the machine
+that builds an artifact, never the one that loads it. fp8 has been flattenable since 0.16.
+
+**No new format tag.** The tags (``..._v1``, the rotated ``..._v2``) describe what the WEIGHTS mean,
+and that is unchanged by the container; a rotated safetensors artifact is still ``_v2`` and still
+refused by a build that cannot rotate. Old builds are kept away from these files by the FILENAME,
+not the tag: they resolve ``<Model>-<SCHEME>.pt`` and know nothing of a ``.safetensors`` sibling, so
+a repo can host both and each build reads the one it understands.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+SAFETENSORS_SUFFIX = ".safetensors"
+
+# Header keys carrying what the pickle kept in the top-level dict. Namespaced so they cannot collide
+# with torchao's, which are ``tensor_names`` plus one key per tensor FQN.
+UNSLOTH_FORMAT_KEY = "unsloth_format"
+UNSLOTH_METADATA_KEY = "unsloth_metadata"
+
+# The torchao release that first shipped the flatten/unflatten pair under this import path. Below it
+# the helpers are absent and a safetensors artifact simply cannot be read, so the loader says so and
+# falls back rather than guessing at the layout.
+MIN_TORCHAO_VERSION = (0, 16)
+
+
+def is_safetensors_checkpoint(name: Optional[str]) -> bool:
+ """Whether ``name`` (a filename or a path) names a safetensors pre-quant artifact."""
+ return bool(name) and str(name).lower().endswith(SAFETENSORS_SUFFIX)
+
+
+def _torchao_helpers() -> Optional[tuple]:
+ """``(flatten, unflatten)`` from torchao, or None when this install cannot do it.
+
+ Imported lazily and by feature rather than by version string: the module moving out of
+ ``prototype`` is a rename we should follow silently, and a version parse is not evidence the
+ symbols exist. Never raises -- an install without them has no safetensors support, which is a
+ fallback, not an error.
+
+ The stub comes FIRST because importing by feature is not enough against it. On Windows ROCm
+ ``install_torchao_windows_rocm_stub`` installs a meta-path finder that answers every
+ ``torchao.*`` import with fabricated callables, so the import below succeeds and hands back two
+ names that return None. Planning would then read safetensors as supported, drop the dense
+ shards, and the load would unflatten nothing. The pickle probe already asks ``is_stubbed`` for
+ the same reason (``diffusion_prequant._register_prequant_safe_globals``).
+ """
+ try:
+ from core._torchao_stub import is_stubbed
+ if is_stubbed("torchao"):
+ return None
+ except Exception: # noqa: BLE001 - no stub module to ask means nothing is stubbed
+ pass
+ try:
+ from torchao.prototype.safetensors.safetensors_support import (
+ flatten_tensor_state_dict,
+ unflatten_tensor_state_dict,
+ )
+ except Exception: # noqa: BLE001 - torchao absent, too old, or the module moved
+ return None
+ return flatten_tensor_state_dict, unflatten_tensor_state_dict
+
+
+def _torchao_version() -> Optional[str]:
+ try:
+ import torchao
+ return getattr(torchao, "__version__", None)
+ except Exception: # noqa: BLE001
+ return None
+
+
+def safetensors_prequant_supported() -> bool:
+ """Whether this install can read (and write) safetensors pre-quant checkpoints."""
+ if _torchao_helpers() is None:
+ return False
+ try:
+ import safetensors # noqa: F401
+ except Exception: # noqa: BLE001
+ return False
+ return True
+
+
+def _first(value: Any) -> Any:
+ """Both torchao helpers return a 2-tuple whose first element is the dict we want.
+
+ Unpacking blindly is the bug this exists to prevent: ``flatten_tensor_state_dict`` returns
+ ``(tensors, metadata)`` and ``unflatten_tensor_state_dict`` returns ``(state_dict, _)``, and a
+ tuple handed on to ``load_state_dict`` fails with a type error that says nothing about torchao.
+ A release that returns the bare dict instead is handled by the same line.
+ """
+ return value[0] if isinstance(value, tuple) else value
+
+
+def unsupported_state_dict_keys(state_dict: Any) -> list:
+ """Keys torchao's unflatten cannot round-trip: the ones with no ``.`` in them.
+
+ ``unflatten_tensor_state_dict`` does ``tensor_name.rsplit(".", 1)`` to split a key into module
+ fqn and weight name, so a ROOT-level parameter or buffer (``pos_embed`` rather than
+ ``embed.weight``) raises ``ValueError: not enough values to unpack`` when the file is read back.
+ Saving one would produce an artifact that writes cleanly and can never be loaded, so the builder
+ refuses up front and says which keys are the problem. Every DiT Unsloth ships today is dotted
+ throughout; this exists so a future one fails at build time rather than in a user's loader.
+ """
+ try:
+ keys = list(state_dict.keys())
+ except Exception: # noqa: BLE001 - not a mapping is the caller's problem, not this check's
+ return []
+ return [k for k in keys if "." not in str(k)]
+
+
+def save_prequant_safetensors(path: str, *, fmt: str, state_dict: Any, metadata: Any) -> None:
+ """Write ``state_dict`` (quantized, tensor subclasses and plain tensors alike) to ``path``.
+
+ ``fmt`` and ``metadata`` land in the header beside torchao's own description of every tensor.
+ Raises when the install cannot serialize this way: the caller is an offline builder that was
+ ASKED for safetensors, and silently writing a pickle under a ``.safetensors`` name would be the
+ worst of both.
+ """
+ helpers = _torchao_helpers()
+ if helpers is None:
+ raise RuntimeError(
+ "this install cannot write a safetensors pre-quant checkpoint: torchao >= "
+ f"{'.'.join(str(p) for p in MIN_TORCHAO_VERSION)} is required for "
+ "torchao.prototype.safetensors.safetensors_support"
+ )
+ from safetensors.torch import save_file
+
+ undotted = unsupported_state_dict_keys(state_dict)
+ if undotted:
+ raise ValueError(
+ "these state dict keys have no '.' and cannot be read back by torchao's unflatten, "
+ f"so a safetensors checkpoint carrying them would never load: {undotted[:8]}"
+ + (f" (+{len(undotted) - 8} more)" if len(undotted) > 8 else "")
+ + ". Write this build as a .pt checkpoint instead."
+ )
+
+ flatten, _ = helpers
+ try:
+ flat, torchao_metadata = flatten(state_dict)
+ except ValueError as exc:
+ # Only the NEW torchao tensor subclasses can be flattened. The one that bites in practice is
+ # int8: through torchao 0.17 ``Int8DynamicActivationInt8WeightConfig`` still produces the
+ # legacy ``LinearActivationQuantizedTensor`` over an ``AffineQuantizedTensor``, which has no
+ # flatten support, while 0.18 produces ``Int8Tensor``, which does. Reading is NOT affected
+ # (0.17 reconstructs an ``Int8Tensor`` file fine), so this is a constraint on the machine
+ # that BUILDS an artifact, and it deserves to say so rather than surface as a bare
+ # "Unsupported tensor type" from inside torchao.
+ if "Unsupported tensor type" not in str(exc):
+ raise
+ raise ValueError(
+ f"{exc}. This torchao ({_torchao_version() or 'unknown'}) still quantises to a legacy "
+ "tensor subclass that cannot be written to safetensors; torchao >= 0.18 produces the "
+ "flattenable subclasses for every scheme Unsloth ships. Upgrade torchao to build this "
+ "artifact, or write it as a .pt checkpoint."
+ ) from exc
+
+ # torchao hands back metadata ALREADY JSON-encoded, i.e. a str -> str dict ready for safetensors.
+ # Encoding it a second time round-trips perfectly against a symmetric reader and is still wrong:
+ # ``is_metadata_torchao`` then rejects the header and every transformers / diffusers loader
+ # refuses the file. The break only shows up on someone else's machine, so pass it through.
+ header = dict(torchao_metadata or {})
+ header[UNSLOTH_FORMAT_KEY] = str(fmt)
+ header[UNSLOTH_METADATA_KEY] = json.dumps(metadata or {}, default = str)
+ save_file(flat, path, metadata = header)
+
+
+def read_prequant_header(path: str) -> Optional[dict]:
+ """``{"format": ..., "metadata": {...}}`` read from the header alone, or None.
+
+ No tensor is touched, so this is the cheap way to answer "what scheme is this artifact, and is
+ it even ours" on a multi-GB file. None means "not an Unsloth safetensors pre-quant checkpoint",
+ which every caller treats as unknown rather than as an error.
+ """
+ try:
+ from safetensors import safe_open
+ with safe_open(path, framework = "pt") as handle:
+ raw = handle.metadata() or {}
+ except Exception: # noqa: BLE001 - unreadable or not safetensors at all
+ return None
+ fmt = raw.get(UNSLOTH_FORMAT_KEY)
+ if not fmt:
+ return None
+ try:
+ metadata = json.loads(raw.get(UNSLOTH_METADATA_KEY) or "{}")
+ except Exception: # noqa: BLE001 - a corrupt metadata blob is not a usable checkpoint
+ return None
+ if not isinstance(metadata, dict):
+ return None
+ return {"format": str(fmt), "metadata": metadata}
+
+
+def load_prequant_safetensors(path: str, *, device: str = "cpu") -> dict:
+ """Read ``path`` into the SAME dict shape the pickle path returns.
+
+ Returning ``{"format", "state_dict", "metadata"}`` rather than a new type is deliberate: every
+ validation and load step downstream (scheme / base / min_features / fast_accum checks, the fp8
+ activation-floor probe that reads the reconstructed tensors, the rotation biconditional, the
+ kernel-preference pin) then runs unchanged on both containers, so the two formats cannot drift
+ into having different acceptance rules.
+ """
+ helpers = _torchao_helpers()
+ if helpers is None:
+ raise RuntimeError(
+ "this install cannot read a safetensors pre-quant checkpoint: torchao >= "
+ f"{'.'.join(str(p) for p in MIN_TORCHAO_VERSION)} is required for "
+ "torchao.prototype.safetensors.safetensors_support"
+ )
+ from safetensors import safe_open
+
+ _, unflatten = helpers
+ with safe_open(path, framework = "pt", device = device) as handle:
+ raw = dict(handle.metadata() or {})
+ tensors = {key: handle.get_tensor(key) for key in handle.keys()}
+
+ fmt = raw.get(UNSLOTH_FORMAT_KEY)
+ if not fmt:
+ raise ValueError(
+ f"{path} is a safetensors file but not an Unsloth pre-quant checkpoint "
+ f"(no {UNSLOTH_FORMAT_KEY!r} in its header)"
+ )
+ metadata = json.loads(raw.get(UNSLOTH_METADATA_KEY) or "{}")
+
+ # torchao reads its OWN keys out of the same header; ours are namespaced and simply ignored. The second element
+ # is what it could NOT account for: a subclass missing one of its parts (a truncated or hand-edited file) is
+ # skipped there rather than raised, which would reach load_state_dict as a bare missing-key error saying nothing
+ # about the artifact. Name it here instead.
+ rebuilt = unflatten(tensors, raw)
+ state_dict = _first(rebuilt)
+ leftover = rebuilt[1] if isinstance(rebuilt, tuple) and len(rebuilt) > 1 else None
+ if leftover:
+ raise ValueError(
+ f"{path} has {len(leftover)} tensor(s) its header does not account for "
+ f"(e.g. {sorted(leftover)[0]!r}); the checkpoint is incomplete or was edited"
+ )
+ return {"format": str(fmt), "state_dict": state_dict, "metadata": metadata}
+
+
+def scheme_is_flattenable(quant_config: Any, *, features: int = 512) -> Optional[bool]:
+ """Whether THIS torchao can flatten what ``quant_config`` quantizes a weight to.
+
+ ``safetensors_prequant_supported`` answers a different question: the helpers import, the package
+ is there. That is necessary and not sufficient, and int8 is the case where the gap bites. Through
+ torchao 0.17 ``Int8DynamicActivationInt8WeightConfig`` still produces a
+ ``LinearActivationQuantizedTensor`` over an ``AffineQuantizedTensor``, which ``flatten`` refuses;
+ 0.18 produces ``Int8Tensor``, which it accepts. Without this the builder passes its preflight,
+ downloads the model, spends the hours of GPU quantization, and only then discovers it cannot
+ write the file it was asked for.
+
+ Probed on one tiny CPU Linear rather than read off a version string, for the same reason
+ ``_torchao_helpers`` imports by feature: the constraint is what the installed release actually
+ produces. ``None`` means the probe itself could not run (no torch, a config this torchao will not
+ apply to a bare Linear), which callers must treat as "proceed": refusing a build because the
+ probe was unavailable would be worse than the late failure it exists to prevent.
+ """
+ helpers = _torchao_helpers()
+ if helpers is None:
+ return False
+ try:
+ import torch
+ from torchao.quantization import quantize_
+
+ probe = torch.nn.Linear(features, features, bias = False)
+ quantize_(probe, quant_config)
+ except Exception: # noqa: BLE001 - an unprobeable config is not evidence of anything
+ return None
+ flatten, _ = helpers
+ try:
+ flatten(probe.state_dict())
+ except ValueError as exc:
+ if "Unsupported tensor type" in str(exc):
+ return False
+ return None
+ except Exception: # noqa: BLE001
+ return None
+ return True
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 800883eec9b..c5401ddd53a 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -2885,14 +2885,9 @@ class VideoBackend:
return None, []
# The root name first, then the legacy scheme name: resolve_prequant_source hands back both and the load tries
# them in that order, so the plan must stage whichever one exists.
- wanted = [
- n
- for n in (
- getattr(source, "filename", None),
- getattr(source, "fallback_filename", None),
- )
- if n
- ]
+ from core.inference.diffusion_prequant import candidate_filenames_of
+
+ wanted = list(candidate_filenames_of(source))
try:
info = api.model_info(source.location, files_metadata = True)
except Exception as exc: # noqa: BLE001 -- unavailable prequant means the dense DiT
@@ -2939,11 +2934,10 @@ class VideoBackend:
return None
from core.inference.diffusion import DiffusionBackend
- for name in (
- getattr(source, "filename", None),
- getattr(source, "fallback_filename", None),
- ):
- if name and DiffusionBackend._hub_file_is_cached(source.location, name):
+ from core.inference.diffusion_prequant import candidate_filenames_of
+
+ for name in candidate_filenames_of(source):
+ if DiffusionBackend._hub_file_is_cached(source.location, name):
return source.location
# No log here: the caller reports the same "keeping its dense denoiser shards" outcome for a miss, and logging
# it twice would read as two separate decisions.
diff --git a/studio/backend/tests/test_build_prequant_checkpoint.py b/studio/backend/tests/test_build_prequant_checkpoint.py
index c422db32fa7..a216f5e4904 100644
--- a/studio/backend/tests/test_build_prequant_checkpoint.py
+++ b/studio/backend/tests/test_build_prequant_checkpoint.py
@@ -12,6 +12,8 @@ import importlib.util
import sys
from pathlib import Path
+import types
+
import pytest
from core.inference.diffusion_convrot import rotation_metadata, rotation_metadata_error
@@ -70,3 +72,135 @@ def test_a_rotated_upload_with_no_declared_name_is_refused_rather_than_published
== "Z-Image-Turbo-INT8-ConvRot.pt"
)
assert build.upload_destination(zimage, "fp8", rotated = False) == "transformer_fp8.pt"
+
+
+def test_a_safetensors_upload_needs_a_name_the_loader_would_ask_for():
+ build = _script()
+ zimage = detect_family("Tongyi-MAI/Z-Image-Turbo", override = "z-image")
+ assert zimage is not None
+ # Every DERIVED name ends in .pt, so no build ever asks the Hub for a safetensors artifact
+ # unless the family declares one. Publishing under a derived name produces a file nothing can
+ # reach, on a repo that looks like it has a checkpoint.
+ with pytest.raises(ValueError, match = "prequant_filenames"):
+ build.upload_destination(zimage, "fp8", rotated = False, safetensors = True)
+ assert (
+ build.upload_destination(
+ zimage,
+ "fp8",
+ rotated = False,
+ safetensors = True,
+ override = "Z-Image-Turbo-FP8.safetensors",
+ )
+ == "Z-Image-Turbo-FP8.safetensors"
+ )
+
+
+def test_a_safetensors_build_refuses_a_declared_name_that_reads_as_a_pickle():
+ build = _script()
+ h3 = detect_video_family("MiniMaxAI/MiniMax-H3")
+ assert h3 is not None
+ # H3 declares a .pt name for int8. Uploading a safetensors artifact there gives every loader a
+ # file whose extension says pickle and whose bytes are not one, so the load fails for a reason
+ # that has nothing to do with the real mistake. Refuse at build time and say which name to fix.
+ with pytest.raises(ValueError, match = r"does not end in '\.safetensors'"):
+ build.upload_destination(h3, "int8", rotated = False, safetensors = True)
+
+
+def test_a_rotated_pickle_build_refuses_a_declared_name_that_reads_as_safetensors():
+ """The mirror image, and the one a family reaches by MOVING to safetensors.
+
+ Once a family points prequant_filenames at a .safetensors artifact, a rotated pickle build for
+ that same family would publish torch.save bytes under a safetensors name. Every loader
+ dispatches on the extension, hands the file to safe_open and rejects it, so the artifact is
+ unopenable for a reason that says nothing about the real mistake. Guarding only the
+ safetensors-build direction left this one live.
+ """
+ build = _script()
+ fam = types.SimpleNamespace(
+ name = "qwen-image-2.1",
+ prequant_filenames = (("fp8", "Qwen-Image-2.1-FP8.safetensors"),),
+ )
+ with pytest.raises(ValueError, match = r"does not end in '\.pt'"):
+ build.upload_destination(fam, "fp8", rotated = True, safetensors = False)
+
+
+def test_an_override_still_has_to_match_the_container_it_is_naming():
+ """The escape hatch skips the family table, not the extension.
+
+ Every loader dispatches on the extension alone, so a safetensors build published as ``.pt`` is
+ read as a pickle and a pickle published as ``.safetensors`` is read from a header it does not
+ have. Both upload cleanly and neither can ever be opened, after the hours the quantization
+ took, which is why this is refused before the upload rather than reported after it.
+ """
+ build = _script()
+ zimage = detect_family("Tongyi-MAI/Z-Image-Turbo", override = "z-image")
+ assert zimage is not None
+
+ with pytest.raises(ValueError, match = r"does not end in '\.safetensors'"):
+ build.upload_destination(
+ zimage, "fp8", rotated = False, safetensors = True, override = "Z-Image-Turbo-FP8.pt"
+ )
+ with pytest.raises(ValueError, match = r"does not end in '\.pt'"):
+ build.upload_destination(
+ zimage,
+ "fp8",
+ rotated = True,
+ safetensors = False,
+ override = "Z-Image-Turbo-FP8.safetensors",
+ )
+ # The matching pairs are untouched, including the rotated escape hatch above.
+ assert (
+ build.upload_destination(
+ zimage, "fp8", rotated = True, override = "Z-Image-Turbo-FP8-ConvRot.pt"
+ )
+ == "Z-Image-Turbo-FP8-ConvRot.pt"
+ )
+ assert (
+ build.upload_destination(
+ zimage,
+ "fp8",
+ rotated = False,
+ safetensors = True,
+ override = "Z-Image-Turbo-FP8.safetensors",
+ )
+ == "Z-Image-Turbo-FP8.safetensors"
+ )
+
+
+def test_a_plain_safetensors_build_derives_the_name_the_loader_now_asks_for_first():
+ """The refusal above predates the derived chain leading with safetensors.
+
+ ``derived_prequant_filenames`` puts ``<Model>-<SCHEME>.safetensors`` ahead of both .pt
+ spellings, so the reachability that refusal protects is exactly what the chain supplies, and a
+ family with no declared entry should not have to pass an override it could compute itself.
+ """
+ build = _script()
+ zimage = detect_family("Tongyi-MAI/Z-Image-Turbo", override = "z-image")
+ assert zimage is not None
+
+ name = build.upload_destination(
+ zimage,
+ "fp8",
+ rotated = False,
+ safetensors = True,
+ upload_repo = "unsloth/Z-Image-Turbo-FP8",
+ )
+ assert name == "Z-Image-Turbo-FP8.safetensors", name
+ # And it is really the first name the loader asks that repo for, read from the resolver
+ # rather than restated here, so the two cannot drift apart.
+ from core.inference.diffusion_prequant import derived_prequant_filenames
+
+ assert derived_prequant_filenames("unsloth/Z-Image-Turbo-FP8", "fp8")[0] == name
+
+ # A ROTATED build still has no derived spelling that carries the marker, so it still refuses.
+ with pytest.raises(ValueError, match = "prequant_filenames"):
+ build.upload_destination(
+ zimage,
+ "fp8",
+ rotated = True,
+ safetensors = True,
+ upload_repo = "unsloth/Z-Image-Turbo-FP8",
+ )
+ # No upload repo means nothing to derive from, so it refuses rather than guessing.
+ with pytest.raises(ValueError, match = "prequant_filenames"):
+ build.upload_destination(zimage, "fp8", rotated = False, safetensors = True)
diff --git a/studio/backend/tests/test_diffusion_auto_policy.py b/studio/backend/tests/test_diffusion_auto_policy.py
index 08463868329..765fb191a76 100644
--- a/studio/backend/tests/test_diffusion_auto_policy.py
+++ b/studio/backend/tests/test_diffusion_auto_policy.py
@@ -26,7 +26,9 @@ def _assume_the_restricted_load_is_available(monkeypatch):
Without this, a machine with no (or a skewed) torchao turns every hosted-prequant decision
below into "keep the dense weights". The capability is covered in test_diffusion_prequant.py."""
import core.inference.diffusion_prequant as _pq
- monkeypatch.setattr(_pq, "restricted_prequant_load_supported", lambda scheme = None: True)
+ monkeypatch.setattr(
+ _pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
+ )
from core.inference.diffusion_auto_policy import (
diff --git a/studio/backend/tests/test_diffusion_backend.py b/studio/backend/tests/test_diffusion_backend.py
index fd0a999df91..88ba298cb4f 100644
--- a/studio/backend/tests/test_diffusion_backend.py
+++ b/studio/backend/tests/test_diffusion_backend.py
@@ -5686,7 +5686,7 @@ _HOSTED_PREQUANT = types.SimpleNamespace(
kind = "repo",
location = "unsloth/Z-Image-Turbo-FP8",
filename = "Z-Image-Turbo-FP8.pt",
- fallback_filename = "transformer_fp8.pt",
+ fallback_filenames = ("transformer_fp8.pt",),
)
@@ -8171,7 +8171,7 @@ def test_download_plan_counts_a_cached_lower_auto_prequant(monkeypatch):
kind = "repo",
location = "unsloth/Qwen-Image-FP8",
filename = "Qwen-Image-INT8.pt",
- fallback_filename = "transformer_int8.pt",
+ fallback_filenames = ("transformer_int8.pt",),
)
_fake_hf_api(
monkeypatch,
@@ -11622,7 +11622,7 @@ def test_a_prequant_repo_missing_its_artifact_marks_the_plan_incomplete(monkeypa
kind = "repo",
location = "unsloth/some-prequant",
filename = "transformer_fp8.safetensors",
- fallback_filename = "transformer.fp8.safetensors",
+ fallback_filenames = ("transformer.fp8.safetensors",),
)
monkeypatch.setattr(diffusion_mod, "usable_prequant_source", lambda *a, **k: source)
monkeypatch.setattr(diffusion_mod, "select_transformer_quant_scheme", lambda *a, **k: "fp8")
diff --git a/studio/backend/tests/test_diffusion_convrot.py b/studio/backend/tests/test_diffusion_convrot.py
index 4b5c54894f9..2990b1cc24d 100644
--- a/studio/backend/tests/test_diffusion_convrot.py
+++ b/studio/backend/tests/test_diffusion_convrot.py
@@ -315,9 +315,9 @@ def test_h3_int8_resolves_to_the_rotated_artifact_with_the_plain_one_behind_it()
src = pq.resolve_prequant_source(fam, "int8")
assert src.location == "unsloth/MiniMax-H3-FP8"
assert src.filename == "MiniMax-H3-INT8-ConvRot.pt"
- assert src.fallback_filename == "MiniMax-H3-INT8.pt"
+ assert "MiniMax-H3-INT8.pt" in src.fallback_filenames
# fp8 is untouched: one artifact, the derived name.
- assert pq.resolve_prequant_source(fam, "fp8").filename == "MiniMax-H3-FP8.pt"
+ assert pq.resolve_prequant_source(fam, "fp8").filename == "MiniMax-H3-FP8.safetensors"
# ── end to end through the prequant loader ────────────────────────────────────────
diff --git a/studio/backend/tests/test_diffusion_more_families.py b/studio/backend/tests/test_diffusion_more_families.py
index a7075b31910..5c4b8841dbd 100644
--- a/studio/backend/tests/test_diffusion_more_families.py
+++ b/studio/backend/tests/test_diffusion_more_families.py
@@ -399,17 +399,24 @@ def test_qwen_image_2512_routes_to_its_own_hosted_prequant():
def test_qwen_image_2512_prequant_filenames_match_its_repo():
- # The filename derives from the repo name, so the variant repo must serve <Model>-<SCHEME>.pt.
- from core.inference.diffusion_prequant import resolve_prequant_source
+ # The names derive from the repo name, so the variant repo must be asked for <Model>-<SCHEME>
+ # in both containers. The .pt is what that repo actually serves today and is asserted to stay
+ # in the chain: preferring safetensors is only allowed to ADD a name in front of it, never to
+ # replace it, or every checkpoint already published would stop resolving.
+ from core.inference.diffusion_prequant import candidate_filenames_of, resolve_prequant_source
fam = detect_family("Qwen/Qwen-Image-2512")
- for scheme, filename in (
- ("int8", "Qwen-Image-2512-INT8.pt"),
- ("fp8", "Qwen-Image-2512-FP8.pt"),
+ for scheme, safetensors_name, pickle_name in (
+ ("int8", "Qwen-Image-2512-INT8.safetensors", "Qwen-Image-2512-INT8.pt"),
+ ("fp8", "Qwen-Image-2512-FP8.safetensors", "Qwen-Image-2512-FP8.pt"),
):
source = resolve_prequant_source(fam, scheme, base_repo = "Qwen/Qwen-Image-2512")
assert source is not None
assert source.location == "unsloth/Qwen-Image-2512-FP8"
- assert source.filename == filename
+ names = list(candidate_filenames_of(source))
+ assert names[0] == safetensors_name, names
+ assert pickle_name in names[1:], names
+ # And the legacy repo-agnostic spelling stays last, for a repo predating the model-named one.
+ assert names[-1] == f"transformer_{scheme}.pt", names
def test_hidream_quant_schemes_not_denied_and_no_extra_excludes():
diff --git a/studio/backend/tests/test_diffusion_pipeline_prequant.py b/studio/backend/tests/test_diffusion_pipeline_prequant.py
index e8297b18887..fcfb93a6b61 100644
--- a/studio/backend/tests/test_diffusion_pipeline_prequant.py
+++ b/studio/backend/tests/test_diffusion_pipeline_prequant.py
@@ -27,7 +27,7 @@ MIB = 1024 * 1024
Z_IMAGE_REPO = "Tongyi-MAI/Z-Image-Turbo"
PREQUANT_REPO = "unsloth/Z-Image-Turbo-FP8"
-PREQUANT_FILE = "Z-Image-Turbo-FP8.pt"
+PREQUANT_FILE = "Z-Image-Turbo-FP8.safetensors"
PREQUANT_BYTES = 6000 * MIB
Z_IMAGE_INDEX = {
@@ -253,7 +253,9 @@ def test_a_gguf_pick_still_never_downloads_a_second_denoiser(monkeypatch):
def test_a_planned_pipeline_pick_is_sized_from_the_hub(monkeypatch, hub):
backend = DiffusionBackend()
monkeypatch.setattr(backend, "_target_for_ordinal", lambda *_a, **_k: _target())
- monkeypatch.setattr(pqmod, "restricted_prequant_load_supported", lambda _scheme: True)
+ monkeypatch.setattr(
+ pqmod, "restricted_prequant_load_supported", lambda _scheme, filename = None: True
+ )
assert backend._dit_prequant_plan_source(
_family(),
"pipeline",
@@ -290,7 +292,9 @@ def _settle_backend(
monkeypatch.setattr(
dmod, "select_transformer_quant_scheme", lambda target, mode, family = None: scheme
)
- monkeypatch.setattr(pqmod, "restricted_prequant_load_supported", lambda _scheme: True)
+ monkeypatch.setattr(
+ pqmod, "restricted_prequant_load_supported", lambda _scheme, filename = None: True
+ )
monkeypatch.setattr(
dmod,
"resolve_dense_quant_candidate",
@@ -691,7 +695,9 @@ def _load_backend(
monkeypatch.setattr(dmod, "_pipeline_quant_uncompilable_reason", lambda *_a, **_k: None)
monkeypatch.setattr(dmod, "stored_denoiser_precision", lambda *_a, **_k: None)
monkeypatch.setattr(dmod, "denoiser_modules", lambda pipe: [("transformer", object())])
- monkeypatch.setattr(pqmod, "restricted_prequant_load_supported", lambda _scheme: True)
+ monkeypatch.setattr(
+ pqmod, "restricted_prequant_load_supported", lambda _scheme, filename = None: True
+ )
plans: list = []
diff --git a/studio/backend/tests/test_diffusion_prequant.py b/studio/backend/tests/test_diffusion_prequant.py
index fef0085a632..33bead5ccc0 100644
--- a/studio/backend/tests/test_diffusion_prequant.py
+++ b/studio/backend/tests/test_diffusion_prequant.py
@@ -35,7 +35,7 @@ def _prequant_source(**overrides):
"kind": "repo",
"location": "unsloth/Z-Image-Turbo-FP8",
"filename": "Z-Image-Turbo-FP8.pt",
- "fallback_filename": "transformer_fp8.pt",
+ "fallback_filenames": ("transformer_fp8.pt",),
**overrides,
}
)
@@ -69,9 +69,13 @@ def test_resolve_family_repo_by_scheme():
fam = _fam(prequant_repos = (("fp8", "org/hosted-fp8"), ("int8", "org/hosted-int8")))
src = resolve_prequant_source(fam, "int8")
assert src.kind == "repo" and src.location == "org/hosted-int8"
- # Model-name convention first (repo scheme suffix stripped), legacy name as fallback.
- assert src.filename == "hosted-INT8.pt"
- assert src.fallback_filename == "transformer_int8.pt"
+ # Model-name convention first (repo scheme suffix stripped), safetensors ahead of the pickle,
+ # legacy name last.
+ assert src.candidate_filenames == (
+ "hosted-INT8.safetensors",
+ "hosted-INT8.pt",
+ "transformer_int8.pt",
+ )
def test_prequant_repo_filename_convention():
@@ -94,7 +98,7 @@ def test_resolve_variant_base_picks_variant_repo():
)
src = resolve_prequant_source(fam, "int8", base_repo = "Org/Model-DEV")
assert src.kind == "repo" and src.location == "org/dev-fp8"
- assert src.filename == "dev-INT8.pt"
+ assert src.filename == "dev-INT8.safetensors"
def test_resolve_variant_base_falls_back_to_default():
@@ -136,13 +140,20 @@ def test_resolve_prefers_a_family_declared_filename():
fam = dataclasses.replace(fam, prequant_filenames = (("int8", "Model-INT8-ConvRot.pt"),))
src = resolve_prequant_source(fam, "int8")
assert src.filename == "Model-INT8-ConvRot.pt"
- assert src.fallback_filename == "Model-INT8.pt"
- # Only for the scheme that declares one; everything else keeps today's derived/legacy pair.
+ assert src.fallback_filenames == (
+ "Model-INT8.safetensors",
+ "Model-INT8.pt",
+ "transformer_int8.pt",
+ )
+ # Only for the scheme that declares one; everything else keeps the plain derived chain.
other = resolve_prequant_source(
dataclasses.replace(fam, prequant_repos = (("fp8", "unsloth/Model-FP8"),)), "fp8"
)
- assert other.filename == "Model-FP8.pt"
- assert other.fallback_filename == "transformer_fp8.pt"
+ assert other.candidate_filenames == (
+ "Model-FP8.safetensors",
+ "Model-FP8.pt",
+ "transformer_fp8.pt",
+ )
def test_resolve_wrong_scheme_is_none():
@@ -175,7 +186,9 @@ def test_local_prequant_path_ready(tmp_path, monkeypatch):
def restricted_load_available(monkeypatch):
"""Whether this install could open a checkpoint depends on the host's torchao. The resolution
tests below are not about that, so pin it on."""
- monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda scheme = None: True)
+ monkeypatch.setattr(
+ pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
+ )
def test_usable_source_missing_path_is_none(tmp_path, monkeypatch, restricted_load_available):
@@ -926,9 +939,13 @@ def test_an_install_that_cannot_restrict_the_load_offers_no_prequant_source(monk
import os
fam = _fam(prequant_repos = (("int8", "org/hosted-int8"),))
- monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda scheme = None: True)
+ monkeypatch.setattr(
+ pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
+ )
assert pq.usable_prequant_source(fam, "int8") is not None
- monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda scheme = None: False)
+ monkeypatch.setattr(
+ pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: False
+ )
# Hosted and local alike: the loader refuses both, so neither is usable.
assert pq.usable_prequant_source(fam, "int8") is None
ckpt = tmp_path / "model.pt"
@@ -1270,10 +1287,13 @@ def test_prequant_checkpoint_cached_reads_only_the_cache(monkeypatch, tmp_path):
# The live root is asked first, and the model-name file resolves, so no legacy lookup.
assert asked == [("unsloth/Z-Image-Turbo-FP8", "Z-Image-Turbo-FP8.pt", "/models/hub")]
- # Only the legacy name on disk does NOT count: whether the repo publishes the canonical one
- # needs a network call, so this reads as "would download" and the GGUF runs.
+ # A cached name FURTHER DOWN the chain now counts. Primary-only was right while the primary
+ # was the only name a repo realistically hosted; with the chain leading on a safetensors name
+ # most repos do not have yet, primary-only would report every existing .pt repo as "would
+ # download several GB" and hand the pick to GGUF while its checkpoint sat in the cache. The
+ # preference is unaffected: the downloader still asks for the better name first.
ckpt.unlink()
- assert prequant_checkpoint_cached(source) is False
+ assert prequant_checkpoint_cached(source) is True
# Neither name cached -> same answer, for the ordinary reason.
legacy.unlink()
assert prequant_checkpoint_cached(source) is False
@@ -1865,3 +1885,211 @@ def test_the_floor_check_ignores_dense_and_unreadable_state_dicts():
assert pq._fp8_activation_floor_present({"w": object()}, None) is True
assert pq._fp8_activation_floor_present(None, None) is True
assert pq._fp8_activation_floor_present({}, None) is True
+
+
+def test_the_plan_only_commits_to_a_hosted_name_this_install_can_open(monkeypatch):
+ """The call that drops the released dense shards must ask both questions, not one.
+
+ The candidate chain now spans two containers, so "the repo has this name" and "this install can
+ open that name" have come apart. A repo still serving only the legacy pickle, met by an install
+ whose torch or torchao cannot restrict that load, would otherwise have the plan spend the
+ download and then refuse it with no dense weights left to fall back to.
+ """
+ from core.inference.diffusion import DiffusionBackend
+
+ class _Sibling:
+ def __init__(self, name, size):
+ self.rfilename, self.size = name, size
+
+ class _Info:
+ siblings = [_Sibling("Model-FP8.pt", 4096)]
+
+ class _Api:
+ def __init__(self, *a, **k):
+ pass
+
+ def model_info(self, *a, **k):
+ return _Info()
+
+ import huggingface_hub
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
+ source = pq.PrequantSource(
+ kind = "repo",
+ location = "unsloth/Model-FP8",
+ filename = "Model-FP8.safetensors",
+ fallback_filenames = ("Model-FP8.pt",),
+ )
+
+ # An install that CAN open the pickle commits to it: the name exists and is readable.
+ monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda *a, **k: True)
+ assert DiffusionBackend._prequant_source_hub_entry(source, None, scheme = "fp8") == (
+ "unsloth/Model-FP8",
+ "Model-FP8.pt",
+ 4096,
+ )
+
+ # One that cannot reports the miss instead, which is what keeps the dense shards in the pull.
+ monkeypatch.setattr(
+ pq,
+ "restricted_prequant_load_supported",
+ lambda scheme = None, filename = None: bool(filename) and filename.endswith(".safetensors"),
+ )
+ failures: list = []
+ assert DiffusionBackend._prequant_source_hub_entry(source, None, failures, scheme = "fp8") is None
+ assert failures, "an unopenable artifact has to leave the plan marked partial"
+
+
+def test_the_runtime_resolver_applies_the_same_capability_filter_as_the_plan(monkeypatch):
+ """Plan and runtime have to agree on WHICH artifact, not only on whether there is one.
+
+ With only the plan filtering, a repo hosting both containers has the plan stage the readable
+ one while the resolver fetches the other, spends a second multi-gigabyte download to fail on
+ it, and falls back to dense weights the plan had already left out.
+ """
+ asked: list = []
+
+ def _download(
+ source,
+ name,
+ hf_token,
+ cache_dir,
+ *,
+ propagate_missing,
+ local_files_only = False,
+ ):
+ asked.append(name)
+ return "/tmp/" + name
+
+ monkeypatch.setattr(pq, "_download_checkpoint_name", _download)
+ monkeypatch.setattr(
+ pq,
+ "restricted_prequant_load_supported",
+ lambda scheme = None, filename = None: not str(filename or "").endswith(".safetensors"),
+ )
+ source = pq.PrequantSource(
+ kind = "repo",
+ location = "unsloth/Model-FP8",
+ filename = "Model-FP8.safetensors",
+ fallback_filenames = ("Model-FP8.pt",),
+ )
+ assert pq._resolve_checkpoint_path(source, None, scheme = "fp8") == "/tmp/Model-FP8.pt"
+ assert asked == ["Model-FP8.pt"], f"the unreadable container was fetched anyway: {asked}"
+
+ # No scheme keeps the whole chain, for the callers that have none to offer.
+ asked.clear()
+ assert pq._resolve_checkpoint_path(source, None) == "/tmp/Model-FP8.safetensors"
+ assert asked == ["Model-FP8.safetensors"], asked
+
+
+def test_a_cached_pickle_is_not_evidence_for_a_safetensors_artifact(monkeypatch):
+ """The derived safetensors name is a guess, and the cache probe walks every candidate, so a
+ cached legacy ``.pt`` would satisfy the evidence gate for an install that cannot open one.
+ Planning would then drop the dense shards and resolve neither file."""
+ fam = DiffusionFamily(
+ name = "probe-fam",
+ pipeline_class = "ProbePipeline",
+ transformer_class = "ProbeTransformer",
+ base_repo = "probe/Probe",
+ prequant_repos = (("fp8", "unsloth/Probe-FP8"),),
+ )
+ # This install reads safetensors and cannot deserialize a pickle.
+ monkeypatch.setattr(
+ pq,
+ "restricted_prequant_load_supported",
+ lambda scheme = None, filename = None: str(filename or "").endswith(".safetensors"),
+ )
+ cached: dict = {}
+ monkeypatch.setattr(
+ pq,
+ "cached_checkpoint_path",
+ lambda source, cache_dir = None, names = None: next(
+ (v for k, v in cached.items() if names is None or k in names), None
+ ),
+ )
+ # A cached .pt only: no evidence for the derived safetensors name, so no usable source.
+ cached["Probe-FP8.pt"] = "/cache/Probe-FP8.pt"
+ assert pq.usable_prequant_source(fam, "fp8", base_repo = "probe/Probe") is None
+ # The safetensors artifact really being in the cache IS evidence.
+ cached["Probe-FP8.safetensors"] = "/cache/Probe-FP8.safetensors"
+ assert pq.usable_prequant_source(fam, "fp8", base_repo = "probe/Probe") is not None
+
+
+def test_an_unreachable_hub_is_reported_as_itself_not_blamed_on_the_last_candidate(monkeypatch):
+ """Online, LocalEntryNotFoundError means the Hub could not be asked, not "this name is absent".
+
+ It subclasses EntryNotFoundError, so catching the base while walking the candidate chain would
+ spend a full attempt on every remaining name and then report the LAST one's error instead of the
+ connection failure that actually happened.
+ """
+ from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError
+
+ asked: list = []
+
+ def _dl(
+ repo_id,
+ filename,
+ token = None,
+ cache_dir = None,
+ local_files_only = False,
+ ):
+ asked.append(filename)
+ raise LocalEntryNotFoundError("connection error")
+
+ hub = types.ModuleType("huggingface_hub")
+ hub.hf_hub_download = _dl
+ monkeypatch.setitem(sys.modules, "huggingface_hub", hub)
+
+ source = PrequantSource(
+ kind = "repo",
+ location = "org/hosted-fp8",
+ filename = "Hosted-FP8.safetensors",
+ fallback_filenames = ("Hosted-FP8.pt", "transformer_fp8.pt"),
+ )
+ with pytest.raises(LocalEntryNotFoundError):
+ pq._resolve_checkpoint_path(source, None, None)
+ assert asked == ["Hosted-FP8.safetensors"], asked
+
+ # Offline, the same exception IS the only verdict there is, so the chain must be walked.
+ asked.clear()
+ with pytest.raises(EntryNotFoundError):
+ pq._resolve_checkpoint_path(source, None, None, local_files_only = True)
+ assert asked == ["Hosted-FP8.safetensors", "Hosted-FP8.pt", "transformer_fp8.pt"], asked
+
+
+def test_a_cached_name_this_install_cannot_open_is_not_a_cache_hit(monkeypatch, tmp_path):
+ """Both directions, because both end with the plan dropping the dense shards for nothing.
+
+ A cached ``.safetensors`` on a host without torchao's flatten helpers is as unusable as a cached
+ ``.pt`` on a host that cannot restrict a pickle load, and ``_resolve_checkpoint_path`` filters
+ out exactly the file the hit was about.
+ """
+ source = PrequantSource(
+ kind = "repo",
+ location = "org/hosted-fp8",
+ filename = "Hosted-FP8.safetensors",
+ fallback_filenames = ("Hosted-FP8.pt",),
+ )
+ cached = {"Hosted-FP8.safetensors": str(tmp_path / "st"), "Hosted-FP8.pt": None}
+ monkeypatch.setattr(pq, "_cached_in_root", lambda src, root, name = None: cached.get(name))
+
+ monkeypatch.setattr(
+ pq, "restricted_prequant_load_supported", lambda scheme = None, name = None: True
+ )
+ assert pq.cached_checkpoint_path(source) == str(tmp_path / "st")
+
+ # The install can read a pickle but not a safetensors artifact: the only cached name is one it
+ # could never open, so this is a miss and the dense shards stay in the plan.
+ monkeypatch.setattr(
+ pq,
+ "restricted_prequant_load_supported",
+ lambda scheme = None, name = None: not str(name).endswith(".safetensors"),
+ )
+ assert pq.cached_checkpoint_path(source) is None
+
+ # And it must still never raise, whatever the readability probe does.
+ def _boom(scheme = None, name = None):
+ raise RuntimeError("torchao exploded")
+
+ monkeypatch.setattr(pq, "restricted_prequant_load_supported", _boom)
+ assert pq.cached_checkpoint_path(source) == str(tmp_path / "st")
diff --git a/studio/backend/tests/test_prequant_safetensors.py b/studio/backend/tests/test_prequant_safetensors.py
new file mode 100644
index 00000000000..1a0f0a0d2a2
--- /dev/null
+++ b/studio/backend/tests/test_prequant_safetensors.py
@@ -0,0 +1,419 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The safetensors pre-quant container: its own round-trip, and how the loaders dispatch to it.
+
+Two layers, deliberately separated. The dispatch tests are hermetic -- they never touch torchao or
+safetensors -- because what they assert is routing: which reader a name selects, which gate a name
+answers, which source survives planning. The round-trip tests are the opposite and are skipped
+without the real libraries, because a fake that "round-trips" proves nothing about a format whose
+entire risk is in the metadata contract.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import pytest
+
+import core.inference.diffusion_prequant as pq
+import core.inference.prequant_safetensors as ps
+from core.inference.diffusion_families import DiffusionFamily
+
+
+def _family(**overrides) -> DiffusionFamily:
+ return DiffusionFamily(
+ **{
+ "name": "test-fam",
+ "base_repo": "org/base",
+ "pipeline_class": "TestPipeline",
+ "transformer_class": "TestTransformer",
+ **overrides,
+ }
+ )
+
+
+# --------------------------------------------------------------------------------------- dispatch
+
+
+ ("name", "expected"),
+ [
+ ("Model-FP8.safetensors", True),
+ ("Model-FP8.SAFETENSORS", True),
+ ("/abs/path/to/Model-FP8.safetensors", True),
+ ("Model-FP8.pt", False),
+ ("transformer_fp8.pt", False),
+ # A name that merely CONTAINS the word is not the container. Dispatch is on the extension
+ # because that is what was asked of the Hub, not on anything resembling a sniff.
+ ("safetensors-notes.pt", False),
+ (None, False),
+ ("", False),
+ ],
+)
+def test_is_safetensors_checkpoint(name, expected):
+ assert ps.is_safetensors_checkpoint(name) is expected
+
+
+def test_load_dispatches_on_extension(monkeypatch):
+ """The two readers are picked by name, and neither is consulted for the other's file."""
+ calls = []
+ monkeypatch.setattr(
+ ps, "load_prequant_safetensors", lambda path, **kw: calls.append(("safetensors", path))
+ )
+ monkeypatch.setattr(
+ pq, "_torch_load_prequant", lambda path, **kw: calls.append(("pickle", path))
+ )
+ pq._load_prequant_checkpoint("/x/Model-FP8.safetensors")
+ pq._load_prequant_checkpoint("/x/Model-FP8.pt", map_location = "cpu")
+ assert calls == [("safetensors", "/x/Model-FP8.safetensors"), ("pickle", "/x/Model-FP8.pt")]
+
+
+def test_safetensors_needs_no_pickle_allowlist(monkeypatch):
+ """The whole point of the container: an install that cannot open a pickle can still load one.
+
+ ``restricted_prequant_load_supported`` is the gate that makes ``video.py`` refuse a pre-quant
+ checkpoint outright. A safetensors artifact names no constructors, so answering the pickle's
+ question for it would strand exactly the installs this format exists to unblock.
+ """
+ monkeypatch.setattr(pq, "_register_prequant_safe_globals", lambda: False)
+ monkeypatch.setattr(ps, "safetensors_prequant_supported", lambda: True)
+
+ assert pq.restricted_prequant_load_supported("fp8") is False
+ assert pq.restricted_prequant_load_supported("fp8", "Model-FP8.pt") is False
+ assert pq.restricted_prequant_load_supported("fp8", "Model-FP8.safetensors") is True
+
+
+def test_safetensors_gate_still_needs_torchao_helpers(monkeypatch):
+ """The other direction: no flatten/unflatten means no safetensors load, so say so up front
+ rather than letting planning drop the dense shards for a file nothing can read."""
+ monkeypatch.setattr(pq, "_register_prequant_safe_globals", lambda: True)
+ monkeypatch.setattr(ps, "safetensors_prequant_supported", lambda: False)
+ assert pq.restricted_prequant_load_supported("fp8", "Model-FP8.safetensors") is False
+
+
+def test_usable_source_survives_a_pickle_only_refusal(monkeypatch):
+ """Regression for the ordering: the gate is asked about the RESOLVED names, not the scheme.
+
+ Asking first and resolving second (what this did before safetensors existed) returns None for a
+ repo whose primary artifact is safetensors, on an install that merely cannot open pickles. The
+ pre-quant is then invisible to memory planning and the load silently runs dense.
+ """
+ fam = _family(
+ prequant_repos = (("fp8", "org/model-fp8"),),
+ prequant_filenames = (("fp8", "Model-FP8.safetensors"),),
+ )
+ monkeypatch.setattr(pq, "_register_prequant_safe_globals", lambda: False)
+ monkeypatch.setattr(ps, "safetensors_prequant_supported", lambda: True)
+
+ src = pq.usable_prequant_source(fam, "fp8")
+ assert src is not None
+ assert src.filename == "Model-FP8.safetensors"
+
+
+def test_usable_source_still_refused_when_nothing_is_readable(monkeypatch):
+ """A family with no DECLARED safetensors name, on a pickle-less install, keeps answering None.
+
+ Regression for a hazard the safetensors-first chain introduced. Every family now derives a
+ ``<Model>-<SCHEME>.safetensors`` candidate, so a naive "is any candidate readable" gate answers
+ yes on a pickle-less install even for a repo that hosts only ``.pt``. Planning would then budget
+ a 6 GB artifact, the download would 404 to the pickle, the pickle would be refused, and the
+ load would fall back to dense under a plan that never budgeted it: the evict-then-OOM this
+ function exists to prevent. A derived name is a guess and does not count as evidence.
+ """
+ fam = _family(prequant_repos = (("fp8", "org/model-fp8"),))
+ monkeypatch.setattr(pq, "_register_prequant_safe_globals", lambda: False)
+ monkeypatch.setattr(ps, "safetensors_prequant_supported", lambda: True)
+ monkeypatch.setattr(pq, "cached_checkpoint_path", lambda source, **kw: None)
+ assert pq.usable_prequant_source(fam, "fp8") is None
+
+
+def test_a_cached_safetensors_artifact_is_evidence_enough(monkeypatch):
+ """The other side of that guard: once the file is actually THERE, the pickle-less install may
+ plan for it. A cached candidate is evidence, exactly as a family-declared name is."""
+ fam = _family(prequant_repos = (("fp8", "org/model-fp8"),))
+ monkeypatch.setattr(pq, "_register_prequant_safe_globals", lambda: False)
+ monkeypatch.setattr(ps, "safetensors_prequant_supported", lambda: True)
+ monkeypatch.setattr(
+ pq, "cached_checkpoint_path", lambda source, **kw: "/cache/model-FP8.safetensors"
+ )
+ src = pq.usable_prequant_source(fam, "fp8")
+ assert src is not None and src.filename == "model-FP8.safetensors"
+
+
+def test_the_derived_chain_puts_safetensors_first_and_keeps_the_pickles(monkeypatch):
+ """The preference itself, and the promise that nothing is dropped behind it: an existing
+ .pt-only repo still resolves both of the names it resolves today."""
+ fam = _family(prequant_repos = (("fp8", "unsloth/Model-FP8"),))
+ src = pq.resolve_prequant_source(fam, "fp8")
+ assert src.candidate_filenames == (
+ "Model-FP8.safetensors",
+ "Model-FP8.pt",
+ "transformer_fp8.pt",
+ )
+
+
+def test_local_scheme_probe_reads_the_header_only(monkeypatch, tmp_path):
+ """The probe must not parse a multi-GB file to learn one string. For safetensors it reads the
+ header, and it must NOT reach the pickle reader on the way."""
+ path = tmp_path / "local-FP8.safetensors"
+ path.write_bytes(b"not really safetensors")
+
+ def _boom(*a, **kw):
+ raise AssertionError("the pickle reader was used for a safetensors artifact")
+
+ monkeypatch.setattr(pq, "_torch_load_prequant", _boom)
+ monkeypatch.setattr(
+ ps,
+ "read_prequant_header",
+ lambda p: {"format": pq.PREQUANT_FORMAT, "metadata": {"scheme": "int8"}},
+ )
+ assert pq.local_prequant_scheme(str(path)) == "int8"
+
+
+def test_local_scheme_probe_rejects_a_foreign_format(monkeypatch, tmp_path):
+ path = tmp_path / "other.safetensors"
+ path.write_bytes(b"x")
+ monkeypatch.setattr(
+ ps,
+ "read_prequant_header",
+ lambda p: {"format": "someone_elses_v1", "metadata": {"scheme": "int8"}},
+ )
+ assert pq.local_prequant_scheme(str(path)) is None
+
+
+def test_undotted_keys_are_refused_before_a_file_exists():
+ """torchao's unflatten splits every key on '.', so a root-level tensor writes fine and can
+ never be read back. Refuse at build time, naming the keys."""
+ assert ps.unsupported_state_dict_keys({"a.weight": 1, "pos_embed": 2}) == ["pos_embed"]
+ assert ps.unsupported_state_dict_keys({"a.weight": 1}) == []
+
+
+# ------------------------------------------------------------------------------------ round-trip
+
+
+def _real_libs():
+ pytest.importorskip("torch")
+ pytest.importorskip("safetensors")
+ pytest.importorskip("torchao")
+ if not ps.safetensors_prequant_supported():
+ pytest.skip("torchao is too old for flatten/unflatten_tensor_state_dict")
+
+
+def test_plain_tensor_round_trip(tmp_path):
+ """Plain tensors (the text-encoder artifact's whole state dict) survive with their metadata."""
+ _real_libs()
+ import torch
+
+ sd = {"enc.layer.weight": torch.ones(4, 4), "enc.layer.bias": torch.zeros(4)}
+ meta = {"scheme": "fp8", "base_model_id": "org/base", "min_features": 512}
+ path = str(tmp_path / "te.safetensors")
+ ps.save_prequant_safetensors(path, fmt = pq.PREQUANT_FORMAT, state_dict = sd, metadata = meta)
+
+ header = ps.read_prequant_header(path)
+ assert header == {"format": pq.PREQUANT_FORMAT, "metadata": meta}
+
+ ckpt = ps.load_prequant_safetensors(path)
+ assert ckpt["format"] == pq.PREQUANT_FORMAT
+ assert ckpt["metadata"] == meta
+ assert set(ckpt["state_dict"]) == set(sd)
+ for key, value in sd.items():
+ assert torch.equal(ckpt["state_dict"][key], value)
+
+
+def test_header_is_readable_as_a_torchao_checkpoint(tmp_path):
+ """Interop, and the trap that makes it fail silently.
+
+ torchao hands back metadata ALREADY JSON-encoded. Encoding it again round-trips perfectly
+ against our own reader and still produces a header ``is_metadata_torchao`` rejects, so every
+ transformers / diffusers loader refuses the file and nothing here would notice.
+ """
+ _real_libs()
+ import torch
+ from safetensors import safe_open
+ from torchao.prototype.safetensors.safetensors_utils import is_metadata_torchao
+
+ path = str(tmp_path / "x.safetensors")
+ ps.save_prequant_safetensors(
+ path,
+ fmt = pq.PREQUANT_FORMAT,
+ state_dict = {"enc.layer.weight": torch.ones(2, 2)},
+ metadata = {"scheme": "fp8"},
+ )
+ with safe_open(path, framework = "pt") as handle:
+ raw = handle.metadata() or {}
+
+ assert is_metadata_torchao(raw)
+ # Our two keys ride alongside torchao's and are ignored by it.
+ assert raw[ps.UNSLOTH_FORMAT_KEY] == pq.PREQUANT_FORMAT
+ assert json.loads(raw[ps.UNSLOTH_METADATA_KEY]) == {"scheme": "fp8"}
+ assert "tensor_names" in raw
+
+
+def test_truncated_checkpoint_is_named_not_silently_partial(tmp_path):
+ """A file whose header does not account for every tensor is refused with the tensor named,
+ rather than reaching load_state_dict as a bare missing-key error."""
+ _real_libs()
+ import torch
+ from safetensors import safe_open
+ from safetensors.torch import save_file
+
+ path = str(tmp_path / "x.safetensors")
+ ps.save_prequant_safetensors(
+ path,
+ fmt = pq.PREQUANT_FORMAT,
+ state_dict = {"enc.layer.weight": torch.ones(2, 2)},
+ metadata = {"scheme": "fp8"},
+ )
+ with safe_open(path, framework = "pt") as handle:
+ raw = dict(handle.metadata() or {})
+ tensors = {k: handle.get_tensor(k) for k in handle.keys()}
+
+ # An extra tensor the header never describes: the shape a truncated or edited artifact takes.
+ tensors["enc.layer.stray"] = torch.zeros(2)
+ stray = str(tmp_path / "stray.safetensors")
+ save_file(tensors, stray, metadata = raw)
+
+ with pytest.raises(ValueError, match = "does not account for"):
+ ps.load_prequant_safetensors(stray)
+
+
[email protected]("scheme", ["fp8", "int8"])
+def test_quantized_round_trip_is_exact(tmp_path, scheme):
+ """The case the format exists for: torchao weight subclasses, reconstructed bit for bit and
+ accepted by ``load_state_dict(strict=True)`` on a module quantized the same way."""
+ _real_libs()
+ import torch
+
+ if not torch.cuda.is_available():
+ pytest.skip("fp8 / int8 quantization needs CUDA")
+ from torchao.quantization import quantize_
+
+ from core.inference.diffusion_transformer_quant import _make_quant_config, make_filter_fn
+
+ def build():
+ module = (
+ torch.nn.Sequential(
+ torch.nn.Linear(1024, 1024, bias = False),
+ torch.nn.Linear(1024, 1024, bias = True),
+ )
+ .cuda()
+ .bfloat16()
+ )
+ quantize_(module, _make_quant_config(scheme), filter_fn = make_filter_fn(512))
+ return module
+
+ source = build()
+ state = {
+ k: (v.detach().to("cpu") if hasattr(v, "detach") else v)
+ for k, v in source.state_dict().items()
+ }
+ path = str(tmp_path / f"{scheme}.safetensors")
+ try:
+ ps.save_prequant_safetensors(
+ path, fmt = pq.PREQUANT_FORMAT, state_dict = state, metadata = {"scheme": scheme}
+ )
+ except ValueError as exc:
+ # A torchao too old to QUANTISE into a flattenable subclass (int8 before 0.18) must say so
+ # in its own terms rather than leak torchao's bare "Unsupported tensor type". Assert the
+ # message, then skip: the round-trip below is not a question this install can answer.
+ assert "torchao >= 0.18" in str(exc), exc
+ pytest.skip(f"this torchao cannot write {scheme} to safetensors: {exc}")
+
+ loaded = ps.load_prequant_safetensors(path)["state_dict"]
+ assert set(loaded) == set(state)
+ for key, value in state.items():
+ got, want = loaded[key], value
+ if hasattr(want, "dequantize"):
+ assert type(got) is type(want)
+ got, want = got.dequantize(), want.dequantize()
+ assert torch.equal(got, want)
+
+ build().load_state_dict(loaded, strict = True, assign = True)
+
+
+def test_the_windows_rocm_torchao_stub_is_not_safetensors_support(monkeypatch):
+ """The stub answers every ``torchao.*`` import with a fabricated callable, so importing the
+ flatten/unflatten pair proves nothing on Windows ROCm: both names bind, both return None, and
+ an install that reported support here would have planning drop the dense shards for a
+ checkpoint the loader can never rebuild. The pickle probe already asks the same question."""
+ import core._torchao_stub as stub
+ from core.inference import prequant_safetensors as ps
+ from core.inference.diffusion_prequant import restricted_prequant_load_supported
+
+ for name in [k for k in list(sys.modules) if k == "torchao" or k.startswith("torchao.")]:
+ monkeypatch.delitem(sys.modules, name, raising = False)
+ monkeypatch.setattr(stub, "_is_windows_rocm", lambda: True)
+ stub.install_torchao_windows_rocm_stub()
+ assert stub.is_stubbed("torchao"), "the stub did not install, so this proves nothing"
+ # The negative control: the import really does succeed against the stub.
+ from torchao.prototype.safetensors.safetensors_support import ( # noqa: F401
+ unflatten_tensor_state_dict,
+ )
+
+ assert ps._torchao_helpers() is None
+ assert ps.safetensors_prequant_supported() is False
+ # And the capability the planners ask is False for a safetensors name too, not only the pickle.
+ assert restricted_prequant_load_supported("fp8", "Model-FP8.safetensors") is False
+ assert restricted_prequant_load_supported("fp8", "Model-FP8.pt") is False
+
+
+def test_a_scheme_this_torchao_cannot_flatten_is_reported_before_the_build(monkeypatch):
+ """The helpers importing is not the same question as this scheme producing something they take.
+
+ Through torchao 0.17 int8 quantises to LinearActivationQuantizedTensor, which flatten refuses,
+ so the builder's container preflight passed and the failure arrived only after the download and
+ the hours of GPU quantization.
+ """
+ import torchao.quantization as tq
+ from core.inference import prequant_safetensors as ps
+
+ quantized: list = []
+ monkeypatch.setattr(tq, "quantize_", lambda mod, cfg, **kw: quantized.append(cfg))
+
+ def _refuses(state_dict):
+ raise ValueError("Unsupported tensor type: <class 'LinearActivationQuantizedTensor'>")
+
+ monkeypatch.setattr(ps, "_torchao_helpers", lambda: (_refuses, object()))
+ assert ps.scheme_is_flattenable("cfg") is False
+ assert quantized == ["cfg"], "the probe must actually quantize, not guess from a version"
+
+ # Flattens cleanly: supported.
+ monkeypatch.setattr(ps, "_torchao_helpers", lambda: (lambda sd: ({}, {}), object()))
+ assert ps.scheme_is_flattenable("cfg") is True
+
+ # An unrelated flatten failure is NOT evidence the scheme is unsupported, and a build must not
+ # be refused on it.
+ def _other(state_dict):
+ raise ValueError("something else entirely")
+
+ monkeypatch.setattr(ps, "_torchao_helpers", lambda: (_other, object()))
+ assert ps.scheme_is_flattenable("cfg") is None
+
+ # A config this torchao will not even apply is the same "no evidence" answer.
+ def _boom(mod, cfg, **kw):
+ raise RuntimeError("config needs CUDA")
+
+ monkeypatch.setattr(tq, "quantize_", _boom)
+ monkeypatch.setattr(ps, "_torchao_helpers", lambda: (_refuses, object()))
+ assert ps.scheme_is_flattenable("cfg") is None
+
+ # No helpers at all is a flat no.
+ monkeypatch.setattr(ps, "_torchao_helpers", lambda: None)
+ assert ps.scheme_is_flattenable("cfg") is False
+
+
+def test_the_real_installed_torchao_answers_the_int8_question(monkeypatch):
+ """Not a mock: the probe against the torchao actually installed, whichever way it answers."""
+ from core.inference.diffusion_transformer_quant import _make_quant_config
+ from core.inference.prequant_safetensors import scheme_is_flattenable
+
+ import torchao
+
+ answer = scheme_is_flattenable(_make_quant_config("int8"))
+ version = tuple(int(p) for p in torchao.__version__.split("+")[0].split(".")[:2])
+ if version < (0, 18):
+ assert answer is False, f"torchao {torchao.__version__} should refuse int8 flatten"
+ else:
+ assert answer is not False, f"torchao {torchao.__version__} should flatten int8"
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 9d290069448..c4fefb2396b 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -141,7 +141,9 @@ def _assume_the_restricted_load_is_available(monkeypatch):
tests are about the load/plan decisions; the capability is covered in
test_diffusion_prequant.py."""
import core.inference.diffusion_prequant as _pq
- monkeypatch.setattr(_pq, "restricted_prequant_load_supported", lambda scheme = None: True)
+ monkeypatch.setattr(
+ _pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
+ )
class _FakeDtype:
diff --git a/studio/backend/tests/test_video_prequant.py b/studio/backend/tests/test_video_prequant.py
index 06a3780ebf2..e2eb608d85e 100644
--- a/studio/backend/tests/test_video_prequant.py
+++ b/studio/backend/tests/test_video_prequant.py
@@ -36,7 +36,9 @@ def _assume_the_restricted_load_is_available(monkeypatch):
Without this, a machine with no (or a skewed) torchao turns every hosted-prequant decision
below into "keep the dense weights". The capability is covered in test_diffusion_prequant.py."""
import core.inference.diffusion_prequant as _pq
- monkeypatch.setattr(_pq, "restricted_prequant_load_supported", lambda scheme = None: True)
+ monkeypatch.setattr(
+ _pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
+ )
from core.inference.video_families import (
@@ -123,14 +125,13 @@ def test_both_h3_schemes_resolve_to_one_repo():
# ── repo-root naming ─────────────────────────────────────────────────────────────
@pytest.mark.parametrize(
"scheme, expected",
- # int8 is the ConvRot-rotated denoiser, which the family names explicitly; fp8 keeps the
- # derived <Model>-<SCHEME>.pt.
- [("int8", "MiniMax-H3-INT8-ConvRot.pt"), ("fp8", "MiniMax-H3-FP8.pt")],
+ # int8 is the ConvRot-rotated denoiser, which the family names explicitly; fp8 leads with the
+ # derived safetensors spelling, with <Model>-<SCHEME>.pt behind it.
+ [("int8", "MiniMax-H3-INT8-ConvRot.pt"), ("fp8", "MiniMax-H3-FP8.safetensors")],
)
def test_h3_resolves_the_primary_name_at_the_repo_root(scheme, expected):
- # The name the hosted repo actually publishes. It has to be the PRIMARY, not the fallback:
- # cached_checkpoint_path deliberately credits only the primary, so landing on the fallback
- # would report a cached checkpoint as "this would have to download" and hand the pick to GGUF.
+ # The name the hosted repo actually publishes has to come FIRST in the chain, because that is
+ # the order the downloader walks: a name behind it is only reached after the one ahead 404s.
fam = detect_video_family("MiniMaxAI/MiniMax-H3")
src = resolve_prequant_source(fam, scheme)
assert src.filename == expected
@@ -145,8 +146,13 @@ def test_h3_int8_keeps_the_plain_denoiser_as_its_fallback():
# this one takes the rotated file when the repo has it.
fam = detect_video_family("MiniMaxAI/MiniMax-H3")
src = resolve_prequant_source(fam, "int8")
- assert src.fallback_filename == "MiniMax-H3-INT8.pt"
- assert "/" not in src.fallback_filename and "\\" not in src.fallback_filename
+ # The declared rotated name leads; the derived chain follows, safetensors before the pickle.
+ assert src.fallback_filenames == (
+ "MiniMax-H3-INT8.safetensors",
+ "MiniMax-H3-INT8.pt",
+ "transformer_int8.pt",
+ )
+ assert all("/" not in n and "\\" not in n for n in src.candidate_filenames)
def test_the_h3_primary_name_is_what_memory_planning_credits():
@@ -183,10 +189,13 @@ def test_the_names_are_built_from_the_repo_and_the_scheme():
# One repo serves both schemes, so the -FP8 suffix on the repo must be stripped and REPLACED by
# the requested scheme rather than carried through.
fam = _fam(prequant_repos = (("int8", "unsloth/Test-FP8"), ("fp8", "unsloth/Test-FP8")))
- assert resolve_prequant_source(fam, "int8").filename == "Test-INT8.pt"
- assert resolve_prequant_source(fam, "fp8").filename == "Test-FP8.pt"
- # The legacy per-scheme name stays available for repos that have not been renamed.
- assert resolve_prequant_source(fam, "int8").fallback_filename == "transformer_int8.pt"
+ assert resolve_prequant_source(fam, "int8").filename == "Test-INT8.safetensors"
+ assert resolve_prequant_source(fam, "fp8").filename == "Test-FP8.safetensors"
+ # The pickle spellings stay available for repos that host no safetensors artifact.
+ assert resolve_prequant_source(fam, "int8").fallback_filenames == (
+ "Test-INT8.pt",
+ "transformer_int8.pt",
+ )
# ── task-keyed artifacts: one repo, one scheme, two denoiser partitions ──────────
@@ -230,7 +239,12 @@ def test_a_task_specific_artifact_gets_no_filename_fallback():
)
assert resolve_prequant_source(fam, "int8", task = "ref2va").fallback_filename is None
# The task-agnostic pick keeps its fallback, unchanged.
- assert resolve_prequant_source(fam, "int8").fallback_filename == "Test-INT8.pt"
+ assert resolve_prequant_source(fam, "int8").candidate_filenames == (
+ "Test-INT8-ConvRot.pt",
+ "Test-INT8.safetensors",
+ "Test-INT8.pt",
+ "transformer_int8.pt",
+ )
def test_a_scheme_without_a_task_row_resolves_exactly_what_it_did_before():
@@ -295,9 +309,9 @@ def test_h3_keyframe_and_text_only_resolve_exactly_what_they_resolved_before(tas
fam = detect_video_family("MiniMaxAI/MiniMax-H3")
int8 = resolve_prequant_source(fam, "int8", task = task)
assert int8.filename == "MiniMax-H3-INT8-ConvRot.pt"
- assert int8.fallback_filename == "MiniMax-H3-INT8.pt"
+ assert "MiniMax-H3-INT8.pt" in int8.fallback_filenames
fp8 = resolve_prequant_source(fam, "fp8", task = task)
- assert fp8.filename == "MiniMax-H3-FP8.pt"
+ assert fp8.filename == "MiniMax-H3-FP8.safetensors"
def test_the_h3_partition_task_matches_the_reference_workflow_name():
diff --git a/tests/test_padding_free_signature_gate.py b/tests/test_padding_free_signature_gate.py
index fa1869a174c..5764b08fb39 100644
--- a/tests/test_padding_free_signature_gate.py
+++ b/tests/test_padding_free_signature_gate.py
@@ -529,7 +529,12 @@ def test_a_class_that_disagrees_with_the_built_model_is_still_caught(monkeypatch
import unsloth.trainer as trainer_module
class _StubSFTTrainer:
- def __init__(self, model = None, args = None, **kwargs):
+ def __init__(
+ self,
+ model = None,
+ args = None,
+ **kwargs,
+ ):
# what actually gets built disagrees with what the config advertised
self.model = _NoKwargs() if isinstance(model, str) else model
self.args = args
@@ -607,7 +612,12 @@ def test_a_mixed_adapter_wrapper_is_unwrapped_to_the_checkpoint():
)
class _NarrowLlama(transformers.LlamaForCausalLM):
- def forward(self, input_ids = None, attention_mask = None, labels = None):
+ def forward(
+ self,
+ input_ids = None,
+ attention_mask = None,
+ labels = None,
+ ):
return super().forward(
input_ids = input_ids, attention_mask = attention_mask, labels = labels
)
diff --git a/unsloth/trainer.py b/unsloth/trainer.py
index 4b983104172..6bb5dbe0acc 100644
--- a/unsloth/trainer.py
+++ b/unsloth/trainer.py
@@ -319,7 +319,6 @@ def _mixed_adapter_wrappers():
"""
try:
from peft import PeftMixedModel
-
return ((PeftMixedModel, ("base_model", "model")),)
except Exception:
return ()
@@ -431,7 +430,6 @@ def _resolve_string_model_class(model_name, model_config, config_arg):
for architecture in getattr(model_config, "architectures", None) or ():
try:
import transformers
-
resolved = getattr(transformers, architecture, None)
except Exception:
resolved = None
@@ -482,7 +480,14 @@ def _resolve_string_model_class(model_name, model_config, config_arg):
# one fetch and not the other.
forward = {
key: init_kwargs[key]
- for key in ("revision", "subfolder", "token", "use_auth_token", "cache_dir", "code_revision")
+ for key in (
+ "revision",
+ "subfolder",
+ "token",
+ "use_auth_token",
+ "cache_dir",
+ "code_revision",
+ )
if key in init_kwargs
}
for auto_class in (
@@ -497,7 +502,6 @@ def _resolve_string_model_class(model_name, model_config, config_arg):
continue
try:
from transformers.dynamic_module_utils import get_class_from_dynamic_module
-
return get_class_from_dynamic_module(reference, model_name, **forward)
except Exception:
continue