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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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_faileddiff --git a/studio/backend/core/inference/video_ltx25.py b/studio/backend/core/inference/video_ltx25.pyindex 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_autoif 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 progressand cancel, and only a file that resolves drops the dense ``text_encoder/`` shards. Pack loads of the base the filewas 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 AutoTeQuantfrom .diffusion_te_prequant import TePrequantSourcefrom .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 sourcesexcept Exception: # noqa: BLE001 -- no hosted encoder: the worker quantizes the dense onereturn {}+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.pyindex 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_familymonkeypatch.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_FILEassert 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.pyindex 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 Noneassert v25.ltx25_te_quant_scheme("off") is Nonefor 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 Noneassert 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_scalefrom 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_080assert 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.0monkeypatch.setenv(v25.LTX25_TE_QUANT_ENV, "1")assert te_prequant_budget_scale(fam, te_quant_mode = None, **kw) == scalemonkeypatch.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.pyindex 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"