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: keep LTX-2.5's bf16 text encoder on an unset request (#14737)

Daniel Han3422056353ae
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index 2766c438cd2..11b76bfc512 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -367,7 +367,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 would otherwise take int8); and only an exactly identified official
+ encoder (LTX-2.5's raw unset included, which takes int8 under UNSLOTH_LTX25_TE_INT8=1); 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)
diff --git a/studio/backend/core/inference/video_ltx25.py b/studio/backend/core/inference/video_ltx25.py
index f0d7920df2d..68898defb93 100644
--- a/studio/backend/core/inference/video_ltx25.py
+++ b/studio/backend/core/inference/video_ltx25.py
@@ -58,6 +58,7 @@ LTX25_DEV_SCHEDULER_OVERRIDES: dict[str, Any] = {
TWO_STAGE_ENV = "UNSLOTH_LTX25_TWO_STAGE"
SAMPLER_ENV = "UNSLOTH_LTX25_SAMPLER"
_OFF = ("0", "false", "no", "off")
+_ON = ("1", "true", "yes", "on")
# Pack components a load never reads: the dev DiT (single-file dev picks bring their own), the prompt enhancer and its
# processor (Studio never enhances), the diffusion decoder (conv decode is the pipeline default), the temporal
@@ -84,9 +85,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
-# 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).
+# 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.
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,15 +709,15 @@ 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 _OFF:
- return None
- return LTX25_TE_QUANT_DEFAULT
+ if (os.environ.get(LTX25_TE_QUANT_ENV) or "").strip().lower() in _ON:
+ return LTX25_TE_QUANT_DEFAULT
+ return None
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 (the default when unset) for int8, or Off for bf16."
+ f"'{scheme}'. Pick int8 for int8, or leave it unset / Off for bf16."
)
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index 063b91aebba..975411ccff1 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -9177,11 +9177,8 @@ def test_plan_is_unchanged_when_no_text_encoder_quant_is_requested(fake_runtime,
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
+ # LTX-2.5's unset request keeps its bf16 encoder (int8 is opt-in), so it is priced at the table too.
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(components) + extra_gb) * _MIB_PER_GB
), fam.name
diff --git a/studio/backend/tests/test_video_ltx25_te_hosted.py b/studio/backend/tests/test_video_ltx25_te_hosted.py
index 9ee14d8da26..8eb46ab2cbd 100644
--- a/studio/backend/tests/test_video_ltx25_te_hosted.py
+++ b/studio/backend/tests/test_video_ltx25_te_hosted.py
@@ -1,7 +1,7 @@
# 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."""
+"""LTX-2.5's hosted int8 ConvRot Gemma 4 encoder: when a load takes it, its planning, its load and its fallback."""
from __future__ import annotations
@@ -63,41 +63,56 @@ class _TinyGemma(nn.Module):
BASE = "Lightricks/LTX-2.5-Diffusers"
-def test_unset_request_resolves_to_the_hosted_file(monkeypatch):
+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.
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,
+ for mode in (None, "auto", ""):
+ assert v25.ltx25_te_prequant_sources(mode, BASE) == {}
+ monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "0")
+ assert v25.ltx25_te_prequant_sources(None, BASE) == {}
+
+
+def test_int8_request_resolves_to_the_hosted_file(monkeypatch):
+ monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
+ source = v25.ltx25_te_prequant_sources("int8", BASE)["text_encoder"]
+ assert (source.kind, source.location, source.filename) == (
+ "repo",
+ v25.LTX25_TE_HOSTED_REPO,
+ v25.LTX25_TE_HOSTED_FILE,
+ )
+ monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "1")
+ for mode in (None, "auto"):
+ assert (
+ v25.ltx25_te_prequant_sources(mode, BASE)["text_encoder"].filename
+ == v25.LTX25_TE_HOSTED_FILE
)
+ monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
# 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") == {}
+ assert v25.ltx25_te_prequant_sources("int8", "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") == {}
+ assert v25.ltx25_te_prequant_sources("int8", "/packs/custom/LTX-2.5-Diffusers") == {}
+ assert v25.ltx25_te_prequant_sources("int8", "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_prequant_sources("int8", 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("int8", 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():
+def test_the_video_planner_stages_the_hosted_file(monkeypatch):
from core.inference.video import VideoBackend
from core.inference.video_families import detect_video_family
+ monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
fam = detect_video_family(BASE)
- sources = VideoBackend._te_prequant_sources(fam, None, base = 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) == {}
diff --git a/studio/backend/tests/test_video_ltx25_te_int8.py b/studio/backend/tests/test_video_ltx25_te_int8.py
index 10371d1bfd4..5bb9996d874 100644
--- a/studio/backend/tests/test_video_ltx25_te_int8.py
+++ b/studio/backend/tests/test_video_ltx25_te_int8.py
@@ -204,10 +204,9 @@ def test_worker_load_quantizes_only_when_asked(monkeypatch):
def test_te_quant_tristate(monkeypatch):
monkeypatch.delenv(v25.LTX25_TE_QUANT_ENV, raising = False)
- # 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(None) is None
+ assert v25.ltx25_te_quant_scheme("auto") is None
+ assert v25.ltx25_te_quant_scheme("") is None
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,8 +215,8 @@ 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 v25.ltx25_te_quant_scheme("auto") == "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"
@@ -235,6 +234,8 @@ 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
diff --git a/studio/backend/tests/test_video_te_quant_default.py b/studio/backend/tests/test_video_te_quant_default.py
index 8d5760efe48..5f7e76f4b93 100644
--- a/studio/backend/tests/test_video_te_quant_default.py
+++ b/studio/backend/tests/test_video_te_quant_default.py
@@ -537,16 +537,24 @@ def test_wan_int8_budget_covers_the_measured_file():
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():
+def test_ltx25_budgets_the_dense_peak_unless_the_hosted_encoder_applies(monkeypatch):
+ monkeypatch.delenv("UNSLOTH_LTX25_TE_INT8", raising = 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 = None, target = None, base = "Lightricks/LTX-2.5-Diffusers"
+ 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.
+ assert (
+ tpq.te_prequant_budget_scale(
+ fam, te_quant_mode = None, target = None, base = "Lightricks/LTX-2.5-Diffusers"
+ )
+ == 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"
+ fam, te_quant_mode = "int8", target = None, base = "someone/ltx25-pack"
)
== 1.0
)