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 LTX-2.5: auto text-encoder precision loads the hosted int8 ConvRot encoder (#17179)

Daniel Hane865fa2c6211
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 9662f9abaac..8fed4fb8a94 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -425,7 +425,7 @@ def video_te_quant_request(
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 takes int8 under UNSLOTH_LTX25_TE_INT8=1); and only an exactly identified official
+ encoder (LTX-2.5's raw unset included, which otherwise takes the hosted int8 encoder); 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)
@@ -9074,6 +9074,14 @@ class VideoBackend:
base = repo_id if kind == "pipeline" else base,
speed_mode = speed_mode,
)
+ if fam.name == "ltx-2.5":
+ # Settle auto once so the memory plan and the encoder worker read one decision.
+ from .video_ltx25 import ltx25_resolve_te_request
+ text_encoder_quant = ltx25_resolve_te_request(
+ text_encoder_quant,
+ repo_id if kind == "pipeline" else base,
+ _te_prequant_failed,
+ )
# An automatic pick whose hosted pre-cast encoder could not be fetched loads the dense encoder: say so.
te_auto_unavailable = auto_te_fetch_failure(
fam, text_encoder_quant if text_encoder_quant_auto else None, _te_prequant_failed
diff --git a/studio/backend/core/inference/video_ltx25.py b/studio/backend/core/inference/video_ltx25.py
index f38726d4a0b..5dcae5237ea 100644
--- a/studio/backend/core/inference/video_ltx25.py
+++ b/studio/backend/core/inference/video_ltx25.py
@@ -71,8 +71,8 @@ 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 ConvRot (ComfyUI's LTX-2.5 encoder) is opt-in: its LPIPS vs bf16 sits above the compile floor. Unset keeps
-# bf16 unless UNSLOTH_LTX25_TE_INT8=1.
+# Auto takes the hosted int8 file only when confirmed, else bf16 (never quantizes at load). A100-40 LPIPS vs bf16
+# 0.133 (bf16 encoder 0.141), peak host 71 -> 52 GiB. Env =0 keeps bf16 auto, =1 makes auto an explicit int8.
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).
@@ -709,13 +709,16 @@ def encoder_resident_for_plan(plan: Any) -> bool:
def ltx25_te_quant_scheme(text_encoder_quant: Optional[str]) -> Optional[str]:
- """``"int8"`` or None (bf16); any other scheme raises ValueError (the worker has only the ConvRot INT8 build)."""
- from .diffusion_precision import normalize_te_quant, te_quant_is_auto
+ """``"int8"``, None (bf16) or ``AutoTeQuant("int8")`` for auto; other schemes raise ValueError."""
+ from .diffusion_precision import AutoTeQuant, 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 _ON:
+ env = (os.environ.get(LTX25_TE_QUANT_ENV) or "").strip().lower()
+ if env in _ON:
return LTX25_TE_QUANT_DEFAULT
- return None
+ if env in _OFF:
+ return None
+ return AutoTeQuant(LTX25_TE_QUANT_DEFAULT)
scheme = normalize_te_quant(text_encoder_quant)
if scheme is None or scheme == LTX25_TE_QUANT_DEFAULT:
return scheme
@@ -733,13 +736,15 @@ def ltx25_te_prequant_sources(
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."""
+ pack may carry other weights. An automatic pick also needs the file confirmed. Never raises."""
try:
- if ltx25_te_quant_scheme(text_encoder_quant) != LTX25_TE_QUANT_DEFAULT:
+ scheme = ltx25_te_quant_scheme(text_encoder_quant)
+ if scheme != LTX25_TE_QUANT_DEFAULT:
return {}
if not base or is_ltx25_single_file_base(base):
return {}
from .diffusion_families import canonical_base
+ from .diffusion_precision import AutoTeQuant
from .diffusion_te_prequant import TePrequantSource
from .model_ids import hf_cache_repo_id
@@ -749,15 +754,56 @@ def ltx25_te_prequant_sources(
identity = hf_cache_repo_id(str(base)) or str(base)
if canonical_base(identity).lower() != canonical_base(LTX25_TE_HOSTED_BASE).lower():
return {}
- return {
+ sources = {
"text_encoder": TePrequantSource(
kind = "repo", location = LTX25_TE_HOSTED_REPO, filename = LTX25_TE_HOSTED_FILE
)
}
+ if isinstance(scheme, AutoTeQuant):
+ from .diffusion_te_prequant import te_prequant_sources_confirmed
+ if not te_prequant_sources_confirmed(sources):
+ return {}
+ return sources
except Exception: # noqa: BLE001 -- no hosted encoder: the worker quantizes the dense one
return {}
+def ltx25_resolve_te_request(
+ text_encoder_quant: Optional[str],
+ base: Optional[str],
+ failures: Optional[dict] = None,
+) -> Optional[str]:
+ """The request a load hands its plan and its worker: an automatic int8 pick becomes ``"int8"`` when the hosted
+ file serves this load, else ``"none"`` (bf16, never the at-load quantization). ``failures`` is the pre-fetch's
+ ``{component: reason}``: a hosted file that could not be fetched keeps bf16. Anything else comes back unchanged."""
+ from .diffusion_precision import AutoTeQuant
+
+ try:
+ scheme = ltx25_te_quant_scheme(text_encoder_quant)
+ except ValueError:
+ return text_encoder_quant
+ if not isinstance(scheme, AutoTeQuant):
+ return text_encoder_quant
+ if failures and "text_encoder" in failures:
+ logger.info(
+ "video.ltx25_te: hosted int8 ConvRot encoder not fetched (%s); the bf16 text encoder loads",
+ failures["text_encoder"],
+ )
+ return "none"
+ if not ltx25_te_prequant_sources(text_encoder_quant, base):
+ logger.info(
+ "video.ltx25_te: hosted int8 ConvRot encoder not available for '%s'; the bf16 text encoder loads",
+ base,
+ )
+ return "none"
+ logger.info(
+ "video.ltx25_te: int8 ConvRot encoder selected automatically (hosted %s/%s)",
+ LTX25_TE_HOSTED_REPO,
+ LTX25_TE_HOSTED_FILE,
+ )
+ return LTX25_TE_QUANT_DEFAULT
+
+
def ltx25_te_budget_scale(text_encoder_quant: Optional[str], bf16_gb: float) -> float:
try:
scheme = ltx25_te_quant_scheme(text_encoder_quant)
diff --git a/studio/backend/tests/test_video_ltx25_te_hosted.py b/studio/backend/tests/test_video_ltx25_te_hosted.py
index d9eba4aea93..56c5f426fc2 100644
--- a/studio/backend/tests/test_video_ltx25_te_hosted.py
+++ b/studio/backend/tests/test_video_ltx25_te_hosted.py
@@ -63,13 +63,69 @@ class _TinyGemma(nn.Module):
BASE = "Lightricks/LTX-2.5-Diffusers"
-def test_unset_request_keeps_the_dense_encoder(monkeypatch):
- # int8 is opt-in for LTX-2.5: an unset request stages no hosted file and keeps the dense text_encoder/ shards.
+def _confirmed(monkeypatch, value):
+ from core.inference import diffusion_te_prequant as tpq
+
+ calls = []
+
+ def _fake(sources, **_kw):
+ calls.append(tuple(sorted(sources)))
+ return value
+
+ monkeypatch.setattr(tpq, "te_prequant_sources_confirmed", _fake)
+ return calls
+
+
+def test_unset_request_takes_the_hosted_file_only_when_confirmed(monkeypatch):
+ # Auto takes the hosted int8 file when it is on disk or listed by the Hub, else keeps the dense shards (bf16).
monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
+ calls = _confirmed(monkeypatch, True)
+ for mode in (None, "auto", ""):
+ assert v25.ltx25_te_prequant_sources(mode, BASE)["text_encoder"].filename == (
+ v25.LTX25_TE_HOSTED_FILE
+ )
+ assert calls == [("text_encoder",)] * 3
+ _confirmed(monkeypatch, False)
for mode in (None, "auto", ""):
assert v25.ltx25_te_prequant_sources(mode, BASE) == {}
+ # An explicit int8 never needs the confirmation: a miss falls back to the at-load quantization.
+ assert v25.ltx25_te_prequant_sources("int8", BASE)["text_encoder"].filename == (
+ v25.LTX25_TE_HOSTED_FILE
+ )
+ # Kill switch: the bf16 auto from before the hosted file, confirmed or not.
+ calls = _confirmed(monkeypatch, True)
monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "0")
assert v25.ltx25_te_prequant_sources(None, BASE) == {}
+ assert v25.ltx25_te_prequant_sources("auto", BASE) == {}
+ assert calls == []
+ # Auto on a custom pack / the single-file release never takes it either.
+ monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
+ assert v25.ltx25_te_prequant_sources(None, "someone/LTX-2.5-Diffusers") == {}
+ assert v25.ltx25_te_prequant_sources(None, v25.LTX25_SINGLE_FILE_REPO) == {}
+
+
+def test_resolve_settles_the_automatic_pick_per_load(monkeypatch):
+ monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
+ _confirmed(monkeypatch, True)
+ for mode in (None, "auto"):
+ resolved = v25.ltx25_resolve_te_request(mode, BASE)
+ assert resolved == "int8"
+ assert v25.ltx25_te_quant_scheme(resolved) == "int8"
+ # A pre-fetch that could not get the file keeps bf16, never the at-load quantization.
+ failed = v25.ltx25_resolve_te_request(None, BASE, {"text_encoder": "EntryNotFoundError: 404"})
+ assert failed == "none" and v25.ltx25_te_quant_scheme(failed) is None
+ assert v25.ltx25_resolve_te_request(None, BASE, {"text_encoder_2": "x"}) == "int8"
+ _confirmed(monkeypatch, False)
+ assert v25.ltx25_resolve_te_request(None, BASE) == "none"
+ assert v25.ltx25_resolve_te_request("auto", "someone/ltx25-pack") == "none"
+ # Explicit requests are untouched: int8 keeps its hosted-else-at-load path, off / none keep bf16.
+ for mode in ("int8", "none", "off", "fp8"):
+ assert v25.ltx25_resolve_te_request(mode, BASE, {"text_encoder": "x"}) == mode
+ monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "0")
+ assert v25.ltx25_resolve_te_request(None, BASE) is None
+ monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "1")
+ assert v25.ltx25_resolve_te_request(None, BASE) is None
+ assert v25.ltx25_te_quant_scheme(v25.ltx25_resolve_te_request(None, BASE)) == "int8"
def test_int8_request_resolves_to_the_hosted_file(monkeypatch):
@@ -109,11 +165,18 @@ def test_the_video_planner_stages_the_hosted_file(monkeypatch):
from core.inference.video_families import detect_video_family
monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
+ _confirmed(monkeypatch, False)
fam = detect_video_family(BASE)
sources = VideoBackend._te_prequant_sources(fam, "int8", base = BASE)
assert sources["text_encoder"].filename == v25.LTX25_TE_HOSTED_FILE
assert VideoBackend._te_prequant_sources(fam, None, base = BASE) == {}
assert VideoBackend._te_prequant_sources(fam, "none", base = BASE) == {}
+ # Confirmed, the unset request stages the hosted file too (and so drops the dense text_encoder/ shards).
+ _confirmed(monkeypatch, True)
+ assert VideoBackend._te_prequant_sources(fam, None, base = BASE)["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):
diff --git a/studio/backend/tests/test_video_ltx25_te_int8.py b/studio/backend/tests/test_video_ltx25_te_int8.py
index 5bb9996d874..63add1e08c8 100644
--- a/studio/backend/tests/test_video_ltx25_te_int8.py
+++ b/studio/backend/tests/test_video_ltx25_te_int8.py
@@ -203,11 +203,15 @@ def test_worker_load_quantizes_only_when_asked(monkeypatch):
def test_te_quant_tristate(monkeypatch):
+ from core.inference.diffusion_precision import AutoTeQuant
+
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 / auto is an automatic int8 pick, which only the hosted file serves.
+ for mode in (None, "auto", ""):
+ picked = v25.ltx25_te_quant_scheme(mode)
+ assert picked == "int8" and isinstance(picked, AutoTeQuant)
assert v25.ltx25_te_quant_scheme("int8") == "int8"
+ assert not isinstance(v25.ltx25_te_quant_scheme("int8"), AutoTeQuant)
assert v25.ltx25_te_quant_scheme("none") is None
assert v25.ltx25_te_quant_scheme("off") is None
for scheme in ("fp8", "fp8_dynamic"):
@@ -215,10 +219,13 @@ def test_te_quant_tristate(monkeypatch):
v25.ltx25_te_quant_scheme(scheme)
monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "1")
assert v25.ltx25_te_quant_scheme(None) == "int8"
+ assert not isinstance(v25.ltx25_te_quant_scheme(None), AutoTeQuant)
assert v25.ltx25_te_quant_scheme("auto") == "int8"
assert v25.ltx25_te_quant_scheme("off") is None
+ # The kill switch: the bf16 auto from before the hosted file.
monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "0")
assert v25.ltx25_te_quant_scheme(None) is None
+ assert v25.ltx25_te_quant_scheme("auto") is None
assert v25.ltx25_te_quant_scheme("int8") == "int8"
@@ -226,15 +233,23 @@ def test_budget_prices_the_int8_encoder(monkeypatch):
from core.inference.diffusion_te_prequant import te_prequant_budget_scale
from core.inference.video_families import detect_video_family
+ from core.inference import diffusion_te_prequant as tpq
+
monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
+ monkeypatch.setattr(tpq, "te_prequant_sources_confirmed", lambda *a, **k: False)
fam = detect_video_family("Lightricks/LTX-2.5-Diffusers")
bf16_gb = fam.bf16_components_gb[1]
kw = {"target": None, "base": "Lightricks/LTX-2.5-Diffusers"}
scale = te_prequant_budget_scale(fam, te_quant_mode = "int8", **kw)
assert scale == pytest.approx(v25.LTX25_TE_INT8_GB / bf16_gb)
assert scale < 0.6
+ assert v25.LTX25_TE_INT8_GB * 1e9 >= 13_028_751_080
assert te_prequant_budget_scale(fam, te_quant_mode = "none", **kw) == 1.0
+ # Auto prices the hosted file only when it is confirmed, else the bf16 encoder it then loads.
assert te_prequant_budget_scale(fam, te_quant_mode = None, **kw) == 1.0
+ monkeypatch.setattr(tpq, "te_prequant_sources_confirmed", lambda *a, **k: True)
+ assert te_prequant_budget_scale(fam, te_quant_mode = None, **kw) == scale
+ assert te_prequant_budget_scale(fam, te_quant_mode = "off", **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")
diff --git a/studio/backend/tests/test_video_te_quant_default.py b/studio/backend/tests/test_video_te_quant_default.py
index ec231d70634..2243ecf6315 100644
--- a/studio/backend/tests/test_video_te_quant_default.py
+++ b/studio/backend/tests/test_video_te_quant_default.py
@@ -572,12 +572,13 @@ def test_wan_int8_budget_covers_the_measured_file():
def test_ltx25_budgets_the_dense_peak_unless_the_hosted_encoder_applies(monkeypatch):
monkeypatch.delenv("UNSLOTH_LTX25_TE_INT8", raising = False)
+ monkeypatch.setattr(tpq, "te_prequant_sources_confirmed", lambda *a, **k: False)
fam = types.SimpleNamespace(name = "ltx-2.5", bf16_components_gb = (40.0, 23.9))
hosted = tpq.te_prequant_budget_scale(
fam, te_quant_mode = "int8", target = None, base = "Lightricks/LTX-2.5-Diffusers"
)
assert hosted < 1.0
- # Unset keeps the bf16 encoder (int8 is opt-in), so its budget is the dense one.
+ # Unset takes the hosted file only when it is confirmed; unconfirmed it loads bf16, so the budget is the dense one.
assert (
tpq.te_prequant_budget_scale(
fam, te_quant_mode = None, target = None, base = "Lightricks/LTX-2.5-Diffusers"