Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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 abuild too old to honour the rotation, which then refuses the v2 tag and drops to the densedownload. 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 overridefrom 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_filenamepreferred = 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 2transformer_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 / 1e9print(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.pyindex 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 planlogger.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 Nonefrom huggingface_hub import HfApiinfo = 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 Nonediff --git a/studio/backend/core/inference/diffusion_prequant.py b/studio/backend/core/inference/diffusion_prequant.pyindex 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, downloadoutput bit-identical (LPIPS 0.0). The checkpoint carries the same scheme + ``min_features`` as theruntime 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 amutable 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 thecaller falls back to dense-quantise (then GGUF). Inert with nothing configured.@@ -26,6 +31,7 @@ from __future__ import annotationsimport threading as _threadingfrom dataclasses import dataclass+from collections.abc import Sequencefrom 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 flooranswer 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 Falserequired = _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: strlocation: strfilename: 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 loadrepo_id = Noneif 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 sameallowlisted ``weights_only`` load the loader uses, so probing a file that turns out not to be acheckpoint 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 Noneif key in _LOCAL_PREQUANT_SCHEME:return _LOCAL_PREQUANT_SCHEME[key]+ from .prequant_safetensors import is_safetensors_checkpoint, read_prequant_header+scheme: Optional[str] = Nonetry:- 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: theloader 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 Nonesrc = 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 Noneif 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 hitreturn None@@ -632,16 +810,17 @@ def load_prequantized_transformer(return Nonepath = _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 acache 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 Noneif 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:+ raisereturn Nonediff --git a/studio/backend/core/inference/diffusion_te_prequant.py b/studio/backend/core/inference/diffusion_te_prequant.pyindex 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 Nonestate_dict = ckpt["state_dict"]diff --git a/studio/backend/core/inference/prequant_safetensors.py b/studio/backend/core/inference/prequant_safetensors.pynew file mode 100644index 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 Truediff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex 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 Nonefrom 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.pyindex 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.utilimport sysfrom pathlib import Path+import types+import pytestfrom 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.pyindex 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 decisionbelow 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.pyindex 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(monkeypakind = "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.pyindex 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.pyindex 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_sourcefam = 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 Noneassert 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", namesdef 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.pyindex 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 * 1024Z_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 * MIBZ_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.pyindex 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 resolutiontests 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(monkimport osfam = _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 Noneckpt = 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 Trueassert pq._fp8_activation_floor_present(None, None) is Trueassert 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.pynew file mode 100644index 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.pyindex 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 intest_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.pyindex 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 decisionbelow 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(tasfam = 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_filenamesfp8 = 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.pyindex 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(monkeypatchimport unsloth.trainer as trainer_moduleclass _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 advertisedself.model = _NoKwargs() if isinstance(model, str) else modelself.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.pyindex 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):continuetry:from transformers.dynamic_module_utils import get_class_from_dynamic_module-return get_class_from_dynamic_module(reference, model_name, **forward)except Exception:continue