Wire hosted pre-quantized DiT checkpoints into the image families

Point prequant_repos for flux.1, flux.2-klein, flux.2-dev, qwen-image
(int8 only there; fp8 is family-denied), z-image and krea-2 at the
unsloth/<Model>-FP8 Hub repos carrying gate-validated int8 and fp8
transformer checkpoints, so the fast quant path loads the small
pre-quantized file instead of materialising the dense bf16 transformer
and quantising on device. Measured on FLUX.2-dev int8: build peak drops
from 60.7 GB (dense + quantize) to 30.7 GB (hosted prequant), identical
30.7 GB resident after either path since loading a checkpoint is
bit-identical to on-the-fly quantisation.

The hosted repos name files <Model>-<SCHEME>.pt, so resolve_prequant_source
now derives that model-name filename from the repo id (scheme suffix
stripped case-insensitively) and carries the legacy transformer_<scheme>.pt
as a fallback the resolver tries when the primary 404s, keeping older
repos loadable.

Wiring a repo also exposed a fallback hazard: with a prequant source
present, the dense-fit preflight used to be skipped entirely, so a failed
prequant download would fall through to the dense bf16 load the memory
plan never budgeted, OOMing after eviction. The preflight now always runs
and gates an allow_dense_fallback flag through _load_dense_quant_pipeline:
a dense misfit still skips the fast path when no prequant exists, but with
one it proceeds and a prequant failure raises to the GGUF build instead of
loading dense. The same flag is set when the auto-policy replans an
offloaded GGUF against a prequant-sized transient.

Tests updated to the new filename convention plus new coverage for the
derivation and the legacy-name fallback; the prequant-skips-refit test now
asserts the re-check runs and forbids the dense fallback. Verified end to
end on GPU: z-image int8 resolves the hosted repo, downloads the
model-name file and renders (6.8s load, 5.9 GB peak).
This commit is contained in:
Daniel Han 2026-07-17 05:47:45 +00:00
commit fbcf070fce
5 changed files with 168 additions and 28 deletions

View file

@ -46,7 +46,18 @@ 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"
assert src.filename == "transformer_int8.pt"
# 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"
def test_prequant_repo_filename_convention():
from core.inference.diffusion_prequant import prequant_repo_filename
assert prequant_repo_filename("unsloth/Z-Image-Turbo-FP8", "int8") == "Z-Image-Turbo-INT8.pt"
assert prequant_repo_filename("unsloth/Z-Image-Turbo-FP8", "fp8") == "Z-Image-Turbo-FP8.pt"
assert prequant_repo_filename("unsloth/Qwen-Image-2512-INT8", "int8") == "Qwen-Image-2512-INT8.pt"
assert prequant_repo_filename("org/Some-Model-quantized", "fp8") == "Some-Model-FP8.pt"
assert prequant_repo_filename("org/PlainRepo", "int8") == "PlainRepo-INT8.pt"
def test_resolve_wrong_scheme_is_none():
@ -480,6 +491,53 @@ def test_load_repo_source_allowed_without_optin(monkeypatch, tmp_path):
assert result is not None
def test_load_repo_source_falls_back_to_legacy_filename(monkeypatch, tmp_path):
# A repo still carrying the legacy transformer_<scheme>.pt name serves the download after
# the model-name filename 404s; both names are requested in order.
_FakeTransformer.calls = {}
_stub_torch_accelerate(monkeypatch, _good_ckpt())
monkeypatch.delenv(pq.ALLOW_LOCAL_PREQUANT_PATH_ENV, raising = False)
downloaded = tmp_path / "transformer_fp8.pt"
downloaded.write_bytes(b"x")
class _NotFound(Exception):
pass
errors = types.ModuleType("huggingface_hub.errors")
errors.EntryNotFoundError = _NotFound
requested = []
def _dl(repo_id, filename, token = None):
requested.append(filename)
if filename != "transformer_fp8.pt":
raise _NotFound(filename)
return str(downloaded)
hub = types.ModuleType("huggingface_hub")
hub.hf_hub_download = _dl
hub.errors = errors
monkeypatch.setitem(sys.modules, "huggingface_hub", hub)
monkeypatch.setitem(sys.modules, "huggingface_hub.errors", errors)
source = PrequantSource(
kind = "repo", location = "org/Z-Image-Turbo-FP8",
filename = "Z-Image-Turbo-FP8.pt", fallback_filename = "transformer_fp8.pt",
)
result = load_prequantized_transformer(
_FakeTransformer,
"Tongyi-MAI/Z-Image-Turbo",
source,
device = "cuda",
dtype = "bfloat16",
hf_token = None,
scheme = "fp8",
logger = None,
)
assert result is not None
assert requested == ["Z-Image-Turbo-FP8.pt", "transformer_fp8.pt"]
def test_load_local_path_outside_allowlist_refused(monkeypatch, tmp_path):
# Even with the opt-in set, a path OUTSIDE every allowlisted directory must not be
# unpickled: enabling one trusted dir is not a wildcard for arbitrary request paths.