Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio diffusion: read hosted files we already ship (LTX-2 fp8 DiT, Qwen-Image-2.1 bf16 VAE), and name a missing int8 text encoder file (#15318)

Daniel Hanb75d92c3eb1d
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 428f1ec8932..9154ca4755c 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -374,6 +374,7 @@ from .diffusion_precision import (
from .diffusion_te_prequant import supplied_component_pipe_kwargs, te_prequant_pipe_kwargs
from .diffusion_fast_load import _snapshot_dir as _load_snapshot_dir
from .diffusion_fast_load import start_load_prefetch, stop_prefetch, te_precast_components
+from .diffusion_hosted_vae import hosted_vae_pipe_kwargs, hosted_vae_plan_files
from .diffusion_fp16_variant import (
fp16_variant_enabled,
is_fp16_dtype,
@@ -4527,6 +4528,17 @@ class DiffusionBackend:
)
elif te_effective is not None and not te_quant_supported(target, te_effective):
te_reason = te_quant_unsupported_reason(te_effective)
+ if normalize_te_quant(te_mode) == "int8":
+ from .diffusion_te_prequant import explicit_int8_unavailable_reason
+ missing = explicit_int8_unavailable_reason(
+ fam,
+ base_repo,
+ target,
+ supplied = supplied_text_encoders or _active_supplied_text_encoders(),
+ local_files_only = local_files_only,
+ )
+ if missing:
+ te_reason = f"{missing}, and the fp8 fallback cannot run here ({te_reason})"
elif te_quant_needs_resident_weights(te_effective) and _memory_request_forces_offload(
memory_mode, cpu_offload
):
@@ -5745,6 +5757,19 @@ class DiffusionBackend:
).items()
if c not in replaced
}
+ vae_hosted_files = (
+ {}
+ if "vae" in replaced
+ else self._hosted_vae_plan_files(
+ fam,
+ kind,
+ base,
+ kwargs.get("gpu_ordinal"),
+ kwargs.get("hf_token"),
+ local_files_only,
+ )
+ )
+ kwargs["_hosted_vae_planned"] = bool(vae_hosted_files)
pipeline_planned = self._pipeline_planned_denoiser_scheme(
fam,
base = base,
@@ -5810,7 +5835,7 @@ class DiffusionBackend:
if kind == "gguf"
else False
),
- skip_te_components = tuple(te_prequant_files) + replaced,
+ skip_te_components = tuple(te_prequant_files) + replaced + tuple(vae_hosted_files),
skip_transformer_weights = skip_transformer_weights,
skipped_files_out = skipped_transformer_files,
local_files_only = local_files_only,
@@ -5854,7 +5879,7 @@ class DiffusionBackend:
te_hub_files = [
(repo, name, int(size or 0))
- for repo, files in te_prequant_files.values()
+ for repo, files in (*te_prequant_files.values(), *vae_hosted_files.values())
for name, size in te_prequant_unmirrored(repo, files)
]
expected += sum(size for _repo, _name, size in te_hub_files)
@@ -5908,6 +5933,7 @@ class DiffusionBackend:
kind = kind,
declared_files = resident_sizes,
prequant_bytes = _prequant_plan_bytes(te_prequant_files)
+ + _prequant_plan_bytes(vae_hosted_files)
+ (int(dit_prequant[2]) if skip_transformer_weights else 0),
extra_bf16_bytes = _predownload_encoder_bf16_bytes(
fam, te_prequant_files, pipeline_declared = bool(resident_sizes)
@@ -6200,6 +6226,32 @@ class DiffusionBackend:
with self._load_cancel_lock:
return tuple(dict.fromkeys(r for repos in self._draining_repos.values() for r in repos))
+ def _hosted_vae_plan_files(
+ self,
+ fam: Any,
+ kind: Optional[str],
+ base: Optional[str],
+ gpu_ordinal: Optional[int],
+ hf_token: Optional[str],
+ local_files_only: bool,
+ ) -> dict[str, tuple[str, list[tuple[str, int]]]]:
+ """``diffusion_hosted_vae.hosted_vae_plan_files`` at this pick's load dtype; {} for a family without one."""
+ if not getattr(fam, "hosted_bf16_vae", None):
+ return {}
+ try:
+ dtype = getattr(self._target_for_ordinal(fam, gpu_ordinal), "dtype", None)
+ except Exception: # noqa: BLE001 -- no target: keep the dense VAE
+ return {}
+ return hosted_vae_plan_files(
+ fam,
+ base,
+ kind = kind,
+ dtype = dtype,
+ hf_token = hf_token,
+ local_files_only = local_files_only,
+ logger = logger,
+ )
+
@staticmethod
def _te_prequant_plan_files(
fam: Any,
@@ -7129,6 +7181,13 @@ class DiffusionBackend:
if allow_device_probe
else {}
)
+ vae_hosted_files = (
+ self._hosted_vae_plan_files(
+ fam, kind, base, load_kwargs.get("gpu_ordinal"), hf_token, False
+ )
+ if allow_device_probe and "vae" not in replaced
+ else {}
+ )
# Settled before the listing: only a checkpoint that resolves on the Hub may drop the released shards.
pipeline_planned = (
self._pipeline_planned_denoiser_scheme(
@@ -7210,7 +7269,7 @@ class DiffusionBackend:
resident_file_sizes_out = resident_file_sizes,
revisions_out = revisions,
fetch_repos_out = fetch_repos,
- skip_te_components = tuple(te_files) + replaced,
+ skip_te_components = tuple(te_files) + replaced + tuple(vae_hosted_files),
skip_transformer_weights = skip_transformer_weights,
failures_out = plan_failures,
fp16_twins = kind == "pipeline"
@@ -7232,7 +7291,8 @@ class DiffusionBackend:
file_sizes.get(repo_id, {}).get(gguf_filename, sizes.get(repo_id, 0))
)
te_prequant_bytes = _prequant_plan_bytes(te_files)
- required_total += te_prequant_bytes
+ required_total += te_prequant_bytes + _prequant_plan_bytes(vae_hosted_files)
+ te_prequant_bytes += _prequant_plan_bytes(vae_hosted_files)
# The prequant replacing the dropped transformer/ shards is footprint nothing else reports.
dit_prequant_bytes = int(dit_prequant[2]) if dit_prequant is not None else 0
required_total += dit_prequant_bytes
@@ -7350,7 +7410,7 @@ class DiffusionBackend:
from .diffusion_te_prequant import te_prequant_unmirrored
- for repo, files in te_files.values():
+ for repo, files in (*te_files.values(), *vae_hosted_files.values()):
# A mirrored encoder still drops the dense shards above but is never staged: the Hub may not hold it.
files = te_prequant_unmirrored(repo, files)
if not files:
@@ -8382,6 +8442,7 @@ class DiffusionBackend:
_pipeline_prequant_skipped: tuple[str, ...] = (),
_prequant_unreachable: tuple[str, ...] = (),
_te_prequant_resolved: bool = True,
+ _hosted_vae_planned: bool = False,
# begin_load's ``normalize_token`` of the request token: False stays the anonymous sentinel.
_hub_token: Any = None,
) -> dict[str, Any]:
@@ -9670,6 +9731,22 @@ class DiffusionBackend:
),
)
)
+ # A miss reads vae/, fetched here when the plan dropped it.
+ if "vae" not in pipe_kwargs:
+ pipe_kwargs.update(
+ hosted_vae_pipe_kwargs(
+ fam,
+ fetch_base,
+ kind = kind,
+ dtype = dtype,
+ hf_token = hf_token,
+ local_files_only = local_files_only,
+ config_source = _base_local_dir,
+ cache_dir = hub_cache_dir(),
+ dense_staged = not _hosted_vae_planned,
+ logger = logger,
+ )
+ )
if pipeline_seed_scheme is not None:
from .diffusion_denoiser_prequant import (
denoiser_prequant_pipe_kwargs,
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index d9c3eef0953..6828ed15a19 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -212,6 +212,8 @@ class DiffusionFamily:
# diffusers; sd-cli also needs a (repo_id, filename) VAE + text encoder(s), each with a trailing SdCppModelFiles
# field name.
sd_cpp_vae: Optional[tuple[str, str]] = None
+ # (base_repo, repo_id, filename); read only by a bf16 pipeline load, every other dtype keeps vae/.
+ hosted_bf16_vae: tuple[tuple[str, str, str], ...] = field(default_factory = tuple)
# VAE latent-format override for sd-cli (--vae-format): "flux2" for FLUX.2, None otherwise
sd_cpp_vae_format: Optional[str] = None
sd_cpp_text_encoders: tuple[tuple[str, str, str], ...] = field(default_factory = tuple)
@@ -1062,6 +1064,14 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
# 2.1 has its own VAE class, so the qwen-image or Wan 2.2 file decodes to noise here
# rather than failing.
sd_cpp_vae = ("unsloth/Qwen-Image-2.1-FP8", "vae/qwen_image_2.1_vae_bf16.safetensors"),
+ # Bit-identical to the fp32 vae/ cast to bf16, so a bf16 render cannot change. Turbo's vae/ is already bf16.
+ hosted_bf16_vae = (
+ (
+ "Qwen/Qwen-Image-2.1",
+ "unsloth/Qwen-Image-2.1-FP8",
+ "vae/qwen_image_2.1_vae_bf16.safetensors",
+ ),
+ ),
# Qwen3-VL 8B, not Qwen2.5-VL, and supplied through --llm rather than --qwen2vl: the
# qwen2vl flag carries Qwen2-VL's vision preprocessing, which this encoder does not want.
# UD-Q4_K_XL, the Dynamic 2.0 rung, rather than the uniform Q4_K_M: same 4-bit class and
diff --git a/studio/backend/core/inference/diffusion_hosted_vae.py b/studio/backend/core/inference/diffusion_hosted_vae.py
new file mode 100644
index 00000000000..65ea65c336e
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_hosted_vae.py
@@ -0,0 +1,234 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hosted bf16 VAE for a bf16 diffusers pipeline load whose base repo stores its VAE in fp32.
+
+Same module as bf16 ``from_pretrained`` of the fp32 ``vae/``, half the bytes. Any load failure falls back to the
+base ``vae/``, fetching it when the plan dropped it. ``UNSLOTH_DIFFUSION_HOSTED_VAE=0`` disables.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+HOSTED_VAE_ENV = "UNSLOTH_DIFFUSION_HOSTED_VAE"
+HOSTED_VAE_COMPONENT = "vae"
+
+
+def hosted_vae_enabled() -> bool:
+ return (os.environ.get(HOSTED_VAE_ENV) or "").strip().lower() not in ("0", "off", "false", "no")
+
+
+def _is_bf16(dtype: Any) -> bool:
+ return str(dtype) in ("torch.bfloat16", "bfloat16")
+
+
+def hosted_vae_source(fam: Any, base: Optional[str]) -> Optional[tuple[str, str]]:
+ """``(repo_id, filename)`` of the hosted bf16 VAE for ``base`` in ``fam``, or None. Pure, never raises."""
+ try:
+ from .diffusion_families import canonical_base
+
+ key = canonical_base(str(base or "")).strip().lower()
+ if not key:
+ return None
+ for row in getattr(fam, "hosted_bf16_vae", ()) or ():
+ if isinstance(row, (tuple, list)) and len(row) == 3 and str(row[0]).lower() == key:
+ return str(row[1]), str(row[2])
+ except Exception: # noqa: BLE001 -- a bad table row is "no hosted VAE"
+ return None
+ return None
+
+
+def hosted_vae_wanted(
+ fam: Any, base: Optional[str], *, kind: Optional[str], dtype: Any
+) -> Optional[tuple[str, str]]:
+ """The hosted VAE this load would read, or None: switch on, full pipeline, bf16 load dtype, a row for the base."""
+ if not hosted_vae_enabled() or kind != "pipeline" or not _is_bf16(dtype):
+ return None
+ return hosted_vae_source(fam, base)
+
+
+def hosted_vae_plan_files(
+ fam: Any,
+ base: Optional[str],
+ *,
+ kind: Optional[str],
+ dtype: Any,
+ hf_token: Optional[str] = None,
+ local_files_only: bool = False,
+ logger: Any = None,
+) -> dict[str, tuple[str, list[tuple[str, int]]]]:
+ """``{"vae": (repo_id, [(filename, size)])}`` when the plan may drop the base's dense ``vae/`` weights, else {}.
+
+ Only a Hub-listed file earns the drop; offline, nothing is dropped. Never raises."""
+ src = hosted_vae_wanted(fam, base, kind = kind, dtype = dtype)
+ if src is None or local_files_only:
+ return {}
+ repo_id, filename = src
+ try:
+ from huggingface_hub import HfApi
+ infos = HfApi(token = hf_token or None).get_paths_info(repo_id, [filename])
+ size = next((int(getattr(i, "size", 0) or 0) for i in infos if i.path == filename), 0)
+ except Exception as exc: # noqa: BLE001 -- unresolvable: keep the dense VAE
+ if logger is not None:
+ logger.info("diffusion.hosted_vae: %s/%s not resolvable (%s)", repo_id, filename, exc)
+ return {}
+ if size <= 0:
+ return {}
+ return {HOSTED_VAE_COMPONENT: (repo_id, [(filename, size)])}
+
+
+def _vae_config(
+ source: str, *, hf_token: Optional[str], local_files_only: bool, cache_dir: Optional[str]
+) -> dict:
+ """The base's ``vae/config.json``, from a staged / local folder or the Hub cache."""
+ import json
+
+ local = os.path.join(os.path.expanduser(source), "vae", "config.json")
+ if not os.path.isfile(local):
+ from huggingface_hub import hf_hub_download
+ local = hf_hub_download(
+ source,
+ "vae/config.json",
+ cache_dir = cache_dir,
+ token = hf_token or None,
+ local_files_only = local_files_only,
+ )
+ with open(local, encoding = "utf-8") as fh:
+ return json.load(fh)
+
+
+def _build_hosted_vae(path: str, config: dict, dtype: Any, logger: Any) -> Any:
+ import diffusers
+
+ from .diffusion_comfy_components import (
+ ComponentFileError,
+ build_vae,
+ read_safetensors_header,
+ )
+
+ header, _meta = read_safetensors_header(path)
+ dtypes = {
+ str(v.get("dtype")) for k, v in header.items() if isinstance(v, dict) and "dtype" in v
+ }
+ if dtypes != {"BF16"}:
+ raise ComponentFileError(
+ f"'{os.path.basename(path)}' is not an all-bf16 VAE ({sorted(dtypes)})"
+ )
+ vae_cls = getattr(diffusers, str(config.get("_class_name") or ""), None)
+ if vae_cls is None:
+ raise ComponentFileError(
+ f"unknown VAE class {config.get('_class_name')!r} in the base config"
+ )
+ return build_vae(path, vae_cls = vae_cls, config = config, dtype = dtype, logger = logger)
+
+
+def hosted_vae_pipe_kwargs(
+ fam: Any,
+ base: Optional[str],
+ *,
+ kind: Optional[str],
+ dtype: Any,
+ hf_token: Optional[str] = None,
+ local_files_only: bool = False,
+ config_source: Optional[str] = None,
+ cache_dir: Optional[str] = None,
+ dense_staged: bool = True,
+ logger: Any = None,
+) -> dict[str, Any]:
+ """``{"vae": module}`` for ``from_pretrained``, or {} to let it read the base's ``vae/``.
+
+ ``dense_staged`` False: the plan dropped ``vae/``, so a failure must load the base VAE itself, never return {}."""
+ src = hosted_vae_wanted(fam, base, kind = kind, dtype = dtype)
+ source = config_source or str(base)
+ if src is None:
+ # Planned at bf16, loading at another dtype: the dropped vae/ must still be loaded.
+ if dense_staged:
+ return {}
+ if logger is not None:
+ logger.info(
+ "diffusion.hosted_vae: %s load does not take the bf16 VAE; loading the base vae/",
+ str(dtype).replace("torch.", ""),
+ )
+ return _dense_vae_kwargs(
+ base,
+ source,
+ dtype,
+ hf_token = hf_token,
+ local_files_only = local_files_only,
+ cache_dir = cache_dir,
+ )
+ repo_id, filename = src
+ try:
+ from .diffusion_te_prequant import te_prequant_mirror_path
+
+ # The plan leaves a mirrored file out of staging, so read it in place.
+ path = te_prequant_mirror_path(repo_id, filename)
+ if path is None:
+ from huggingface_hub import hf_hub_download
+ path = hf_hub_download(
+ repo_id,
+ filename,
+ cache_dir = cache_dir,
+ token = hf_token or None,
+ local_files_only = local_files_only,
+ )
+ config = _vae_config(
+ source, hf_token = hf_token, local_files_only = local_files_only, cache_dir = cache_dir
+ )
+ vae = _build_hosted_vae(path, config, dtype, logger)
+ if logger is not None:
+ logger.info(
+ "diffusion.hosted_vae: reading %s/%s (bf16, %d bytes) instead of the base vae/ weights",
+ repo_id,
+ filename,
+ os.path.getsize(path),
+ )
+ return {HOSTED_VAE_COMPONENT: vae}
+ except Exception as exc: # noqa: BLE001 -- fall back to the base repo's VAE
+ if logger is not None:
+ logger.warning(
+ "diffusion.hosted_vae: %s/%s not used (%s); loading the base vae/ instead",
+ repo_id,
+ filename,
+ exc,
+ )
+ if dense_staged:
+ return {}
+ return _dense_vae_kwargs(
+ base,
+ source,
+ dtype,
+ hf_token = hf_token,
+ local_files_only = local_files_only,
+ cache_dir = cache_dir,
+ )
+
+
+def _dense_vae_kwargs(
+ base: Optional[str],
+ source: str,
+ dtype: Any,
+ *,
+ hf_token: Optional[str],
+ local_files_only: bool,
+ cache_dir: Optional[str],
+) -> dict[str, Any]:
+ """The base's own ``vae/`` read by id, so the Hub cache supplies (or downloads) the weights the plan left out."""
+ import diffusers
+
+ config = _vae_config(
+ source, hf_token = hf_token, local_files_only = local_files_only, cache_dir = cache_dir
+ )
+ vae_cls = getattr(diffusers, str(config.get("_class_name") or ""))
+ kwargs: dict[str, Any] = {
+ "subfolder": "vae",
+ "torch_dtype": dtype,
+ "local_files_only": local_files_only,
+ }
+ if cache_dir:
+ kwargs["cache_dir"] = cache_dir
+ if hf_token:
+ kwargs["token"] = hf_token
+ return {HOSTED_VAE_COMPONENT: vae_cls.from_pretrained(str(base), **kwargs)}
diff --git a/studio/backend/core/inference/diffusion_precision.py b/studio/backend/core/inference/diffusion_precision.py
index f0a0f49d793..d4c9af7a8bc 100644
--- a/studio/backend/core/inference/diffusion_precision.py
+++ b/studio/backend/core/inference/diffusion_precision.py
@@ -452,7 +452,12 @@ def _quantize_text_encoders(
# the fallback only over a dense encoder and with torchao present; otherwise fp8.
skip = None
if skip is None:
- _note(logger, f"int8 has no keep-bf16 schedule for family '{family}'; using fp8")
+ _note(
+ logger,
+ f"the hosted int8 ConvRot text encoder for '{family}' did not load; using fp8"
+ if _family_hosts_te_int8(family)
+ else f"int8 has no keep-bf16 schedule for family '{family}'; using fp8",
+ )
mode = TE_QUANT_FP8
downgrade_reason = (
f"int8 has no measured keep-bf16 schedule for family '{family}' "
diff --git a/studio/backend/core/inference/diffusion_te_prequant.py b/studio/backend/core/inference/diffusion_te_prequant.py
index 0289d478223..2651a1edeb6 100644
--- a/studio/backend/core/inference/diffusion_te_prequant.py
+++ b/studio/backend/core/inference/diffusion_te_prequant.py
@@ -472,6 +472,55 @@ def explicit_int8_takes_hosted_file(
return len(takes) == len(TE_INT8_CONVROT_FILES[name]) and all(takes.values())
+def explicit_int8_unavailable_reason(
+ fam: Any,
+ base: Optional[str],
+ target: Any,
+ *,
+ supplied: Iterable[str] = (),
+ local_files_only: Optional[bool] = None,
+) -> Optional[str]:
+ """Why an explicit int8 request cannot take the int8 ConvRot file(s) ``fam`` names, or None when it can (or the
+ family names none). Names each unconfirmed file so an int8-only host (Apple Silicon) reports the missing file.
+ Never raises."""
+ try:
+ name = str(getattr(fam, "name", "") or "").strip().lower()
+ named = []
+ for component in TE_INT8_CONVROT_FILES.get(name, {}):
+ if component in set(supplied or ()):
+ continue
+ standalone: dict[str, str] = {}
+ if component == "text_encoder_4":
+ from .diffusion_hidream import HIDREAM_LLAMA_REPO
+ standalone = {"text_encoder_4": HIDREAM_LLAMA_REPO}
+ component_base = standalone.get(component) or base or getattr(fam, "base_repo", "")
+ got = te_prequant_sources_for_base(
+ fam,
+ str(component_base or ""),
+ te_quant_mode = "int8",
+ target = target,
+ components = (component,),
+ **({"standalone_component_bases": standalone} if standalone else {}),
+ ).get(component)
+ # Only a missing int8 FILE; other refusals carry their own reasons.
+ if got is None or got.kind != "repo" or _is_fp8_te_name(got.filename):
+ continue
+ if not te_prequant_sources_confirmed(
+ {component: replace(got, fallback_filenames = ())},
+ local_files_only = local_files_only,
+ ):
+ named.append(f"{got.location}/{got.filename}")
+ if not named:
+ return None
+ offline = bool(local_files_only) or _hub_offline()
+ where = (
+ "is not in the local cache (offline load)" if offline else "is not published on the Hub"
+ )
+ return f"the hosted int8 ConvRot text encoder {', '.join(named)} for {getattr(fam, 'name', fam)} {where}"
+ except Exception: # noqa: BLE001 - unanswerable: no reason to add
+ return None
+
+
def _auto_pick(te_quant_mode: Any) -> bool:
try:
from .diffusion_precision import te_quant_picked_automatically
@@ -1277,11 +1326,14 @@ def load_prequant_text_encoder(
_cast_fp8(encoder, target)
setattr(encoder, TE_PREQUANT_SCHEME_ATTR, "fp8")
if logger is not None:
+ # The FILE's scheme, not the request's (an fp8 fallback used to log int8).
logger.info(
- "diffusion.te_prequant: loaded %s %s checkpoint (%s)",
+ "diffusion.te_prequant: loaded %s fp8 checkpoint (%s)%s",
component,
- scheme,
- source.kind,
+ path if source.kind == "path" else f"{source.location}/{os.path.basename(path)}",
+ "; the int8 request took the fp8 file because the int8 ConvRot file is not available"
+ if scheme == "int8"
+ else "",
)
return encoder
except Exception as exc: # noqa: BLE001 - fall back to the dense download + cast
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index a71064319dd..1e0ad93233f 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -857,7 +857,11 @@ def _assert_video_precision_for_target(
return
# MPS runs a family's hosted int8 ConvRot encoder without fp8 (the loader's own rule), so an explicit int8 must not
# be rewritten to fp8 below and then refused for the fp8 support MPS lacks.
- from .diffusion_te_prequant import family_te_int8_convrot, int8_convrot_te_runs_on
+ from .diffusion_te_prequant import (
+ explicit_int8_unavailable_reason,
+ family_te_int8_convrot,
+ int8_convrot_te_runs_on,
+ )
if (
te_mode == "int8"
@@ -865,6 +869,19 @@ def _assert_video_precision_for_target(
and family_te_int8_convrot(fam, "text_encoder") is not None
and int8_convrot_te_runs_on(target)
):
+ # An unpublished file otherwise failed inside the load, after the eviction.
+ missing = explicit_int8_unavailable_reason(fam, getattr(fam, "base_repo", None), target)
+ if missing:
+ raise RuntimeError(
+ precision_refusal_message(
+ "text_encoder_quant",
+ te_mode,
+ f"{missing}, and this host runs int8 text encoders only from that file "
+ f"({te_quant_unsupported_reason('fp8')})",
+ off_label = "leave it unset to keep the dense bf16 encoder",
+ auto_available = False,
+ )
+ )
return
te_effective = effective_te_quant(te_mode, getattr(fam, "name", None))
te_reason = None
diff --git a/studio/backend/core/inference/video_families.py b/studio/backend/core/inference/video_families.py
index d95209174bb..7c99a8bf145 100644
--- a/studio/backend/core/inference/video_families.py
+++ b/studio/backend/core/inference/video_families.py
@@ -709,7 +709,13 @@ _FAMILIES: tuple[VideoFamily, ...] = (
# gemma_3_12B_it_fp4_mixed; the hosted layerwise fp8 file is the nearest scheme we serve.
te_quant_auto = "fp8",
# Hosted 2.3 DISTILLED DiT, used only by the 2.3 single-file assembly. fp8 only: LTX-2.3-INT8.pt predates the int8 excludes.
- prequant_variant_repos = (("lightricks/ltx-2.3", "fp8", "unsloth/LTX-2.3-FP8"),),
+ # Keyed on the 2.0 base so 2.3 never resolves it. fp8 only: LTX-2-INT8.safetensors predates
+ # _LTX2_INT8_EXCLUDES and quantizes Linears the runtime keeps bf16, so int8 keeps quantizing at load.
+ prequant_variant_repos = (
+ ("lightricks/ltx-2.3", "fp8", "unsloth/LTX-2.3-FP8"),
+ ("lightricks/ltx-2", "fp8", "unsloth/LTX-2-FP8"),
+ ),
+ # No prequant_resident_gb_by_scheme row: it is per family and would reprice 2.3's quantize-at-load plan.
# no steady gain on LTX's VAE / vocoder convs, but a per-shape re-tune (first render 26 s vs 10 s)
cudnn_benchmark = False,
# Block RMSNorm (hidden 4096) R0_BLOCK 4096 vs 2048 tie on B200: 3 of 6 cold servers rendered another clip.
diff --git a/studio/backend/tests/test_diffusion_dit_trainer_ltx2.py b/studio/backend/tests/test_diffusion_dit_trainer_ltx2.py
index bb42b770e08..aa8df3c88d9 100644
--- a/studio/backend/tests/test_diffusion_dit_trainer_ltx2.py
+++ b/studio/backend/tests/test_diffusion_dit_trainer_ltx2.py
@@ -576,7 +576,8 @@ def test_ltx2_preflight_refuses_a_diffusers_without_the_pipeline(monkeypatch):
def test_a_component_repo_is_refused_as_a_training_base():
# unsloth/LTX-2-FP8 holds only pre-cast components (no model_index.json): not a training base.
catalogued = _component_only_repos()
- assert catalogued["unsloth/ltx-2-fp8"] == ("ltx-2", "text_encoder", "Lightricks/LTX-2")
+ # It also hosts the pre-quantized DiT, which the video registry lists first.
+ assert catalogued["unsloth/ltx-2-fp8"] == ("ltx-2", "transformer", "Lightricks/LTX-2")
for base, family in (("unsloth/LTX-2-FP8", None), ("unsloth/LTX-2-FP8", "ltx-2")):
with pytest.raises(ValueError) as exc:
resolve_trainable_family(base, family)
diff --git a/studio/backend/tests/test_diffusion_hosted_vae.py b/studio/backend/tests/test_diffusion_hosted_vae.py
new file mode 100644
index 00000000000..a33b492afa9
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_hosted_vae.py
@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hosted bf16 VAE (diffusion_hosted_vae). CPU, tiny, no network."""
+
+from __future__ import annotations
+
+import json
+import logging
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+diffusers = pytest.importorskip("diffusers")
+
+from core.inference import diffusion_hosted_vae as hv
+from core.inference.diffusion_families import detect_family
+
+BASE = "Qwen/Qwen-Image-2.1"
+REPO = "unsloth/Qwen-Image-2.1-FP8"
+FILE = "vae/qwen_image_2.1_vae_bf16.safetensors"
+
+
+def fam():
+ family = detect_family(BASE)
+ assert family is not None and family.name == "qwen-image-2.1"
+ return family
+
+
[email protected](autouse = True)
+def _switch_on(monkeypatch):
+ monkeypatch.delenv(hv.HOSTED_VAE_ENV, raising = False)
+
+
+def test_the_registry_names_the_hosted_file_for_the_base_and_its_mirror(fam):
+ assert hv.hosted_vae_source(fam, BASE) == (REPO, FILE)
+ assert hv.hosted_vae_source(fam, "unsloth/Qwen-Image-2.1") == (REPO, FILE)
+ # Turbo's own vae/ is already bf16; forks and unknown bases never take it.
+ assert hv.hosted_vae_source(fam, "Qwen/Qwen-Image-2.1-Turbo") is None
+ assert hv.hosted_vae_source(fam, "someone/Qwen-Image-2.1-fork") is None
+ assert hv.hosted_vae_source(fam, None) is None
+
+
+def test_only_a_bf16_pipeline_load_wants_it(fam, monkeypatch):
+ assert hv.hosted_vae_wanted(fam, BASE, kind = "pipeline", dtype = torch.bfloat16) == (REPO, FILE)
+ for dtype in (torch.float16, torch.float32):
+ assert hv.hosted_vae_wanted(fam, BASE, kind = "pipeline", dtype = dtype) is None
+ for kind in ("gguf", "single_file", None):
+ assert hv.hosted_vae_wanted(fam, BASE, kind = kind, dtype = torch.bfloat16) is None
+ monkeypatch.setenv(hv.HOSTED_VAE_ENV, "0")
+ assert hv.hosted_vae_wanted(fam, BASE, kind = "pipeline", dtype = torch.bfloat16) is None
+
+
+def test_other_families_have_no_hosted_vae():
+ for repo in ("Qwen/Qwen-Image", "black-forest-labs/FLUX.1-dev", "Tongyi-MAI/Z-Image-Turbo"):
+ family = detect_family(repo)
+ assert family is not None
+ assert hv.hosted_vae_source(family, repo) is None
+
+
+def _paths_api(
+ monkeypatch,
+ size = 675_480_808,
+ fail = False,
+):
+ import huggingface_hub
+ class _Api:
+ def __init__(self, token = None):
+ pass
+
+ def get_paths_info(self, repo_id, paths):
+ if fail:
+ raise RuntimeError("404 Client Error")
+ return [types.SimpleNamespace(path = p, size = size) for p in paths]
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", _Api)
+
+
+def test_the_plan_drops_vae_only_when_the_hub_lists_the_file(fam, monkeypatch):
+ _paths_api(monkeypatch)
+ got = hv.hosted_vae_plan_files(fam, BASE, kind = "pipeline", dtype = torch.bfloat16)
+ assert got == {"vae": (REPO, [(FILE, 675_480_808)])}
+ assert hv.hosted_vae_plan_files(fam, BASE, kind = "pipeline", dtype = torch.float16) == {}
+ assert (
+ hv.hosted_vae_plan_files(
+ fam, BASE, kind = "pipeline", dtype = torch.bfloat16, local_files_only = True
+ )
+ == {}
+ )
+ _paths_api(monkeypatch, fail = True)
+ assert hv.hosted_vae_plan_files(fam, BASE, kind = "pipeline", dtype = torch.bfloat16) == {}
+
+
+def test_the_skip_drops_only_vae_weights():
+ from core.inference.diffusion_te_prequant import is_prequant_covered_weight
+
+ assert is_prequant_covered_weight("vae/diffusion_pytorch_model.safetensors", ("vae",))
+ assert not is_prequant_covered_weight("vae/config.json", ("vae",))
+ assert not is_prequant_covered_weight("transformer/x.safetensors", ("vae",))
+
+
+def _vae_class():
+ cls = getattr(diffusers, "AutoencoderKLQwenImage21", None)
+ if cls is not None:
+ return cls, {
+ "base_dim": 32,
+ "decoder_base_dim": 32,
+ "z_dim": 4,
+ "dim_mult": [1, 1],
+ "num_res_blocks": 1,
+ "temperal_downsample": [False],
+ "latents_mean": [0.0] * 4,
+ "latents_std": [1.0] * 4,
+ }
+ return diffusers.AutoencoderKLWan, {
+ "base_dim": 8,
+ "z_dim": 4,
+ "dim_mult": [1, 2],
+ "num_res_blocks": 1,
+ "temperal_downsample": [False],
+ "latents_mean": [0.0] * 4,
+ "latents_std": [1.0] * 4,
+ }
+
+
+def tiny(tmp_path):
+ """A base folder with an fp32 vae/ (as the Hub stores it) and the bf16 single file cast from it."""
+ from safetensors.torch import save_file
+
+ cls, cfg = _vae_class()
+ torch.manual_seed(0)
+ dense = cls(**cfg)
+ base = tmp_path / "base"
+ dense.save_pretrained(base / "vae")
+ hosted = tmp_path / "hosted.safetensors"
+ save_file(
+ {k: v.to(torch.bfloat16).contiguous() for k, v in dense.state_dict().items()}, str(hosted)
+ )
+ return types.SimpleNamespace(cls = cls, base = str(base), hosted = str(hosted), tmp = tmp_path)
+
+
+def _hub(monkeypatch, path):
+ import huggingface_hub
+
+ seen: list = []
+
+ def fake(repo_id, filename, **kwargs):
+ seen.append((repo_id, filename))
+ if path is None:
+ raise FileNotFoundError(f"{repo_id}/{filename} not found")
+ return path
+
+ monkeypatch.setattr(huggingface_hub, "hf_hub_download", fake)
+ return seen
+
+
+def _kwargs(fam, tiny, **over):
+ kw = dict(
+ kind = "pipeline",
+ dtype = torch.bfloat16,
+ config_source = tiny.base,
+ logger = logging.getLogger("t"),
+ )
+ kw.update(over)
+ return kw
+
+
+def test_the_hosted_file_builds_the_module_from_pretrained_builds(fam, tiny, monkeypatch, caplog):
+ seen = _hub(monkeypatch, tiny.hosted)
+ with caplog.at_level(logging.INFO):
+ got = hv.hosted_vae_pipe_kwargs(fam, BASE, **_kwargs(fam, tiny))
+ assert seen == [(REPO, FILE)]
+ assert "diffusion.hosted_vae: reading" in caplog.text
+ vae = got["vae"]
+ ref = tiny.cls.from_pretrained(tiny.base, subfolder = "vae", torch_dtype = torch.bfloat16)
+ assert type(vae) is type(ref)
+ a, b = vae.state_dict(), ref.state_dict()
+ assert set(a) == set(b)
+ for k in a:
+ assert a[k].dtype == b[k].dtype and torch.equal(a[k], b[k]), k
+ assert not vae.training
+ z = torch.randn(1, 4, 1, 4, 4, dtype = torch.bfloat16)
+ with torch.no_grad():
+ assert torch.equal(vae.decode(z).sample, ref.decode(z).sample)
+
+
[email protected]("dtype", ["float16", "float32"])
+def test_other_dtypes_never_open_it(fam, tiny, monkeypatch, dtype):
+ seen = _hub(monkeypatch, tiny.hosted)
+ assert (
+ hv.hosted_vae_pipe_kwargs(fam, BASE, **_kwargs(fam, tiny, dtype = getattr(torch, dtype)))
+ == {}
+ )
+ assert seen == []
+
+
+def test_kill_switch(fam, tiny, monkeypatch):
+ seen = _hub(monkeypatch, tiny.hosted)
+ monkeypatch.setenv(hv.HOSTED_VAE_ENV, "0")
+ assert hv.hosted_vae_pipe_kwargs(fam, BASE, **_kwargs(fam, tiny)) == {}
+ assert seen == []
+
+
+def test_a_mirrored_file_is_read_in_place_not_downloaded(fam, tiny, monkeypatch):
+ from safetensors.torch import load_file, save_file
+
+ from core.inference.diffusion_te_prequant import TE_PREQUANT_MIRROR_ENV
+
+ mirror = tiny.tmp / "mirror"
+ dest = mirror / REPO / FILE
+ dest.parent.mkdir(parents = True)
+ save_file(load_file(tiny.hosted), str(dest))
+ monkeypatch.setenv(TE_PREQUANT_MIRROR_ENV, str(mirror))
+ seen = _hub(monkeypatch, None)
+ got = hv.hosted_vae_pipe_kwargs(fam, BASE, **_kwargs(fam, tiny))
+ assert seen == []
+ assert "vae" in got
+
+
+def test_a_missing_file_leaves_the_staged_vae(fam, tiny, monkeypatch, caplog):
+ _hub(monkeypatch, None)
+ with caplog.at_level(logging.WARNING):
+ assert hv.hosted_vae_pipe_kwargs(fam, BASE, **_kwargs(fam, tiny)) == {}
+ assert "not used" in caplog.text
+
+
+def test_a_mismatched_file_is_refused(fam, tiny, monkeypatch, caplog):
+ from safetensors.torch import load_file, save_file
+
+ state = load_file(tiny.hosted)
+ key = sorted(state)[0]
+ state[key] = torch.zeros(3, dtype = torch.bfloat16)
+ bad = tiny.tmp / "bad.safetensors"
+ save_file(state, str(bad))
+ _hub(monkeypatch, str(bad))
+ with caplog.at_level(logging.WARNING):
+ assert hv.hosted_vae_pipe_kwargs(fam, BASE, **_kwargs(fam, tiny)) == {}
+ assert "not used" in caplog.text
+
+
+def test_an_fp32_file_is_not_a_bf16_source(fam, tiny, monkeypatch):
+ from safetensors.torch import load_file, save_file
+
+ fp32 = tiny.tmp / "fp32.safetensors"
+ save_file({k: v.float() for k, v in load_file(tiny.hosted).items()}, str(fp32))
+ _hub(monkeypatch, str(fp32))
+ assert hv.hosted_vae_pipe_kwargs(fam, BASE, **_kwargs(fam, tiny)) == {}
+
+
+def test_when_the_plan_dropped_vae_a_miss_loads_the_base_vae_itself(fam, tiny, monkeypatch):
+ _hub(monkeypatch, None)
+ asked: list = []
+
+ def from_pretrained(source, **kwargs):
+ asked.append((source, kwargs["subfolder"], kwargs["torch_dtype"]))
+ return "dense-vae"
+
+ monkeypatch.setattr(tiny.cls, "from_pretrained", from_pretrained)
+ got = hv.hosted_vae_pipe_kwargs(fam, BASE, **_kwargs(fam, tiny, dense_staged = False))
+ assert got == {"vae": "dense-vae"}
+ assert asked == [(BASE, "vae", torch.bfloat16)]
+ # Same when the load landed at another dtype than the plan assumed.
+ asked.clear()
+ got = hv.hosted_vae_pipe_kwargs(
+ fam, BASE, **_kwargs(fam, tiny, dense_staged = False, dtype = torch.float32)
+ )
+ assert got == {"vae": "dense-vae"} and asked == [(BASE, "vae", torch.float32)]
+
+
+def test_the_backend_plans_through_the_load_target(fam, monkeypatch):
+ from core.inference import diffusion as diff
+
+ _paths_api(monkeypatch)
+ backend = diff.DiffusionBackend.__new__(diff.DiffusionBackend)
+ monkeypatch.setattr(
+ backend,
+ "_target_for_ordinal",
+ lambda f, o: types.SimpleNamespace(dtype = torch.bfloat16),
+ raising = False,
+ )
+ got = backend._hosted_vae_plan_files(fam, "pipeline", BASE, None, None, False)
+ assert got == {"vae": (REPO, [(FILE, 675_480_808)])}
+ monkeypatch.setattr(
+ backend,
+ "_target_for_ordinal",
+ lambda f, o: types.SimpleNamespace(dtype = torch.float16),
+ raising = False,
+ )
+ assert backend._hosted_vae_plan_files(fam, "pipeline", BASE, None, None, False) == {}
+ assert json.dumps(got)
diff --git a/studio/backend/tests/test_diffusion_pipeline_prequant.py b/studio/backend/tests/test_diffusion_pipeline_prequant.py
index 5dfff048568..5c98bc6d75d 100644
--- a/studio/backend/tests/test_diffusion_pipeline_prequant.py
+++ b/studio/backend/tests/test_diffusion_pipeline_prequant.py
@@ -249,6 +249,22 @@ def test_the_artifact_carries_the_denoiser_share_of_the_unified_memory_verdict(m
assert not [name for name, _s in seen["declared_files"] if name.startswith("transformer/")]
+def test_the_hosted_vae_carries_its_share_of_the_unified_memory_verdict(monkeypatch, hub):
+ """A hosted VAE that replaces the dropped vae/ shards is priced in the memory verdict."""
+ backend = _plan_backend(monkeypatch, planned = None)
+ hosted = {"vae": ("unsloth/hosted-vae", [("vae.safetensors", 675)])}
+ monkeypatch.setattr(DiffusionBackend, "_hosted_vae_plan_files", lambda *_a, **_k: hosted)
+ seen: dict = {}
+
+ def _shortfall(_self, *_a, **kwargs):
+ seen.update(kwargs)
+ return None
+
+ monkeypatch.setattr(DiffusionBackend, "declared_footprint_shortfall", _shortfall)
+ backend.download_plan(Z_IMAGE_REPO, model_kind = "pipeline")
+ assert seen["prequant_bytes"] == 675
+
+
def test_a_gguf_pick_still_never_downloads_a_second_denoiser(monkeypatch):
"""A GGUF pick never sizes an uncached hosted checkpoint: there it is a SECOND denoiser."""
backend = DiffusionBackend()
diff --git a/studio/backend/tests/test_diffusion_te_int8_missing_file.py b/studio/backend/tests/test_diffusion_te_int8_missing_file.py
new file mode 100644
index 00000000000..a8a57cb28a6
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_te_int8_missing_file.py
@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Explicit int8 TE quant with an unpublished int8 file: CUDA falls back to fp8 and says so; Apple Silicon refuses
+up front, naming the file. Network-free."""
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+import core.inference.diffusion_precision as prec # noqa: E402
+import core.inference.diffusion_te_prequant as tpq # noqa: E402
+from core.inference.diffusion_families import _FAMILIES # noqa: E402
+from core.inference.video_families import _FAMILIES as _VIDEO_FAMILIES # noqa: E402
+
+CUDA_BF16 = types.SimpleNamespace(device = "cuda", dtype = torch.bfloat16, backend = "cuda", index = 0)
+MPS_BF16 = types.SimpleNamespace(device = "mps", dtype = torch.bfloat16, backend = "mps", index = 0)
+
+# The named files the Hub did not list on 2026-10-25 (HfApi().list_repo_files on each repo).
+UNPUBLISHED = {
+ "FLUX.1-schnell-text_encoder_2-INT8-ConvRot.safetensors",
+ "FLUX.2-klein-4B-text_encoder-INT8-ConvRot.safetensors",
+ "FLUX.2-klein-9B-text_encoder-INT8-ConvRot.safetensors",
+ "Z-Image-Turbo-text_encoder-INT8-ConvRot.safetensors",
+ "HiDream-I1-Full-text_encoder_4-INT8-ConvRot.safetensors",
+ "ideogram-4-text_encoder-INT8-ConvRot.safetensors",
+ "Lumina-Image-2.0-text_encoder-INT8-ConvRot.safetensors",
+ "Wan2.2-TI2V-5B-text_encoder-INT8-ConvRot.safetensors",
+}
+_ALL = {f.name: f for f in tuple(_FAMILIES) + tuple(_VIDEO_FAMILIES)}
+AFFECTED = sorted(
+ name
+ for name, comps in tpq.TE_INT8_CONVROT_FILES.items()
+ if any(entry[1] in UNPUBLISHED for entry in comps.values())
+)
+
+
+def hub(monkeypatch):
+ """The Hub lists every named file except the unpublished ones; nothing is cached."""
+ from core.inference.diffusion_text_encoder_trim import KEEP_LM_HEAD_ENV
+
+ monkeypatch.delenv(KEEP_LM_HEAD_ENV, raising = False)
+ monkeypatch.setattr(tpq, "_confirmed_cache", {})
+ monkeypatch.setattr(tpq, "_held_locally", lambda *a, **k: False)
+ monkeypatch.setattr(tpq, "_hub_offline", lambda: False)
+
+ def hub_files(pending, _api):
+ return {c: s.filename for c, s in pending.items() if s.filename not in UNPUBLISHED}
+
+ monkeypatch.setattr(tpq, "te_prequant_hub_files", hub_files)
+ import huggingface_hub
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", lambda *a, **k: object())
+
+
+def _cuda(monkeypatch):
+ monkeypatch.setattr(prec, "te_quant_supported", lambda target, mode: target.device == "cuda")
+
+
+def test_the_affected_set_is_the_survey_list():
+ assert set(AFFECTED) == {
+ "flux.1",
+ "flux.1-kontext",
+ "flux.2-klein",
+ "hidream-i1",
+ "ideogram-4",
+ "lumina-2",
+ "wan2.1-t2v-1.3b",
+ "wan2.1-t2v-14b",
+ "wan2.2-t2v-a14b",
+ "wan2.2-ti2v-5b",
+ "z-image",
+ }
+
+
[email protected]("name", AFFECTED)
+def test_cuda_explicit_int8_has_the_hosted_fp8_file_behind_the_missing_one(name, hub, monkeypatch):
+ _cuda(monkeypatch)
+ fam = _ALL[name]
+ sources = tpq.te_prequant_sources_for_base(
+ fam,
+ fam.base_repo,
+ te_quant_mode = "int8",
+ target = CUDA_BF16,
+ components = tuple(c for c in tpq.TE_INT8_CONVROT_FILES[name] if c != "text_encoder_4"),
+ )
+ assert sources
+ for source in sources.values():
+ chain = tpq.te_candidate_filenames(source)
+ assert chain[0] in UNPUBLISHED
+ assert any("fp8" in n.lower() for n in chain[1:]), chain
+ assert prec.preflight_te_quant("int8", fam, fam.base_repo, CUDA_BF16) == "fp8"
+
+
[email protected]("name", AFFECTED)
+def test_the_unavailable_reason_names_the_missing_file(name, hub, monkeypatch):
+ _cuda(monkeypatch)
+ fam = _ALL[name]
+ reason = tpq.explicit_int8_unavailable_reason(fam, fam.base_repo, MPS_BF16)
+ assert reason is not None and "is not published on the Hub" in reason
+ assert any(f in reason for f in UNPUBLISHED)
+
+
+ "name", ["qwen-image", "qwen-image-2.1", "krea-2", "flux.2-dev", "moss-image"]
+)
+def test_a_published_file_has_no_unavailable_reason(name, hub, monkeypatch):
+ _cuda(monkeypatch)
+ fam = _ALL[name]
+ assert tpq.explicit_int8_unavailable_reason(fam, fam.base_repo, MPS_BF16) is None
+ assert tpq.explicit_int8_unavailable_reason(fam, fam.base_repo, CUDA_BF16) is None
+
+
+def test_a_family_naming_no_file_has_no_reason(hub):
+ assert tpq.explicit_int8_unavailable_reason(_ALL["ltx-2"], "Lightricks/LTX-2", MPS_BF16) is None
+
+
[email protected]("name", ["z-image", "lumina-2", "flux.1", "ideogram-4"])
+def test_image_mps_refusal_names_the_missing_file(name, hub, monkeypatch):
+ import core.inference.diffusion as D
+
+ fam = _ALL[name]
+ with pytest.raises(RuntimeError) as err:
+ D.DiffusionBackend()._assert_precision_for_target(
+ fam,
+ MPS_BF16,
+ model_kind = "pipeline",
+ pinned = None,
+ te_mode = "int8",
+ memory_mode = None,
+ cpu_offload = False,
+ base_repo = fam.base_repo,
+ )
+ text = str(err.value)
+ assert "INT8-ConvRot.safetensors" in text and "is not published on the Hub" in text
+ assert "fp8" in text
+
+
[email protected]("name", ["wan2.2-ti2v-5b", "wan2.1-t2v-1.3b"])
+def test_video_mps_explicit_int8_with_the_file_missing_is_refused_before_the_load(name, hub):
+ from core.inference.video import _assert_video_precision_for_target
+ with pytest.raises(
+ RuntimeError, match = "Wan2.2-TI2V-5B-text_encoder-INT8-ConvRot.safetensors.*not published"
+ ):
+ _assert_video_precision_for_target(
+ _ALL[name], MPS_BF16, model_kind = "pipeline", text_encoder_quant = "int8"
+ )
+
+
+def test_video_mps_explicit_int8_passes_once_the_file_is_published(hub, monkeypatch):
+ from core.inference.video import _assert_video_precision_for_target
+ monkeypatch.setattr(
+ tpq,
+ "te_prequant_hub_files",
+ lambda pending, _api: {c: s.filename for c, s in pending.items()},
+ )
+ _assert_video_precision_for_target(
+ _ALL["wan2.2-ti2v-5b"], MPS_BF16, model_kind = "pipeline", text_encoder_quant = "int8"
+ )
+
+
+def test_cuda_video_explicit_int8_still_passes_the_gate(hub, monkeypatch):
+ import core.inference.video as V
+ monkeypatch.setattr(V, "te_quant_supported", lambda target, mode: True)
+ V._assert_video_precision_for_target(
+ _ALL["wan2.2-ti2v-5b"], CUDA_BF16, model_kind = "pipeline", text_encoder_quant = "int8"
+ )
+
+
+def test_cuda_load_reports_the_fp8_fallback_for_an_explicit_int8(monkeypatch):
+ monkeypatch.setattr(prec, "te_quant_supported", lambda target, mode: True)
+ monkeypatch.setattr(prec, "_cast_fp8", lambda enc, tgt: None)
+ encoder = types.SimpleNamespace(**{tpq.TE_PREQUANT_SCHEME_ATTR: "fp8"})
+ pipe = types.SimpleNamespace(text_encoder = encoder)
+ outcome = prec.quantize_text_encoders(pipe, CUDA_BF16, mode = "int8", family = "z-image")
+ assert outcome.mode == "fp8"
+ assert outcome.status == prec.RESOLVED_FELL_BACK
+ assert "int8 ConvRot text encoder is not available" in outcome.reason
+ assert "fp8 was used instead" in outcome.reason
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 975411ccff1..58a96e7c046 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -12464,7 +12464,9 @@ def test_ltx23_prequant_source_resolves_the_hosted_fp8_only():
source
) # the artifact the repo actually hosts
assert resolve_prequant_source(fam, "int8", base_repo = LTX23_PREQUANT_BASE) is None
- assert resolve_prequant_source(fam, "fp8", base_repo = "Lightricks/LTX-2") is None
+ # LTX-2 (2.0) resolves its own hosted fp8 file, never the 2.3 one.
+ ltx2 = resolve_prequant_source(fam, "fp8", base_repo = "Lightricks/LTX-2")
+ assert ltx2 is not None and ltx2.location == "unsloth/LTX-2-FP8"
def _ltx23_fp8_card(monkeypatch, *, fp8 = True):
diff --git a/studio/backend/tests/test_video_ltx2_prequant.py b/studio/backend/tests/test_video_ltx2_prequant.py
new file mode 100644
index 00000000000..1c263fd535d
--- /dev/null
+++ b/studio/backend/tests/test_video_ltx2_prequant.py
@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hosted LTX-2 (2.0) DiT checkpoints (unsloth/LTX-2-FP8): only the 2.0 base seeds them, only fp8 resolves.
+Network-free and torch-free; metadata copied from the published safetensors headers."""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+
+from core.inference.diffusion_prequant import (
+ PREQUANT_FORMAT,
+ _validate_checkpoint,
+ resolve_prequant_source,
+)
+from core.inference.video_families import (
+ detect_video_family,
+ video_family_prequant_repo,
+ video_family_prequant_schemes,
+)
+
+BASE = "Lightricks/LTX-2"
+REPO = "unsloth/LTX-2-FP8"
+
+# unsloth_metadata of LTX-2-FP8.safetensors and LTX-2-INT8.safetensors (revision 35b7c2304c), verbatim.
+_FP8_META = {
+ "base_model_id": "Lightricks/LTX-2",
+ "family": "ltx-2",
+ "scheme": "fp8",
+ "min_features": 512,
+ "exclude_name_tokens": [],
+ "require_bf16": True,
+ "fast_accum": False,
+ "torch_dtype": "bfloat16",
+ "quant_backend": "torchao",
+ "transformer_class": "LTX2VideoTransformer3DModel",
+ "torch_version": "2.10.0+cu130",
+ "torchao_version": "0.17.0",
+ "diffusers_version": "0.39.0",
+ "fp8_granularity": "per_row",
+}
+_INT8_META = {
+ "base_model_id": "Lightricks/LTX-2",
+ "family": "ltx-2",
+ "scheme": "int8",
+ "min_features": 512,
+ "exclude_name_tokens": [
+ "norm",
+ "_mod",
+ "modulation",
+ "timestep_embed",
+ "guidance_embed",
+ "time_text_embed",
+ "pooled",
+ "time_embed",
+ ],
+ "require_bf16": False,
+ "fast_accum": None,
+ "torch_dtype": "bfloat16",
+ "quant_backend": "torchao",
+ "transformer_class": "LTX2VideoTransformer3DModel",
+ "torch_version": "2.10.0+cu130",
+ "torchao_version": "0.17.0",
+ "diffusers_version": "0.39.0",
+}
+
+
+def fam():
+ family = detect_video_family(BASE)
+ assert family is not None and family.name == "ltx-2"
+ return family
+
+
+def test_the_20_base_resolves_the_hosted_fp8_file(fam):
+ assert video_family_prequant_repo(fam, "fp8", BASE) == REPO
+ assert video_family_prequant_repo(fam, "fp8", REPO) == REPO
+ src = resolve_prequant_source(fam, "fp8", base_repo = BASE)
+ assert (src.kind, src.location, src.filename) == ("repo", REPO, "LTX-2-FP8.safetensors")
+ assert "LTX-2-FP8.pt" in src.fallback_filenames
+
+
+def test_int8_is_not_wired(fam):
+ # LTX-2-INT8.safetensors predates the LTX-2 int8 excludes; the loader would refuse it.
+ assert video_family_prequant_repo(fam, "int8", BASE) is None
+ assert resolve_prequant_source(fam, "int8", base_repo = BASE) is None
+
+
[email protected]("base", ["Lightricks/LTX-2.3", None, "", "someone/LTX-2-fork"])
+def test_no_other_base_takes_the_20_file(fam, base):
+ assert video_family_prequant_repo(fam, "fp8", base) != REPO
+
+
+def test_23_keeps_its_own_file(fam):
+ src = resolve_prequant_source(fam, "fp8", base_repo = "Lightricks/LTX-2.3")
+ assert (src.location, src.filename) == ("unsloth/LTX-2.3-FP8", "LTX-2.3-FP8.safetensors")
+ assert set(video_family_prequant_schemes(fam)) == {"fp8"}
+
+
+def test_the_published_fp8_metadata_passes_the_loader():
+ ckpt = {"format": PREQUANT_FORMAT, "metadata": dict(_FP8_META)}
+ assert _validate_checkpoint(
+ ckpt,
+ "fp8",
+ BASE,
+ logging.getLogger("t"),
+ min_features = 512,
+ component = "transformer",
+ metadata_only = True,
+ )
+ for other in ("Lightricks/LTX-2.3", "Lightricks/LTX-2.5-Diffusers"):
+ assert not _validate_checkpoint(
+ ckpt, "fp8", other, logging.getLogger("t"), min_features = 512, metadata_only = True
+ )
+
+
+def test_the_published_int8_metadata_is_refused():
+ ckpt = {"format": PREQUANT_FORMAT, "metadata": dict(_INT8_META)}
+ assert not _validate_checkpoint(
+ ckpt, "int8", BASE, logging.getLogger("t"), min_features = 512, metadata_only = True
+ )
+
+
+def test_an_explicit_fp8_pipeline_load_plans_the_seed(fam, monkeypatch):
+ from core.inference import video as vid
+ from core.inference import video_denoiser_prequant as vdp
+
+ monkeypatch.setattr(vdp, "hosted_denoiser_refused", lambda *a, **k: False)
+ sources = vdp.denoiser_prequant_sources(fam, "fp8", BASE)
+ assert set(sources) == {"transformer"} and sources["transformer"].location == REPO
+ assert vdp.denoiser_prequant_sources(fam, "auto", BASE) is None
+ assert vdp.denoiser_prequant_sources(fam, "int8", BASE) is None
+ assert vid._planned_denoiser_components(fam, "pipeline") == ("transformer",)
+
+
+def _api(siblings):
+ import types
+
+ asked: list = []
+
+ def model_info(repo_id, **_kwargs):
+ asked.append(repo_id)
+ return types.SimpleNamespace(
+ siblings = [types.SimpleNamespace(rfilename = n, size = s) for n, s in siblings.items()]
+ )
+
+ return types.SimpleNamespace(token = None, model_info = model_info, asked = asked)
+
+
+def test_the_plan_credits_the_hosted_file(fam, monkeypatch):
+ import core.inference.diffusion_prequant as pq
+ from core.inference import video_denoiser_prequant as vdp
+ from core.inference.video import VideoBackend
+
+ monkeypatch.setattr(
+ pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True
+ )
+ monkeypatch.setattr(vdp, "hosted_denoiser_refused", lambda *a, **k: False)
+ published = {
+ "LTX-2-FP8.pt": 18_913_229_341,
+ "LTX-2-FP8.safetensors": 18_913_466_264,
+ "LTX-2-INT8.safetensors": 19_091_964_368,
+ }
+ api = _api(published)
+ repo, files = VideoBackend._denoiser_prequant_hub_files(fam, "fp8", BASE, api)
+ assert (repo, files) == (REPO, [("LTX-2-FP8.safetensors", 18_913_466_264)])
diff --git a/studio/backend/tests/test_video_te_quant_default.py b/studio/backend/tests/test_video_te_quant_default.py
index 5f7e76f4b93..48f3bb185e3 100644
--- a/studio/backend/tests/test_video_te_quant_default.py
+++ b/studio/backend/tests/test_video_te_quant_default.py
@@ -409,9 +409,13 @@ def test_hunyuanvideo_default_fp8_leaves_the_byt5_encoder_dense(name, monkeypatc
MPS_BF16 = types.SimpleNamespace(device = "mps", dtype = torch.bfloat16)
-def test_an_explicit_wan_int8_on_mps_reaches_the_hosted_convrot_file():
+def test_an_explicit_wan_int8_on_mps_reaches_the_hosted_convrot_file(monkeypatch):
# MPS runs the hosted int8 ConvRot encoder without fp8, so the gate must not rewrite int8 to fp8 and refuse it.
+ # Once the file is there: the gate now refuses an unpublished one up front (test_diffusion_te_int8_missing_file).
+ import core.inference.diffusion_te_prequant as tpq
import core.inference.video as v
+
+ monkeypatch.setattr(tpq, "te_prequant_sources_confirmed", lambda sources, **k: True)
v._assert_video_precision_for_target(
_family("wan2.2-ti2v-5b"), MPS_BF16, model_kind = "pipeline", text_encoder_quant = "int8"
)