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: seed LTX-2.5 fp8 / int8 loads from hosted pre-quantized DiTs (#13516)

Daniel Handf55fc4ea4c9
diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.py
index 0cfd7cf1c23..edfb09e05ea 100644
--- a/studio/backend/core/inference/diffusion_transformer_quant.py
+++ b/studio/backend/core/inference/diffusion_transformer_quant.py
@@ -253,10 +253,14 @@ _INT8_FAMILY_CONVROT_REPO: dict[str, str] = {
# Variant repos that also host a rotated build (``<Model>-INT8-ConvRot.safetensors``), listed for the same reason.
_INT8_FAMILY_CONVROT_VARIANT_REPOS: dict[str, tuple[str, ...]] = {
"qwen-image-2.1": ("unsloth/Qwen-Image-2.1-Turbo-FP8",),
+ # Rotation baked into the file (every quantized Linear, group 256) and read back from its metadata. LTX-2.5 has no
+ # runtime ConvRot spec above, so quantizing at load stays plain int8.
+ "ltx-2.5": ("unsloth/LTX-2.5-FP8",),
}
-# Families whose int8 runs ConvRot unless the env turns it off; the rest stay opt-in (``=1``).
-_INT8_FAMILY_CONVROT_DEFAULT_ON: frozenset[str] = frozenset({"qwen-image-2.1", "z-image"})
+# Families whose int8 runs ConvRot unless the env turns it off; the rest stay opt-in (``=1``). For ltx-2.5 this only
+# picks the hosted rotated file (the env's ``0`` picks the plain one).
+_INT8_FAMILY_CONVROT_DEFAULT_ON: frozenset[str] = frozenset({"qwen-image-2.1", "z-image", "ltx-2.5"})
INT8_CONVROT_ENV = "UNSLOTH_DIFFUSION_INT8_CONVROT"
diff --git a/studio/backend/core/inference/video_families.py b/studio/backend/core/inference/video_families.py
index e9ccc8885c9..3b7c42e76cb 100644
--- a/studio/backend/core/inference/video_families.py
+++ b/studio/backend/core/inference/video_families.py
@@ -489,6 +489,16 @@ _FAMILIES: tuple[VideoFamily, ...] = (
# transformer 42.0 bf16 (both DiT files are 42,018,190,584 bytes); Gemma 4 12B 23.9 (text_encoder/ shards),
# held by the encoder worker; VAE 1.45 + connectors 6.34 + latent upsampler 1.0 + audio VAE / vocoder 0.37.
bf16_components_gb = (42.0, 23.9, 9.2),
+ # Hosted DiTs baked from the pack's distilled transformer/ (tensor-identical to the single-file distilled DiT).
+ # Keyed on the pack: only a pipeline load seeds a hosted denoiser, and the pack never loads its dev DiT. int8
+ # resolves LTX-2.5-INT8-ConvRot.safetensors (rotation in its metadata), LTX-2.5-INT8 with
+ # UNSLOTH_DIFFUSION_INT8_CONVROT=0; fp8 resolves LTX-2.5-FP8.safetensors.
+ prequant_variant_repos = (
+ ("lightricks/ltx-2.5-diffusers", "int8", "unsloth/LTX-2.5-FP8"),
+ ("lightricks/ltx-2.5-diffusers", "fp8", "unsloth/LTX-2.5-FP8"),
+ ),
+ # File sizes (decimal GB): int8 keeps the audio stream, AV cross-attention and adaLN in bf16; fp8 quantizes them.
+ prequant_resident_gb_by_scheme = (("int8", 25.11), ("fp8", 19.06)),
supports_keyframes = True,
accepts_last_frame = False,
# Same DiT layout as LTX-2.3, so the same measured knobs.
diff --git a/studio/backend/tests/test_video_ltx25_prequant.py b/studio/backend/tests/test_video_ltx25_prequant.py
new file mode 100644
index 00000000000..9c3864573ae
--- /dev/null
+++ b/studio/backend/tests/test_video_ltx25_prequant.py
@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hosted LTX-2.5 DiT checkpoints (unsloth/LTX-2.5-FP8): which base seeds them, which file each scheme asks for, and
+that the metadata the builder bakes is what this runtime accepts. Network-free and torch-free."""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+
+from core.inference.diffusion_prequant import (
+ PREQUANT_FORMAT,
+ PREQUANT_FORMAT_ROTATED,
+ _validate_checkpoint,
+ prequant_format_for,
+ prequant_mirror_path,
+ resolve_prequant_source,
+)
+from core.inference.diffusion_transformer_quant import (
+ INT8_CONVROT_ENV,
+ convrot_prequant_filename,
+ convrot_spec_for_scheme,
+ exclude_tokens_for_scheme,
+ int8_convrot_enabled,
+)
+from core.inference.video_families import (
+ detect_video_family,
+ video_family_prequant_repo,
+ video_family_prequant_resident_gb,
+ video_family_prequant_schemes,
+)
+
+PACK = "Lightricks/LTX-2.5-Diffusers"
+SINGLE_FILE_RELEASE = "Lightricks/LTX-2.5"
+REPO = "unsloth/LTX-2.5-FP8"
+
+
+def fam():
+ family = detect_video_family(PACK)
+ assert family is not None and family.name == "ltx-2.5"
+ return family
+
+
[email protected](autouse = True)
+def _no_convrot_env(monkeypatch):
+ monkeypatch.delenv(INT8_CONVROT_ENV, raising = False)
+
+
[email protected]("scheme", ["int8", "fp8"])
+def test_the_pack_resolves_the_hosted_repo(fam, scheme):
+ assert video_family_prequant_repo(fam, scheme, PACK) == REPO
+ # Keyed on the lowercased id, so the spelling a caller passes does not matter.
+ assert video_family_prequant_repo(fam, scheme, PACK.lower()) == REPO
+
+
[email protected]("scheme", ["int8", "fp8"])
[email protected]("base", [SINGLE_FILE_RELEASE, None, "", "someone/LTX-2.5-Diffusers-fork"])
+def test_no_other_base_resolves_it(fam, scheme, base):
+ # The single-file release, an unnamed base and a fork never seed a checkpoint baked from the pack's DiT.
+ assert video_family_prequant_repo(fam, scheme, base) is None
+ assert resolve_prequant_source(fam, scheme, base_repo = base) is None
+
+
[email protected]("scheme", ["nvfp4", "mxfp8"])
+def test_only_the_hosted_schemes_resolve(fam, scheme):
+ assert video_family_prequant_repo(fam, scheme, PACK) is None
+ assert set(video_family_prequant_schemes(fam)) == {"int8", "fp8"}
+
+
+def test_fp8_asks_for_its_own_file_first(fam):
+ src = resolve_prequant_source(fam, "fp8", base_repo = PACK)
+ assert (src.kind, src.location, src.filename) == ("repo", REPO, "LTX-2.5-FP8.safetensors")
+ assert src.fallback_filenames[0] == "LTX-2.5-FP8.pt"
+
+
+ "env, first, second",
+ [
+ (None, "LTX-2.5-INT8-ConvRot.safetensors", "LTX-2.5-INT8.safetensors"),
+ ("1", "LTX-2.5-INT8-ConvRot.safetensors", "LTX-2.5-INT8.safetensors"),
+ ("0", "LTX-2.5-INT8.safetensors", "LTX-2.5-INT8.pt"),
+ ],
+)
+def test_int8_asks_for_the_rotated_file_unless_convrot_is_off(fam, monkeypatch, env, first, second):
+ if env is not None:
+ monkeypatch.setenv(INT8_CONVROT_ENV, env)
+ src = resolve_prequant_source(fam, "int8", base_repo = PACK)
+ assert (src.location, src.filename, src.fallback_filenames[0]) == (REPO, first, second)
+ # The plain file stays in the chain behind the rotated one, so a repo without it still serves int8.
+ assert "LTX-2.5-INT8.safetensors" in (src.filename,) + tuple(src.fallback_filenames)
+
+
+def test_quantizing_at_load_stays_plain_int8():
+ # The rotation lives in the hosted file's metadata; there is no runtime ConvRot spec for LTX-2.5, so the default-on
+ # flag only picks the hosted file and never rotates a dense DiT.
+ assert int8_convrot_enabled("ltx-2.5")
+ assert convrot_spec_for_scheme("int8", "ltx-2.5") == (0, ())
+ assert convrot_prequant_filename("int8", "ltx-2.5") is None
+
+
+def test_ltx23_keeps_its_own_hosted_dit():
+ ltx2 = detect_video_family("Lightricks/LTX-2.3")
+ assert ltx2 is not None and ltx2.name == "ltx-2"
+ src = resolve_prequant_source(ltx2, "fp8", base_repo = "Lightricks/LTX-2.3")
+ assert (src.location, src.filename) == ("unsloth/LTX-2.3-FP8", "LTX-2.3-FP8.safetensors")
+ assert resolve_prequant_source(ltx2, "int8", base_repo = "Lightricks/LTX-2.3") is None
+ assert video_family_prequant_repo(ltx2, "fp8", PACK) is None
+
+
+def test_the_plan_prices_the_hosted_files(fam):
+ int8 = video_family_prequant_resident_gb(fam, "int8")
+ fp8 = video_family_prequant_resident_gb(fam, "fp8")
+ assert int8 == pytest.approx(25.11) and fp8 == pytest.approx(19.06)
+ assert fp8 < int8 < fam.bf16_components_gb[0]
+
+
+def test_only_a_pack_pipeline_load_plans_the_seed(fam, monkeypatch):
+ from core.inference import video as vid
+ from core.inference import video_denoiser_prequant as vdp
+
+ monkeypatch.setattr(vdp, "hosted_denoiser_refused", lambda *a, **k: False)
+ sources = vdp.denoiser_prequant_sources(fam, "int8", PACK)
+ assert set(sources) == {"transformer"}
+ assert sources["transformer"].location == REPO
+ assert vdp.denoiser_prequant_sources(fam, "int8", SINGLE_FILE_RELEASE) is None
+ assert vdp.denoiser_prequant_sources(fam, "auto", PACK) is None
+ assert vid._planned_denoiser_components(fam, "pipeline") == ("transformer",)
+ assert vid._planned_denoiser_components(fam, "single_file") == ()
+
+
+def test_a_local_mirror_serves_the_staged_files(monkeypatch, tmp_path):
+ folder = tmp_path / "unsloth" / "LTX-2.5-FP8"
+ folder.mkdir(parents = True)
+ for name in ("LTX-2.5-FP8.safetensors", "LTX-2.5-INT8-ConvRot.safetensors"):
+ (folder / name).write_bytes(b"x")
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_PREQUANT_MIRROR", str(tmp_path))
+ assert prequant_mirror_path(REPO, "LTX-2.5-INT8-ConvRot.safetensors") == str(
+ folder / "LTX-2.5-INT8-ConvRot.safetensors"
+ )
+ assert prequant_mirror_path(REPO, "LTX-2.5-INT8.safetensors") is None
+
+
+# What scripts/build_prequant_checkpoint.py wrote into the staged files' unsloth_metadata (fingerprint, version and
+# rotation fqn list left out). The loader checks these against this runtime's filter, so a drift in the int8 excludes
+# would refuse every hosted file and silently fall back to quantizing at load.
+_BAKED = {
+ "base_model_id": PACK,
+ "family": "ltx-2.5",
+ "min_features": 512,
+ "torch_dtype": "bfloat16",
+ "quant_backend": "torchao",
+ "transformer_class": "LTX2VideoTransformer3DModel",
+ "component": "transformer",
+}
+_BAKED_INT8_EXCLUDES = [
+ "norm",
+ "_mod",
+ "modulation",
+ "timestep_embed",
+ "guidance_embed",
+ "time_text_embed",
+ "pooled",
+ "time_embed",
+ "audio",
+ "av_cross_attn",
+ "adaln",
+]
+
+
+def _meta(scheme: str, rotated: bool = False) -> dict:
+ meta = dict(_BAKED, scheme = scheme)
+ if scheme == "fp8":
+ meta.update(
+ exclude_name_tokens = [],
+ require_bf16 = True,
+ require_divisible = 16,
+ fast_accum = True,
+ fp8_granularity = "per_row",
+ )
+ else:
+ meta.update(
+ exclude_name_tokens = list(_BAKED_INT8_EXCLUDES),
+ require_bf16 = False,
+ require_divisible = 0,
+ fast_accum = None,
+ )
+ if rotated:
+ meta.update(
+ activation_rotation = "convrot_hadamard_v1",
+ activation_rotation_group = 256,
+ activation_rotation_fqns = ["transformer_blocks.0.attn1.to_q"],
+ )
+ return meta
+
+
+def test_the_baked_int8_excludes_are_this_runtimes():
+ assert list(exclude_tokens_for_scheme("int8", "ltx-2.5")) == _BAKED_INT8_EXCLUDES
+ assert list(exclude_tokens_for_scheme("fp8", "ltx-2.5")) == []
+
+
+ "scheme, rotated, fmt",
+ [("fp8", False, PREQUANT_FORMAT), ("int8", False, PREQUANT_FORMAT), ("int8", True, PREQUANT_FORMAT_ROTATED)],
+)
+def test_the_baked_metadata_passes_the_loader(scheme, rotated, fmt):
+ meta = _meta(scheme, rotated)
+ # Only the rotated file carries the v2 tag an older loader refuses; FP8 / INT8 stay v1.
+ assert prequant_format_for(meta) == fmt
+ ckpt = {"format": fmt, "metadata": meta}
+ assert _validate_checkpoint(
+ ckpt,
+ scheme,
+ PACK,
+ logging.getLogger("t"),
+ min_features = 512,
+ fast_accum = True if scheme == "fp8" else None,
+ component = "transformer",
+ metadata_only = True,
+ )
+ # The same file is refused for any other base, so it can never seed the single-file release or LTX-2.3.
+ for other in (SINGLE_FILE_RELEASE, "Lightricks/LTX-2.3"):
+ assert not _validate_checkpoint(
+ ckpt, scheme, other, logging.getLogger("t"), min_features = 512, metadata_only = True
+ )
+
+
+def _api(siblings = None, missing = False):
+ import types
+
+ asked: list = []
+
+ def model_info(repo_id, **_kwargs):
+ asked.append(repo_id)
+ if missing:
+ raise RuntimeError(f"404 Client Error: {repo_id}")
+ return types.SimpleNamespace(
+ siblings = [types.SimpleNamespace(rfilename = n, size = s) for n, s in (siblings or {}).items()]
+ )
+
+ return types.SimpleNamespace(token = None, model_info = model_info, asked = asked)
+
+
+_PUBLISHED = {
+ "LTX-2.5-FP8.safetensors": 19_056_002_016,
+ "LTX-2.5-INT8.safetensors": 25_105_102_312,
+ "LTX-2.5-INT8-ConvRot.safetensors": 25_105_121_000,
+ "README.md": 1,
+}
+
+
+def _planning(monkeypatch):
+ import core.inference.diffusion_prequant as pq
+ from core.inference import video_denoiser_prequant as vdp
+
+ monkeypatch.setattr(pq, "restricted_prequant_load_supported", lambda scheme = None, filename = None: True)
+ monkeypatch.setattr(vdp, "hosted_denoiser_refused", lambda *a, **k: False)
+
+
+ "scheme, env, expected",
+ [
+ ("int8", None, "LTX-2.5-INT8-ConvRot.safetensors"),
+ ("int8", "0", "LTX-2.5-INT8.safetensors"),
+ ("fp8", None, "LTX-2.5-FP8.safetensors"),
+ ],
+)
+def test_once_published_the_plan_credits_the_hosted_file(fam, monkeypatch, _planning, scheme, env, expected):
+ from core.inference.video import VideoBackend
+
+ if env is not None:
+ monkeypatch.setenv(INT8_CONVROT_ENV, env)
+ api = _api(_PUBLISHED)
+ repo, files = VideoBackend._denoiser_prequant_hub_files(fam, scheme, PACK, api)
+ assert (repo, files) == (REPO, [(expected, _PUBLISHED[expected])])
+ assert api.asked == [REPO]
+
+
+def test_until_published_the_plan_keeps_the_dense_shards(fam, _planning):
+ # The repo 404s today: the plan keeps transformer/, and the load quantizes at load instead (the hosted files'
+ # renders are pixel-identical to that, so nothing but load time and the download changes).
+ from core.inference.video import VideoBackend
+
+ assert VideoBackend._denoiser_prequant_hub_files(fam, "int8", PACK, _api(missing = True)) == (None, [])
+ # A listing without the rotated file still serves int8 from the plain one.
+ plain = {k: v for k, v in _PUBLISHED.items() if "ConvRot" not in k}
+ assert VideoBackend._denoiser_prequant_hub_files(fam, "int8", PACK, _api(plain)) == (
+ REPO,
+ [("LTX-2.5-INT8.safetensors", plain["LTX-2.5-INT8.safetensors"])],
+ )
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/host-artifact-policy.ts b/studio/frontend/src/features/model-picker/components/model-selector/host-artifact-policy.ts
index 7ea0cee15d0..0cae5f3380b 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/host-artifact-policy.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/host-artifact-policy.ts
@@ -113,3 +113,19 @@ export function h3PerfSuffix(
if (id === H3_GGUF_ID) return "Slow";
return null;
}
+
+/** Video pipelines whose fp8 / int8 load runs a quantized DiT (a hosted pre-quantized checkpoint, else quantized at
+ * load). Other video rows stay bare: the dense-quant row rule is image-only. */
+const DENSE_QUANT_VIDEO_PIPELINES = new Set(["lightricks/ltx-2.5-diffusers"]);
+
+/** Speed qualifier for those video rows, from the same host scheme list as the image rows. */
+export function videoDensePerfSuffix(
+ repoId: string,
+ host: HostClass,
+ denseQuantSchemes?: readonly string[] | null,
+): string | null {
+ if (!hostRunsDenseQuant(host)) return null;
+ return DENSE_QUANT_VIDEO_PIPELINES.has(repoId.trim().toLowerCase())
+ ? densePerfSuffix(denseQuantSchemes)
+ : null;
+}
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
index 0261b336683..9b3f548597c 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
@@ -175,6 +175,25 @@ assert.equal(groupForRepoId("lightricks/ltx-2.3", VIDEO_CATALOG), ltx23);
assert.equal(groupForRepoId("lightricks/ltx-2.3-fp8", VIDEO_CATALOG), ltx23);
// ...but the LTX-2.0 base stays its own group (different model).
assert.notEqual(groupForRepoId("Lightricks/LTX-2", VIDEO_CATALOG), ltx23);
+// LTX-2.5 is its own group (different DiT and encoder); the hosted prequant repo id finds it, never 2.3.
+const ltx25 = groupForRepoId("Lightricks/LTX-2.5-Diffusers", VIDEO_CATALOG);
+assert.ok(ltx25);
+assert.notEqual(ltx25, ltx23);
+assert.equal(groupForRepoId("unsloth/LTX-2.5-FP8", VIDEO_CATALOG), ltx25);
+assert.equal(groupForRepoId("lightricks/ltx-2.5-diffusers", VIDEO_CATALOG), ltx25);
+assert.equal(curatedArtifactTakesDenseQuant("Lightricks/LTX-2.5-Diffusers", VIDEO_CATALOG), true);
+assert.equal(
+ curatedRowLabelFor("Lightricks/LTX-2.5-Diffusers", VIDEO_CATALOG, "dense-quant", ["fp8"])?.name,
+ "LTX 2.5 distilled (Diffusers) (Fast FP8)",
+);
+assert.equal(
+ curatedRowLabelFor("Lightricks/LTX-2.5-Diffusers", VIDEO_CATALOG, "dense-quant", ["int8", "fp8"])?.name,
+ "LTX 2.5 distilled (Diffusers) (Fast FP8)",
+);
+// Only a host that runs the dense quant gets the qualifier; other video rows stay bare there.
+assert.equal(curatedRowLabelFor("Lightricks/LTX-2.5-Diffusers", VIDEO_CATALOG, "accelerated")?.name, "LTX 2.5 distilled (Diffusers)");
+assert.equal(curatedRowLabelFor("Lightricks/LTX-2.5-Diffusers", VIDEO_CATALOG, "gguf-only")?.name, "LTX 2.5 distilled (Diffusers)");
+assert.equal(curatedRowLabelFor("Lightricks/LTX-2", VIDEO_CATALOG, "dense-quant", ["fp8"])?.name, "LTX 2 (base)");
// SDXL Turbo and Base stay separate groups (different checkpoints).
assert.notEqual(
groupForRepoId("stabilityai/sdxl-turbo", IMAGE_CATALOG),
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
index 259e5f2e99f..11e4a87f51c 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
@@ -25,6 +25,7 @@ import {
ggufPerfSuffix,
h3PerfSuffix,
hostRunsDenseQuant,
+ videoDensePerfSuffix,
} from "./host-artifact-policy.ts";
import type { ModelCapabilities } from "./model-capabilities";
import type { ModelOption } from "./types";
@@ -559,11 +560,14 @@ export const VIDEO_CATALOG: CatalogGroup[] = [
},
{
// LTX-2.5 distilled: the Diffusers pack (its Gemma 4 encoder runs in Studio's transformers 5.10 sidecar) plus
- // the official split single-file DiT, which loads against the companion files beside it in the same repo.
+ // the official split single-file DiT, which loads against the companion files beside it in the same repo. The
+ // pack's fp8 / int8 loads seed the hosted unsloth/LTX-2.5-FP8 DiT (backend prequant_variant_repos); the alias
+ // keeps a pasted prequant repo id finding this group. Video rows carry no prequantRepo (image-only field).
canonicalId: "Lightricks/LTX-2.5-Diffusers",
displayName: "LTX 2.5 distilled",
description: "Text- and image-to-video with audio",
scope: "video",
+ aliases: ["unsloth/LTX-2.5-FP8"],
capabilities: { audio: true },
artifacts: [
// Both repos are gated on the Hub (license + token).
@@ -571,6 +575,8 @@ export const VIDEO_CATALOG: CatalogGroup[] = [
label: "BF16 - Diffusers",
gated: true,
offloadFitTiers: LTX25_OFFLOAD_TIERS,
+ // The DiT's 37,975,718,400 bf16 bytes (transformer/ shard index).
+ totalParams: 18_987_859_200,
}),
bf16Single(
"Lightricks/LTX-2.5",
@@ -1076,7 +1082,10 @@ function curatedPerfSuffix(
if (artifactUsesDenseQuant(hit.group, hit.artifact, host)) {
return densePerfSuffix(denseQuantSchemes);
}
- return h3PerfSuffix(hit.artifact.repoId, host, denseQuantSchemes);
+ return (
+ h3PerfSuffix(hit.artifact.repoId, host, denseQuantSchemes) ??
+ videoDensePerfSuffix(hit.artifact.repoId, host, denseQuantSchemes)
+ );
}
/** A curated row as name plus chips. The name used to carry the artifact in brackets ("MiniMax H3