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: video families default to a hosted quantized text encoder (#14000)

Daniel Han9877243cdb7f
diff --git a/scripts/build_ltx25_te_int8_convrot.py b/scripts/build_ltx25_te_int8_convrot.py
new file mode 100644
index 00000000000..a2e91ca6d32
--- /dev/null
+++ b/scripts/build_ltx25_te_int8_convrot.py
@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Build the hosted int8 ConvRot Gemma 4 encoder LTX-2.5's text-encoder sidecar loads instead of quantizing at load.
+
+The file IS the sidecar's own at-load build, written once: this runs the worker's ``_load`` (transformers 5.10
+sidecar, ``from_pretrained(torch_dtype = bfloat16)``, the dead-tail trim, then ``quantize_int8_convrot_`` on the card)
+and saves the resulting state dict. So every key is the loaded model's own name (transformers 5 renames some
+checkpoint keys at load), every decoder projection is the ``Int8ConvRotLinear`` buffers (``<name>.weight`` int8,
+``<name>.weight_scale`` float32 [out, 1]) and every other tensor is the bf16 tensor the at-load path holds. The tied
+``lm_head`` has no key (it is re-tied to the embedding at load). The header is the plain-tensor container the prequant
+readers share (``unsloth_format`` + ``unsloth_metadata`` + ``tensor_names``), written canonically, so a rebuild on the
+same device kind is byte-identical.
+
+ python scripts/build_ltx25_te_int8_convrot.py \\
+ --out outputs/te_default/unsloth/LTX-2.5-FP8/LTX-2.5-text_encoder-INT8-ConvRot.safetensors
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+ROOT = Path(__file__).resolve().parent.parent
+BACKEND = ROOT / "studio" / "backend"
+
+
+def main(argv = None) -> int:
+ p = argparse.ArgumentParser()
+ p.add_argument("--base", default = "Lightricks/LTX-2.5-Diffusers")
+ p.add_argument(
+ "--repo", default = None, help = "local pack folder or Hub id to read (default: --base)"
+ )
+ p.add_argument("--out", required = True)
+ p.add_argument(
+ "--device", default = "cuda:0", help = "the at-load path quantizes on the card when it has one"
+ )
+ p.add_argument(
+ "--venv-dir", default = None, help = "the transformers 5.10 sidecar (default: Studio's)"
+ )
+ p.add_argument("--hf-token", default = None)
+ args = p.parse_args(argv)
+ sys.path.insert(0, str(BACKEND))
+ venv_dir = args.venv_dir
+ if venv_dir is None:
+ from utils.transformers_version import _VENV_T5_510_DIR
+ venv_dir = _VENV_T5_510_DIR
+ result = build(
+ args.repo or args.base,
+ Path(args.out),
+ base = args.base,
+ device = args.device,
+ venv_dir = venv_dir,
+ hf_token = args.hf_token,
+ )
+ print(json.dumps(result))
+ return 0
+
+
+def build(
+ repo: str,
+ out: Path,
+ *,
+ base: str,
+ device: str,
+ venv_dir: Optional[str] = None,
+ hf_token: Optional[str] = None,
+) -> dict:
+ """Load ``repo``'s encoder the worker's way, quantized, and write it to ``out``; its size, sha256 and counts."""
+ sys.path.insert(0, str(BACKEND))
+ sys.path.insert(0, str(ROOT / "scripts"))
+ from core.inference import video_ltx25_te_worker as worker
+
+ if venv_dir:
+ worker._activate_sidecar(venv_dir)
+ import safetensors
+ import torch
+
+ from build_te_int8_convrot_checkpoint import _write_safetensors
+ from core.inference.prequant_safetensors import UNSLOTH_FORMAT_KEY, UNSLOTH_METADATA_KEY
+ from core.inference.video_ltx25 import LTX25_TE_HOSTED_FORMAT
+ from core.inference.video_minimax_h3_te import _int8_convrot_linear_class
+
+ device = _available_device(torch, device)
+ on_card = device.startswith(("cuda", "xpu"))
+ config = {
+ "repo": repo,
+ "hf_token": hf_token,
+ "device": device,
+ "dtype": "bfloat16",
+ "resident": on_card,
+ "te_quant": worker.TE_QUANT_INT8_CONVROT,
+ }
+ _tokenizer, model = worker._load(config)
+ if config.get("_te_source") != "quantized_at_load":
+ raise SystemExit(f"expected the at-load build, got {config.get('_te_source')!r}")
+ quantized = sum(1 for m in model.modules() if isinstance(m, _int8_convrot_linear_class()))
+ state = model.state_dict()
+ # The tied head is the embedding under a second name; the loader re-ties it, so it never gets a key of its own.
+ # The dead-tail trim normally drops it already, but a kept head (or a trim that did not engage) must not ship a
+ # second 262k-vocab copy.
+ if _head_is_tied(state):
+ state.pop("lm_head.weight")
+ tensors = {k: v.detach().to("cpu").contiguous() for k, v in state.items()}
+ del model
+ names = sorted(tensors)
+ try:
+ import transformers
+
+ cfg = transformers.AutoConfig.from_pretrained(
+ repo, subfolder = "text_encoder", token = hf_token
+ )
+ te_class = (getattr(cfg, "architectures", None) or [None])[0]
+ transformers_version = transformers.__version__
+ except Exception: # noqa: BLE001 -- forensic metadata only
+ te_class, transformers_version = None, None
+ metadata = {
+ "base_model_id": base,
+ "family": "ltx-2.5",
+ "scheme": "int8",
+ "component": "text_encoder",
+ "te_class": te_class or "Gemma4UnifiedForConditionalGeneration",
+ "torch_dtype": "bfloat16",
+ "quant": {
+ "format": "int8_convrot",
+ "group_size": worker.CONVROT_GROUP,
+ "weight_only": True,
+ "scale": "per_output_channel_absmax_over_127",
+ "linears": quantized,
+ "quantized_on": torch.device(device).type if on_card else "cpu",
+ },
+ "lm_head": "tied to the input embedding, no key",
+ "torch_version": torch.__version__,
+ "transformers_version": transformers_version,
+ "safetensors_version": safetensors.__version__,
+ }
+ header = {
+ UNSLOTH_FORMAT_KEY: LTX25_TE_HOSTED_FORMAT,
+ UNSLOTH_METADATA_KEY: json.dumps(metadata, sort_keys = True),
+ "tensor_names": json.dumps(names),
+ }
+ # Plain tensors only, so the shared reader (prequant_safetensors.load_plain_prequant_safetensors) accepts it.
+ header.update({name: json.dumps({"_type": "Tensor"}) for name in names})
+ out.parent.mkdir(parents = True, exist_ok = True)
+ tmp = out.with_name(out.name + ".tmp")
+ _write_safetensors(tmp, tensors, header)
+ os.replace(tmp, out)
+ digest = hashlib.sha256()
+ with open(out, "rb") as fh:
+ for chunk in iter(lambda: fh.read(1 << 24), b""):
+ digest.update(chunk)
+ return {
+ "out": str(out),
+ "bytes": out.stat().st_size,
+ "sha256": digest.hexdigest(),
+ "quantized_linears": quantized,
+ "tensors": len(names),
+ }
+
+
+def _available_device(torch, device: str) -> str:
+ """``device`` when its backend is usable here, else ``cpu``: the worker moves a resident build onto the device."""
+ kind = torch.device(device).type
+ backend = getattr(torch, kind, None) if kind in ("cuda", "xpu") else None
+ if backend is None:
+ return device
+ is_available = getattr(backend, "is_available", None)
+ if callable(is_available) and is_available():
+ return device
+ print(f"{device} is not available on this host; building on the CPU", file = sys.stderr)
+ return "cpu"
+
+
+def _head_is_tied(state: dict) -> bool:
+ """Whether ``lm_head.weight`` is the same storage as another tensor in ``state`` (the input embedding)."""
+ head = state.get("lm_head.weight")
+ if head is None:
+ return False
+ return any(
+ name != "lm_head.weight" and t.shape == head.shape and t.data_ptr() == head.data_ptr()
+ for name, t in state.items()
+ )
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/build_te_int8_convrot_checkpoint.py b/scripts/build_te_int8_convrot_checkpoint.py
index 5b7086e9dda..4228fb3f253 100644
--- a/scripts/build_te_int8_convrot_checkpoint.py
+++ b/scripts/build_te_int8_convrot_checkpoint.py
@@ -33,6 +33,17 @@ BACKEND = Path(__file__).resolve().parent.parent / "studio" / "backend"
DECODER_LINEAR = re.compile(
r"^model\.language_model\.layers\.\d+\.(self_attn\.[qkvo]_proj|mlp\.(gate|up|down)_proj)\.weight$"
)
+# UMT5 / T5 encoder blocks (Wan's UMT5-XXL): self-attention q/k/v/o and the MLP, gated (wi_0 / wi_1) or not (wi), + wo.
+T5_ENCODER_LINEAR = re.compile(
+ r"^encoder\.block\.\d+\.layer\.(0\.SelfAttention\.[qkvo]|1\.DenseReluDense\.(wi_0|wi_1|wi|wo))\.weight$"
+)
+_T5_CLASSES = ("UMT5EncoderModel", "T5EncoderModel")
+# The encoder classes' _keep_in_fp32_modules: a projection kept dense is stored float32, as from_pretrained holds it.
+_T5_KEEP_FP32 = ("wo",)
+
+
+def _linear_pattern(te_class):
+ return T5_ENCODER_LINEAR if te_class in _T5_CLASSES else DECODER_LINEAR
_ST_DTYPES = {"float32": "F32", "bfloat16": "BF16", "float16": "F16", "int8": "I8", "uint8": "U8"}
@@ -89,7 +100,13 @@ def main(argv = None) -> int:
"--device", default = "cuda" if os.environ.get("CUDA_VISIBLE_DEVICES") != "" else "cpu"
)
p.add_argument("--hf-token", default = None)
+ p.add_argument(
+ "--keep-dense",
+ default = "",
+ help = "comma-separated Linear leaf names left dense (e.g. 'wo' for UMT5); fp32-kept modules stay float32",
+ )
args = p.parse_args(argv)
+ keep_dense = tuple(t for t in (x.strip() for x in args.keep_dense.split(",")) if t)
sys.path.insert(0, str(BACKEND))
import safetensors
@@ -115,6 +132,9 @@ def main(argv = None) -> int:
else:
with safe_open(str(src / "model.safetensors"), framework = "pt") as handle:
weight_map = {name: "model.safetensors" for name in handle.keys()}
+ te_class = (config.get("architectures") or [None])[0]
+ pattern = _linear_pattern(te_class)
+ keep_fp32 = _T5_KEEP_FP32 if te_class in _T5_CLASSES else ()
device = torch.device(args.device if torch.cuda.is_available() else "cpu")
quant = {"format": "int8_tensorwise", "convrot": True, "convrot_groupsize": args.group}
blob = torch.tensor(list(json.dumps(quant).encode("utf-8")), dtype = torch.uint8)
@@ -126,28 +146,38 @@ def main(argv = None) -> int:
if name == "lm_head.weight":
continue
tensor = handle.get_tensor(name)
- if DECODER_LINEAR.match(name):
+ leaf = (
+ name[: -len(".weight")].rsplit(".", 1)[-1] if name.endswith(".weight") else ""
+ )
+ if pattern.match(name) and leaf not in keep_dense:
q, scale = quantize_int8_convrot_weight(tensor.to(device), args.group)
prefix = name[: -len(".weight")]
tensors[name] = q.cpu().contiguous()
tensors[prefix + ".weight_scale"] = scale.cpu().contiguous()
tensors[prefix + ".comfy_quant"] = blob.clone()
quantized += 1
+ elif pattern.match(name) and leaf in keep_fp32:
+ tensors[name] = tensor.to(torch.float32).contiguous()
else:
tensors[name] = tensor.to(torch.bfloat16).contiguous()
if not quantized:
- raise SystemExit("no decoder projections matched; is this a Qwen3-VL text encoder?")
+ raise SystemExit("no projections matched; is this a Qwen3-VL or UMT5 text encoder?")
metadata = {
"base_model_id": args.base,
"family": args.family,
"scheme": "int8",
"component": args.component,
- "te_class": (config.get("architectures") or [None])[0],
+ "te_class": te_class,
"torch_dtype": "bfloat16",
"quant": dict(
- quant, weight_only = True, scale = "per_output_channel_absmax_over_127", linears = quantized
+ quant,
+ weight_only = True,
+ scale = "per_output_channel_absmax_over_127",
+ linears = quantized,
+ pattern = pattern.pattern,
+ kept_dense = list(keep_dense),
),
- "lm_head": "dropped",
+ "lm_head": "dropped" if te_class not in _T5_CLASSES else "absent",
"torch_version": torch.__version__,
"transformers_version": transformers.__version__,
"safetensors_version": safetensors.__version__,
diff --git a/scripts/convert_prequant_to_safetensors.py b/scripts/convert_prequant_to_safetensors.py
index 93c5309fcb6..addae135927 100644
--- a/scripts/convert_prequant_to_safetensors.py
+++ b/scripts/convert_prequant_to_safetensors.py
@@ -179,6 +179,27 @@ def _untie(flat: dict) -> dict:
return out
+def tied_copies(state_dict: dict) -> dict:
+ """``{alias: source}`` for keys that share storage, shape and stride with an earlier key (a tied embedding)."""
+ seen: dict = {}
+ aliases = {}
+ for key, value in state_dict.items():
+ if not getattr(value, "numel", lambda: 0)():
+ continue
+ ident = (
+ value.untyped_storage().data_ptr(),
+ value.storage_offset(),
+ tuple(value.shape),
+ tuple(value.stride()),
+ value.dtype,
+ )
+ if ident in seen:
+ aliases[key] = seen[ident]
+ else:
+ seen[ident] = key
+ return aliases
+
+
def write_plain_safetensors(
path: str, *, fmt: str, state_dict: dict, metadata: dict, extra: dict
) -> None:
@@ -214,7 +235,13 @@ def write_plain_safetensors(
def convert(
- src: str, out_dir: str, *, repo: str | None, revision: str | None, sha: str | None
+ src: str,
+ out_dir: str,
+ *,
+ repo: str | None,
+ revision: str | None,
+ sha: str | None,
+ drop_tied: bool = False,
) -> dict:
import torch
@@ -259,9 +286,24 @@ def convert(
metadata = dict(ckpt.get("metadata") or {})
state_dict = ckpt["state_dict"]
extra = {SOURCE_KEY: json.dumps(source)}
+ dropped: dict = {}
if is_te:
- write_plain_safetensors(dst, fmt = fmt, state_dict = state_dict, metadata = metadata, extra = extra)
+ written = state_dict
+ if drop_tied:
+ # Store a tied embedding once (UMT5's encoder.embed_tokens.weight is shared.weight): the TE loader fills
+ # the alias from the model's own tie (diffusion_te_prequant._fill_tied_aliases). Older readers refuse such
+ # a file and load the dense encoder, so only use it for an encoder no older release was pointed at.
+ # A tied lm_head stays: the loader never fills a head alias (whether a head is tied is per config).
+ dropped = {
+ alias: key
+ for alias, key in tied_copies(state_dict).items()
+ if not alias.endswith("lm_head.weight")
+ }
+ written = {k: v for k, v in state_dict.items() if k not in dropped}
+ write_plain_safetensors(dst, fmt = fmt, state_dict = written, metadata = metadata, extra = extra)
back = ps.load_plain_prequant_safetensors(dst)
+ for alias, source_key in dropped.items():
+ back["state_dict"][alias] = back["state_dict"][source_key]
else:
if fmt not in dp.PREQUANT_FORMATS:
raise ValueError(f"{src}: unrecognised format {fmt!r}")
@@ -328,6 +370,7 @@ def convert(
"dst_sha256": sha256_of(dst),
"seconds": round(time.time() - t0, 1),
"verified_bit_identical": True,
+ "tied_copies_dropped": dropped,
}
return rec
@@ -342,6 +385,11 @@ def main(argv = None) -> int:
p.add_argument("--revision", default = None)
p.add_argument("--sha256", default = None, help = "known sha256 of a single SRC (skips hashing it)")
p.add_argument("--report", default = None, help = "append one JSON line per file here")
+ p.add_argument(
+ "--drop-tied-copies",
+ action = "store_true",
+ help = "text encoders: store a tied tensor once (the loader re-fills the alias from the model's tie)",
+ )
args = p.parse_args(argv)
sys.path.insert(0, str(BACKEND))
for src in args.src:
@@ -351,6 +399,7 @@ def main(argv = None) -> int:
repo = args.repo,
revision = args.revision,
sha = args.sha256 if len(args.src) == 1 else None,
+ drop_tied = args.drop_tied_copies,
)
line = json.dumps(rec)
print(line, flush = True)
diff --git a/studio/backend/core/inference/diffusion_precision.py b/studio/backend/core/inference/diffusion_precision.py
index 32c8bbd8591..38c75a3e676 100644
--- a/studio/backend/core/inference/diffusion_precision.py
+++ b/studio/backend/core/inference/diffusion_precision.py
@@ -246,14 +246,17 @@ def quantize_text_encoders(
family: Optional[str] = None,
offload_active: bool = False,
logger: Any = None,
+ encoders: Optional[tuple[str, ...]] = None,
) -> TEQuantOutcome:
"""Quantise each present text encoder in place with ``mode``. Returns a ``TEQuantOutcome``
carrying the mode applied (None when disabled, unsupported, or nothing was cast) plus WHY it
differs from the request. ``int8`` needs a per-family schedule (``_TE_INT8_SKIP``); without one
it falls back to ``fp8``. Under ``offload_active`` the torchao modes are skipped (their
subclasses reject ``Module.to()``); layerwise ``fp8`` still engages. Best-effort: any failure
- leaves the encoder dense."""
+ leaves the encoder dense. ``encoders`` limits the cast to those pipeline attributes (the rest stay as loaded),
+ e.g. HunyuanVideo-1.5's automatic fp8 targets its Qwen tower and leaves the ByT5 glyph encoder dense."""
mode = normalize_te_quant(mode)
+ attrs = tuple(a for a in _TEXT_ENCODER_ATTRS if encoders is None or a in encoders)
if mode is None:
present = [a for a in _TEXT_ENCODER_ATTRS if getattr(pipe, a, None) is not None]
stored_int8 = [a for a in present if _hosted_te_scheme(getattr(pipe, a)) == TE_QUANT_INT8]
@@ -266,7 +269,7 @@ def quantize_text_encoders(
)
return TEQuantOutcome(None)
# A hosted int8 ConvRot encoder is already quantized (plain tensors, offload-safe): report it, never re-cast it.
- present = [a for a in _TEXT_ENCODER_ATTRS if getattr(pipe, a, None) is not None]
+ present = [a for a in attrs if getattr(pipe, a, None) is not None]
hosted_int8 = [a for a in present if _hosted_te_scheme(getattr(pipe, a)) == TE_QUANT_INT8]
if mode == TE_QUANT_INT8 and hosted_int8 and len(hosted_int8) == len(present):
return TEQuantOutcome(
@@ -286,11 +289,13 @@ def quantize_text_encoders(
"(it degrades large encoders without one), so fp8 was used instead"
)
if _family_hosts_te_int8(family):
+ from .diffusion_te_prequant import _TE_INT8_HEADLESS_FAMILIES
from .diffusion_text_encoder_trim import KEEP_LM_HEAD_ENV, family_trims_lm_head
downgrade_reason = (
f"{KEEP_LM_HEAD_ENV} keeps lm_head, which the int8 ConvRot text encoder does not carry, "
"so fp8 was used instead"
if not family_trims_lm_head(family)
+ and (family or "").strip().lower() not in _TE_INT8_HEADLESS_FAMILIES
else "the hosted int8 ConvRot text encoder is not available (not published yet, offline, "
"or refused, see the server log), so fp8 was used instead"
)
@@ -329,7 +334,7 @@ def quantize_text_encoders(
caster = _cast_fp8
cast: list[str] = []
failed: list[str] = []
- for attr in _TEXT_ENCODER_ATTRS:
+ for attr in attrs:
encoder = getattr(pipe, attr, None)
if encoder is None:
continue
diff --git a/studio/backend/core/inference/diffusion_te_prequant.py b/studio/backend/core/inference/diffusion_te_prequant.py
index cfff60b79b7..7361202dd1c 100644
--- a/studio/backend/core/inference/diffusion_te_prequant.py
+++ b/studio/backend/core/inference/diffusion_te_prequant.py
@@ -55,6 +55,18 @@ TE_INT8_CONVROT_FILES: dict[str, dict[str, tuple[str, str]]] = {
"Qwen-Image-2.1-text_encoder-INT8-ConvRot.safetensors",
),
},
+ # UMT5-XXL, one file for all four Wan bases (an equivalence group below): every self-attention and gated-FFN
+ # projection of encoder.block int8 in the group-256 Hadamard basis, the shared embedding and norms dense. Opt-in
+ # (text_encoder_quant=int8); the family default is the fp8 file beside it, as ComfyUI's Wan templates.
+ **{
+ name: {
+ "text_encoder": (
+ "unsloth/Wan2.2-TI2V-5B-FP8",
+ "Wan2.2-TI2V-5B-text_encoder-INT8-ConvRot.safetensors",
+ ),
+ }
+ for name in ("wan2.2-ti2v-5b", "wan2.2-t2v-a14b", "wan2.1-t2v-1.3b", "wan2.1-t2v-14b")
+ },
# Qwen3-VL-4B, the same build as BFL's qwen3vl_4b_int8_convrot except that embed_tokens stays bf16: every int8
# projection matches BFL's byte for byte. The base and distilled repos carry the same bytes (one encoder).
"flux.3-klein": {
@@ -71,6 +83,12 @@ TE_INT8_CONVROT_FILES: dict[str, dict[str, tuple[str, str]]] = {
},
}
+# Families whose encoder class has no lm_head at all (UMT5EncoderModel), so the int8 file needs no lm_head trim and the
+# UNSLOTH_TE_KEEP_LM_HEAD kill switch has nothing to keep.
+_TE_INT8_HEADLESS_FAMILIES = frozenset(
+ {"wan2.2-ti2v-5b", "wan2.2-t2v-a14b", "wan2.1-t2v-1.3b", "wan2.1-t2v-14b"}
+)
+
# The scheme the loaded FILE carried ("fp8" / "int8"), so quantize_text_encoders never re-casts an int8 encoder.
TE_PREQUANT_SCHEME_ATTR = "_unsloth_te_prequant_scheme"
@@ -148,7 +166,16 @@ TE_PREQUANT_BUDGET_SCALE = 0.65
TE_INT8_CONVROT_BUDGET_SCALE = 0.56
# Per family where the default under-states: FLUX.3's Qwen3-VL-4B file is 5,247,076,320 bytes against 8,875,719,344
# dense, 0.591 (its bf16 embedding table is a larger share of a 4B encoder), rounded up.
-_TE_INT8_CONVROT_BUDGET_SCALES = {"flux.3-klein": 0.60, "flux.3-klein-base": 0.60}
+# Wan's UMT5 keeps its 256k-row embedding dense: its int8 file is 6,735,404,944 bytes against 11,361,851,208 dense,
+# 0.593, rounded up the same way.
+_TE_INT8_CONVROT_BUDGET_SCALES = {
+ "flux.3-klein": 0.60,
+ "flux.3-klein-base": 0.60,
+ **{
+ name: 0.62
+ for name in ("wan2.2-ti2v-5b", "wan2.2-t2v-a14b", "wan2.1-t2v-1.3b", "wan2.1-t2v-14b")
+ },
+}
def te_int8_convrot_budget_scale(fam: Any) -> float:
@@ -174,7 +201,11 @@ def te_prequant_budget_scale(
Best-effort like the rest of this module: anything unresolvable returns 1.0, i.e. today's
bf16 budget."""
if getattr(fam, "name", None) == "ltx-2.5":
- from .video_ltx25 import ltx25_te_budget_scale
+ from .video_ltx25 import ltx25_te_budget_scale, ltx25_te_prequant_sources
+
+ # Only the hosted file is int8-sized end to end: the at-load fallback materializes the dense encoder first.
+ if not ltx25_te_prequant_sources(te_quant_mode, base):
+ return 1.0
components = getattr(fam, "bf16_components_gb", None) or (0.0, 0.0)
return ltx25_te_budget_scale(te_quant_mode, components[1])
try:
@@ -227,6 +258,25 @@ _TE_EQUIVALENT_BASES: tuple[frozenset[str], ...] = (
"qwen/qwen-image-2.1-turbo",
}
),
+ # UMT5-XXL: Wan2.2 TI2V-5B and T2V-A14B ship byte-identical bf16 text_encoder/ shards, Wan2.1 T2V-1.3B and 14B
+ # byte-identical fp32 ones, and every Wan2.1 fp32 tensor rounds to the Wan2.2 bf16 one bit for bit (all 242,
+ # compared 2026-10-16), so a bf16 load of either gives bit-identical prompt embeddings.
+ frozenset(
+ {
+ "wan-ai/wan2.2-ti2v-5b-diffusers",
+ "wan-ai/wan2.2-t2v-a14b-diffusers",
+ "wan-ai/wan2.1-t2v-1.3b-diffusers",
+ "wan-ai/wan2.1-t2v-14b-diffusers",
+ }
+ ),
+ # Qwen2.5-VL-7B text tower (Qwen2_5_VLTextModel): the HunyuanVideo-1.5 480p and 720p repacks ship identical
+ # text_encoder/ sha256 (compared 2026-10-16). Kept apart from the Qwen-Image group, whose file is the full VLM.
+ frozenset(
+ {
+ "hunyuanvideo-community/hunyuanvideo-1.5-diffusers-480p_t2v",
+ "hunyuanvideo-community/hunyuanvideo-1.5-diffusers-720p_t2v",
+ }
+ ),
# Qwen3-VL-4B: the FLUX.3 Klein distilled and base text_encoder/ shards carry identical sha256 (2026-10-16)
frozenset(
{
@@ -428,7 +478,8 @@ def resolve_te_prequant_source(
fp8 = resolve_te_prequant_source(fam, component, "fp8")
from .diffusion_text_encoder_trim import family_trims_lm_head
- if not family_trims_lm_head(getattr(fam, "name", None)):
+ family = str(getattr(fam, "name", "") or "").strip().lower()
+ if family not in _TE_INT8_HEADLESS_FAMILIES and not family_trims_lm_head(family):
# The int8 file has no lm_head; with the head kept (UNSLOTH_TE_KEEP_LM_HEAD) only the fp8 one can serve.
return fp8
fallback = ()
@@ -709,6 +760,7 @@ def load_prequant_text_encoder(
encoder = encoder_cls(config)
if trim:
trim_text_encoder(encoder)
+ _fill_tied_aliases(encoder, state_dict)
encoder.load_state_dict(state_dict, strict = True, assign = True)
if _has_meta_tensors(encoder):
# Non-persistent buffers (built in __init__, absent from the state dict) stay on meta. Rebuild on CPU so
@@ -993,9 +1045,6 @@ def _build_int8_convrot_encoder(
_validate_comfy_quant,
)
- if not trim:
- # The file has no lm_head; a build that keeps one would load it random.
- raise ValueError("the int8 ConvRot encoder carries no lm_head and needs the lm_head trim")
if LM_HEAD_KEY in state_dict:
raise ValueError("the int8 ConvRot encoder unexpectedly carries an lm_head")
scale_suffix, quant_suffix = ".weight_scale", ".comfy_quant"
@@ -1005,8 +1054,16 @@ def _build_int8_convrot_encoder(
# include_buffers=False: rotary inv_freq buffers are built for real; parameters arrive via assign=True.
with init_empty_weights(include_buffers = False):
encoder = encoder_cls(config)
+ # An encoder-only class (UMT5EncoderModel) has no head at all; one that has a head needs the trim, as the file
+ # carries no lm_head and a kept one would load random.
+ if getattr(encoder, "lm_head", None) is not None and not trim:
+ raise ValueError("the int8 ConvRot encoder carries no lm_head and needs the lm_head trim")
trim_text_encoder(encoder)
- if not is_trimmed(encoder) and config_ties_lm_head(config):
+ if (
+ getattr(encoder, "lm_head", None) is not None
+ and not is_trimmed(encoder)
+ and config_ties_lm_head(config)
+ ):
# A tied head (FLUX.3's Qwen3-VL-4B) is kept by the trim, but this file has no lm_head key for it and the
# family reads hidden states only, so drop it here: a meta head would fail the strict load below.
head = encoder.lm_head
@@ -1040,6 +1097,13 @@ def _build_int8_convrot_encoder(
)
if any(k.endswith(quant_suffix) for k in state_dict):
raise ValueError("quant metadata for a projection with no scale")
+ # The encoder's own fp32-kept modules (T5's ``wo``, which overflows in low precision): a float32 tensor stored for
+ # one stays float32, as from_pretrained keeps it.
+ keep_fp32 = tuple(str(m) for m in (getattr(encoder, "_keep_in_fp32_modules", None) or ()))
+
+ def _kept_fp32(key: str) -> bool:
+ return any(token in key.split(".") for token in keep_fp32)
+
# Storage dtypes stay (int8 payload, float32 scales); every dense float tensor follows the compute dtype.
for key, tensor in list(state_dict.items()):
if (
@@ -1047,19 +1111,31 @@ def _build_int8_convrot_encoder(
and not key.endswith(scale_suffix)
and dtype is not None
and tensor.dtype != dtype
+ and not (tensor.dtype == torch.float32 and _kept_fp32(key))
):
state_dict[key] = tensor.to(dtype)
- # A dense decoder projection would load as bf16 and outgrow the budget this path is priced at.
+ # A dense block projection would load as bf16 and outgrow the budget this path is priced at. The block stack is
+ # model.language_model.layers on a decoder VLM, encoder.block on T5 / UMT5.
language_model = getattr(getattr(encoder, "model", None), "language_model", None)
layers = getattr(language_model, "layers", None)
if layers is None:
- raise ValueError("encoder has no model.language_model.layers")
- dense = [n for n, m in layers.named_modules() if isinstance(m, torch.nn.Linear)]
+ layers = getattr(getattr(encoder, "encoder", None), "block", None)
+ if layers is None:
+ raise ValueError("encoder has no model.language_model.layers or encoder.block")
+ dense = [
+ n for n, m in layers.named_modules() if isinstance(m, torch.nn.Linear) and not _kept_fp32(n)
+ ]
if dense:
raise ValueError(
f"{len(dense)} decoder projection(s) are not quantized in this artifact, e.g. {sorted(dense)[0]}"
)
+ _fill_tied_aliases(encoder, state_dict)
encoder.load_state_dict(state_dict, strict = True, assign = True)
+ # assign=True gives a tied pair separate tensors; re-tie a headless encoder (UMT5's encoder.embed_tokens ->
+ # shared). One with a (trimmed) head is left as loaded: its head is a stand-in with no weight to tie.
+ tie = getattr(encoder, "tie_weights", None)
+ if callable(tie) and getattr(encoder, "lm_head", None) is None:
+ tie()
stranded = _meta_tensor_names(encoder)
if stranded:
raise ValueError(f"{len(stranded)} tensor(s) still on the meta device, e.g. {stranded[0]}")
@@ -1068,6 +1144,33 @@ def _build_int8_convrot_encoder(
return encoder
+def _fill_tied_aliases(encoder: Any, state_dict: dict) -> None:
+ """Give a key the file leaves out because the model ties it to another one the source of that tie.
+
+ A tied embedding is one tensor under two names (UMT5's ``encoder.embed_tokens.weight`` is ``shared.weight``), and a
+ file that stores it once (the dense shards themselves, an int8 build, a converter run with --drop-tied-copies)
+ would otherwise fail the strict load. Only ties the MODEL declares: transformers 5's ``_tied_weights_keys`` map,
+ or one parameter registered under two names (4.x shares the module). ``lm_head`` ties are left alone, because
+ whether a head is tied depends on the config and the callers handle it themselves."""
+ pairs: list = []
+ tied = getattr(encoder, "_tied_weights_keys", None)
+ if isinstance(tied, dict):
+ pairs.extend((str(t), str(s)) for t, s in tied.items())
+ try:
+ names: dict = {}
+ for name, param in encoder.named_parameters(remove_duplicate = False):
+ names.setdefault(id(param), []).append(name)
+ for group in names.values():
+ pairs.extend((t, s) for t in group for s in group if t != s)
+ except Exception: # noqa: BLE001 - no parameter walk, no shared-module ties to fill
+ pass
+ for target, source in pairs:
+ if target.endswith("lm_head.weight"):
+ continue
+ if target not in state_dict and source in state_dict:
+ state_dict[target] = state_dict[source]
+
+
def _safetensors_te_class(path: str) -> Optional[str]:
try:
import json
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index de446371902..e27f424cc0a 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -193,6 +193,7 @@ from .diffusion_precision import (
effective_te_quant,
normalize_te_quant,
quantize_text_encoders,
+ resolve_te_quant_request,
te_quant_needs_resident_weights,
te_quant_supported,
te_quant_unsupported_reason,
@@ -305,6 +306,53 @@ def resolve_video_model_kind(gguf_filename: Optional[str], model_kind: Optional[
return "gguf" if gguf_filename.strip().lower().endswith(".gguf") else "single_file"
+def video_te_quant_request(
+ fam: Any,
+ text_encoder_quant: Optional[str],
+ *,
+ base: Optional[str] = None,
+ speed_mode: Optional[str] = None,
+) -> tuple[Optional[str], bool]:
+ """``(request, auto_selected)``: an unset / "auto" encoder request on a family with ``te_quant_auto`` becomes that
+ scheme; anything else comes back as given, raw, because MiniMax-H3 and LTX-2.5 read the raw tri-state themselves.
+
+ ``auto_selected`` keeps the pick from being treated as a request the caller made: nobody asked for it, so a host
+ that cannot run it (fp8 below cc 8.9, a hosted file that is not there) gets the dense encoder, never a refusal.
+
+ Two limits on the automatic pick, never on an explicit scheme: Speed="off" is bit-exact, so it keeps the released
+ encoder (LTX-2.5's raw unset included, which would otherwise take int8); and only an exactly identified official
+ ``base`` takes the hosted file, so a custom pack that merely shares the folder name keeps its own weights."""
+ unset = text_encoder_quant is None or str(text_encoder_quant).strip().lower() in ("", "auto")
+ auto_scheme = getattr(fam, "te_quant_auto", None)
+ speed_off = speed_mode is not None and str(speed_mode).strip().lower() == SPEED_OFF
+ if unset and speed_off and (auto_scheme or getattr(fam, "name", None) == "ltx-2.5"):
+ return "none", False
+ if not auto_scheme:
+ return text_encoder_quant, False
+ mode, auto = resolve_te_quant_request(text_encoder_quant, auto_scheme)
+ if not auto:
+ return text_encoder_quant, False
+ if base is not None and not _te_base_is_official(fam, base):
+ return None, False
+ return mode, True
+
+
+def _te_base_is_official(fam: Any, base: str) -> bool:
+ """The load's base is the family's registered base (or a verified equivalent), by exact id after mirror and HF
+ cache canonicalization: no final-folder-name match."""
+ from .diffusion_families import canonical_base
+ from .diffusion_te_prequant import _TE_EQUIVALENT_BASES
+ from .model_ids import hf_cache_repo_id
+
+ registered = canonical_base(str(getattr(fam, "base_repo", "") or "")).lower()
+ loading = canonical_base(hf_cache_repo_id(str(base)) or str(base)).lower()
+ if not registered or not loading:
+ return False
+ return loading == registered or any(
+ loading in group and registered in group for group in _TE_EQUIVALENT_BASES
+ )
+
+
def assert_video_precision_available(
fam: Any,
*,
@@ -698,6 +746,17 @@ def _assert_video_precision_for_target(
return
if getattr(fam, "name", None) == "ltx-2.5":
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
+
+ if (
+ te_mode == "int8"
+ and model_kind in ("pipeline", "single_file")
+ and family_te_int8_convrot(fam, "text_encoder") is not None
+ and int8_convrot_te_runs_on(target)
+ ):
+ return
te_effective = effective_te_quant(te_mode, getattr(fam, "name", None))
te_reason = None
if te_quant_needs_resident_weights(te_effective) and not torchao_quantize_importable():
@@ -3570,10 +3629,17 @@ class VideoBackend:
fam, kind, kwargs.get("gguf_filename"), kwargs.get("h3_task")
)
# An fp8 encoder request loads a hosted pre-cast checkpoint, so neither the estimate nor the pull includes
- # those dense shards.
- te_sources = self._te_prequant_sources(
+ # those dense shards. Resolved through the family default the loader applies, so an unset request on a
+ # family whose default is a hosted encoder does not stage the dense one. kwargs keep the RAW request.
+ te_planned, _ = video_te_quant_request(
fam,
kwargs.get("text_encoder_quant"),
+ base = base,
+ speed_mode = kwargs.get("speed_mode"),
+ )
+ te_sources = self._te_prequant_sources(
+ fam,
+ te_planned,
kwargs.get("gpu_ordinal"),
base = base,
)
@@ -3605,7 +3671,7 @@ class VideoBackend:
transformer_quant = kwargs.get("transformer_quant"),
speed_mode = kwargs.get("speed_mode"),
memory_mode = kwargs.get("memory_mode"),
- text_encoder_quant = kwargs.get("text_encoder_quant"),
+ text_encoder_quant = te_planned,
gpu_ordinal = kwargs.get("gpu_ordinal"),
hf_token = kwargs.get("hf_token"),
ltx25_dev = ltx25_dev,
@@ -3678,6 +3744,16 @@ class VideoBackend:
H3_TE_QUANT_REPO,
H3_LEGACY_TE_QUANT_REPO,
)
+ # The same for a hosted pre-cast encoder (unsloth/Wan2.2-TI2V-5B-FP8 for every Wan base).
+ te_repos = tuple(
+ src.location
+ for src in (te_sources or {}).values()
+ if getattr(src, "kind", None) == "repo"
+ )
+ if te_repos:
+ self._loading.asset_repos = tuple(
+ dict.fromkeys(self._loading.asset_repos + te_repos)
+ )
# Dense shards dropped: a delete of the seeded repo mid-fetch strands the load.
if skip_transformer_weights:
claimed = self._denoiser_prequant_repo_ids(
@@ -4623,7 +4699,15 @@ class VideoBackend:
) -> dict[str, Any]:
"""``{component: source}`` for the text encoders this load will take PRE-CAST from a
hosted checkpoint instead of the base repo's dense weights (``{}`` when none)."""
+ if getattr(fam, "name", None) == "ltx-2.5":
+ # The sidecar worker loads LTX-2.5's hosted int8 ConvRot Gemma 4 encoder; resolving it here is what lets
+ # the plan, the estimate and the pre-fetch stage that file and drop the dense text_encoder/ shards.
+ from .video_ltx25 import ltx25_te_prequant_sources
+ return ltx25_te_prequant_sources(
+ text_encoder_quant, base or str(getattr(fam, "base_repo", "") or "")
+ )
from .diffusion_te_prequant import te_prequant_sources_for_base
+
return te_prequant_sources_for_base(
fam,
base or str(getattr(fam, "base_repo", "") or ""),
@@ -5730,6 +5814,11 @@ class VideoBackend:
h3_task = _h3_single_file_task(fam, kind, gguf_filename, h3_task)
# A dev LTX-2.5 load is single stage and never opens the latent upsampler.
ltx25_dev = _ltx25_dev_load(fam, kind, gguf_filename, repo_id, display_repo_id)
+ # The family default the loader applies to an unset encoder request, so the plan stages the hosted encoder
+ # instead of the dense shards the load would not open. H3 keeps reading the raw request below.
+ te_planned, _ = video_te_quant_request(
+ fam, text_encoder_quant, base = base, speed_mode = load_kwargs.get("speed_mode")
+ )
# The same resolution the load makes, so an H3 auto pick the loader will serve from a hosted checkpoint is not
# staged dense here first: that is 66.3 GB the panel downloads and the load never opens, and the replacement
# would then arrive outside this plan.
@@ -5754,7 +5843,7 @@ class VideoBackend:
transformer_quant = transformer_quant,
speed_mode = load_kwargs.get("speed_mode"),
memory_mode = load_kwargs.get("memory_mode"),
- text_encoder_quant = text_encoder_quant,
+ text_encoder_quant = te_planned,
gpu_ordinal = load_kwargs.get("gpu_ordinal"),
hf_token = hf_token,
ltx25_dev = ltx25_dev,
@@ -5876,7 +5965,7 @@ class VideoBackend:
# Pre-cast encoders first: only a checkpoint that really resolves earns the right to drop the dense shards
te_sources = self._te_prequant_sources(
fam,
- text_encoder_quant,
+ te_planned,
load_kwargs.get("gpu_ordinal"),
base = base,
)
@@ -6587,6 +6676,27 @@ class VideoBackend:
target = self._device_target(gpu_ordinal)
device = target.device
+ # Text-encoder tri-state, resolved once here so the memory plan, the pre-cast injection and the dense cast below
+ # see one decision: unset / "auto" takes the family's te_quant_auto (the hosted encoder ComfyUI's template
+ # matches), "none" / "off" keep the released one, an explicit scheme pins itself. An automatic pick this card
+ # cannot run is dropped rather than refused.
+ text_encoder_quant_requested = text_encoder_quant
+ text_encoder_quant, text_encoder_quant_auto = video_te_quant_request(
+ fam,
+ text_encoder_quant,
+ base = repo_id if kind == "pipeline" else base,
+ speed_mode = speed_mode,
+ )
+ if text_encoder_quant_auto:
+ from . import diffusion_precision as _precision
+ if _precision.te_quant_supported(target, text_encoder_quant):
+ logger.info(
+ "video.text_encoder_quant: '%s' selected automatically for %s (unset request)",
+ text_encoder_quant,
+ fam.name,
+ )
+ else:
+ text_encoder_quant = None
# FlashInfer only serves hosted pre-quantised denoisers. Modular H3 installs below; a conventional load installs
# after its live-memory plan keeps the seed (a capacity-settled seed can still be dropped).
_nvfp4_install_wanted = (
@@ -7105,6 +7215,7 @@ class VideoBackend:
resident = encoder_resident_for_plan(plan),
budget_mib = (getattr(plan, "estimates", None) or {}).get("safe_device_budget_mib"),
te_quant = ltx25_te_quant_scheme(text_encoder_quant),
+ base_repo = base,
)
# Installed only while this load is current: a load superseded during the start must not overwrite the
# newer load's worker (whose token-scoped cleanup could then never find it).
@@ -7151,6 +7262,9 @@ class VideoBackend:
local_files_only = local_files_only,
)
pipe_kwargs.update(te_injected)
+ if text_encoder_quant_auto and not te_injected:
+ # Nobody asked for a runtime cast: without its hosted file the automatic pick keeps the released encoder.
+ text_encoder_quant = None
# The fp8-sized budget is valid only once the pre-cast encoder is in hand. Injection is best-effort (an
# unreachable / corrupt / base-mismatched checkpoint falls back to the dense encoder), and a dense encoder under
# an fp8 budget under-states the resident requirement by ~11 GB for ltx-2, which is the direction that OOMs.
@@ -7208,6 +7322,8 @@ class VideoBackend:
c
for c in tuple(_te_prequant_skipped or ()) + tuple(_denoiser_prequant_skipped or ())
if c not in pipe_kwargs
+ # LTX-2.5's skipped encoder is the worker's: it loads the hosted file, else re-reads the Hub itself.
+ and not (ltx25_client is not None and c == "text_encoder")
]
if missing_dense and _base_local_dir:
logger.warning(
@@ -7747,11 +7863,15 @@ class VideoBackend:
family = fam.name,
offload_active = plan.offload_policy != "none",
logger = logger,
+ encoders = (getattr(fam, "te_quant_auto_encoders", None) or None)
+ if text_encoder_quant_auto
+ else None,
)
text_encoder_quant_engaged = text_encoder_outcome.mode
if (
(text_encoder_quant_engaged is None or text_encoder_outcome.partial)
and normalize_te_quant(text_encoder_quant) is not None
+ and not text_encoder_quant_auto
and not precision_fallback_allowed()
):
del pipe
@@ -8153,9 +8273,14 @@ class VideoBackend:
else transformer_quant_decline_status,
),
"text_encoder_quant": (
- text_encoder_quant,
+ # The RAW request: an automatic pick must not read as a scheme the caller pinned.
+ text_encoder_quant_requested,
text_encoder_quant_engaged or "off",
- text_encoder_outcome.reason
+ (
+ f"{text_encoder_outcome.reason or 'engaged'} (selected automatically: the family default)"
+ if text_encoder_quant_auto and text_encoder_quant_engaged is not None
+ else text_encoder_outcome.reason
+ )
or (
"dense text encoder quantised in place"
if text_encoder_quant_engaged is not None
diff --git a/studio/backend/core/inference/video_families.py b/studio/backend/core/inference/video_families.py
index 5fe2f00472a..d89dfab82ee 100644
--- a/studio/backend/core/inference/video_families.py
+++ b/studio/backend/core/inference/video_families.py
@@ -296,6 +296,14 @@ class VideoFamily:
# Hosted PRE-CAST text-encoder checkpoints as (scheme, component, repo_id); same semantics as
# DiffusionFamily.te_prequant_repos.
te_prequant_repos: tuple[tuple[str, str, str], ...] = field(default_factory = tuple)
+ # The scheme an UNSET text_encoder_quant takes (video.video_te_quant_request), same contract as
+ # DiffusionFamily.te_quant_auto: must be a scheme this family HOSTS (te_prequant_repos / TE_INT8_CONVROT_FILES), so
+ # the default never costs a dense download plus an in-place cast. "none" / "off" still pin the released encoder.
+ # MiniMax-H3 and LTX-2.5 resolve their own tri-state and leave this unset.
+ te_quant_auto: Optional[str] = None
+ # The pipeline encoders that automatic pick casts, when not all of them (empty = every present encoder). An
+ # explicit text_encoder_quant still covers every encoder.
+ te_quant_auto_encoders: tuple[str, ...] = ()
# Hosted PRE-QUANTIZED DENOISER checkpoints as (scheme, repo_id). The DiT, NOT the text encoder that
# te_prequant_repos above covers: the two are separate artifacts because a load can take one without the other. Same
# semantics as DiffusionFamily.prequant_repos, so the shared diffusion_prequant resolver reads this table through
@@ -432,6 +440,8 @@ _WAN21_VAE_UNTILED = UntiledVae(bytes_per_latent_pixel = 0.6 * 2**20, output_sca
# LTX-2 / 2.3 holds every frame: peak per output frame x latent pixel, 0.102-0.105 MiB measured bf16 (B200). LTX-2.5
# has the same conv decoder layout (vae/ of the Diffusers pack); unmeasured, priced as 2.3.
_LTX2_VAE_UNTILED = UntiledVae(bytes_per_frame_latent_pixel = 0.11 * 2**20, temporal_scale = 8)
+# Wan2.1 and Wan2.2 ship one UMT5-XXL encoder, so every Wan family loads the same hosted pre-cast file.
+_WAN_UMT5_TE_PREQUANT = (("fp8", "text_encoder", "unsloth/Wan2.2-TI2V-5B-FP8"),)
_FAMILIES: tuple[VideoFamily, ...] = (
VideoFamily(
@@ -650,6 +660,9 @@ _FAMILIES: tuple[VideoFamily, ...] = (
gguf_repo = "unsloth/LTX-2.3-GGUF",
# pre-cast Gemma3-12B TE (fp32 ~49 GB on the hub, pre-cast ~13.2 GB): the biggest download win
te_prequant_repos = (("fp8", "text_encoder", "unsloth/LTX-2-FP8"),),
+ # fp8 by default. ComfyUI's LTX-2 / LTX-2.3 workflow templates (video_ltx2_t2v.json, video_ltx2_3_t2v.json) load
+ # 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"),),
# no steady gain on LTX's VAE / vocoder convs, but a per-shape re-tune (first render 26 s vs 10 s)
@@ -708,6 +721,12 @@ _FAMILIES: tuple[VideoFamily, ...] = (
# UMT5 keeps its overflowing `wo` in fp32 itself; the VAE stays fp32 (vae_force_fp32).
fp16_guard = "native",
# Byte-identical mirror of QuantStack/Wan2.2-TI2V-5B-GGUF (13 quants + companion VAE).
+ # UMT5-XXL pre-cast fp8, one file for all four Wan bases (diffusion_te_prequant._TE_EQUIVALENT_BASES), the
+ # int8 ConvRot one beside it (TE_INT8_CONVROT_FILES). fp8 by default, as ComfyUI's Wan templates load
+ # umt5_xxl_fp8_e4m3fn_scaled (workflow templates video_wan2_2_5B_ti2v.json, video_wan2_2_14B_t2v.json,
+ # text_to_video_wan.json).
+ te_prequant_repos = _WAN_UMT5_TE_PREQUANT,
+ te_quant_auto = "fp8",
gguf_repo = "unsloth/Wan2.2-TI2V-5B-GGUF",
# expand_timesteps on the loaded config keeps the first-frame latent clean.
i2v_pipeline_class = "WanImageToVideoPipeline",
@@ -764,6 +783,12 @@ _FAMILIES: tuple[VideoFamily, ...] = (
# 114.3 fp32 sum. UMT5 TE bf16 (11.4); VAE fp32 (0.5).
bf16_components_gb = (57.2, 11.4, 0.5),
vae_force_fp32 = True,
+ # UMT5-XXL pre-cast fp8, one file for all four Wan bases (diffusion_te_prequant._TE_EQUIVALENT_BASES), the
+ # int8 ConvRot one beside it (TE_INT8_CONVROT_FILES). fp8 by default, as ComfyUI's Wan templates load
+ # umt5_xxl_fp8_e4m3fn_scaled (workflow templates video_wan2_2_5B_ti2v.json, video_wan2_2_14B_t2v.json,
+ # text_to_video_wan.json).
+ te_prequant_repos = _WAN_UMT5_TE_PREQUANT,
+ te_quant_auto = "fp8",
# same VAE as TI2V-5B
cudnn_benchmark = False,
# no gguf_repo: community GGUFs split the experts; a gguf / single_file pick of either expert loads the pair
@@ -788,6 +813,12 @@ _FAMILIES: tuple[VideoFamily, ...] = (
resolution_presets = ((832, 480), (480, 832)),
bf16_components_gb = (2.8, 11.4, 0.5),
vae_force_fp32 = True,
+ # UMT5-XXL pre-cast fp8, one file for all four Wan bases (diffusion_te_prequant._TE_EQUIVALENT_BASES), the
+ # int8 ConvRot one beside it (TE_INT8_CONVROT_FILES). fp8 by default, as ComfyUI's Wan templates load
+ # umt5_xxl_fp8_e4m3fn_scaled (workflow templates video_wan2_2_5B_ti2v.json, video_wan2_2_14B_t2v.json,
+ # text_to_video_wan.json).
+ te_prequant_repos = _WAN_UMT5_TE_PREQUANT,
+ te_quant_auto = "fp8",
cudnn_benchmark = False,
),
# Wan2.1-T2V-14B: same keys as one Wan2.2 A14B expert, run as a single denoiser.
@@ -809,6 +840,12 @@ _FAMILIES: tuple[VideoFamily, ...] = (
resolution_presets = ((832, 480), (1280, 720), (480, 832), (720, 1280)),
bf16_components_gb = (28.6, 11.4, 0.5),
vae_force_fp32 = True,
+ # UMT5-XXL pre-cast fp8, one file for all four Wan bases (diffusion_te_prequant._TE_EQUIVALENT_BASES), the
+ # int8 ConvRot one beside it (TE_INT8_CONVROT_FILES). fp8 by default, as ComfyUI's Wan templates load
+ # umt5_xxl_fp8_e4m3fn_scaled (workflow templates video_wan2_2_5B_ti2v.json, video_wan2_2_14B_t2v.json,
+ # text_to_video_wan.json).
+ te_prequant_repos = _WAN_UMT5_TE_PREQUANT,
+ te_quant_auto = "fp8",
cudnn_benchmark = False,
),
# HunyuanVideo-1.5 (diffusers >= 0.39): 8.3B DiT, Qwen2.5-VL + ByT5 encoders. Three quirks: no guidance kwarg (CFG
@@ -852,6 +889,13 @@ _FAMILIES: tuple[VideoFamily, ...] = (
resolution_presets = ((832, 480), (480, 832), (640, 640)),
# DiT fp32 on disk (32.0 to 16.6 bf16); VAE 4.7 to 2.4; Qwen2.5-VL TE bf16 14.0 + ByT5 0.8
bf16_components_gb = (16.6, 14.8, 2.4),
+ # Qwen2.5-VL-7B text tower pre-cast fp8 (ByT5 stays dense: glyph rendering). fp8 by default, as ComfyUI's
+ # HunyuanVideo-1.5 template (video_hunyuan_video_1.5_720p_t2v.json) loads qwen_2.5_vl_7b_fp8_scaled. The tensors are Qwen/Qwen2.5-VL-7B-Instruct's
+ # language model unchanged (Apache-2.0), and the 480p and 720p repacks ship the same bytes.
+ te_prequant_repos = (("fp8", "text_encoder", "unsloth/HunyuanVideo-1.5-FP8"),),
+ te_quant_auto = "fp8",
+ # Only the Qwen tower: the ByT5 glyph encoder (text_encoder_2) stays dense under the default.
+ te_quant_auto_encoders = ("text_encoder",),
fp16_guard = "native",
cudnn_benchmark = False,
# Needs the capture-safe forward (diffusion_capture_safe) and the memoized trim (diffusion_attention).
@@ -887,6 +931,13 @@ _FAMILIES: tuple[VideoFamily, ...] = (
# 720p-class presets: landscape, vertical, square (all /16).
resolution_presets = ((1280, 720), (720, 1280), (960, 960)),
bf16_components_gb = (16.6, 14.8, 2.4),
+ # Qwen2.5-VL-7B text tower pre-cast fp8 (ByT5 stays dense: glyph rendering). fp8 by default, as ComfyUI's
+ # HunyuanVideo-1.5 template (video_hunyuan_video_1.5_720p_t2v.json) loads qwen_2.5_vl_7b_fp8_scaled. The tensors are Qwen/Qwen2.5-VL-7B-Instruct's
+ # language model unchanged (Apache-2.0), and the 480p and 720p repacks ship the same bytes.
+ te_prequant_repos = (("fp8", "text_encoder", "unsloth/HunyuanVideo-1.5-FP8"),),
+ te_quant_auto = "fp8",
+ # Only the Qwen tower: the ByT5 glyph encoder (text_encoder_2) stays dense under the default.
+ te_quant_auto_encoders = ("text_encoder",),
fp16_guard = "native",
cudnn_benchmark = False,
),
diff --git a/studio/backend/core/inference/video_ltx25.py b/studio/backend/core/inference/video_ltx25.py
index 002d019e454..a8d6dae718e 100644
--- a/studio/backend/core/inference/video_ltx25.py
+++ b/studio/backend/core/inference/video_ltx25.py
@@ -84,11 +84,23 @@ TEXT_ENCODER_MIN_TRANSFORMERS = "5.10.1"
# What the encoder worker holds on the card beyond its weights, on every plan tier: its CUDA context (~0.6 GB on
# Hopper / Blackwell) plus allocator slack. The weights are the family table's text-encoder term.
LTX25_WORKER_RESIDENT_GB = 1.0
-# int8 encoder is opt-in: LPIPS 0.310 vs bf16, above the 0.256 compile floor.
+# An unset text_encoder_quant runs the int8 ConvRot encoder, as ComfyUI's LTX-2.5 templates load Lightricks'
+# gemma4-12b-with-proj-ltx-2.5-comfy-int8-convrot. "none" / "off" pin the bf16 encoder; UNSLOTH_LTX25_TE_INT8=0 makes
+# an unset request bf16 again (an operator kill switch, not the default).
LTX25_TE_QUANT_DEFAULT = "int8"
LTX25_TE_QUANT_ENV = "UNSLOTH_LTX25_TE_INT8"
# Measured int8 encoder weights (12,424 MiB vs 22,811 MiB bf16).
LTX25_TE_INT8_GB = 13.1
+# The dense bf16 encoder (the family table's text-encoder term), what quantizing at load materializes first.
+LTX25_TE_BF16_GB = 23.9
+# The hosted build of that same at-load quantization (scripts/build_ltx25_te_int8_convrot.py): the worker loads it
+# instead of reading the 23.9 GB bf16 encoder and quantizing it, and the plan drops the dense text_encoder/ shards. A
+# file that cannot be fetched or loaded falls back to the at-load quantization of the dense encoder.
+LTX25_TE_HOSTED_REPO = "unsloth/LTX-2.5-FP8"
+LTX25_TE_HOSTED_FILE = "LTX-2.5-text_encoder-INT8-ConvRot.safetensors"
+LTX25_TE_HOSTED_FORMAT = "unsloth_ltx25_text_encoder_int8_convrot_v1"
+# The base the hosted encoder was cut from: a custom pack can keep the architecture and carry other weights.
+LTX25_TE_HOSTED_BASE = "Lightricks/LTX-2.5-Diffusers"
# The pack's latent_upsampler/ (995,743,320 bytes), part of the family table's companions; only two-stage loads hold it.
LTX25_LATENT_UPSAMPLER_GB = 1.0
@@ -676,18 +688,51 @@ def ltx25_te_quant_scheme(text_encoder_quant: Optional[str]) -> Optional[str]:
from .diffusion_precision import normalize_te_quant, te_quant_is_auto
if te_quant_is_auto(text_encoder_quant):
- if (os.environ.get(LTX25_TE_QUANT_ENV) or "").strip().lower() in ("1", "true", "yes", "on"):
- return LTX25_TE_QUANT_DEFAULT
- return None
+ if (os.environ.get(LTX25_TE_QUANT_ENV) or "").strip().lower() in _OFF:
+ return None
+ return LTX25_TE_QUANT_DEFAULT
scheme = normalize_te_quant(text_encoder_quant)
if scheme is None or scheme == LTX25_TE_QUANT_DEFAULT:
return scheme
raise ValueError(
f"LTX-2.5's Gemma 4 text encoder runs int8 (ConvRot, as in ComfyUI's LTX-2.5 workflows) or bf16, not "
- f"'{scheme}'. Pick int8 for int8, or leave it unset / Off for bf16."
+ f"'{scheme}'. Pick int8 (the default when unset) for int8, or Off for bf16."
)
+def ltx25_te_prequant_sources(
+ text_encoder_quant: Optional[str], base: Optional[str]
+) -> dict[str, Any]:
+ """``{"text_encoder": source}`` when this load takes the hosted int8 ConvRot encoder, else ``{}``.
+
+ The video backend's pre-cast planner asks this for LTX-2.5, so the hosted file is fetched with the load's progress
+ and cancel, and only a file that resolves drops the dense ``text_encoder/`` shards. Pack loads of the base the file
+ was cut from only: the single-file release reads its text projections out of its own encoder file, and a custom
+ pack may carry other weights. Pure, never raises."""
+ try:
+ if ltx25_te_quant_scheme(text_encoder_quant) != LTX25_TE_QUANT_DEFAULT:
+ return {}
+ if not base or is_ltx25_single_file_base(base):
+ return {}
+ from .diffusion_families import canonical_base
+ from .diffusion_te_prequant import TePrequantSource
+ from .model_ids import hf_cache_repo_id
+
+ # Exact identity (an HF cache snapshot counts as its repo): the worker strict-loads the hosted state dict into
+ # whatever architecture the pack builds, so a same-shaped custom pack that merely shares the folder name
+ # would silently lose its own encoder weights.
+ identity = hf_cache_repo_id(str(base)) or str(base)
+ if canonical_base(identity).lower() != canonical_base(LTX25_TE_HOSTED_BASE).lower():
+ return {}
+ return {
+ "text_encoder": TePrequantSource(
+ kind = "repo", location = LTX25_TE_HOSTED_REPO, filename = LTX25_TE_HOSTED_FILE
+ )
+ }
+ except Exception: # noqa: BLE001 -- no hosted encoder: the worker quantizes the dense one
+ return {}
+
+
def ltx25_te_budget_scale(text_encoder_quant: Optional[str], bf16_gb: float) -> float:
try:
scheme = ltx25_te_quant_scheme(text_encoder_quant)
@@ -703,9 +748,13 @@ def ltx25_te_outcome(client: Any) -> Any:
scheme = (getattr(client, "config", None) or {}).get("te_quant")
if scheme:
- return TEQuantOutcome(
- scheme, "int8 ConvRot weight-only Gemma 4 encoder (ComfyUI's LTX-2.5 encoder)"
- )
+ source = (getattr(client, "info", None) or {}).get("te_source")
+ detail = "int8 ConvRot weight-only Gemma 4 encoder (ComfyUI's LTX-2.5 encoder)"
+ if source == "hosted":
+ detail += f", loaded from {LTX25_TE_HOSTED_REPO}"
+ elif source == "quantized_at_load":
+ detail += ", quantized at load"
+ return TEQuantOutcome(scheme, detail)
return TEQuantOutcome(None)
@@ -774,6 +823,8 @@ class Ltx25TextEncoderClient:
single_file: Optional[str] = None,
budget_mib: Optional[int] = None,
te_quant: Optional[str] = None,
+ te_prequant: Optional[dict] = None,
+ hub_repo: Optional[str] = None,
) -> None:
self.config = {
"repo": repo,
@@ -790,6 +841,13 @@ class Ltx25TextEncoderClient:
# The load's memory budget: a non-resident encoder onloads only into what the server leaves of it.
"budget_mib": budget_mib,
"te_quant": te_quant,
+ # The hosted int8 file ({repo, filename, mirror_path}) for an int8 load, else None; and the Hub id of the
+ # pack, where the dense fallback reads when ``repo`` is a scoped snapshot that skipped its shards.
+ "te_prequant": te_prequant,
+ "hub_repo": hub_repo,
+ # A plan priced at the hosted file's size cannot cover the dense fallback's peak: the worker refuses it
+ # when free memory does not hold the dense encoder.
+ "dense_te_gb": LTX25_TE_BF16_GB if te_prequant else None,
}
self.cancel_event = cancel_event
self._proc: Any = None
@@ -1069,10 +1127,24 @@ def start_text_encoder(
resident: bool,
budget_mib: Optional[int] = None,
te_quant: Optional[str] = None,
+ base_repo: Optional[str] = None,
) -> Ltx25TextEncoderClient:
"""Check the sidecar (a named refusal before any weight is read), then spawn the encoder worker so the Gemma 4
- load overlaps the DiT load."""
+ load overlaps the DiT load. ``base_repo`` is the upstream pack id (``repo`` may be its local snapshot); an int8
+ load of the pack the hosted encoder was cut from hands the worker that file."""
venv_dir = ensure_text_encoder_sidecar()
+ te_prequant = None
+ hub_repo = base_repo or repo
+ sources = ltx25_te_prequant_sources(te_quant, hub_repo) if te_quant else {}
+ source = sources.get("text_encoder")
+ if source is not None:
+ from .diffusion_te_prequant import te_prequant_mirror_path
+ te_prequant = {
+ "repo": source.location,
+ "filename": source.filename,
+ "mirror_path": te_prequant_mirror_path(source.location, source.filename),
+ "base": LTX25_TE_HOSTED_BASE,
+ }
client = Ltx25TextEncoderClient(
repo = repo,
hf_token = hf_token,
@@ -1085,6 +1157,8 @@ def start_text_encoder(
single_file = LTX25_SINGLE_TEXT_ENCODER if is_ltx25_single_file_base(repo) else None,
budget_mib = budget_mib,
te_quant = te_quant,
+ te_prequant = te_prequant,
+ hub_repo = hub_repo if hub_repo != repo else None,
)
client.start()
return client
diff --git a/studio/backend/core/inference/video_ltx25_te_worker.py b/studio/backend/core/inference/video_ltx25_te_worker.py
index dd99ed9b4c8..a5b127e89ae 100644
--- a/studio/backend/core/inference/video_ltx25_te_worker.py
+++ b/studio/backend/core/inference/video_ltx25_te_worker.py
@@ -149,14 +149,31 @@ def _load(config: dict) -> tuple[Any, Any]:
tokenizer = transformers.AutoTokenizer.from_pretrained(
repo, subfolder = "tokenizer", **common
)
- model = model_cls.from_pretrained(
- repo, subfolder = "text_encoder", torch_dtype = dtype, **common
- )
+ model = None
+ if config.get("te_quant") == TE_QUANT_INT8_CONVROT and config.get("te_prequant"):
+ try:
+ model = _load_hosted(config, model_cls, dtype, common)
+ config["_te_source"] = "hosted"
+ except Exception as exc: # noqa: BLE001 -- the dense encoder quantized at load is the same build
+ _require_room_for_dense(config, exc)
+ print(
+ f"video.ltx25_te: hosted int8 ConvRot encoder unavailable ({exc}); quantizing the dense "
+ "encoder at load",
+ file = sys.stderr,
+ flush = True,
+ )
+ model = None
+ if model is None:
+ model = _load_dense(config, model_cls, dtype, common)
model.eval()
model.requires_grad_(False)
_truncate_dead_tail(tokenizer, model)
if config.get("te_quant") == TE_QUANT_INT8_CONVROT:
- quantize_int8_convrot_(model, config.get("device") or "cpu", bool(config.get("resident")))
+ if config.get("_te_source") != "hosted":
+ quantize_int8_convrot_(
+ model, config.get("device") or "cpu", bool(config.get("resident"))
+ )
+ config["_te_source"] = "quantized_at_load"
elif config.get("te_quant"):
raise RuntimeError(f"unsupported text encoder precision '{config.get('te_quant')}'")
if config.get("resident"):
@@ -164,12 +181,171 @@ def _load(config: dict) -> tuple[Any, Any]:
return tokenizer, model
-# Matches ComfyUI's gemma4 int8-convrot encoder, built from the bf16 weights on disk (no second 15 GB download).
+# Matches ComfyUI's gemma4 int8-convrot encoder. Loaded from the hosted build of this same quantization
+# (scripts/build_ltx25_te_int8_convrot.py) when the server hands one over, else built from the bf16 weights at load.
TE_QUANT_INT8_CONVROT = "int8"
CONVROT_GROUP = 256
_PROJECTIONS = ("q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj")
+def _available_host_bytes() -> Optional[int]:
+ try:
+ import psutil
+ return int(psutil.virtual_memory().available)
+ except Exception: # noqa: BLE001 -- no psutil in this venv
+ pass
+ try:
+ with open("/proc/meminfo", encoding = "utf-8") as fh:
+ for line in fh:
+ if line.startswith("MemAvailable:"):
+ return int(line.split()[1]) * 1024
+ except OSError:
+ pass
+ return None
+
+
+def _require_room_for_dense(config: dict, exc: Exception) -> None:
+ """The load was planned at the hosted file's size: refuse the dense fallback when free memory cannot hold the
+ dense encoder, rather than let the OS kill the process mid-read (on Apple Silicon the same pool as the DiT)."""
+ need = float(config.get("dense_te_gb") or 0.0) * 1000**3
+ free = _available_host_bytes()
+ if need and free is not None and free < need:
+ raise RuntimeError(
+ f"The hosted int8 text encoder could not be loaded ({exc}), and quantizing the dense encoder at load "
+ f"needs about {need / 1000**3:.0f} GB of free memory ({free / 1000**3:.0f} GB free)."
+ ) from exc
+
+
+def _load_dense(config: dict, model_cls: Any, dtype: Any, common: dict) -> Any:
+ """The pack's bf16 encoder. A scoped snapshot whose dense shards the plan dropped for the hosted file has none to
+ open, so a failed read retries the pack's Hub id (``hub_repo``) the way a fresh load would fetch it."""
+ repo, hub_repo = config["repo"], config.get("hub_repo")
+ try:
+ return model_cls.from_pretrained(
+ repo, subfolder = "text_encoder", torch_dtype = dtype, **common
+ )
+ except Exception:
+ # Offline too: a complete dense snapshot may already be cached under the Hub id.
+ if not hub_repo or hub_repo == repo:
+ raise
+ return model_cls.from_pretrained(
+ hub_repo, subfolder = "text_encoder", torch_dtype = dtype, **common
+ )
+
+
+def _hosted_path(spec: dict, common: dict) -> str:
+ mirror = spec.get("mirror_path")
+ if mirror and os.path.isfile(mirror):
+ return mirror
+ from huggingface_hub import hf_hub_download, try_to_load_from_cache
+
+ kwargs = dict(common)
+ # The server stages this file with reuse_other_cache_root (hf_hub_download_with_xet_fallback), so a copy cached
+ # only under huggingface_hub's own root counts as staged and the dense shards are dropped. Resolve it the same way,
+ # else a local_files_only load misses it here and has no dense encoder to fall back to.
+ if kwargs.get("cache_dir"):
+ try:
+ here = try_to_load_from_cache(
+ spec["repo"], spec["filename"], cache_dir = kwargs["cache_dir"]
+ )
+ if not isinstance(here, str):
+ elsewhere = try_to_load_from_cache(spec["repo"], spec["filename"], cache_dir = None)
+ if isinstance(elsewhere, str) and os.path.isfile(elsewhere):
+ kwargs["cache_dir"] = None
+ except Exception: # noqa: BLE001 -- an unreadable cache keeps the configured root
+ pass
+ return hf_hub_download(spec["repo"], spec["filename"], **kwargs)
+
+
+def _load_hosted(config: dict, model_cls: Any, dtype: Any, common: dict) -> Any:
+ """The hosted int8 ConvRot encoder: the skeleton meta-initialised from the pack's text_encoder config, every
+ decoder projection swapped for ``Int8ConvRotLinear``, then the file assigned in strictly (the tied lm_head is the
+ one key it lacks, re-tied to the embedding). Raises on any mismatch; the caller falls back to the at-load build."""
+ import torch
+ import transformers
+ from accelerate import init_empty_weights
+ from torch import nn
+
+ from core.inference.prequant_safetensors import load_plain_prequant_safetensors
+ from core.inference.video_ltx25 import LTX25_TE_HOSTED_FORMAT
+ from core.inference.video_minimax_h3_te import _int8_convrot_linear_class, _meta_tensor_names
+
+ spec = config["te_prequant"]
+ ckpt = load_plain_prequant_safetensors(_hosted_path(spec, common))
+ if ckpt.get("format") != LTX25_TE_HOSTED_FORMAT:
+ raise ValueError(f"not an LTX-2.5 int8 ConvRot encoder (format {ckpt.get('format')!r})")
+ meta = ckpt.get("metadata") or {}
+ quant = meta.get("quant") or {}
+ if str(meta.get("base_model_id") or "").lower() != str(spec.get("base") or "").lower():
+ raise ValueError(f"built from {meta.get('base_model_id')!r}, not {spec.get('base')!r}")
+ if meta.get("scheme") != "int8" or quant.get("group_size") != CONVROT_GROUP:
+ raise ValueError(
+ f"unexpected scheme {meta.get('scheme')!r} / group {quant.get('group_size')!r}"
+ )
+ state_dict = ckpt["state_dict"]
+ for key, tensor in list(state_dict.items()):
+ # The int8 codes and fp32 scales keep their storage; dense tensors follow the load dtype, as from_pretrained.
+ if (
+ tensor.is_floating_point()
+ and not key.endswith(".weight_scale")
+ and tensor.dtype != dtype
+ ):
+ state_dict[key] = tensor.to(dtype)
+ repo, hub_repo = config["repo"], config.get("hub_repo")
+ try:
+ cfg = transformers.AutoConfig.from_pretrained(repo, subfolder = "text_encoder", **common)
+ except Exception:
+ if not hub_repo or hub_repo == repo:
+ raise
+ cfg = transformers.AutoConfig.from_pretrained(hub_repo, subfolder = "text_encoder", **common)
+ previous = torch.get_default_dtype()
+ # from_pretrained(torch_dtype = bf16) builds under the same default, so buffers made in __init__ match it.
+ torch.set_default_dtype(dtype)
+ try:
+ with init_empty_weights(include_buffers = False):
+ model = model_cls(cfg)
+ finally:
+ torch.set_default_dtype(previous)
+ cls = _int8_convrot_linear_class()
+ for layer in _decoder_layers(model):
+ for parent in (getattr(layer, "self_attn", None), getattr(layer, "mlp", None)):
+ if parent is None:
+ continue
+ for name in _PROJECTIONS:
+ linear = getattr(parent, name, None)
+ if isinstance(linear, nn.Linear):
+ setattr(
+ parent,
+ name,
+ cls(
+ linear.in_features,
+ linear.out_features,
+ linear.bias is not None,
+ CONVROT_GROUP,
+ ),
+ )
+ result = model.load_state_dict(state_dict, strict = False, assign = True)
+ tied = {"lm_head.weight"} if getattr(cfg, "tie_word_embeddings", False) else set()
+ missing = set(result.missing_keys) - tied
+ if missing or result.unexpected_keys:
+ raise ValueError(
+ f"hosted encoder does not match the model: missing {sorted(missing)[:3]}, "
+ f"unexpected {sorted(result.unexpected_keys)[:3]}"
+ )
+ tie = getattr(model, "tie_weights", None)
+ if callable(tie):
+ tie()
+ stranded = _meta_tensor_names(model)
+ if stranded:
+ raise ValueError(f"{len(stranded)} tensor(s) still on the meta device, e.g. {stranded[0]}")
+ swapped = sum(1 for m in model.modules() if isinstance(m, cls))
+ if swapped != int(quant.get("linears") or -1):
+ raise ValueError(
+ f"{swapped} projections swapped, the file quantized {quant.get('linears')}"
+ )
+ return model
+
+
def _decoder_layers(model: Any) -> Any:
inner = getattr(model, "model", model)
language = getattr(inner, "language_model", inner)
@@ -502,6 +678,8 @@ def run_text_encoder_worker(*, cmd_queue: Any, resp_queue: Any, config: dict) ->
),
"resident": bool(config.get("resident")),
"te_quant": config.get("te_quant") or None,
+ # "hosted" (the unsloth file), "quantized_at_load" (built from the dense encoder) or None (bf16).
+ "te_source": config.get("_te_source"),
"weights_mib": _weights_mib_or_none(model),
**_memory_stats(config.get("device") or ""),
}
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 10b57512eea..0e06a1c273d 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -6215,10 +6215,11 @@ class VideoLoadRequest(BaseModel):
"torchao int8 COMPUTE with per-family keep-bf16 selection (cc >= 8.0; falls back to fp8 "
"for a family without a measured schedule); nvfp4 = torchao 4-bit weight-only, "
"dequantised to bf16 per forward (cc >= 8.0). null/auto leaves the choice to the backend, "
- "which keeps the encoder dense on every family except MiniMax-H3, where it takes the "
- "hosted quantized conditioner; "
- "none/off always keeps the released bf16 encoder, which on MiniMax-H3 is the only way "
- "to ask for it. Mirrors the image backend's field.",
+ "which takes the hosted pre-quantized encoder matching ComfyUI's template for the family: "
+ "fp8 for Wan, LTX-2 / LTX-2.3 and HunyuanVideo-1.5, int8 ConvRot for LTX-2.5, and the "
+ "hosted quantized conditioner on MiniMax-H3; a host that cannot run it keeps the dense "
+ "encoder. none/off always keeps the released bf16 encoder. Mirrors the image backend's "
+ "field.",
)
h3_task: Optional[Literal["fl2va", "ref2va"]] = Field(
diff --git a/studio/backend/tests/test_diffusion_te_prequant.py b/studio/backend/tests/test_diffusion_te_prequant.py
index bc7b1d5d215..abf84b57c8d 100644
--- a/studio/backend/tests/test_diffusion_te_prequant.py
+++ b/studio/backend/tests/test_diffusion_te_prequant.py
@@ -883,11 +883,13 @@ def test_shipped_video_and_image_families_resolve_the_scale(monkeypatch):
monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
scale = tpq.TE_PREQUANT_BUDGET_SCALE
- # ltx-2 hosts its Gemma3-12B encoder pre-cast; the Wan families do not.
+ # ltx-2 hosts its Gemma3-12B encoder pre-cast, and every Wan family the one UMT5-XXL file.
for repo, expected in (
("Lightricks/LTX-2", scale),
- ("Wan-AI/Wan2.2-TI2V-5B-Diffusers", 1.0),
- ("Wan-AI/Wan2.2-T2V-A14B-Diffusers", 1.0),
+ ("Wan-AI/Wan2.2-TI2V-5B-Diffusers", scale),
+ ("Wan-AI/Wan2.2-T2V-A14B-Diffusers", scale),
+ ("Wan-AI/Wan2.1-T2V-1.3B-Diffusers", scale),
+ ("Wan-AI/Wan2.1-T2V-14B-Diffusers", scale),
):
fam = detect_video_family(repo)
assert _budget_scale(fam, base = repo) == expected, repo
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 59c85db8efe..c2a0b44fe25 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -9639,6 +9639,8 @@ def test_gguf_plan_budgets_a_pre_cast_text_encoder_at_its_real_size(
gguf_filename = "model.gguf",
base_repo = "Lightricks/LTX-2",
family_override = "ltx-2",
+ # Pinned dense: unset now takes the family's hosted fp8 encoder.
+ text_encoder_quant = "none",
)
bf16_companion = calls[0]["companion_dense_mib"]
bf16_dense = calls[0]["model_dense_mib"]
@@ -9689,12 +9691,22 @@ def test_plan_returns_to_bf16_when_the_pre_cast_encoder_does_not_inject(fake_run
def test_plan_keeps_the_bf16_budget_without_a_hosted_pre_cast_encoder(fake_runtime, monkeypatch):
- # Wan requests fp8 the same way, but hosts no pre-cast checkpoint: the encoder is downloaded
- # dense and cast in place AFTER assembly, so its PEAK is bf16 and the budget must not shrink.
+ # A family that requests fp8 the same way but hosts no pre-cast checkpoint: the encoder is
+ # downloaded dense and cast in place AFTER assembly, so its PEAK is bf16 and the budget must not
+ # shrink. Every shipped generic-path family now hosts one, so the table entry is dropped here.
+ import dataclasses
+
+ import core.inference.video_families as vf
from core.inference.video_families import detect_video_family
_allow_te_prequant(monkeypatch)
- components = detect_video_family("Wan-AI/Wan2.2-TI2V-5B-Diffusers").bf16_components_gb
+ wan = detect_video_family("Wan-AI/Wan2.2-TI2V-5B-Diffusers")
+ bare = dataclasses.replace(wan, te_prequant_repos = (), te_quant_auto = None)
+ monkeypatch.setattr(vf, "_FAMILIES", tuple(bare if f is wan else f for f in vf._FAMILIES))
+ import core.inference.diffusion_te_prequant as tpq
+
+ monkeypatch.setattr(tpq, "TE_INT8_CONVROT_FILES", {})
+ components = wan.bf16_components_gb
calls = _capture_plan(monkeypatch)
VideoBackend().load_pipeline(
@@ -9703,6 +9715,24 @@ def test_plan_keeps_the_bf16_budget_without_a_hosted_pre_cast_encoder(fake_runti
assert calls[0]["model_dense_mib"] == int(sum(components) * _MIB_PER_GB)
+def test_default_load_budgets_the_hosted_encoder_its_family_defaults_to(fake_runtime, monkeypatch):
+ # An UNSET request on a family with te_quant_auto takes the hosted fp8 encoder, so the plan is
+ # built from the pre-cast size, exactly as for an explicit fp8; "none" keeps the bf16 budget.
+ from core.inference.video_families import detect_video_family
+ scale = _allow_te_prequant(monkeypatch)
+ for repo in ("Wan-AI/Wan2.2-TI2V-5B-Diffusers", "Wan-AI/Wan2.1-T2V-1.3B-Diffusers"):
+ fam = detect_video_family(repo)
+ transformer_gb, text_encoder_gb, vae_gb = fam.bf16_components_gb
+ calls = _capture_plan(monkeypatch)
+ VideoBackend().load_pipeline(repo, model_kind = "pipeline")
+ assert calls[0]["text_encoder_dense_mib"] == int(
+ text_encoder_gb * scale * _MIB_PER_GB
+ ), repo
+ calls = _capture_plan(monkeypatch)
+ VideoBackend().load_pipeline(repo, model_kind = "pipeline", text_encoder_quant = "none")
+ assert calls[0]["text_encoder_dense_mib"] == int(text_encoder_gb * _MIB_PER_GB), repo
+
+
def test_plan_is_unchanged_when_no_text_encoder_quant_is_requested(fake_runtime, monkeypatch):
# The whole change is inert on a default load: every family keeps its bf16-table budget, so no
# existing decision on any device moves.
@@ -9720,13 +9750,24 @@ def test_plan_is_unchanged_when_no_text_encoder_quant_is_requested(fake_runtime,
if fam.modular_workflow:
continue
calls.clear()
- VideoBackend().load_pipeline(fam.base_repo, model_kind = "pipeline")
+ # "none": a family with te_quant_auto takes its hosted encoder on an unset request, which
+ # test_default_load_budgets_the_hosted_encoder_its_family_defaults_to covers.
+ VideoBackend().load_pipeline(
+ fam.base_repo,
+ model_kind = "pipeline",
+ text_encoder_quant = "none" if fam.te_quant_auto else None,
+ )
# LTX-2.5's encoder runs in a second process; its CUDA context is priced on top of the table.
from core.inference.video_ltx25 import LTX25_WORKER_RESIDENT_GB
extra_gb = LTX25_WORKER_RESIDENT_GB if fam.name == "ltx-2.5" else 0.0
+ components = list(fam.bf16_components_gb)
+ if fam.name == "ltx-2.5":
+ # LTX-2.5's unset request is its int8 ConvRot encoder (ComfyUI's), so the table's encoder is priced int8.
+ from core.inference.video_ltx25 import LTX25_TE_INT8_GB
+ components[1] = LTX25_TE_INT8_GB
assert calls[0]["model_dense_mib"] == int(
- (sum(fam.bf16_components_gb) + extra_gb) * _MIB_PER_GB
+ (sum(components) + extra_gb) * _MIB_PER_GB
), fam.name
@@ -14122,3 +14163,40 @@ def test_a_diffusers_without_the_i2v_class_reports_no_first_frame(fake_runtime):
with pytest.raises(ValueError, match = "WanImageToVideoPipeline"):
backend.begin_generate(prompt = "p", first_frame = _data_url(64, 64))
assert backend.generate_progress()["active"] is False
+
+
+def test_an_automatic_encoder_pick_that_does_not_engage_loads_dense_without_a_refusal(
+ fake_runtime, monkeypatch
+):
+ """Wan's unset request resolves to the hosted fp8 encoder. When nothing engages (the file is not
+ published yet and the stub pipeline has no encoder to cast), the load keeps the dense encoder and
+ reports the raw request; the same outcome on an EXPLICIT fp8 is still refused."""
+ import core.inference.diffusion_precision as precision
+ import core.inference.diffusion_te_prequant as tpq
+ import core.inference.video as video_mod
+
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", raising = False)
+ monkeypatch.setattr(precision, "te_quant_supported", lambda target, mode: True)
+ monkeypatch.setattr(tpq, "te_prequant_pipe_kwargs", lambda *a, **k: {})
+ seen = []
+
+ def _quantize(pipe, target, *, mode, **kw):
+ seen.append(mode)
+ return precision.TEQuantOutcome(None, "no text encoder could be cast", "unsupported")
+
+ monkeypatch.setattr(video_mod, "quantize_text_encoders", _quantize)
+ backend = VideoBackend()
+ status = backend.load_pipeline("Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline")
+ # No hosted file injected: the automatic pick keeps the released encoder instead of casting it at runtime.
+ assert [precision.normalize_te_quant(m) for m in seen] == [None]
+ assert status["resolved"]["text_encoder_quant"]["requested"] in (None, "auto")
+ backend.unload()
+ seen.clear()
+ status = VideoBackend().load_pipeline(
+ "Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", text_encoder_quant = "none"
+ )
+ assert [precision.normalize_te_quant(m) for m in seen] == [None]
+ with pytest.raises(RuntimeError, match = "text_encoder_quant"):
+ VideoBackend().load_pipeline(
+ "Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", text_encoder_quant = "fp8"
+ )
diff --git a/studio/backend/tests/test_video_ltx25_te_hosted.py b/studio/backend/tests/test_video_ltx25_te_hosted.py
new file mode 100644
index 00000000000..b11b982596d
--- /dev/null
+++ b/studio/backend/tests/test_video_ltx25_te_hosted.py
@@ -0,0 +1,377 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""LTX-2.5's hosted int8 ConvRot Gemma 4 encoder: the default, its planning, its load and its fallback."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+import torch
+from torch import nn
+
+from core.inference import video_ltx25 as v25
+from core.inference import video_ltx25_te_worker as worker
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[3] / "scripts"))
+
+
+class _Attn(nn.Module):
+ def __init__(self, d):
+ super().__init__()
+ self.q_proj = nn.Linear(d, d, bias = False)
+ self.k_proj = nn.Linear(d, d // 2, bias = False)
+ self.o_proj = nn.Linear(d, d, bias = False)
+ self.q_norm = nn.LayerNorm(d)
+
+
+class _Mlp(nn.Module):
+ def __init__(self, d):
+ super().__init__()
+ self.gate_proj = nn.Linear(d, 2 * d, bias = False)
+ self.up_proj = nn.Linear(d, 2 * d, bias = False)
+ self.down_proj = nn.Linear(2 * d, d, bias = False)
+
+
+class _Layer(nn.Module):
+ def __init__(self, d):
+ super().__init__()
+ self.self_attn = _Attn(d)
+ self.mlp = _Mlp(d)
+
+
+class _TinyGemma(nn.Module):
+ """The shape of Gemma4UnifiedForConditionalGeneration the worker walks: model.language_model.layers."""
+
+ def __init__(
+ self,
+ d = 256,
+ layers = 2,
+ ):
+ super().__init__()
+ self.model = nn.Module()
+ self.model.language_model = nn.Module()
+ self.model.language_model.embed_tokens = nn.Embedding(16, d)
+ self.model.language_model.layers = nn.ModuleList(_Layer(d) for _ in range(layers))
+
+
+BASE = "Lightricks/LTX-2.5-Diffusers"
+
+
+def test_unset_request_resolves_to_the_hosted_file(monkeypatch):
+ monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
+ for mode in (None, "auto", "int8"):
+ source = v25.ltx25_te_prequant_sources(mode, BASE)["text_encoder"]
+ assert (source.kind, source.location, source.filename) == (
+ "repo",
+ v25.LTX25_TE_HOSTED_REPO,
+ v25.LTX25_TE_HOSTED_FILE,
+ )
+ # none / off pin the bf16 encoder: no hosted file, the dense shards stay in the plan.
+ assert v25.ltx25_te_prequant_sources("none", BASE) == {}
+ assert v25.ltx25_te_prequant_sources("off", BASE) == {}
+ # Only the base it was cut from, and never the single-file release (its encoder file carries the projections).
+ assert v25.ltx25_te_prequant_sources(None, "someone/ltx-2.5-finetune") == {}
+ # Exact identity: a custom pack that only shares the folder name keeps its own encoder weights.
+ assert v25.ltx25_te_prequant_sources(None, "/packs/custom/LTX-2.5-Diffusers") == {}
+ assert v25.ltx25_te_prequant_sources(None, "someone/LTX-2.5-Diffusers") == {}
+ cached = "/hf/hub/models--Lightricks--LTX-2.5-Diffusers/snapshots/abc123"
+ assert (
+ v25.ltx25_te_prequant_sources(None, cached)["text_encoder"].location
+ == v25.LTX25_TE_HOSTED_REPO
+ )
+ assert v25.ltx25_te_prequant_sources(None, v25.LTX25_SINGLE_FILE_REPO) == {}
+ assert v25.ltx25_te_prequant_sources("fp8", BASE) == {}
+ monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "0")
+ assert v25.ltx25_te_prequant_sources(None, BASE) == {}
+
+
+def test_the_video_planner_stages_the_hosted_file():
+ from core.inference.video import VideoBackend
+ from core.inference.video_families import detect_video_family
+
+ fam = detect_video_family(BASE)
+ sources = VideoBackend._te_prequant_sources(fam, None, base = BASE)
+ assert sources["text_encoder"].filename == v25.LTX25_TE_HOSTED_FILE
+ assert VideoBackend._te_prequant_sources(fam, "none", base = BASE) == {}
+
+
+def test_client_hands_the_worker_the_hosted_file(monkeypatch):
+ monkeypatch.setattr(v25, "ensure_text_encoder_sidecar", lambda: "/nonexistent")
+ monkeypatch.setattr(v25.Ltx25TextEncoderClient, "start", lambda self: None)
+ common = dict(
+ hf_token = None,
+ cache_dir = None,
+ local_files_only = True,
+ device = "cpu",
+ dtype = "bfloat16",
+ resident = False,
+ )
+ client = v25.start_text_encoder(repo = "/snap/ltx25", base_repo = BASE, te_quant = "int8", **common)
+ spec = client.config["te_prequant"]
+ assert (spec["repo"], spec["filename"], spec["base"]) == (
+ v25.LTX25_TE_HOSTED_REPO,
+ v25.LTX25_TE_HOSTED_FILE,
+ v25.LTX25_TE_HOSTED_BASE,
+ )
+ # The scoped snapshot may have skipped the dense shards, so the fallback knows the Hub id.
+ assert client.config["hub_repo"] == BASE
+ assert v25.start_text_encoder(repo = BASE, te_quant = None, **common).config["te_prequant"] is None
+ # The dense fallback's peak travels with the hosted file, so the worker can refuse it on a short host.
+ assert client.config["dense_te_gb"] == v25.LTX25_TE_BF16_GB
+
+
+def _write_tiny_encoder(folder: Path) -> _TinyGemma:
+ from safetensors.torch import save_file
+
+ torch.manual_seed(0)
+ model = _TinyGemma().to(torch.bfloat16)
+ te = folder / "text_encoder"
+ te.mkdir(parents = True)
+ save_file(
+ {k: v.contiguous() for k, v in model.state_dict().items()}, str(te / "model.safetensors")
+ )
+ (te / "model.safetensors.index.json").write_text(
+ json.dumps({"weight_map": {k: "model.safetensors" for k in model.state_dict()}})
+ )
+ (te / "config.json").write_text(
+ json.dumps({"architectures": ["Gemma4UnifiedForConditionalGeneration"]})
+ )
+ return model
+
+
+def _build(pack: Path, out: Path) -> dict:
+ """The builder runs the worker's own at-load path (here against the stand-in transformers) and saves it."""
+ import build_ltx25_te_int8_convrot as builder
+ return builder.build(str(pack), out, base = BASE, device = "cpu")
+
+
+def _fake_transformers(monkeypatch, folder: Path):
+ from safetensors.torch import load_file
+ class _Cls(_TinyGemma):
+ @classmethod
+ def from_pretrained(
+ cls,
+ repo,
+ subfolder = None,
+ **_kw,
+ ):
+ path = Path(repo) / (subfolder or "") / "model.safetensors"
+ if not path.is_file():
+ raise OSError(f"no weights at {path}")
+ model = _TinyGemma().to(torch.bfloat16)
+ model.load_state_dict(load_file(str(path)))
+ return model
+
+ def __init__(self, _config = None):
+ super().__init__()
+
+ monkeypatch.setitem(
+ sys.modules,
+ "transformers",
+ SimpleNamespace(
+ __version__ = "5.10.2",
+ Gemma4UnifiedForConditionalGeneration = _Cls,
+ AutoTokenizer = SimpleNamespace(from_pretrained = lambda *a, **k: object()),
+ AutoConfig = SimpleNamespace(
+ from_pretrained = lambda *a, **k: SimpleNamespace(tie_word_embeddings = False)
+ ),
+ ),
+ )
+
+
+def test_hosted_load_equals_the_at_load_build(tmp_path, monkeypatch):
+ _write_tiny_encoder(tmp_path / "pack")
+ _fake_transformers(monkeypatch, tmp_path / "pack")
+ out = tmp_path / "hosted.safetensors"
+ first = _build(tmp_path / "pack", out)
+ assert first["quantized_linears"] == 12
+ # Deterministic: a rebuild is byte-identical.
+ again = _build(tmp_path / "pack", tmp_path / "again.safetensors")
+ assert again["sha256"] == first["sha256"]
+ assert hashlib.sha256(out.read_bytes()).hexdigest() == first["sha256"]
+
+ base = {
+ "repo": str(tmp_path / "pack"),
+ "device": "cpu",
+ "dtype": "bfloat16",
+ "te_quant": "int8",
+ }
+ spec = {"repo": "unsloth/LTX-2.5-FP8", "filename": "x", "mirror_path": str(out), "base": BASE}
+ config_hosted = dict(base, te_prequant = dict(spec))
+ _tok, hosted = worker._load(config_hosted)
+ config_at_load = dict(base)
+ _tok, at_load = worker._load(config_at_load)
+ assert config_hosted["_te_source"] == "hosted"
+ assert config_at_load["_te_source"] == "quantized_at_load"
+ a, b = hosted.state_dict(), at_load.state_dict()
+ assert a.keys() == b.keys()
+ for key in a:
+ assert a[key].dtype == b[key].dtype and torch.equal(a[key], b[key]), key
+ x = torch.randn(3, 256, dtype = torch.bfloat16)
+ for layer_a, layer_b in zip(
+ hosted.model.language_model.layers, at_load.model.language_model.layers
+ ):
+ assert type(layer_a.mlp.down_proj).__name__ == "Int8ConvRotLinear"
+ assert torch.equal(layer_a.self_attn.q_proj(x), layer_b.self_attn.q_proj(x))
+
+
+def test_missing_or_foreign_hosted_file_falls_back_to_the_at_load_build(tmp_path, monkeypatch):
+ _write_tiny_encoder(tmp_path / "pack")
+ _fake_transformers(monkeypatch, tmp_path / "pack")
+ base = {
+ "repo": str(tmp_path / "pack"),
+ "device": "cpu",
+ "dtype": "bfloat16",
+ "te_quant": "int8",
+ }
+ missing = {
+ "repo": "unsloth/LTX-2.5-FP8",
+ "filename": "x",
+ "mirror_path": str(tmp_path / "absent.safetensors"),
+ "base": BASE,
+ }
+ monkeypatch.setattr(worker, "_hosted_path", lambda spec, common: spec["mirror_path"])
+ config = dict(base, te_prequant = missing)
+ _tok, model = worker._load(config)
+ assert config["_te_source"] == "quantized_at_load"
+ assert type(model.model.language_model.layers[0].mlp.gate_proj).__name__ == "Int8ConvRotLinear"
+ # Built from another base: refused, the dense encoder is quantized instead.
+ out = tmp_path / "hosted.safetensors"
+ _build(tmp_path / "pack", out)
+ config = dict(base, te_prequant = dict(missing, mirror_path = str(out), base = "someone/else"))
+ worker._load(config)
+ assert config["_te_source"] == "quantized_at_load"
+
+
+def test_a_rejected_hosted_file_refuses_the_dense_fallback_without_room(tmp_path, monkeypatch):
+ _write_tiny_encoder(tmp_path / "pack")
+ _fake_transformers(monkeypatch, tmp_path / "pack")
+ monkeypatch.setattr(worker, "_hosted_path", lambda spec, common: spec["mirror_path"])
+ monkeypatch.setattr(worker, "_available_host_bytes", lambda: 8 * 1000**3)
+ config = {
+ "repo": str(tmp_path / "pack"),
+ "device": "cpu",
+ "dtype": "bfloat16",
+ "te_quant": "int8",
+ "dense_te_gb": 23.9,
+ "te_prequant": {
+ "repo": "r",
+ "filename": "x",
+ "mirror_path": str(tmp_path / "absent"),
+ "base": BASE,
+ },
+ }
+ with pytest.raises(RuntimeError, match = "needs about 24 GB"):
+ worker._load(config)
+ monkeypatch.setattr(worker, "_available_host_bytes", lambda: 64 * 1000**3)
+ worker._load(config)
+ assert config["_te_source"] == "quantized_at_load"
+
+
+def test_offline_dense_fallback_still_tries_the_cached_hub_id(tmp_path, monkeypatch):
+ _write_tiny_encoder(tmp_path / "hub")
+ _fake_transformers(monkeypatch, tmp_path / "hub")
+ (tmp_path / "snap").mkdir()
+ config = {
+ "repo": str(tmp_path / "snap"),
+ "hub_repo": str(tmp_path / "hub"),
+ "device": "cpu",
+ "dtype": "bfloat16",
+ "te_quant": None,
+ "local_files_only": True,
+ }
+ _tok, model = worker._load(config)
+ assert isinstance(model.model.language_model.layers[0].self_attn.q_proj, nn.Linear)
+
+
+def test_none_keeps_bf16_and_dense_fallback_reads_the_hub_id(tmp_path, monkeypatch):
+ _write_tiny_encoder(tmp_path / "hub")
+ _fake_transformers(monkeypatch, tmp_path / "hub")
+ # A scoped snapshot without the encoder shards: the dense read retries the pack's Hub id.
+ (tmp_path / "snap").mkdir()
+ config = {
+ "repo": str(tmp_path / "snap"),
+ "hub_repo": str(tmp_path / "hub"),
+ "device": "cpu",
+ "dtype": "bfloat16",
+ "te_quant": None,
+ }
+ _tok, model = worker._load(config)
+ assert isinstance(model.model.language_model.layers[0].self_attn.q_proj, nn.Linear)
+ assert config.get("_te_source") is None
+
+
+def _hf_cache_entry(root: Path, repo: str, filename: str, payload: bytes) -> Path:
+ commit = "0" * 40
+ folder = root / ("models--" + repo.replace("/", "--"))
+ (folder / "refs").mkdir(parents = True)
+ (folder / "refs" / "main").write_text(commit)
+ target = folder / "snapshots" / commit / filename
+ target.parent.mkdir(parents = True)
+ target.write_bytes(payload)
+ return target
+
+
+def test_hosted_path_resolves_a_copy_under_the_other_cache_root(tmp_path, monkeypatch):
+ # The server stages with reuse_other_cache_root, so a copy cached only under huggingface_hub's own root counts as
+ # staged (and the dense shards are dropped). The worker must find it too, offline.
+ import huggingface_hub.constants as hub_constants
+
+ repo, filename = "unsloth/LTX-2.5-FP8", "LTX-2.5-text_encoder-INT8-ConvRot.safetensors"
+ default_root, configured = tmp_path / "default", tmp_path / "configured"
+ configured.mkdir()
+ staged = _hf_cache_entry(default_root, repo, filename, b"hosted")
+ monkeypatch.setattr(hub_constants, "HF_HUB_CACHE", str(default_root))
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ spec = {"repo": repo, "filename": filename, "mirror_path": None}
+ common = {"token": None, "cache_dir": str(configured), "local_files_only": True}
+ assert Path(worker._hosted_path(spec, common)).read_bytes() == staged.read_bytes()
+ # A copy under the configured root still wins.
+ mine = _hf_cache_entry(configured, repo, filename, b"configured")
+ assert Path(worker._hosted_path(spec, common)) == mine
+
+
+def test_builder_drops_a_tied_lm_head(tmp_path, monkeypatch):
+ import build_ltx25_te_int8_convrot as builder
+
+ class _Tied(_TinyGemma):
+ def __init__(self):
+ super().__init__()
+ self.lm_head = nn.Linear(256, 16, bias = False)
+ self.lm_head.weight = self.model.language_model.embed_tokens.weight
+
+ def _load(config):
+ config["_te_source"] = "quantized_at_load"
+ return object(), _Tied().to(torch.bfloat16)
+
+ monkeypatch.setattr(worker, "_load", _load)
+ out = tmp_path / "hosted.safetensors"
+ builder.build("unused", out, base = BASE, device = "cpu")
+ from safetensors import safe_open
+
+ with safe_open(str(out), "pt") as fh:
+ keys = set(fh.keys())
+ assert "model.language_model.embed_tokens.weight" in keys
+ assert "lm_head.weight" not in keys
+
+
+def test_builder_builds_on_the_cpu_when_the_card_is_absent(tmp_path, monkeypatch):
+ import build_ltx25_te_int8_convrot as builder
+
+ seen: dict = {}
+
+ def _load(config):
+ seen.update(config)
+ config["_te_source"] = "quantized_at_load"
+ return object(), _TinyGemma().to(torch.bfloat16)
+
+ monkeypatch.setattr(worker, "_load", _load)
+ monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
+ builder.build("unused", tmp_path / "hosted.safetensors", base = BASE, device = "cuda:0")
+ assert seen["device"] == "cpu" and seen["resident"] is False
diff --git a/studio/backend/tests/test_video_ltx25_te_int8.py b/studio/backend/tests/test_video_ltx25_te_int8.py
index 9c24e1f74d5..10371d1bfd4 100644
--- a/studio/backend/tests/test_video_ltx25_te_int8.py
+++ b/studio/backend/tests/test_video_ltx25_te_int8.py
@@ -204,9 +204,10 @@ def test_worker_load_quantizes_only_when_asked(monkeypatch):
def test_te_quant_tristate(monkeypatch):
monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
- assert v25.ltx25_te_quant_scheme(None) is None
- assert v25.ltx25_te_quant_scheme("auto") is None
- assert v25.ltx25_te_quant_scheme("") is None
+ # Unset is int8 ConvRot, as ComfyUI's LTX-2.5 templates; none / off pin bf16.
+ assert v25.ltx25_te_quant_scheme(None) == "int8"
+ assert v25.ltx25_te_quant_scheme("auto") == "int8"
+ assert v25.ltx25_te_quant_scheme("") == "int8"
assert v25.ltx25_te_quant_scheme("int8") == "int8"
assert v25.ltx25_te_quant_scheme("none") is None
assert v25.ltx25_te_quant_scheme("off") is None
@@ -216,6 +217,10 @@ def test_te_quant_tristate(monkeypatch):
monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "1")
assert v25.ltx25_te_quant_scheme(None) == "int8"
assert v25.ltx25_te_quant_scheme("off") is None
+ # The kill switch turns only the unset default off.
+ monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "0")
+ assert v25.ltx25_te_quant_scheme(None) is None
+ assert v25.ltx25_te_quant_scheme("int8") == "int8"
def test_budget_prices_the_int8_encoder(monkeypatch):
@@ -230,9 +235,9 @@ def test_budget_prices_the_int8_encoder(monkeypatch):
assert scale == pytest.approx(v25.LTX25_TE_INT8_GB / bf16_gb)
assert scale < 0.6
assert te_prequant_budget_scale(fam, te_quant_mode = "none", **kw) == 1.0
- assert te_prequant_budget_scale(fam, te_quant_mode = None, **kw) == 1.0
- monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "1")
assert te_prequant_budget_scale(fam, te_quant_mode = None, **kw) == scale
+ monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "0")
+ assert te_prequant_budget_scale(fam, te_quant_mode = None, **kw) == 1.0
def test_client_carries_the_scheme_and_status_reports_it():
diff --git a/studio/backend/tests/test_video_te_quant_default.py b/studio/backend/tests/test_video_te_quant_default.py
new file mode 100644
index 00000000000..2581393ae44
--- /dev/null
+++ b/studio/backend/tests/test_video_te_quant_default.py
@@ -0,0 +1,534 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Video families default to a hosted quantized text encoder, the scheme ComfyUI's templates load."""
+
+from __future__ import annotations
+
+import json
+import re
+import types
+
+import pytest
+import torch
+
+import core.inference.diffusion_te_prequant as tpq
+from core.inference.video import video_te_quant_request
+from core.inference.video_families import _FAMILIES, detect_video_family
+
+CUDA_BF16 = types.SimpleNamespace(device = "cuda", dtype = torch.bfloat16)
+WAN_REPO = "unsloth/Wan2.2-TI2V-5B-FP8"
+WAN_BASES = (
+ "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
+ "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
+ "Wan-AI/Wan2.1-T2V-1.3B-Diffusers",
+ "Wan-AI/Wan2.1-T2V-14B-Diffusers",
+)
+
+# family -> (default scheme, hosted repo, preferred filename)
+EXPECTED_DEFAULTS = {
+ "wan2.2-ti2v-5b": ("fp8", WAN_REPO, "Wan2.2-TI2V-5B-text_encoder-FP8.safetensors"),
+ "wan2.2-t2v-a14b": ("fp8", WAN_REPO, "Wan2.2-TI2V-5B-text_encoder-FP8.safetensors"),
+ "wan2.1-t2v-1.3b": ("fp8", WAN_REPO, "Wan2.2-TI2V-5B-text_encoder-FP8.safetensors"),
+ "wan2.1-t2v-14b": ("fp8", WAN_REPO, "Wan2.2-TI2V-5B-text_encoder-FP8.safetensors"),
+ "ltx-2": ("fp8", "unsloth/LTX-2-FP8", "LTX-2-text_encoder-FP8.safetensors"),
+ "hunyuanvideo-1.5": (
+ "fp8",
+ "unsloth/HunyuanVideo-1.5-FP8",
+ "HunyuanVideo-1.5-text_encoder-FP8.safetensors",
+ ),
+ "hunyuanvideo-1.5-720p": (
+ "fp8",
+ "unsloth/HunyuanVideo-1.5-FP8",
+ "HunyuanVideo-1.5-text_encoder-FP8.safetensors",
+ ),
+}
+HV15_BASES = (
+ "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v",
+ "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v",
+)
+
+
+def test_every_generic_path_video_family_has_a_default():
+ """Every family that casts its own encoder in place defaults to a hosted one; only H3 and LTX-2.5 resolve theirs."""
+ assert {f.name for f in _FAMILIES if f.te_quant_auto} == set(EXPECTED_DEFAULTS)
+ assert {f.name for f in _FAMILIES if not f.te_quant_auto} == {"minimax-h3", "ltx-2.5"}
+
+
+def test_the_two_hunyuanvideo_repacks_share_one_encoder_and_not_qwen_images():
+ assert tpq.te_base_equivalent(*HV15_BASES)
+ # Qwen-Image's hosted file is the full Qwen2.5-VL (vision tower, lm_head), a different key layout.
+ assert not tpq.te_base_equivalent(HV15_BASES[0], "Qwen/Qwen-Image")
+
+
+def _family(name):
+ return detect_video_family("", override = name)
+
+
+def test_every_video_family_default_scheme_is_one_we_host():
+ """The video twin of the image sweep: a te_quant_auto with no hosted file would cost a dense download plus an
+ in-place cast on every default load."""
+ offenders = []
+ for fam in _FAMILIES:
+ scheme = getattr(fam, "te_quant_auto", None)
+ if scheme is None:
+ continue
+ if not any(
+ tpq.resolve_te_prequant_source(fam, c, scheme) for c in tpq.TE_PREQUANT_COMPONENTS
+ ):
+ offenders.append(f"{fam.name}: te_quant_auto={scheme!r} is not hosted")
+ assert not offenders, offenders
+
+
[email protected]("name", sorted(EXPECTED_DEFAULTS))
+def test_an_unset_request_resolves_to_the_hosted_encoder(name):
+ scheme, repo, filename = EXPECTED_DEFAULTS[name]
+ fam = _family(name)
+ for raw in (None, "", "auto", "AUTO"):
+ assert video_te_quant_request(fam, raw) == (scheme, True), raw
+ sources = tpq.te_prequant_sources_for_base(
+ fam, fam.base_repo, te_quant_mode = video_te_quant_request(fam, None)[0], target = CUDA_BF16
+ )
+ source = sources["text_encoder"]
+ assert (source.kind, source.location, source.filename) == ("repo", repo, filename)
+
+
[email protected]("name", sorted(EXPECTED_DEFAULTS))
[email protected]("raw", ["none", "off", "Off"])
+def test_none_and_off_pin_the_dense_encoder(name, raw):
+ fam = _family(name)
+ mode, auto = video_te_quant_request(fam, raw)
+ assert not auto
+ assert (
+ tpq.te_prequant_sources_for_base(fam, fam.base_repo, te_quant_mode = mode, target = CUDA_BF16)
+ == {}
+ )
+
+
+def test_an_explicit_scheme_pins_itself_and_is_not_marked_automatic():
+ fam = _family("wan2.2-ti2v-5b")
+ assert video_te_quant_request(fam, "int8") == ("int8", False)
+ assert video_te_quant_request(fam, "fp8") == ("fp8", False)
+
+
[email protected]("name", ["minimax-h3", "ltx-2.5"])
+def test_families_with_their_own_tristate_get_the_raw_request(name):
+ """H3 and LTX-2.5 read the raw request themselves (unset vs none), so nothing is folded for them."""
+ fam = _family(name)
+ assert fam.te_quant_auto is None
+ for raw in (None, "none", "int8"):
+ assert video_te_quant_request(fam, raw) == (raw, False)
+
+
+def test_unsupported_hardware_gets_no_hosted_encoder_for_the_default():
+ fam = _family("wan2.2-ti2v-5b")
+ mps = types.SimpleNamespace(device = "mps", dtype = torch.bfloat16)
+ mode, _ = video_te_quant_request(fam, None)
+ assert (
+ tpq.te_prequant_sources_for_base(fam, fam.base_repo, te_quant_mode = mode, target = mps) == {}
+ )
+
+
[email protected]("a", WAN_BASES)
[email protected]("b", WAN_BASES)
+def test_every_wan_base_takes_the_one_umt5_file(a, b):
+ assert tpq.te_base_equivalent(a, b)
+
+
+def test_wan_is_not_equivalent_to_other_encoders():
+ assert not tpq.te_base_equivalent(WAN_BASES[0], "Lightricks/LTX-2")
+ assert not tpq.te_base_equivalent(WAN_BASES[2], "Qwen/Qwen-Image")
+
+
+def test_wan_int8_resolves_the_convrot_file_then_the_fp8_one():
+ for name in ("wan2.2-ti2v-5b", "wan2.2-t2v-a14b", "wan2.1-t2v-1.3b", "wan2.1-t2v-14b"):
+ source = tpq.resolve_te_prequant_source(_family(name), "text_encoder", "int8")
+ assert source.location == WAN_REPO
+ assert tpq.te_candidate_filenames(source) == (
+ "Wan2.2-TI2V-5B-text_encoder-INT8-ConvRot.safetensors",
+ "Wan2.2-TI2V-5B-text_encoder-FP8.safetensors",
+ "Wan2.2-TI2V-5B-text_encoder-FP8.pt",
+ ), name
+
+
+def test_wan_int8_needs_no_lm_head_trim(monkeypatch):
+ """UMT5EncoderModel has no lm_head, so the keep-lm_head switch cannot push it onto the fp8 file."""
+ from core.inference.diffusion_text_encoder_trim import KEEP_LM_HEAD_ENV
+
+ monkeypatch.setenv(KEEP_LM_HEAD_ENV, "1")
+ source = tpq.resolve_te_prequant_source(_family("wan2.2-ti2v-5b"), "text_encoder", "int8")
+ assert source.filename == "Wan2.2-TI2V-5B-text_encoder-INT8-ConvRot.safetensors"
+
+
+# ---- the int8 ConvRot runtime on a UMT5 encoder ---------------------------------------------------------------------
+
+GROUP = 256
+_UMT5_LINEAR = re.compile(
+ r"^encoder\.block\.\d+\.layer\.(0\.SelfAttention\.[qkvo]|1\.DenseReluDense\.(wi_0|wi_1|wo))\.weight$"
+)
+
+
+def _umt5_config():
+ from transformers import UMT5Config
+ return UMT5Config(
+ vocab_size = 64,
+ d_model = 256,
+ d_kv = 64,
+ d_ff = 512,
+ num_layers = 2,
+ num_heads = 4,
+ feed_forward_proj = "gated-gelu",
+ relative_attention_num_buckets = 8,
+ dropout_rate = 0.0,
+ )
+
+
+def _umt5(seed = 0):
+ from transformers import UMT5EncoderModel
+
+ torch.manual_seed(seed)
+ model = UMT5EncoderModel(_umt5_config()).eval()
+ for module in model.modules():
+ if isinstance(module, torch.nn.Linear):
+ torch.nn.init.normal_(module.weight, std = 0.05)
+ return model
+
+
+def _int8_state(encoder, *, keep_wo: bool):
+ blob = torch.tensor(
+ list(
+ json.dumps(
+ {"format": "int8_tensorwise", "convrot": True, "convrot_groupsize": GROUP}
+ ).encode()
+ ),
+ dtype = torch.uint8,
+ )
+ state = {}
+ for k, v in encoder.state_dict().items():
+ if _UMT5_LINEAR.match(k) and not (keep_wo and ".wo." in k):
+ q, s = tpq.quantize_int8_convrot_weight(v, GROUP)
+ state[k], state[k[:-7] + ".weight_scale"], state[k[:-7] + ".comfy_quant"] = (
+ q,
+ s,
+ blob.clone(),
+ )
+ else:
+ state[k] = v.detach().clone().float()
+ return state
+
+
+def _dequantized(encoder, state):
+ from core.inference.diffusion_convrot import build_convrot_hadamard
+
+ h = build_convrot_hadamard(GROUP, dtype = torch.float32)
+ sd = encoder.state_dict()
+ for k in list(sd):
+ if k + "_scale" in state:
+ q, s = state[k].float(), state[k + "_scale"]
+ o, i = q.shape
+ sd[k] = ((q * s).reshape(o, i // GROUP, GROUP) @ h).reshape(o, i)
+ encoder.load_state_dict(sd)
+ return encoder
+
+
+def _hidden(encoder, ids):
+ with torch.no_grad():
+ return encoder(input_ids = ids, attention_mask = torch.ones_like(ids)).last_hidden_state
+
+
[email protected]("keep_wo", [False, True])
+def test_a_umt5_int8_convrot_file_builds_and_matches_its_dequantized_weights(keep_wo):
+ from transformers import UMT5EncoderModel
+
+ from core.inference.video_minimax_h3_te import _int8_convrot_linear_class
+
+ reference = _umt5(seed = 3)
+ state = _int8_state(reference, keep_wo = keep_wo)
+ encoder = tpq._build_int8_convrot_encoder(
+ UMT5EncoderModel, _umt5_config(), dict(state), dtype = torch.float32, trim = False
+ )
+ cls = _int8_convrot_linear_class()
+ swapped = sum(isinstance(m, cls) for m in encoder.encoder.block.modules())
+ assert swapped == 2 * (6 if keep_wo else 7)
+ ids = torch.randint(0, 64, (1, 11))
+ expected = _hidden(_dequantized(_umt5(seed = 3), state), ids)
+ torch.testing.assert_close(_hidden(encoder, ids), expected, rtol = 1e-4, atol = 1e-4)
+
+
+def test_a_dense_kept_umt5_wo_stays_float32_under_a_bf16_load():
+ """T5's ``wo`` is in _keep_in_fp32_modules (it overflows in low precision); a dense one keeps float32 storage."""
+ from transformers import UMT5EncoderModel
+
+ state = _int8_state(_umt5(seed = 1), keep_wo = True)
+ encoder = tpq._build_int8_convrot_encoder(
+ UMT5EncoderModel, _umt5_config(), dict(state), dtype = torch.bfloat16, trim = False
+ )
+ ff = encoder.encoder.block[0].layer[1].DenseReluDense
+ assert ff.wo.weight.dtype == torch.float32
+ assert encoder.shared.weight.dtype == torch.bfloat16
+
+
+def test_a_umt5_file_storing_the_tied_embedding_once_loads_tied():
+ """The hosted UMT5 files hold shared.weight only, like the dense shards; the alias is filled from the model's tie."""
+ from transformers import UMT5EncoderModel
+
+ state = _int8_state(_umt5(seed = 2), keep_wo = False)
+ state.pop("encoder.embed_tokens.weight")
+ encoder = tpq._build_int8_convrot_encoder(
+ UMT5EncoderModel, _umt5_config(), dict(state), dtype = torch.float32, trim = False
+ )
+ assert encoder.encoder.embed_tokens.weight.data_ptr() == encoder.shared.weight.data_ptr()
+ ids = torch.randint(0, 64, (1, 7))
+ expected = _hidden(_dequantized(_umt5(seed = 2), state), ids)
+ torch.testing.assert_close(_hidden(encoder, ids), expected, rtol = 1e-4, atol = 1e-4)
+
+
+def test_fill_tied_aliases_leaves_a_head_alone():
+ model = types.SimpleNamespace(
+ _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight", "b.weight": "a.weight"},
+ named_parameters = lambda remove_duplicate = False: iter(()),
+ )
+ state = {"model.embed_tokens.weight": torch.zeros(1), "a.weight": torch.ones(1)}
+ tpq._fill_tied_aliases(model, state)
+ assert "lm_head.weight" not in state
+ assert state["b.weight"] is state["a.weight"]
+
+
+def test_a_umt5_file_missing_a_projection_is_refused():
+ from transformers import UMT5EncoderModel
+
+ state = _int8_state(_umt5(), keep_wo = False)
+ name = "encoder.block.0.layer.0.SelfAttention.q"
+ q, s = state.pop(name + ".weight"), state.pop(name + ".weight_scale")
+ state.pop(name + ".comfy_quant")
+ state[name + ".weight"] = (q.float() * s).float()
+ with pytest.raises(ValueError, match = "not quantized"):
+ tpq._build_int8_convrot_encoder(
+ UMT5EncoderModel, _umt5_config(), state, dtype = torch.float32, trim = False
+ )
+
+
+def _converter():
+ import importlib.util
+ from pathlib import Path
+
+ path = Path(__file__).resolve().parents[3] / "scripts" / "convert_prequant_to_safetensors.py"
+ spec = importlib.util.spec_from_file_location("convert_prequant_to_safetensors", path)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_the_converter_can_store_a_tied_embedding_once(tmp_path, monkeypatch):
+ """--drop-tied-copies writes UMT5's shared/embed_tokens pair once, the round trip still verifies, and the fp8
+ loader fills the alias back from the model's own tie."""
+ pytest.importorskip("diffusers") # _cast_fp8 installs diffusers' layerwise hooks
+ import core.inference.prequant_safetensors as ps
+ from core.inference.diffusion_precision import _cast_fp8
+ from core.inference.diffusion_prequant import ALLOW_LOCAL_PREQUANT_PATH_ENV
+
+ conv = _converter()
+ encoder = _umt5(seed = 4)
+ target = types.SimpleNamespace(dtype = torch.float32)
+ _cast_fp8(encoder, target)
+ state = encoder.state_dict()
+ assert conv.tied_copies(state) == {"encoder.embed_tokens.weight": "shared.weight"}
+ src = tmp_path / "Wan-text_encoder-FP8.pt"
+ torch.save(
+ {
+ "format": tpq.TE_PREQUANT_FORMAT,
+ "state_dict": state,
+ "metadata": {
+ "scheme": "fp8",
+ "component": "text_encoder",
+ "base_model_id": WAN_BASES[0],
+ "te_class": "UMT5EncoderModel",
+ },
+ },
+ src,
+ )
+ rec = conv.convert(str(src), str(tmp_path), repo = None, revision = None, sha = None, drop_tied = True)
+ assert rec["verified_bit_identical"] and rec["tied_copies_dropped"]
+ assert (
+ "encoder.embed_tokens.weight"
+ not in ps.load_plain_prequant_safetensors(rec["dst"])["state_dict"]
+ )
+ plain = conv.convert(str(src), str(tmp_path / "plain"), repo = None, revision = None, sha = None)
+ assert plain["dst_bytes"] > rec["dst_bytes"]
+
+ import transformers
+
+ monkeypatch.setattr(
+ transformers.AutoConfig, "from_pretrained", lambda *_a, **_k: _umt5_config()
+ )
+ monkeypatch.setenv(ALLOW_LOCAL_PREQUANT_PATH_ENV, str(tmp_path))
+ loaded = tpq.load_prequant_text_encoder(
+ WAN_BASES[2],
+ "text_encoder",
+ tpq.TePrequantSource(kind = "path", location = rec["dst"]),
+ dtype = torch.float32,
+ scheme = "fp8",
+ local_files_only = True,
+ )
+ assert loaded is not None
+ assert loaded.encoder.embed_tokens.weight.data_ptr() == loaded.shared.weight.data_ptr()
+ ids = torch.randint(0, 64, (1, 9))
+ torch.testing.assert_close(_hidden(loaded, ids), _hidden(encoder, ids), rtol = 0, atol = 0)
+
+
[email protected]("name", ["hunyuanvideo-1.5", "hunyuanvideo-1.5-720p"])
+def test_hunyuanvideo_default_fp8_leaves_the_byt5_encoder_dense(name, monkeypatch):
+ import inspect
+
+ import core.inference.diffusion_precision as dp
+ import core.inference.video as video
+
+ fam = next(f for f in _FAMILIES if f.name == name)
+ assert fam.te_quant_auto_encoders == ("text_encoder",)
+ cast: list = []
+ monkeypatch.setattr(dp, "te_quant_supported", lambda *a, **k: True)
+ monkeypatch.setattr(dp, "_cast_fp8", lambda enc, tgt: cast.append(enc))
+ qwen, byt5 = object(), object()
+ pipe = types.SimpleNamespace(text_encoder = qwen, text_encoder_2 = byt5)
+ outcome = dp.quantize_text_encoders(
+ pipe, CUDA_BF16, mode = "fp8", family = name, encoders = fam.te_quant_auto_encoders
+ )
+ assert outcome.mode == "fp8" and not outcome.partial
+ assert cast == [qwen]
+ # An explicit fp8 (no encoders limit) still covers both towers.
+ cast.clear()
+ dp.quantize_text_encoders(pipe, CUDA_BF16, mode = "fp8", family = name)
+ assert cast == [qwen, byt5]
+ # The loader passes the limit only for the automatic pick.
+ src = inspect.getsource(video)
+ call = src[src.index("text_encoder_outcome = quantize_text_encoders(") :][:600]
+ assert 'getattr(fam, "te_quant_auto_encoders", None)' in call
+ assert "if text_encoder_quant_auto" in call
+
+
+MPS_BF16 = types.SimpleNamespace(device = "mps", dtype = torch.bfloat16)
+
+
+def test_an_explicit_wan_int8_on_mps_reaches_the_hosted_convrot_file():
+ # MPS runs the hosted int8 ConvRot encoder without fp8, so the gate must not rewrite int8 to fp8 and refuse it.
+ import core.inference.video as v
+ v._assert_video_precision_for_target(
+ _family("wan2.2-ti2v-5b"), MPS_BF16, model_kind = "pipeline", text_encoder_quant = "int8"
+ )
+ # A family with no hosted int8 file still meets the generic gate.
+ with pytest.raises(RuntimeError, match = "text_encoder_quant"):
+ v._assert_video_precision_for_target(
+ _family("ltx-2"), MPS_BF16, model_kind = "pipeline", text_encoder_quant = "int8"
+ )
+
+
+def test_the_builder_quantizes_a_non_gated_t5_feed_forward():
+ import importlib.util
+ from pathlib import Path
+
+ path = Path(__file__).resolve().parents[3] / "scripts" / "build_te_int8_convrot_checkpoint.py"
+ spec = importlib.util.spec_from_file_location("build_te_int8_convrot_checkpoint", path)
+ builder = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(builder)
+ pattern = builder._linear_pattern("T5EncoderModel")
+ for proj in ("wi", "wi_0", "wi_1", "wo"):
+ assert pattern.match(f"encoder.block.3.layer.1.DenseReluDense.{proj}.weight"), proj
+ assert not pattern.match("encoder.block.3.layer.1.DenseReluDense.wix.weight")
+
+
+def test_a_wan_load_claims_the_hosted_encoder_repo_while_it_fetches():
+ # The hosted file lives in a third repo; without the claim the delete-cached guard admits deleting it mid-load.
+ import inspect
+
+ import core.inference.video as v
+
+ src = inspect.getsource(v.VideoBackend)
+ claim = src[src.index("te_repos = tuple(") :][:400]
+ assert "te_sources" in claim and 'kind", None) == "repo"' in claim
+ assert "self._loading.asset_repos = tuple(" in src[src.index("te_repos = tuple(") :][:700]
+
+
+ "base, hosted",
+ [
+ ("Wan-AI/Wan2.2-TI2V-5B-Diffusers", True),
+ ("/hf/hub/models--Wan-AI--Wan2.2-TI2V-5B-Diffusers/snapshots/abc123", True),
+ ("/packs/custom/Wan2.2-TI2V-5B-Diffusers", False),
+ ("someone/Wan2.2-TI2V-5B-Diffusers", False),
+ ],
+)
+def test_the_automatic_encoder_needs_the_exact_official_base(base, hosted):
+ # A custom pack that only shares the folder name keeps its own encoder weights.
+ mode, auto = video_te_quant_request(_family("wan2.2-ti2v-5b"), None, base = base)
+ assert (mode, auto) == (("fp8", True) if hosted else (None, False))
+ # An explicit scheme is never second-guessed.
+ assert video_te_quant_request(_family("wan2.2-ti2v-5b"), "fp8", base = base) == ("fp8", False)
+
+
[email protected]("name", ["wan2.2-ti2v-5b", "ltx-2", "ltx-2.5"])
+def test_speed_off_keeps_the_released_encoder_unless_a_scheme_is_named(name):
+ fam = _family(name)
+ assert video_te_quant_request(fam, None, speed_mode = "off") == ("none", False)
+ assert video_te_quant_request(fam, "auto", speed_mode = "off") == ("none", False)
+ assert video_te_quant_request(fam, "int8", speed_mode = "off") == ("int8", False)
+ if name != "ltx-2.5":
+ assert video_te_quant_request(fam, None, speed_mode = "default")[1] is True
+
+
+def test_wan_int8_budget_covers_the_measured_file():
+ # 6,735,404,944 bytes int8 against 11,361,851,208 dense (Wan2.2-TI2V-5B UMT5).
+ for name in ("wan2.2-ti2v-5b", "wan2.1-t2v-14b"):
+ assert 11_361_851_208 * tpq.te_int8_convrot_budget_scale(name) >= 6_735_404_944
+ assert tpq.te_int8_convrot_budget_scale("qwen-image-2.1") == tpq.TE_INT8_CONVROT_BUDGET_SCALE
+
+
+def test_ltx25_budgets_the_dense_peak_unless_the_hosted_encoder_applies():
+ fam = types.SimpleNamespace(name = "ltx-2.5", bf16_components_gb = (40.0, 23.9))
+ hosted = tpq.te_prequant_budget_scale(
+ fam, te_quant_mode = None, target = None, base = "Lightricks/LTX-2.5-Diffusers"
+ )
+ assert hosted < 1.0
+ # A custom pack quantizes the dense encoder at load: its peak is the dense one.
+ assert (
+ tpq.te_prequant_budget_scale(
+ fam, te_quant_mode = None, target = None, base = "someone/ltx25-pack"
+ )
+ == 1.0
+ )
+ assert (
+ tpq.te_prequant_budget_scale(
+ fam, te_quant_mode = "none", target = None, base = "Lightricks/LTX-2.5-Diffusers"
+ )
+ == 1.0
+ )
+
+
+def test_drop_tied_copies_keeps_a_tied_lm_head(tmp_path):
+ import core.inference.prequant_safetensors as ps
+
+ conv = _converter()
+ embed = torch.randn(8, 4)
+ shared = torch.randn(8, 4)
+ state = {
+ "shared.weight": shared,
+ "encoder.embed_tokens.weight": shared,
+ "model.embed_tokens.weight": embed,
+ "lm_head.weight": embed,
+ }
+ src = tmp_path / "te-FP8.pt"
+ torch.save(
+ {
+ "format": tpq.TE_PREQUANT_FORMAT,
+ "state_dict": state,
+ "metadata": {
+ "scheme": "fp8",
+ "component": "text_encoder",
+ "base_model_id": WAN_BASES[0],
+ },
+ },
+ src,
+ )
+ rec = conv.convert(str(src), str(tmp_path), repo = None, revision = None, sha = None, drop_tied = True)
+ # The loader fills the embedding alias from the model's tie, never a head one.
+ assert rec["tied_copies_dropped"] == {"encoder.embed_tokens.weight": "shared.weight"}
+ assert "lm_head.weight" in ps.load_plain_prequant_safetensors(rec["dst"])["state_dict"]
diff --git a/studio/frontend/src/features/video/api.ts b/studio/frontend/src/features/video/api.ts
index 4ebd7482dc3..b371921de8d 100644
--- a/studio/frontend/src/features/video/api.ts
+++ b/studio/frontend/src/features/video/api.ts
@@ -177,8 +177,9 @@ export interface VideoLoadRequest {
// CUDA / ROCm physical indices this load may use; omit for automatic. Neither engine shards a
// checkpoint, so several cards resolve to the one with the most free VRAM.
gpu_ids?: number[];
- // Text-encoder precision (omit to keep the dense bf16 encoder). Refused with a 409 when the host cannot run it.
- text_encoder_quant?: "fp8" | "fp8_dynamic" | "int8" | "nvfp4";
+ // Text-encoder precision. Omit for the family default (the hosted quantized encoder ComfyUI's template matches);
+ // "none" keeps the dense bf16 encoder. An explicit scheme is refused with a 409 when the host cannot run it.
+ text_encoder_quant?: "none" | "fp8" | "fp8_dynamic" | "int8" | "nvfp4";
}
/** One reference video, with the soundtrack MiniMax-H3 conditions on alongside it. */