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.3 about 4.5x faster per clip (unguided distilled sampling, compile fixes, hosted FP8) (#12067)

Daniel Han3d45be340b1e
diff --git a/studio/backend/core/inference/diffusion_speed.py b/studio/backend/core/inference/diffusion_speed.py
index 09ab6645b25..8fe300e6a74 100644
--- a/studio/backend/core/inference/diffusion_speed.py
+++ b/studio/backend/core/inference/diffusion_speed.py
@@ -871,6 +871,9 @@ def compile_dynamic(transformer: Any, dynamic: Optional[bool]) -> Optional[bool]
(text + target, length s87 - s89) then fuses into torchao's per-row activation-quant reduction, which inductor
cannot split (CantSplit, every render failed). Automatic dynamic (None) compiles the first shapes static and only
generalises what actually varies: stable after ~3 recompiles, same numerics."""
+ # Static kernels for video DiTs: dynamic shapes made LTX-2.3's QK-norm + RoPE kernels ~3x slower.
+ if transformer is not None and getattr(transformer, "_unsloth_compile_static", False):
+ return False
if dynamic and transformer is not None and _carries_torchao_weights(transformer):
return None
return dynamic
diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.py
index 347c094db43..23d45078861 100644
--- a/studio/backend/core/inference/diffusion_transformer_quant.py
+++ b/studio/backend/core/inference/diffusion_transformer_quant.py
@@ -1069,6 +1069,23 @@ def select_transformer_quant_scheme(
return None
+def explicit_scheme_cached_ok(
+ target: Any,
+ requested: Optional[str],
+ family: Optional[str] = None,
+) -> bool:
+ """``select_transformer_quant_scheme(...) == requested`` for an explicit scheme, read from ``_SMOKE_CACHE`` only:
+ never spawns the smoke probe, so a caller that must not touch the GPU (training active) can ask. Unprobed counts
+ as supported, like ``unproven_ok``; a probed failure does not."""
+ requested = normalize_transformer_quant(requested)
+ if requested in (None, TQ_AUTO) or not dense_transformer_supported(target):
+ return False
+ if nvfp4_blocked(requested) or _family_denied(family, requested, None):
+ return False
+ card = _smoke_cache_device_key(str(getattr(target, "device", "cuda")))
+ return _SMOKE_CACHE.get((requested, card), True)
+
+
def dense_quant_host_capable(target: Any) -> bool:
"""Whether an ``auto`` request could engage a dense scheme on this host.
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index e8eeacc2c63..ed3bdc24ddc 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -127,6 +127,7 @@ from .diffusion_nvfp4_flag import nvfp4_diffusion_enabled
from .diffusion_nvfp4_install import nvfp4_backend_fields as _nvfp4_backend_fields
from .diffusion_transformer_quant import (
TQ_AUTO,
+ TQ_FP8,
TQ_INT8,
dense_transformer_supported,
dense_transformer_unsupported_reason,
@@ -140,6 +141,7 @@ from .diffusion_transformer_quant import (
normalize_transformer_quant,
quantize_transformer,
mark_source_precision,
+ explicit_scheme_cached_ok,
select_transformer_quant_scheme,
stored_denoiser_precision,
transformer_is_quantised,
@@ -256,6 +258,8 @@ def assert_video_precision_available(
text_encoder_quant: Optional[str] = None,
memory_mode: Optional[str] = None,
gpu_ordinal: Optional[int] = None,
+ checkpoint_filename: Optional[str] = None,
+ checkpoint_repo: Optional[str] = None,
) -> None:
"""Raise ``RuntimeError`` (the route's 409) when an EXPLICIT precision cannot run here.
@@ -298,9 +302,129 @@ def assert_video_precision_available(
transformer_quant = transformer_quant,
text_encoder_quant = text_encoder_quant,
memory_mode = memory_mode,
+ checkpoint_filename = checkpoint_filename,
+ checkpoint_repo = checkpoint_repo,
)
+def _ltx23_prequant_pick(
+ fam: Any,
+ model_kind: str,
+ checkpoint_filename: Optional[str],
+ pinned: Optional[str],
+ checkpoint_repo: Optional[str] = None,
+) -> bool:
+ """An explicit fp8 on the OFFICIAL bf16 LTX-2.3 distilled single file (``checkpoint_repo`` is the pick's repo id or
+ local path): served by the hosted pre-quantized DiT. A same-named file of other provenance keeps its own DiT."""
+ if (
+ getattr(fam, "name", None) != "ltx-2"
+ or model_kind != "single_file"
+ or not checkpoint_filename
+ ):
+ return False
+ if pinned != TQ_FP8:
+ return False
+ from .video_ltx2 import ltx23_prequant_eligible
+
+ return ltx23_prequant_eligible(checkpoint_filename, checkpoint_repo)
+
+
+def _ltx23_prequant_serves(
+ fam: Any,
+ model_kind: str,
+ checkpoint_filename: Optional[str],
+ pinned: Optional[str],
+ *,
+ target: Any,
+ memory_mode: Optional[str],
+ checkpoint_repo: Optional[str] = None,
+ probe: bool = True,
+) -> bool:
+ """``_ltx23_prequant_pick`` on a load that can seed the hosted DiT: a torchao-capable target and a memory request
+ that keeps the DiT resident (torchao tensors do not survive the offload hooks). The staging, the download plan, the
+ pricing and the injection all read this, so the ~19 GB artifact is never fetched for a load that falls back to bf16
+ (UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK). A measured offload is only known inside the load."""
+ return (
+ _ltx23_prequant_pick(fam, model_kind, checkpoint_filename, pinned, checkpoint_repo)
+ and not _memory_request_forces_offload(memory_mode, False)
+ and bool(dense_transformer_supported(target))
+ and (
+ _ltx23_prequant_scheme_supported(fam, target, pinned)
+ if probe
+ # Training owns the GPU: cached verdict only, never the smoke probe.
+ else explicit_scheme_cached_ok(target, pinned, family = getattr(fam, "name", None))
+ )
+ )
+
+
+def _ltx23_prequant_scheme_supported(fam: Any, target: Any, pinned: Optional[str]) -> bool:
+ """Whether ``target`` runs ``pinned`` at all, by the check an explicit scheme gets on the normal precision path. The
+ hosted DiT is a torchao fp8 checkpoint, so a card with the dense torchao path but no fp8 kernels (Ampere: int8 only)
+ must not stage, claim, price or seed it. ``unproven_ok`` as at the pre-eviction gate: an out-of-memory smoke probe
+ is the resident model, not the scheme."""
+ try:
+ return (
+ select_transformer_quant_scheme(
+ target, pinned, family = getattr(fam, "name", None), unproven_ok = True
+ )
+ == pinned
+ )
+ except Exception: # noqa: BLE001 -- unanswerable reads as unsupported, which keeps the refusal
+ return False
+
+
+def _ltx23_prequant_serves_on_card(
+ fam: Any,
+ model_kind: str,
+ checkpoint_filename: Optional[str],
+ transformer_quant: Optional[str],
+ *,
+ memory_mode: Optional[str],
+ gpu_ordinal: Optional[int],
+ checkpoint_repo: Optional[str] = None,
+ probe: bool = True,
+ hash_source: bool = True,
+) -> bool:
+ """``_ltx23_prequant_serves`` before the load, asked of the card it will use. An unanswerable probe keeps the pick.
+ ``hash_source=False`` (planning) never hashes a local source file; see ``ltx23_identity_without_hashing``."""
+ if not hash_source:
+ from .video_ltx2 import ltx23_identity_without_hashing
+ with ltx23_identity_without_hashing():
+ return _ltx23_prequant_serves_on_card(
+ fam,
+ model_kind,
+ checkpoint_filename,
+ transformer_quant,
+ memory_mode = memory_mode,
+ gpu_ordinal = gpu_ordinal,
+ checkpoint_repo = checkpoint_repo,
+ probe = probe,
+ )
+ pinned = normalize_transformer_quant(transformer_quant)
+ if not _ltx23_prequant_pick(fam, model_kind, checkpoint_filename, pinned, checkpoint_repo):
+ return False
+ try:
+ # Scoped, not pinned: a pooled worker thread must not keep this request's card.
+ with diffusion_device_scope(gpu_ordinal):
+ target = (
+ resolve_diffusion_device_target()
+ if gpu_ordinal is None
+ else resolve_diffusion_device_target(ordinal = gpu_ordinal)
+ )
+ return _ltx23_prequant_serves(
+ fam,
+ model_kind,
+ checkpoint_filename,
+ pinned,
+ target = target,
+ memory_mode = memory_mode,
+ checkpoint_repo = checkpoint_repo,
+ probe = probe,
+ )
+ except Exception: # noqa: BLE001
+ return True
+
+
def _assert_video_precision_for_target(
fam: Any,
target: Any,
@@ -309,6 +433,8 @@ def _assert_video_precision_for_target(
transformer_quant: Optional[str] = None,
text_encoder_quant: Optional[str] = None,
memory_mode: Optional[str] = None,
+ checkpoint_filename: Optional[str] = None,
+ checkpoint_repo: Optional[str] = None,
) -> None:
"""The body of ``assert_video_precision_available``, run with the selected card current."""
pinned = normalize_transformer_quant(transformer_quant)
@@ -322,11 +448,32 @@ def _assert_video_precision_for_target(
)
if pinned is not None and pinned != TQ_AUTO:
reason = None
- if model_kind != "pipeline":
+ if _ltx23_prequant_pick(fam, model_kind, checkpoint_filename, pinned, checkpoint_repo):
+ if not dense_transformer_supported(target):
+ reason = dense_transformer_unsupported_reason(target)
+ elif forces_offload:
+ reason = (
+ f"'{normalize_memory_mode(memory_mode)}' memory places the DiT under CPU "
+ "offload, and torchao quantised tensors cannot be moved by the offload hooks"
+ )
+ elif not _ltx23_prequant_scheme_supported(fam, target, pinned):
+ # Check the hosted DiT's scheme now, else it fails only after the eviction and the 19 GB pull.
+ reason = explain_unusable_scheme(getattr(fam, "name", None), pinned)
+ elif model_kind != "pipeline":
reason = (
f"the dense DiT quant applies to full-pipeline loads only, and this is a "
f"'{model_kind}' load, which runs the precision its checkpoint carries"
)
+ from .video_ltx2 import LTX23_PREQUANT_BASE, LTX23_PREQUANT_SOURCE_FILES
+ if (
+ pinned == TQ_FP8
+ and getattr(fam, "name", None) == "ltx-2"
+ and Path(str(checkpoint_filename or "")).name.lower() in LTX23_PREQUANT_SOURCE_FILES
+ ):
+ reason += (
+ f"; the hosted fp8 DiT replaces only the official {LTX23_PREQUANT_BASE} file, and this "
+ "one could not be verified as it"
+ )
elif (
pinned in NATIVE_QUANT_SCHEMES
and not getattr(fam, "modular_workflow", None)
@@ -1200,11 +1347,16 @@ def _video_auto_denoiser_scheme(
try:
if getattr(fam, "modular_workflow", None):
return None
- # Registry before the smoke probe: a scheme with no hosted row can never seed, so it must not spawn probes.
- hosted = video_family_prequant_schemes(fam)
+ # Registry first: a scheme with no hosted row for THIS base never seeds, so it must not spawn probes.
+ from .video_denoiser_prequant import denoiser_prequant_sources
+
+ hosted = tuple(
+ s
+ for s in video_family_prequant_schemes(fam)
+ if denoiser_prequant_sources(fam, s, base_repo) is not None
+ )
if not hosted or (not auto and normalize_transformer_quant(requested) not in hosted):
return None
- from .video_denoiser_prequant import denoiser_prequant_sources
scheme = select_transformer_quant_scheme(
target,
@@ -1876,6 +2028,8 @@ class VideoBackend:
text_encoder_quant = text_encoder_quant,
memory_mode = memory_mode,
gpu_ordinal = gpu_ordinal,
+ checkpoint_filename = gguf_filename,
+ checkpoint_repo = repo_id,
)
# Resolved out here so the companion claim is published in the SAME locked section as _loading. begin_load
# returns as soon as the thread is scheduled, and a delete arriving in that gap sees only repo_id and base_repo,
@@ -1894,6 +2048,20 @@ class VideoBackend:
claimed_assets = (
(H3_GGUF_REPO, H3_COMPONENT_REPO, H3_LEGACY_COMPONENT_REPO) if h3_native else ()
)
+ # Claim the hosted LTX-2.3 FP8 DiT repo with _loading.
+ if _ltx23_prequant_serves_on_card(
+ fam,
+ resolve_video_model_kind(gguf_filename, model_kind),
+ gguf_filename,
+ transformer_quant,
+ memory_mode = memory_mode,
+ gpu_ordinal = gpu_ordinal,
+ checkpoint_repo = repo_id,
+ ):
+ from .video_ltx2 import LTX23_PREQUANT_BASE
+ claimed_assets = claimed_assets + self._denoiser_prequant_repo_ids(
+ fam, TQ_FP8, LTX23_PREQUANT_BASE
+ )
with self._lock:
if self._loading is not None and self._loading.error is None:
@@ -2170,6 +2338,35 @@ class VideoBackend:
cancel_event = cancel_event,
local_files_only = local_files_only,
)
+ # Fetch the hosted DiT here, under this load's cancel event, and claim it against a mid-load delete.
+ if _ltx23_prequant_serves_on_card(
+ fam,
+ kind,
+ kwargs.get("gguf_filename"),
+ kwargs.get("transformer_quant"),
+ memory_mode = kwargs.get("memory_mode"),
+ gpu_ordinal = kwargs.get("gpu_ordinal"),
+ checkpoint_repo = kwargs["repo_id"],
+ ):
+ from .video_ltx2 import LTX23_PREQUANT_BASE
+
+ ltx23_sources = self._denoiser_prequant_source_list(
+ fam, TQ_FP8, LTX23_PREQUANT_BASE
+ )
+ with self._lock:
+ if self._load_token == token and self._loading is not None:
+ self._loading.asset_repos = tuple(
+ dict.fromkeys(
+ self._loading.asset_repos
+ + tuple(src.location for src in ltx23_sources)
+ )
+ )
+ self._fetch_denoiser_prequant(
+ ltx23_sources,
+ kwargs.get("hf_token"),
+ cancel_event = cancel_event,
+ local_files_only = local_files_only,
+ )
# The denoiser artifact too: the injection that would fetch it has no cancel event.
if skip_transformer_weights:
self._fetch_denoiser_prequant(
@@ -3618,6 +3815,7 @@ class VideoBackend:
transformer_quant: Optional[str] = None,
text_encoder_quant: Optional[str] = None,
h3_task: Optional[str] = None,
+ allow_device_probe: bool = True,
**load_kwargs: Any,
) -> dict[str, Any]:
"""The repos + exact files this pick needs, for staging through the Hub download
@@ -3799,6 +3997,23 @@ class VideoBackend:
)
if dq_repo:
total += add(dq_repo, dq_files)
+ elif _ltx23_prequant_serves_on_card(
+ fam,
+ kind,
+ gguf_filename,
+ transformer_quant,
+ memory_mode = load_kwargs.get("memory_mode"),
+ gpu_ordinal = load_kwargs.get("gpu_ordinal"),
+ checkpoint_repo = repo_id,
+ probe = allow_device_probe,
+ hash_source = False,
+ ):
+ from .video_ltx2 import LTX23_PREQUANT_BASE
+ lq_repo, lq_files = self._denoiser_prequant_hub_files(
+ fam, TQ_FP8, LTX23_PREQUANT_BASE, api
+ )
+ if lq_repo:
+ total += add(lq_repo, lq_files)
# And H3's quantized conditioner, which replaces the base repo's dense text_encoder/. VERIFIED, like the
# load: this entry both ADDS 27 GB and REMOVES the dense encoder from the base entry below, so a name match
# that the load will decline gets the plan and the disk preflight wrong in both directions at once -- 27 GB
@@ -4523,6 +4738,21 @@ class VideoBackend:
transformer_mib = estimate_safetensors_dense_mib(size_mib)
if transformer_mib is not None:
transformer_mib = int(transformer_mib * dtype_scale)
+ # Price the plan at the hosted fp8 DiT: the bf16 file size would plan an offload and skip the seed.
+ ltx23_prequant_pick = transformer_mib is not None and _ltx23_prequant_serves(
+ fam,
+ kind,
+ gguf_filename,
+ normalize_transformer_quant(transformer_quant),
+ target = target,
+ memory_mode = memory_mode,
+ checkpoint_repo = repo_id,
+ )
+ ltx23_dense_transformer_mib = transformer_mib
+ if ltx23_prequant_pick:
+ # The hosted artifact size, not 0.55 x file: the file also carries companions (over-stated ~6 GB).
+ from .video_ltx2 import LTX23_PREQUANT_RESIDENT_GB
+ transformer_mib = int(LTX23_PREQUANT_RESIDENT_GB * mib_per_gb)
runtime_mib = estimate_video_runtime_mib(
width = fam.resolution_presets[0][0],
height = fam.resolution_presets[0][1],
@@ -4795,6 +5025,56 @@ class VideoBackend:
from .video_ltx2 import is_ltx23_checkpoint, load_ltx23_pipeline
if fam.name == "ltx-2" and is_ltx23_checkpoint(checkpoint_path):
+ # Explicit fp8 takes the hosted DiT, resident only: offload hooks' Module.to() rejects torchao tensors.
+ ltx23_override = None
+ ltx23_scheme = normalize_transformer_quant(transformer_quant)
+ seeded = None
+ if ltx23_prequant_pick and plan.offload_policy == "none":
+ from .video_ltx2 import load_ltx23_prequant_transformer
+ seeded = load_ltx23_prequant_transformer(
+ fam,
+ ltx23_scheme,
+ checkpoint_path,
+ config_repo = base,
+ device = device,
+ dtype = dtype,
+ hf_token = hf_token,
+ cache_dir = hub_cache_dir(),
+ local_files_only = local_files_only,
+ logger = logger,
+ )
+ if seeded is not None:
+ ltx23_override, ltx23_source = seeded
+ denoiser_injected = {"transformer": ltx23_override}
+ denoiser_seed_scheme = ltx23_scheme
+ denoiser_seed_sources = {"transformer": ltx23_source}
+ elif ltx23_prequant_pick:
+ # Decline before the dense assembly loads the 44 GB bf16 DiT only to refuse it.
+ ltx23_reason = (
+ f"this GPU's '{plan.offload_policy}' memory plan offloads the DiT even at fp8 size, and "
+ "torchao quantised tensors cannot be moved by the offload hooks"
+ if plan.offload_policy != "none"
+ else "the hosted fp8 DiT (unsloth/LTX-2.3-FP8) could not be loaded"
+ + (" from the local cache" if local_files_only else "")
+ )
+ if not precision_fallback_allowed():
+ clear_gpu_cache()
+ raise RuntimeError(
+ precision_refusal_message(
+ "transformer_quant",
+ ltx23_scheme,
+ ltx23_reason,
+ off_label = "Off to run the DiT at bf16",
+ )
+ )
+ logger.warning("video.ltx23_prequant: %s; loading the bf16 DiT", ltx23_reason)
+ transformer_mib = ltx23_dense_transformer_mib
+ plan, bf16_plan, quant_replanned = _plan_for_te_scale(
+ settled_te_scale, log = False
+ )
+ raise_on_unified_memory_shortfall(
+ plan, family = getattr(fam, "name", None), logger = logger
+ )
# 2.3 checkpoints need the full assembly: new config flags, key renames the stock converter lacks, and
# the 2.3 connectors/VAEs/vocoder.
pipe = load_ltx23_pipeline(
@@ -4810,6 +5090,7 @@ class VideoBackend:
# the one path that does not read them. There is no staged snapshot to fall back on either --
# _base_local_dir is None for 2.3 by design -- so every component below resolves the hub id.
local_files_only = local_files_only,
+ transformer_override = ltx23_override,
)
else:
transformer = transformer_cls.from_single_file(str(checkpoint_path), **sf_kwargs)
@@ -4885,7 +5166,7 @@ class VideoBackend:
transformer_quant_decline = (
"auto: the bf16 DiT fits resident, where int8 costs accuracy for little or no speed"
)
- if transformer_quant_pinned is not None and kind != "pipeline":
+ if transformer_quant_pinned is not None and kind != "pipeline" and not denoiser_injected:
transformer_quant_decline = (
f"the dense DiT quant applies to full-pipeline loads only, and this is a "
f"'{kind}' load, which runs the precision its checkpoint carries"
@@ -5174,6 +5455,14 @@ class VideoBackend:
# quadratic math backend.
target = types.SimpleNamespace(device = target.device, dtype = dtype),
)
+ if fam.name == "ltx-2":
+ # Token counts depend only on (w, h, frames), so static compile: one recompile per shape, ~1.3x faster.
+ ltx_dit = getattr(view, fam.denoiser_attr, None)
+ if ltx_dit is not None:
+ try:
+ ltx_dit._unsloth_compile_static = True
+ except Exception: # noqa: BLE001 -- not a settable module (tests/fakes)
+ pass
applied = apply_speed_optims(
view,
target,
@@ -5186,6 +5475,14 @@ class VideoBackend:
offload_active = plan.offload_policy != "none",
cuda_graph_default = False,
)
+ if fam.name == "ltx-2" and applied.get("compiled"):
+ from .video_ltx2 import install_stg_compile_adapter
+ install_stg_compile_adapter(getattr(view, fam.denoiser_attr, None))
+ if fam.name == "ltx-2" and applied.get("cudnn_benchmark"):
+ # cudnn.benchmark: no steady gain on LTX's VAE / vocoder convs, but a per-shape re-tune (first render 26 s vs 10 s).
+ from .video_ltx2 import disable_cudnn_benchmark
+ if disable_cudnn_benchmark():
+ applied = {**applied, "cudnn_benchmark": False}
if view is pipe:
attention_engaged = engaged
speed_optims = tuple(k for k, v in applied.items() if v)
@@ -6860,6 +7157,18 @@ class VideoBackend:
):
kwargs["sigmas"] = list(LTX23_DISTILLED_SIGMAS)
sigma_ctx = ltx23_verbatim_sigmas(pipe)
+ if fam.name == "ltx-2":
+ from .video_ltx2 import (
+ ensure_recompile_limit,
+ ltx2_distilled_guidance_kwargs,
+ ltx2_distilled_ids,
+ )
+
+ # Distilled DiT is sampled unguided; newer diffusers defaults would add STG + modality passes.
+ if ltx2_distilled_ids(state.gguf_filename, state.repo_id, state.base_repo):
+ kwargs.update(ltx2_distilled_guidance_kwargs(call_params, guidance))
+ # The render thread copies this thread's context, so raise the recompile limit here.
+ ensure_recompile_limit()
if not fam.supports_cfg:
pass
elif fam.guidance_via_guider:
diff --git a/studio/backend/core/inference/video_families.py b/studio/backend/core/inference/video_families.py
index fdb29fa68d7..be9a59423ac 100644
--- a/studio/backend/core/inference/video_families.py
+++ b/studio/backend/core/inference/video_families.py
@@ -244,6 +244,8 @@ _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"),),
+ # 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"),),
),
# Wan2.2-TI2V-5B (diffusers >= 0.35, verified on 0.39): ~5B single-stream DiT (UMT5 encoder), no audio. Its VAE's
# temporal compression 4 gives valid frame counts 4k+1. Defaults 50 steps / CFG 5.
@@ -794,11 +796,21 @@ def default_video_generation_params(
beats the family base repo. ``fallback`` is used when no identifier names a variant --
callers pass the resolved family's own default so a Wan model loaded from an opaque local
path under an explicit family_override still gets 50/5.0, not the hardcoded LTX 40/4.0."""
+ variant = video_generation_variant(*identifiers)
+ for key, steps, guidance in _VIDEO_GENERATION_DEFAULTS:
+ if key == variant:
+ return steps, guidance
+ return fallback
+
+
+def video_generation_variant(*identifiers: Optional[str]) -> Optional[str]:
+ """The ``_VIDEO_GENERATION_DEFAULTS`` key the first identifier naming one matches, or None; the precedence
+ ``default_video_generation_params`` uses, so every per-variant decision agrees with the defaults."""
for identifier in identifiers:
needle = (identifier or "").lower()
- for key, steps, guidance in _VIDEO_GENERATION_DEFAULTS:
+ for key, _steps, _guidance in _VIDEO_GENERATION_DEFAULTS:
# Match the key as a name segment: reject a preceding ASCII letter so "swan-video" does not false-match
# "wan".
if re.search(r"(?<![a-z])" + re.escape(key), needle):
- return steps, guidance
- return fallback
+ return key
+ return None
diff --git a/studio/backend/core/inference/video_ltx2.py b/studio/backend/core/inference/video_ltx2.py
index 705cb9f6903..6a79a5143e8 100644
--- a/studio/backend/core/inference/video_ltx2.py
+++ b/studio/backend/core/inference/video_ltx2.py
@@ -23,8 +23,11 @@ authoritative 2.3 mapping the loader hasn't absorbed). Assembled through the con
from __future__ import annotations
+import contextlib
+import contextvars
+import threading
from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Iterator, Optional
from loggers import get_logger
@@ -320,20 +323,37 @@ def _split_checkpoint(state: dict[str, Any]) -> dict[str, dict[str, Any]]:
"vocoder": {},
}
for key, value in state.items():
- bare = key[len(_DIT_PREFIX) :] if key.startswith(_DIT_PREFIX) else key
- if bare.startswith("vae."):
- groups["vae"][bare[len("vae.") :]] = value
- elif bare.startswith("audio_vae."):
- groups["audio_vae"][bare[len("audio_vae.") :]] = value
- elif bare.startswith("vocoder."):
- groups["vocoder"][bare[len("vocoder.") :]] = value
- elif bare.startswith(_CONNECTOR_KEY_PREFIXES):
- groups["connectors"][bare] = value
- else:
- groups["dit"][bare] = value
+ group, name = _checkpoint_group(key)
+ groups[group][name] = value
return groups
+def _checkpoint_group(key: str) -> tuple[str, str]:
+ """(component group, key within it) for one combined-checkpoint key; see ``_split_checkpoint``."""
+ bare = key[len(_DIT_PREFIX) :] if key.startswith(_DIT_PREFIX) else key
+ for prefix, group in (("vae.", "vae"), ("audio_vae.", "audio_vae"), ("vocoder.", "vocoder")):
+ if bare.startswith(prefix):
+ return group, bare[len(prefix) :]
+ if bare.startswith(_CONNECTOR_KEY_PREFIXES):
+ return "connectors", bare
+ return "dit", bare
+
+
+def _load_checkpoint_without_dit(checkpoint_path: Path | str) -> Optional[dict[str, Any]]:
+ """The non-DiT tensors of a combined safetensors checkpoint, read selectively (the DiT is ~44 GB of
+ the 46 GB file); None when the file is not safetensors, so the caller reads it whole."""
+ if not str(checkpoint_path).lower().endswith(".safetensors"):
+ return None
+ from safetensors import safe_open
+
+ with safe_open(str(checkpoint_path), framework = "pt", device = "cpu") as handle:
+ return {
+ key: handle.get_tensor(key)
+ for key in handle.keys()
+ if _checkpoint_group(key)[0] != "dit"
+ }
+
+
def _load_extras_file(
filename: str,
hf_token: Optional[str],
@@ -390,9 +410,385 @@ LTX23_DISTILLED_SIGMAS: tuple[float, ...] = (
def ltx2_distilled_ids(*ids: Optional[str]) -> bool:
- """True when any loaded-checkpoint id names the distilled DiT (same substring the
- generation-defaults table keys on, so sigmas and the 8-step default stay in lockstep)."""
- return any("distilled" in str(i or "").lower() for i in ids)
+ """Distilled DiT, by the generation defaults' precedence (selected file before repo): a dev file under a
+ '...distilled...' folder stays dev."""
+ from .video_families import video_generation_variant
+ return (
+ video_generation_variant(*(str(i) if i is not None else None for i in ids)) == "distilled"
+ )
+
+
+# LTX2Pipeline guidance kwargs and their off values: diffusers #14447 moved defaults to the dev recipe (STG + modality passes).
+_LTX2_GUIDANCE_OFF: dict[str, float] = {
+ "stg_scale": 0.0,
+ "modality_scale": 1.0,
+ "guidance_rescale": 0.0,
+ "audio_stg_scale": 0.0,
+ "audio_modality_scale": 1.0,
+ "audio_guidance_rescale": 0.0,
+}
+
+
+def ltx2_distilled_guidance_kwargs(call_params: Any, guidance: Optional[float]) -> dict[str, float]:
+ """Distilled LTX-2/2.3 guidance: STG, modality and rescale off, audio CFG = video CFG (one unguided forward per
+ step). Only kwargs the installed pipeline accepts, so older diffusers get the call they always did."""
+ kwargs = {k: v for k, v in _LTX2_GUIDANCE_OFF.items() if k in call_params}
+ if "audio_guidance_scale" in call_params:
+ # Pre-#14447: audio follows the video CFG.
+ kwargs["audio_guidance_scale"] = float(guidance if guidance is not None else 1.0)
+ return kwargs
+
+
+# Hosted 2.3 checkpoints were baked from this file only; distilled-1.1 and dev DiTs may not take them.
+LTX23_PREQUANT_BASE = "Lightricks/LTX-2.3"
+LTX23_PREQUANT_SOURCE_FILES = frozenset({"ltx-2.3-22b-distilled.safetensors"})
+# Resident size of LTX-2.3-FP8.pt (19,057,628,489 bytes); companions are priced separately.
+LTX23_PREQUANT_RESIDENT_GB = 19.06
+
+
+# The hosted DiT REPLACES the file's own, so the file must be the official one (a same-named fine-tune would be swapped silently).
+LTX23_PREQUANT_SOURCE_REPOS = frozenset({"lightricks/ltx-2.3"})
+_LTX23_HUB_REPO_DIRS = frozenset(
+ "models--" + r.replace("/", "--") for r in LTX23_PREQUANT_SOURCE_REPOS
+)
+LTX23_PREQUANT_SOURCE_SIZE = 46_149_345_038
+# LFS sha256, also the Hub cache blob name.
+LTX23_PREQUANT_SOURCE_SHA256 = "14409a4d1337a8ded02fa87fb895b17a91ab2c6588f7cc3352e624ff18a689bf"
+# Elsewhere the whole file is hashed once (~30 s), persisted per (realpath, size, mtime_ns, inode); a sample misses partial fine-tunes.
+_LTX23_HASH_CHUNK = 16 << 20
+_LTX23_VERDICTS_FILE = "ltx23-source-verdicts.json"
+_LTX23_VERDICTS_VERSION = 1
+_LTX23_VERIFY_LOCK = threading.Lock()
+_LTX23_NO_HASH: contextvars.ContextVar[bool] = contextvars.ContextVar(
+ "ltx23_no_hash", default = False
+)
+
+
+def ltx23_identity_without_hashing() -> Iterator[None]:
+ """For planning (the download plan and its precision check): a local file with the official size and no stored
+ verdict reads as official instead of being hashed there, like an uncached Hub pick; the load hashes it."""
+ token = _LTX23_NO_HASH.set(True)
+ try:
+ yield
+ finally:
+ _LTX23_NO_HASH.reset(token)
+
+
+def _ltx23_verdicts_path() -> Path:
+ from utils.paths.storage_roots import cache_root
+ return cache_root() / _LTX23_VERDICTS_FILE
+
+
+def _ltx23_read_verdicts() -> dict[str, Any]:
+ import json
+
+ try:
+ data = json.loads(_ltx23_verdicts_path().read_text(encoding = "utf-8"))
+ except (OSError, ValueError):
+ return {}
+ if (
+ not isinstance(data, dict)
+ or data.get("version") != _LTX23_VERDICTS_VERSION
+ or data.get("sha256") != LTX23_PREQUANT_SOURCE_SHA256
+ or not isinstance(data.get("files"), dict)
+ ):
+ return {}
+ return data["files"]
+
+
+def _ltx23_write_verdict(real: str, record: dict[str, Any]) -> None:
+ import json
+ import os
+ import uuid
+
+ files = _ltx23_read_verdicts()
+ files[real] = record
+ path = _ltx23_verdicts_path()
+ tmp = path.with_name(f".{path.name}.tmp-{uuid.uuid4().hex[:8]}")
+ payload = {
+ "version": _LTX23_VERDICTS_VERSION,
+ "sha256": LTX23_PREQUANT_SOURCE_SHA256,
+ "files": files,
+ }
+ try:
+ path.parent.mkdir(parents = True, exist_ok = True)
+ with tmp.open("w", encoding = "utf-8") as fh:
+ json.dump(payload, fh)
+ fh.flush()
+ os.fsync(fh.fileno())
+ os.replace(tmp, path)
+ except OSError as exc:
+ logger.debug("Could not persist the LTX-2.3 source verdict: %s", exc)
+ try:
+ tmp.unlink(missing_ok = True)
+ except OSError:
+ pass
+
+
+def _ltx23_in_hub_cache_root(root: Path) -> bool:
+ """Whether *root* is one of the Hugging Face hub caches Studio downloads into (a look-alike tree elsewhere is not)."""
+ try:
+ from hub.utils.hf_cache_state import hf_cache_roots
+ return any(root == Path(r).resolve() for r in hf_cache_roots())
+ except Exception: # noqa: BLE001 - unknown roots: hash instead
+ return False
+
+
+def _ltx23_stat_key(stat: Any) -> dict[str, int]:
+ return {"size": stat.st_size, "mtime_ns": stat.st_mtime_ns, "inode": stat.st_ino}
+
+
+def ltx23_source_sha256(path: Path | str) -> str:
+ """The full sha256 of *path*. Raises OSError on a read failure."""
+ import hashlib
+
+ digest = hashlib.sha256()
+ buf = bytearray(_LTX23_HASH_CHUNK)
+ view = memoryview(buf)
+ with open(path, "rb", buffering = 0) as fh:
+ while n := fh.readinto(buf):
+ digest.update(view[:n])
+ return digest.hexdigest()
+
+
+def ltx23_source_file_verified(checkpoint_path: Path | str) -> bool:
+ """Whether the file on disk is the official ``ltx-2.3-22b-distilled.safetensors``: its size, then the Hub cache's
+ content-addressed blob name, else the full sha256 (persisted per realpath, size, mtime and inode). Never raises."""
+ try:
+ path = Path(str(checkpoint_path)).expanduser()
+ if path.name.lower() not in LTX23_PREQUANT_SOURCE_FILES:
+ return False
+ real = path.resolve()
+ stat = real.stat()
+ if stat.st_size != LTX23_PREQUANT_SOURCE_SIZE:
+ return False
+ if (
+ real.name == LTX23_PREQUANT_SOURCE_SHA256
+ and real.parent.name == "blobs"
+ and real.parent.parent.name.lower() in _LTX23_HUB_REPO_DIRS
+ and _ltx23_in_hub_cache_root(real.parent.parent.parent)
+ ):
+ return True
+ key = _ltx23_stat_key(stat)
+ stored = _ltx23_read_verdicts().get(str(real))
+ if isinstance(stored, dict) and {k: stored.get(k) for k in key} == key:
+ return stored.get("verified") is True
+ if _LTX23_NO_HASH.get():
+ return True
+ with _LTX23_VERIFY_LOCK:
+ stored = _ltx23_read_verdicts().get(str(real))
+ if isinstance(stored, dict) and {k: stored.get(k) for k in key} == key:
+ return stored.get("verified") is True
+ logger.info(
+ "video.ltx23_prequant: hashing %s once to confirm it is the official file", real
+ )
+ verified = ltx23_source_sha256(real) == LTX23_PREQUANT_SOURCE_SHA256
+ # Changed while being read: neither stored nor trusted.
+ if _ltx23_stat_key(real.stat()) != key:
+ return False
+ _ltx23_write_verdict(str(real), {**key, "verified": verified})
+ return verified
+ except Exception: # noqa: BLE001 -- unverifiable is not official
+ return False
+
+
+def _ltx23_hub_cached_file(repo_id: str, filename: str) -> Optional[Path]:
+ """The cached copy of *filename* in *repo_id* under either cache root, network-free; None when not cached."""
+ try:
+ from huggingface_hub import try_to_load_from_cache
+
+ from .diffusion import hub_cache_dir
+ for cache_dir in dict.fromkeys((None, hub_cache_dir())):
+ hit = try_to_load_from_cache(repo_id, filename, cache_dir = cache_dir)
+ if isinstance(hit, str):
+ return Path(hit)
+ except Exception: # noqa: BLE001 -- a lookup failure reads as not cached
+ return None
+ return None
+
+
+def ltx23_prequant_eligible(
+ checkpoint_filename: Optional[str], repo_id: Optional[str] = None
+) -> bool:
+ """Whether the hosted DiT may replace this pick's own: the official file by name AND identity (local content, or
+ the official Hub repo, its cached copy verified by content; the load re-checks)."""
+ if not checkpoint_filename or not repo_id:
+ return False
+ if Path(str(checkpoint_filename)).name.lower() not in LTX23_PREQUANT_SOURCE_FILES:
+ return False
+ try:
+ root = Path(str(repo_id)).expanduser()
+ if root.is_file():
+ return ltx23_source_file_verified(root)
+ if root.is_dir():
+ from .diffusion_families import resolve_local_gguf_child
+ return ltx23_source_file_verified(
+ resolve_local_gguf_child(root, str(checkpoint_filename))
+ )
+ except Exception: # noqa: BLE001 -- an unresolvable local pick is not verified
+ return False
+ if str(repo_id).strip().lower() not in LTX23_PREQUANT_SOURCE_REPOS:
+ return False
+ cached = _ltx23_hub_cached_file(str(repo_id).strip(), str(checkpoint_filename))
+ return True if cached is None else ltx23_source_file_verified(cached)
+
+
+class _LTX23PrequantConfig:
+ """Transformer "class" for ``load_prequantized_transformer``: the 2.0 config + 2.3 overrides, since the
+ single-file 2.3 repo has no ``transformer/``."""
+
+ def __init__(self, config_repo: str):
+ self.config_repo = config_repo
+
+ def load_config(self, _base: str, **kwargs: Any) -> dict[str, Any]:
+ from diffusers import LTX2VideoTransformer3DModel
+
+ config = dict(LTX2VideoTransformer3DModel.load_config(self.config_repo, **kwargs))
+ config.update(LTX_2_3_TRANSFORMER_CONFIG_OVERRIDES)
+ return config
+
+ @staticmethod
+ def from_config(config: Any) -> Any:
+ from diffusers import LTX2VideoTransformer3DModel
+ return LTX2VideoTransformer3DModel.from_config(config)
+
+
+def load_ltx23_prequant_transformer(
+ fam: Any,
+ scheme: str,
+ checkpoint_path: Path | str,
+ *,
+ config_repo: str,
+ device: str,
+ dtype: Any,
+ hf_token: Optional[str] = None,
+ cache_dir: Optional[str] = None,
+ local_files_only: bool = False,
+ logger: Any = None,
+) -> Optional[tuple[Any, Any]]:
+ """``(transformer, source)`` from the hosted pre-quantized 2.3 distilled DiT, or None (the
+ caller keeps the dense DiT). Never raises."""
+ try:
+ if not ltx23_source_file_verified(checkpoint_path):
+ if logger is not None:
+ logger.warning(
+ "video.ltx23_prequant: %s is not the official LTX-2.3 distilled file, keeping its own DiT",
+ checkpoint_path,
+ )
+ return None
+ from .diffusion_prequant import load_prequantized_transformer, resolve_prequant_source
+ from .diffusion_transformer_quant import DEFAULT_MIN_LINEAR_FEATURES
+
+ source = resolve_prequant_source(fam, scheme, base_repo = LTX23_PREQUANT_BASE)
+ if source is None:
+ return None
+ module = load_prequantized_transformer(
+ _LTX23PrequantConfig(config_repo),
+ LTX23_PREQUANT_BASE,
+ source,
+ device = device,
+ dtype = dtype,
+ hf_token = hf_token,
+ scheme = scheme,
+ min_features = DEFAULT_MIN_LINEAR_FEATURES,
+ cache_dir = cache_dir,
+ local_files_only = local_files_only,
+ logger = logger,
+ )
+ return None if module is None else (module, source)
+ except Exception as exc: # noqa: BLE001 -- a hosted checkpoint is an optimisation, never a blocker
+ if logger is not None:
+ logger.warning(
+ "video.ltx23_prequant: %s failed, keeping the dense DiT: %s", scheme, exc
+ )
+ return None
+
+
+def disable_cudnn_benchmark() -> bool:
+ """Switch the process-wide cudnn.benchmark off (True when it changed)."""
+ try:
+ import torch
+
+ if not torch.backends.cudnn.benchmark:
+ return False
+ torch.backends.cudnn.benchmark = False
+ return True
+ except Exception: # noqa: BLE001 -- optimisation only
+ return False
+
+
+# Static compile: 1 graph per shape unguided, 4 guided; dynamo's default limit of 8 fails the third guided resolution.
+LTX2_RECOMPILE_LIMIT = 64
+
+
+def ensure_recompile_limit(limit: int = LTX2_RECOMPILE_LIMIT) -> None:
+ """Raise dynamo's recompile limit in the calling thread: torch >= 2.12 keeps config per thread context, so the
+ render thread would otherwise see the default 8 despite the load-time raise."""
+ try:
+ import torch._dynamo.config as dynamo_cfg
+ except Exception: # noqa: BLE001 -- no dynamo, nothing compiled
+ return
+ for attr in ("recompile_limit", "cache_size_limit"): # name varies by torch version
+ try:
+ if hasattr(dynamo_cfg, attr) and (getattr(dynamo_cfg, attr) or 0) < limit:
+ setattr(dynamo_cfg, attr, limit)
+ except Exception: # noqa: BLE001 -- optimisation only
+ pass
+
+
+def _recompile_limit_hit(exc: BaseException) -> bool:
+ try:
+ import torch
+ kind = getattr(torch._dynamo.exc, "FailOnRecompileLimitHit", None)
+ except Exception: # noqa: BLE001
+ return False
+ return isinstance(kind, type) and isinstance(exc, kind)
+
+
+def install_stg_compile_adapter(transformer: Any) -> int:
+ """Convert the STG pass's 0-d ``all_perturbed`` tensor to a bool before the compiled block (LTX2Attention branches
+ on it, which fails fullgraph and drops the DiT to eager). Keeps the guard's marker so ``guard_compiled_blocks``
+ stays idempotent; past the recompile limit drops to eager instead of failing. Returns blocks adapted."""
+ try:
+ import torch
+ except Exception: # noqa: BLE001
+ return 0
+ count = 0
+ for module in getattr(transformer, "modules", lambda: ())():
+ if type(module).__name__ != "LTX2VideoTransformerBlock":
+ continue
+ inner = getattr(module, "_compiled_call_impl", None)
+ if inner is None or getattr(inner, "_unsloth_stg_adapter", False):
+ continue
+
+ guard = getattr(inner, "_unsloth_compile_guard", None)
+
+ def adapted(
+ *args: Any,
+ _inner: Any = inner,
+ _guard: Any = guard,
+ **kwargs: Any,
+ ) -> Any:
+ flag = kwargs.get("all_perturbed")
+ if isinstance(flag, torch.Tensor):
+ kwargs["all_perturbed"] = bool(flag)
+ try:
+ return _inner(*args, **kwargs)
+ except Exception as exc: # noqa: BLE001 -- reraised unless the recompile limit was hit
+ if _guard is None or _guard.error is not None or not _recompile_limit_hit(exc):
+ raise
+ # Past the recompile limit fullgraph raises unclassified by the guard: drop this DiT to eager.
+ _guard.fail(exc, transformer)
+ exc.__traceback__ = None
+ return _inner(*args, **kwargs)
+
+ adapted._unsloth_stg_adapter = True
+ if guard is not None:
+ adapted._unsloth_compile_guard = guard
+ module._compiled_call_impl = adapted
+ count += 1
+ return count
def ltx23_verbatim_sigmas(pipe: Any) -> Any:
@@ -575,6 +971,7 @@ def load_ltx23_pipeline(
hf_token: Optional[str] = None,
text_encoder: Optional[Any] = None,
local_files_only: bool = False,
+ transformer_override: Optional[Any] = None,
) -> Any:
"""Full LTX-2.3 pipeline from a single-file/GGUF checkpoint. Assembled per-component
(constructor, not from_pretrained) because the base model_index pins LTX2Vocoder while 2.3
@@ -601,7 +998,11 @@ def load_ltx23_pipeline(
is_gguf,
LTX23_EXTRAS_REPO,
)
- state = load_single_file_checkpoint(str(checkpoint_path))
+ state = None
+ if transformer_override is not None and not is_gguf:
+ state = _load_checkpoint_without_dit(checkpoint_path)
+ if state is None:
+ state = load_single_file_checkpoint(str(checkpoint_path))
groups = _split_checkpoint(state)
del state
@@ -615,14 +1016,19 @@ def load_ltx23_pipeline(
"instead (Q8_0 for the highest fidelity) or the official bf16 checkpoint."
)
- transformer = load_ltx23_transformer(
- groups["dit"],
- base_repo = base_repo,
- torch_dtype = torch_dtype,
- is_gguf = is_gguf,
- hf_token = hf_token,
- local_files_only = local_files_only,
- )
+ if transformer_override is not None:
+ # Pre-built (hosted) DiT: the file contributes only connectors / VAEs / vocoder.
+ transformer = transformer_override
+ groups.pop("dit", None)
+ else:
+ transformer = load_ltx23_transformer(
+ groups["dit"],
+ base_repo = base_repo,
+ torch_dtype = torch_dtype,
+ is_gguf = is_gguf,
+ hf_token = hf_token,
+ local_files_only = local_files_only,
+ )
connectors = load_ltx23_connectors(
groups["connectors"],
variant = variant,
diff --git a/studio/backend/routes/video.py b/studio/backend/routes/video.py
index 3963170ef76..79bc412e1dd 100644
--- a/studio/backend/routes/video.py
+++ b/studio/backend/routes/video.py
@@ -201,8 +201,13 @@ async def video_download_plan(
if fam is not None:
gpu_ordinal = await _selected_gpu_ordinal(request.gpu_ids, allow_ranking = not training)
if fam is not None and not training:
+ from core.inference.video_ltx2 import ltx23_identity_without_hashing
+ def _plan_precision_check(*args, **kwargs):
+ with ltx23_identity_without_hashing():
+ assert_video_precision_available(*args, **kwargs)
+
await asyncio.to_thread(
- assert_video_precision_available,
+ _plan_precision_check,
fam,
model_kind = kind,
transformer_quant = request.transformer_quant,
@@ -210,6 +215,8 @@ async def video_download_plan(
memory_mode = request.memory_mode,
# Judged on the card this pick would load on, as the loader does.
gpu_ordinal = gpu_ordinal,
+ checkpoint_filename = request.gguf_filename,
+ checkpoint_repo = request.model_path,
)
plan = await asyncio.to_thread(
backend.download_plan,
@@ -229,6 +236,10 @@ async def video_download_plan(
# And the MiniMax-H3 partition: the two denoisers live in separate 66.28 GB subfolders, so a ref2va load opens
# transformer_ref/, which the plan would otherwise miss while staging the fl2va transformer/.
h3_task = request.h3_task,
+ # Forward the memory / speed policy: an fp8 LTX-2.3 pick under balanced / low_vram loads bf16 and must not stage the FP8 DiT.
+ memory_mode = request.memory_mode,
+ speed_mode = request.speed_mode,
+ allow_device_probe = not training,
)
return DiffusionDownloadPlanResponse(**plan)
except (ValueError, FileNotFoundError) as exc:
@@ -370,6 +381,8 @@ async def load_video_model_gated(
# anything is measured, and an offloaded DiT or encoder skips the torchao build.
memory_mode = request.memory_mode,
gpu_ordinal = gpu_ordinal,
+ checkpoint_filename = request.gguf_filename,
+ checkpoint_repo = request.model_path,
)
# Same bar again, for a speech GGUF picked out of a mixed video repo. The backend's own assertion runs on the
# load worker, INSIDE acquire_for, so a refusal there arrives having already evicted the chat model.
diff --git a/studio/backend/tests/test_video_backend.py b/studio/backend/tests/test_video_backend.py
index b5b375cfca0..1977c9f6567 100644
--- a/studio/backend/tests/test_video_backend.py
+++ b/studio/backend/tests/test_video_backend.py
@@ -10,6 +10,7 @@ import builtins
import contextlib
import dataclasses
import functools
+import inspect
import sys
import threading
import time
@@ -3634,6 +3635,40 @@ def test_begin_load_publishes_the_h3_companion_claim_with_the_loading_state(
assert H3_COMPONENT_REPO in claimed
+def test_begin_load_publishes_the_hosted_ltx23_fp8_claim_with_the_loading_state(
+ fake_runtime, monkeypatch
+):
+ # The hosted DiT's repo is claimed with _loading (like H3's), so a delete before the worker's claim cannot race the fetch.
+ import threading
+ from types import SimpleNamespace
+
+ from core.inference import video as video_mod
+
+ monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
+ _ltx23_fp8_card(monkeypatch)
+ monkeypatch.setattr(
+ video_mod, "assert_video_precision_available", lambda fam, **kw: None, raising = False
+ )
+ monkeypatch.setattr(
+ threading, "Thread", lambda *a, **k: SimpleNamespace(start = lambda: None, daemon = True)
+ )
+
+ def _claimed(**kwargs):
+ backend = VideoBackend()
+ backend.begin_load(
+ "Lightricks/LTX-2.3",
+ gguf_filename = "ltx-2.3-22b-distilled.safetensors",
+ family_override = "ltx-2",
+ model_kind = "single_file",
+ **kwargs,
+ )
+ return backend.loading_repo_ids()
+
+ assert "unsloth/LTX-2.3-FP8" in _claimed(transformer_quant = "fp8")
+ assert "unsloth/LTX-2.3-FP8" not in _claimed()
+ assert "unsloth/LTX-2.3-FP8" not in _claimed(transformer_quant = "fp8", memory_mode = "balanced")
+
+
def test_begin_load_claims_no_companion_repos_for_a_non_h3_family(fake_runtime, monkeypatch):
# H3-native only: naming the companions on a pipeline load would block deletes of repos it
# never reads.
@@ -11188,3 +11223,953 @@ def test_video_auto_quant_still_engages_when_the_budget_is_unknown(fake_runtime,
"Wan-AI/Wan2.2-TI2V-5B-Diffusers", model_kind = "pipeline", speed_mode = "default"
)
assert calls == ["auto"]
+
+
+def _guided_ltx_call(monkeypatch, pipe):
+ """Give the fake pipeline the multimodal-guidance kwargs of LTX2Pipeline.__call__ (diffusers main)."""
+ original = type(pipe).__call__
+
+ def __call__(
+ self,
+ *,
+ stg_scale = 1.0,
+ modality_scale = 3.0,
+ guidance_rescale = 0.7,
+ audio_guidance_scale = 7.0,
+ audio_stg_scale = 1.0,
+ audio_modality_scale = 3.0,
+ audio_guidance_rescale = 0.7,
+ **kwargs,
+ ):
+ out = original(self, **kwargs)
+ self.last_kwargs.update(
+ stg_scale = stg_scale,
+ modality_scale = modality_scale,
+ guidance_rescale = guidance_rescale,
+ audio_guidance_scale = audio_guidance_scale,
+ audio_stg_scale = audio_stg_scale,
+ audio_modality_scale = audio_modality_scale,
+ audio_guidance_rescale = audio_guidance_rescale,
+ )
+ return out
+
+ __call__.__signature__ = inspect.Signature(
+ [inspect.Parameter("self", inspect.Parameter.POSITIONAL_OR_KEYWORD)]
+ + [
+ inspect.Parameter(name, inspect.Parameter.KEYWORD_ONLY, default = None)
+ for name in (
+ "prompt",
+ "negative_prompt",
+ "num_inference_steps",
+ "guidance_scale",
+ "width",
+ "height",
+ "num_frames",
+ "frame_rate",
+ "generator",
+ "sigmas",
+ "callback_on_step_end",
+ "stg_scale",
+ "modality_scale",
+ "guidance_rescale",
+ "audio_guidance_scale",
+ "audio_stg_scale",
+ "audio_modality_scale",
+ "audio_guidance_rescale",
+ )
+ ]
+ )
+ monkeypatch.setattr(type(pipe), "__call__", __call__)
+
+
+def test_generate_distilled_turns_multimodal_guidance_off(fake_runtime, tmp_path, monkeypatch):
+ # Distilled DiT: every #14447 guidance term must be off, else four DiT forwards per step.
+ backend = _load_ltx23_from_dir(tmp_path)
+ _guided_ltx_call(monkeypatch, backend._state.pipe)
+ backend.generate(prompt = "a sloth")
+ call = backend._state.pipe.last_kwargs
+ assert call["guidance_scale"] == 1.0
+ assert call["stg_scale"] == 0.0 and call["audio_stg_scale"] == 0.0
+ assert call["modality_scale"] == 1.0 and call["audio_modality_scale"] == 1.0
+ assert call["guidance_rescale"] == 0.0 and call["audio_guidance_rescale"] == 0.0
+ assert call["audio_guidance_scale"] == 1.0
+ backend.generate(prompt = "a sloth", guidance = 2.5)
+ assert backend._state.pipe.last_kwargs["audio_guidance_scale"] == 2.5
+
+
+def test_generate_dev_keeps_pipeline_guidance_defaults(fake_runtime, tmp_path, monkeypatch):
+ (tmp_path / "ltx-2.3-22b-dev-Q4_K_M.gguf").write_bytes(b"w")
+ backend = VideoBackend()
+ backend.load_pipeline(
+ str(tmp_path),
+ gguf_filename = "ltx-2.3-22b-dev-Q4_K_M.gguf",
+ base_repo = "Lightricks/LTX-2",
+ family_override = "ltx-2",
+ )
+ _guided_ltx_call(monkeypatch, backend._state.pipe)
+ backend.generate(prompt = "a sloth")
+ call = backend._state.pipe.last_kwargs
+ assert call["stg_scale"] == 1.0 and call["audio_guidance_scale"] == 7.0
+
+
+def test_ltx2_distilled_guidance_kwargs_follow_the_signature():
+ from core.inference.video_ltx2 import ltx2_distilled_guidance_kwargs
+
+ assert ltx2_distilled_guidance_kwargs({"prompt": None, "guidance_scale": None}, 1.0) == {}
+ full = ltx2_distilled_guidance_kwargs(
+ {"stg_scale": 0, "modality_scale": 0, "audio_guidance_scale": 0, "guidance_rescale": 0},
+ None,
+ )
+ assert full == {
+ "stg_scale": 0.0,
+ "modality_scale": 1.0,
+ "guidance_rescale": 0.0,
+ "audio_guidance_scale": 1.0,
+ }
+
+
+def test_stg_compile_adapter_hands_the_block_a_python_bool():
+ torch = pytest.importorskip("torch")
+ if not hasattr(torch, "nn") or not hasattr(torch, "all"):
+ pytest.skip("real torch required")
+ from core.inference.video_ltx2 import install_stg_compile_adapter
+
+ seen = []
+
+ def compiled(*args, **kwargs):
+ seen.append(kwargs.get("all_perturbed"))
+ return "out"
+
+ compiled._unsloth_compile_guard = "guard"
+ block = type("LTX2VideoTransformerBlock", (torch.nn.Module,), {})()
+ block._compiled_call_impl = compiled
+ other = torch.nn.Linear(1, 1)
+ other._compiled_call_impl = compiled
+ root = torch.nn.ModuleList([block, other])
+ assert install_stg_compile_adapter(root) == 1
+ assert install_stg_compile_adapter(root) == 0 # idempotent
+ assert other._compiled_call_impl is compiled # only LTX-2 blocks
+ wrapped = block._compiled_call_impl
+ assert wrapped._unsloth_compile_guard == "guard" # guard_compiled_blocks stays idempotent
+ assert wrapped(all_perturbed = torch.tensor(True)) == "out"
+ assert wrapped(all_perturbed = False) == "out"
+ assert seen == [True, False] and type(seen[0]) is bool
+
+
+def test_stg_compile_adapter_drops_to_eager_past_the_recompile_limit():
+ # Past the recompile limit fullgraph raises FailOnRecompileLimitHit; the adapter routes it to eager, other errors propagate.
+ torch = pytest.importorskip("torch")
+ limit_hit = getattr(
+ getattr(getattr(torch, "_dynamo", None), "exc", None), "FailOnRecompileLimitHit", None
+ )
+ if not hasattr(torch, "nn") or not isinstance(limit_hit, type):
+ pytest.skip("real torch with FailOnRecompileLimitHit required")
+ from core.inference.diffusion_speed import compile_fallback_error, guard_compiled_blocks
+ from core.inference.video_ltx2 import install_stg_compile_adapter
+
+ raised = {"exc": limit_hit("Hard failure due to fullgraph=True")}
+
+ class LTX2VideoTransformerBlock(torch.nn.Module):
+ def forward(self, all_perturbed = False):
+ return "eager"
+
+ def compiled(*args, **kwargs):
+ raise raised["exc"]
+
+ block = LTX2VideoTransformerBlock()
+ block._compiled_call_impl = compiled
+ root = torch.nn.ModuleList([block])
+ assert guard_compiled_blocks(root) == 1
+ assert install_stg_compile_adapter(root) == 1
+ raised["exc"] = ValueError("a kernel error, not a compile failure")
+ with pytest.raises(ValueError):
+ block(all_perturbed = torch.tensor(False))
+ assert compile_fallback_error(types.SimpleNamespace(transformer = root)) is None
+ raised["exc"] = limit_hit("Hard failure due to fullgraph=True")
+ assert block(all_perturbed = torch.tensor(True)) == "eager"
+ assert "FailOnRecompileLimitHit" in compile_fallback_error(
+ types.SimpleNamespace(transformer = root)
+ )
+ assert block._compiled_call_impl is None # the whole DiT runs eager for the rest of the load
+ assert block(all_perturbed = False) == "eager"
+
+
+def test_ltx2_recompile_limit_reaches_the_render_thread():
+ # torch >= 2.12 keeps dynamo config per thread context; the render copies the caller's context.
+ pytest.importorskip("torch")
+ try:
+ import torch._dynamo.config as dynamo_cfg
+ except Exception: # noqa: BLE001
+ pytest.skip("real torch._dynamo required")
+ import contextvars
+
+ from core.inference.video_ltx2 import LTX2_RECOMPILE_LIMIT, ensure_recompile_limit
+
+ seen = {}
+
+ def caller():
+ ensure_recompile_limit()
+ ctx = contextvars.copy_context()
+ worker = threading.Thread(
+ target = lambda: ctx.run(lambda: seen.update(limit = dynamo_cfg.recompile_limit))
+ )
+ worker.start()
+ worker.join()
+
+ thread = threading.Thread(target = caller)
+ thread.start()
+ thread.join()
+ assert seen["limit"] >= LTX2_RECOMPILE_LIMIT
+
+
+def test_precision_gate_admits_fp8_only_for_the_ltx23_prequant_file(fake_runtime, monkeypatch):
+ # #742: explicit fp8 on the distilled file is served by the hosted DiT; other single files / schemes are still refused.
+ import core.inference.video as video_mod
+
+ monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
+ _ltx23_fp8_card(monkeypatch)
+ fam = types.SimpleNamespace(name = "ltx-2")
+ video_mod.assert_video_precision_available(
+ fam,
+ model_kind = "single_file",
+ transformer_quant = "fp8",
+ checkpoint_filename = "ltx-2.3-22b-distilled.safetensors",
+ checkpoint_repo = "Lightricks/LTX-2.3",
+ )
+ for filename, scheme in (
+ ("ltx-2.3-22b-dev.safetensors", "fp8"),
+ ("ltx-2.3-22b-distilled-1.1.safetensors", "fp8"),
+ ("ltx-2.3-22b-distilled.safetensors", "int8"),
+ (None, "fp8"),
+ ):
+ with pytest.raises(RuntimeError, match = "full-pipeline loads only"):
+ video_mod.assert_video_precision_available(
+ fam,
+ model_kind = "single_file",
+ transformer_quant = scheme,
+ checkpoint_filename = filename,
+ checkpoint_repo = "Lightricks/LTX-2.3",
+ )
+ with pytest.raises(RuntimeError, match = "offload"):
+ video_mod.assert_video_precision_available(
+ fam,
+ model_kind = "single_file",
+ transformer_quant = "fp8",
+ memory_mode = "low_vram",
+ checkpoint_filename = "ltx-2.3-22b-distilled.safetensors",
+ checkpoint_repo = "Lightricks/LTX-2.3",
+ )
+
+
+def test_ltx23_prequant_source_resolves_the_hosted_fp8_only():
+ from core.inference.diffusion_prequant import resolve_prequant_source
+ from core.inference.video_families import detect_video_family
+ from core.inference.video_ltx2 import LTX23_PREQUANT_BASE
+
+ fam = detect_video_family("Lightricks/LTX-2.3")
+ source = resolve_prequant_source(fam, "fp8", base_repo = LTX23_PREQUANT_BASE)
+ assert source is not None and source.location == "unsloth/LTX-2.3-FP8"
+ from core.inference.diffusion_prequant import candidate_filenames_of
+
+ assert "LTX-2.3-FP8.pt" in candidate_filenames_of(
+ source
+ ) # the artifact the repo actually hosts
+ assert resolve_prequant_source(fam, "int8", base_repo = LTX23_PREQUANT_BASE) is None
+ assert resolve_prequant_source(fam, "fp8", base_repo = "Lightricks/LTX-2") is None
+
+
+def _ltx23_fp8_card(monkeypatch, *, fp8 = True):
+ """The explicit fp8 scheme check on the card the load uses: sm_89+ runs fp8, Ampere (sm_80/86) only int8."""
+ from core.inference import video as video_mod
+ monkeypatch.setattr(
+ video_mod, "_ltx23_prequant_scheme_supported", lambda fam, target, pinned: fp8
+ )
+
+
+def _ltx23_official_file(monkeypatch):
+ """Stand-in 1-byte fixtures pass as the official LTX-2.3 distilled file (identity is tested on its own)."""
+ from core.inference import video_ltx2
+ monkeypatch.setattr(video_ltx2, "ltx23_source_file_verified", lambda path: True)
+
+
+def _ampere_or_hopper(monkeypatch, *, fp8):
+ """A CUDA bf16 card with the dense torchao path, whose explicit fp8 passes only on sm_89+: patched at the smoke
+ probe, under the real scheme selector, so the check under test is the one the normal precision path runs."""
+ from core.inference import diffusion_transformer_quant as tq, video as video_mod
+
+ monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
+ monkeypatch.setattr(tq, "dense_transformer_supported", lambda target: True)
+ monkeypatch.setattr(
+ tq,
+ "_scheme_supported",
+ lambda scheme, device, unproven_ok = False: scheme != "fp8" or fp8,
+ )
+ return types.SimpleNamespace(device = "cuda", dtype = "bfloat16")
+
+
[email protected]("fp8", [False, True], ids = ["sm80", "sm90"])
+def test_ltx23_hosted_fp8_seed_requires_fp8_on_the_card(fake_runtime, monkeypatch, fp8):
+ # Ampere runs torchao int8 but not fp8: the preflight must refuse before the eviction and 19 GB pull.
+ from core.inference import video as video_mod
+
+ target = _ampere_or_hopper(monkeypatch, fp8 = fp8)
+ fam = types.SimpleNamespace(name = "ltx-2")
+ name = "ltx-2.3-22b-distilled.safetensors"
+ repo = "Lightricks/LTX-2.3"
+ assert (
+ video_mod._ltx23_prequant_serves(
+ fam, "single_file", name, "fp8", target = target, memory_mode = None, checkpoint_repo = repo
+ )
+ is fp8
+ )
+ monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda **kw: target)
+ assert (
+ video_mod._ltx23_prequant_serves_on_card(
+ fam,
+ "single_file",
+ name,
+ "fp8",
+ memory_mode = None,
+ gpu_ordinal = None,
+ checkpoint_repo = repo,
+ )
+ is fp8
+ )
+ kwargs = dict(
+ model_kind = "single_file",
+ transformer_quant = "fp8",
+ checkpoint_filename = name,
+ checkpoint_repo = repo,
+ )
+ if fp8:
+ video_mod.assert_video_precision_available(fam, **kwargs)
+ else:
+ with pytest.raises(RuntimeError, match = "fp8"):
+ video_mod.assert_video_precision_available(fam, **kwargs)
+
+
+def _ltx23_verdict_store(monkeypatch, tmp_path):
+ """Point the persisted LTX-2.3 identity verdicts at a per-test file and count full hashes."""
+ from core.inference import video_ltx2
+
+ store = tmp_path / "verdicts" / "ltx23-source-verdicts.json"
+ monkeypatch.setattr(video_ltx2, "_ltx23_verdicts_path", lambda: store)
+ hashed: list = []
+ real_hash = video_ltx2.ltx23_source_sha256
+
+ def _counting(path):
+ hashed.append(str(path))
+ return real_hash(path)
+
+ monkeypatch.setattr(video_ltx2, "ltx23_source_sha256", _counting)
+ return store, hashed
+
+
+def _ltx23_synthetic_official(monkeypatch, path):
+ """Write a small safetensors-shaped file at *path* and pin the official identity (size and sha256) to it, so the
+ real check runs against bytes the test controls. Returns (size, the four 1 MiB windows a sampled check read)."""
+ import hashlib
+
+ from core.inference import video_ltx2
+
+ header = b'{"__metadata__":{"model_version":"2.3.0"}}'
+ blob = len(header).to_bytes(8, "little") + header + bytes(range(256)) * (4096 * 6)
+ path.write_bytes(blob)
+ sample = 1 << 20
+ data = 8 + len(header)
+ offsets = [data + (len(blob) - data) * k // 4 for k in (1, 2, 3)] + [len(blob) - sample]
+ monkeypatch.setattr(video_ltx2, "LTX23_PREQUANT_SOURCE_SIZE", len(blob))
+ monkeypatch.setattr(
+ video_ltx2, "LTX23_PREQUANT_SOURCE_SHA256", hashlib.sha256(blob).hexdigest()
+ )
+ return len(blob), offsets
+
+
+def test_ltx23_local_file_is_substituted_only_when_it_is_the_official_one(tmp_path, monkeypatch):
+ from core.inference import video_ltx2
+
+ _ltx23_verdict_store(monkeypatch, tmp_path)
+ name = "ltx-2.3-22b-distilled.safetensors"
+ official = tmp_path / "official"
+ official.mkdir()
+ size, offsets = _ltx23_synthetic_official(monkeypatch, official / name)
+ assert video_ltx2.ltx23_prequant_eligible(name, str(official))
+ assert video_ltx2.ltx23_prequant_eligible(name, str(official / name))
+ # One tensor byte changed, inside and outside any sampled window: not served.
+ outside = offsets[0] - 4096
+ assert all(not (off <= outside < off + (1 << 20)) for off in offsets)
+ for where in (offsets[1] + 7, outside, 12):
+ tuned = tmp_path / f"tuned_{where}"
+ tuned.mkdir()
+ blob = bytearray((official / name).read_bytes())
+ blob[where] ^= 0xFF
+ (tuned / name).write_bytes(bytes(blob))
+ assert not video_ltx2.ltx23_prequant_eligible(name, str(tuned)), where
+ assert not video_ltx2.ltx23_source_file_verified(tuned / name), where
+ short = tmp_path / "short"
+ short.mkdir()
+ (short / name).write_bytes(b"w")
+ assert not video_ltx2.ltx23_prequant_eligible(name, str(short))
+ assert not video_ltx2.ltx23_prequant_eligible(name, str(tmp_path / "missing"))
+ assert size == video_ltx2.LTX23_PREQUANT_SOURCE_SIZE
+
+
+def test_ltx23_local_verdict_is_hashed_once_and_invalidated_by_a_change(tmp_path, monkeypatch):
+ import os
+
+ from core.inference import video_ltx2
+
+ store, hashed = _ltx23_verdict_store(monkeypatch, tmp_path)
+ name = "ltx-2.3-22b-distilled.safetensors"
+ path = tmp_path / name
+ _ltx23_synthetic_official(monkeypatch, path)
+ assert video_ltx2.ltx23_source_file_verified(path)
+ assert video_ltx2.ltx23_source_file_verified(path)
+ assert len(hashed) == 1 and store.is_file()
+ blob = bytearray(path.read_bytes())
+ blob[-3] ^= 0xFF
+ stat = path.stat()
+ path.write_bytes(bytes(blob))
+ os.utime(path, ns = (stat.st_atime_ns, stat.st_mtime_ns + 1_000_000_000))
+ assert not video_ltx2.ltx23_source_file_verified(path)
+ assert not video_ltx2.ltx23_source_file_verified(path)
+ assert len(hashed) == 2
+ # Planning never hashes.
+ other = tmp_path / "other" / name
+ other.parent.mkdir()
+ other.write_bytes(bytes(blob))
+ with video_ltx2.ltx23_identity_without_hashing():
+ assert not video_ltx2.ltx23_source_file_verified(path)
+ assert video_ltx2.ltx23_source_file_verified(other)
+ assert len(hashed) == 2
+
+ def _unreadable(p):
+ raise OSError("EIO")
+
+ monkeypatch.setattr(video_ltx2, "ltx23_source_sha256", _unreadable)
+ assert not video_ltx2.ltx23_source_file_verified(other)
+ assert str(other.resolve()) not in video_ltx2._ltx23_read_verdicts()
+
+
+def test_ltx23_hub_pick_is_substituted_only_from_the_official_repo(tmp_path, monkeypatch):
+ from core.inference import video_ltx2
+
+ name = "ltx-2.3-22b-distilled.safetensors"
+ cached: dict = {"hit": None}
+ monkeypatch.setattr(video_ltx2, "_ltx23_hub_cached_file", lambda repo, filename: cached["hit"])
+ assert video_ltx2.ltx23_prequant_eligible(name, "Lightricks/LTX-2.3")
+ assert video_ltx2.ltx23_prequant_eligible(f"sub/{name}", "lightricks/ltx-2.3")
+ for repo in ("someone/LTX-2.3-finetune", "unsloth/LTX-2.3-GGUF", "Lightricks/LTX-2"):
+ assert not video_ltx2.ltx23_prequant_eligible(name, repo), repo
+ assert not video_ltx2.ltx23_prequant_eligible(name, None)
+ assert not video_ltx2.ltx23_prequant_eligible(
+ "ltx-2.3-22b-dev.safetensors", "Lightricks/LTX-2.3"
+ )
+ # Cached: an official-size content-addressed blob is the file, no hashing.
+ _, hashed = _ltx23_verdict_store(monkeypatch, tmp_path)
+ blobs = tmp_path / "models--Lightricks--LTX-2.3" / "blobs"
+ blobs.mkdir(parents = True)
+ import hub.utils.hf_cache_state as hf_cache_state
+
+ monkeypatch.setattr(hf_cache_state, "hf_cache_roots", lambda *a, **k: [tmp_path])
+ good = blobs / video_ltx2.LTX23_PREQUANT_SOURCE_SHA256
+ with open(good, "wb") as fh:
+ fh.truncate(video_ltx2.LTX23_PREQUANT_SOURCE_SIZE) # sparse
+ snap = tmp_path / "snap"
+ snap.mkdir()
+ (snap / name).symlink_to(good)
+ cached["hit"] = snap / name
+ assert video_ltx2.ltx23_source_file_verified(snap / name)
+ assert hashed == []
+ assert video_ltx2.ltx23_prequant_eligible(name, "Lightricks/LTX-2.3")
+ # A digest-named file outside the official repo's cache blobs is hashed like any local file.
+ elsewhere = tmp_path / "mine" / "models--Lightricks--LTX-2.3" / "blobs"
+ elsewhere.mkdir(parents = True)
+ fake = elsewhere / video_ltx2.LTX23_PREQUANT_SOURCE_SHA256
+ with open(fake, "wb") as fh:
+ fh.truncate(video_ltx2.LTX23_PREQUANT_SOURCE_SIZE)
+ (snap / name).unlink()
+ (snap / name).symlink_to(fake)
+ monkeypatch.setattr(
+ video_ltx2, "ltx23_source_sha256", lambda path: hashed.append(path) or "1" * 64
+ )
+ assert not video_ltx2.ltx23_source_file_verified(snap / name)
+ assert hashed
+ (snap / name).unlink()
+ (snap / name).symlink_to(good)
+ bad = blobs / ("0" * 64)
+ with open(bad, "wb") as fh:
+ fh.truncate(video_ltx2.LTX23_PREQUANT_SOURCE_SIZE) # right size, wrong content (zeros)
+ (snap / name).unlink()
+ (snap / name).symlink_to(bad)
+ monkeypatch.setattr(video_ltx2, "ltx23_source_sha256", lambda path: "0" * 64)
+ assert not video_ltx2.ltx23_prequant_eligible(name, "Lightricks/LTX-2.3")
+
+
+def test_ltx23_unverified_same_name_pick_is_refused_not_substituted(
+ fake_runtime, tmp_path, monkeypatch
+):
+ from core.inference import video as video_mod, video_ltx2
+
+ target = _ampere_or_hopper(monkeypatch, fp8 = True)
+ monkeypatch.setattr(video_mod, "resolve_diffusion_device_target", lambda **kw: target)
+ monkeypatch.setattr(video_ltx2, "_ltx23_hub_cached_file", lambda repo, filename: None)
+ fam = types.SimpleNamespace(name = "ltx-2")
+ name = "ltx-2.3-22b-distilled.safetensors"
+ local = tmp_path / "local"
+ local.mkdir()
+ (local / name).write_bytes(b"a fine-tuned DiT under the official name")
+
+ def _check(repo):
+ video_mod.assert_video_precision_available(
+ fam,
+ model_kind = "single_file",
+ transformer_quant = "fp8",
+ checkpoint_filename = name,
+ checkpoint_repo = repo,
+ )
+
+ def _serves(repo):
+ return video_mod._ltx23_prequant_serves(
+ fam, "single_file", name, "fp8", target = target, memory_mode = None, checkpoint_repo = repo
+ )
+
+ _check("Lightricks/LTX-2.3")
+ assert _serves("Lightricks/LTX-2.3")
+ for repo in (str(local), "someone/LTX-2.3-finetune"):
+ assert not _serves(repo), repo
+ with pytest.raises(RuntimeError, match = "could not be verified"):
+ _check(repo)
+
+
+def test_ltx23_prequant_loader_keeps_an_unverified_files_own_dit(tmp_path, monkeypatch):
+ from core.inference import diffusion_prequant, video_ltx2
+
+ resolved: list = []
+ monkeypatch.setattr(
+ diffusion_prequant, "resolve_prequant_source", lambda *a, **k: resolved.append(1)
+ )
+ path = tmp_path / "ltx-2.3-22b-distilled.safetensors"
+ path.write_bytes(b"w")
+ fam = types.SimpleNamespace(name = "ltx-2")
+ assert (
+ video_ltx2.load_ltx23_prequant_transformer(
+ fam, "fp8", path, config_repo = "Lightricks/LTX-2", device = "cuda", dtype = None
+ )
+ is None
+ )
+ assert resolved == []
+
+
+def _load_ltx23_single_file_fp8(
+ tmp_path,
+ monkeypatch,
+ seeded,
+ memory_mode = None,
+):
+ from core.inference import video as video_mod, video_ltx2
+
+ monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: True)
+ _ltx23_fp8_card(monkeypatch)
+ monkeypatch.setattr(video_ltx2, "is_ltx23_checkpoint", lambda path: True)
+ _ltx23_official_file(monkeypatch)
+ calls: dict = {}
+
+ def _prequant(fam, scheme, checkpoint_path, **kwargs):
+ calls["prequant"] = (scheme, str(checkpoint_path), kwargs.get("config_repo"))
+ return seeded
+
+ def _assemble(checkpoint_path, **kwargs):
+ calls["override"] = kwargs.get("transformer_override")
+ return _FakePipeline.from_pretrained("Lightricks/LTX-2")
+
+ monkeypatch.setattr(video_ltx2, "load_ltx23_prequant_transformer", _prequant)
+ monkeypatch.setattr(video_ltx2, "load_ltx23_pipeline", _assemble)
+ (tmp_path / "ltx-2.3-22b-distilled.safetensors").write_bytes(b"w")
+ backend = VideoBackend()
+ backend.load_pipeline(
+ str(tmp_path),
+ gguf_filename = "ltx-2.3-22b-distilled.safetensors",
+ base_repo = "Lightricks/LTX-2",
+ family_override = "ltx-2",
+ transformer_quant = "fp8",
+ memory_mode = memory_mode,
+ )
+ return backend, calls
+
+
+def test_ltx23_single_file_fp8_seeds_the_hosted_denoiser(fake_runtime, tmp_path, monkeypatch):
+ seeded_dit = object()
+ source = types.SimpleNamespace(
+ location = "unsloth/LTX-2.3-FP8", kind = "repo", filename = "LTX-2.3-FP8.pt"
+ )
+ backend, calls = _load_ltx23_single_file_fp8(tmp_path, monkeypatch, (seeded_dit, source))
+ assert calls["prequant"][0] == "fp8" and calls["prequant"][2] == "Lightricks/LTX-2"
+ assert calls["override"] is seeded_dit
+ status = backend.status()
+ assert status["transformer_quant"] == "fp8"
+ assert "unsloth/LTX-2.3-FP8" in str(status["resolved"]["transformer_quant"])
+ backend.unload()
+
+
+def test_ltx23_single_file_fp8_without_a_checkpoint_is_refused(fake_runtime, tmp_path, monkeypatch):
+ # Refused before the dense assembly loads the 44 GB bf16 DiT.
+ from core.inference import video_ltx2
+
+ assembled = []
+ monkeypatch.setattr(
+ video_ltx2, "load_ltx23_pipeline", lambda *a, **k: assembled.append(1), raising = False
+ )
+ with pytest.raises(RuntimeError, match = "unsloth/LTX-2.3-FP8"):
+ _load_ltx23_single_file_fp8(tmp_path, monkeypatch, None)
+
+
+def test_ltx23_hosted_fp8_fallback_rechecks_unified_memory(fake_runtime, tmp_path, monkeypatch):
+ from core.inference import video as video_mod
+
+ priced = _ltx23_fp8_plan_at(monkeypatch, fits_mib = 10**9)
+ checked: list = []
+ monkeypatch.setattr(
+ video_mod,
+ "raise_on_unified_memory_shortfall",
+ lambda plan, **k: checked.append(len(priced)),
+ )
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
+ backend, calls = _load_ltx23_single_file_fp8(tmp_path, monkeypatch, None)
+ assert calls["override"] is None
+ assert priced[-1] > priced[0]
+ assert checked and checked[-1] == len(priced)
+ backend.unload()
+
+
+def _ltx23_fp8_plan_at(monkeypatch, fits_mib):
+ """A card where a DiT priced above ``fits_mib`` (the plan's model size less its companions) offloads; returns the
+ DiT sizes the plans were priced at."""
+ import dataclasses
+
+ from core.inference import video as video_mod
+
+ monkeypatch.setattr(video_mod, "estimate_safetensors_dense_mib", lambda size_mib: 44_000)
+ real_plan = video_mod.plan_diffusion_memory
+ priced: list = []
+
+ def _plan(**kwargs):
+ planned = real_plan(**kwargs)
+ dit_mib = (kwargs.get("model_dense_mib") or 0) - (kwargs.get("companion_dense_mib") or 0)
+ priced.append(dit_mib)
+ if dit_mib > fits_mib:
+ return dataclasses.replace(planned, offload_policy = "model")
+ return dataclasses.replace(planned, offload_policy = "none")
+
+ monkeypatch.setattr(video_mod, "plan_diffusion_memory", _plan)
+ return priced
+
+
+def test_ltx23_single_file_fp8_is_planned_at_the_hosted_dit_size(
+ fake_runtime, tmp_path, monkeypatch
+):
+ priced = _ltx23_fp8_plan_at(monkeypatch, fits_mib = 30_000)
+ seeded_dit = object()
+ source = types.SimpleNamespace(
+ location = "unsloth/LTX-2.3-FP8", kind = "repo", filename = "LTX-2.3-FP8.pt"
+ )
+ backend, calls = _load_ltx23_single_file_fp8(tmp_path, monkeypatch, (seeded_dit, source))
+ assert calls["override"] is seeded_dit
+ assert priced and all(mib < 30_000 for mib in priced)
+ assert backend.status()["transformer_quant"] == "fp8"
+ backend.unload()
+
+
+def test_ltx23_single_file_fp8_is_priced_at_the_hosted_artifact_not_the_scaled_file(
+ fake_runtime, tmp_path, monkeypatch
+):
+ # Priced at the hosted DiT (~18,175 MiB), not file x fp8 factor (~24,200 MiB): budget between the two.
+ priced = _ltx23_fp8_plan_at(monkeypatch, fits_mib = 20_000)
+ seeded_dit = object()
+ source = types.SimpleNamespace(
+ location = "unsloth/LTX-2.3-FP8", kind = "repo", filename = "LTX-2.3-FP8.pt"
+ )
+ backend, calls = _load_ltx23_single_file_fp8(tmp_path, monkeypatch, (seeded_dit, source))
+ assert calls["override"] is seeded_dit
+ assert priced and all(18_000 < mib < 20_000 for mib in priced), priced
+ backend.unload()
+
+
+def test_ltx23_single_file_fp8_just_under_the_hosted_artifact_still_offloads(
+ fake_runtime, tmp_path, monkeypatch
+):
+ _ltx23_fp8_plan_at(monkeypatch, fits_mib = 18_000)
+ with pytest.raises(RuntimeError, match = "offloads the DiT even at fp8 size"):
+ _load_ltx23_single_file_fp8(tmp_path, monkeypatch, (object(), None))
+
+
+def test_ltx23_single_file_fp8_that_still_offloads_is_refused_before_the_assembly(
+ fake_runtime, tmp_path, monkeypatch
+):
+ _ltx23_fp8_plan_at(monkeypatch, fits_mib = 1_000)
+ with pytest.raises(RuntimeError, match = "offloads the DiT even at fp8 size"):
+ _load_ltx23_single_file_fp8(tmp_path, monkeypatch, (object(), None))
+
+
+def test_ltx2_distilled_detection_follows_the_selected_checkpoint():
+ # The selected file decides before its repo / folder.
+ from core.inference.video_families import default_video_generation_params
+ from core.inference.video_ltx2 import ltx2_distilled_ids
+
+ cases = [
+ (("ltx-2.3-22b-distilled.safetensors", "Lightricks/LTX-2.3", "Lightricks/LTX-2"), True),
+ (
+ ("distilled-1.1/ltx-2.3-22b-distilled-1.1-Q4_K_M.gguf", "unsloth/LTX-2.3-GGUF", None),
+ True,
+ ),
+ ((None, "someone/LTX-2.3-distilled-diffusers", None), True),
+ (("model.safetensors", "/models/ltx-2.3-distilled", "Lightricks/LTX-2"), True),
+ (
+ ("ltx-2.3-22b-dev.safetensors", "/models/ltx-2.3-distilled-mirror", "Lightricks/LTX-2"),
+ False,
+ ),
+ (("ltx-2.3-22b-dev-Q4_K_M.gguf", "me/ltx-distilled-and-dev", None), False),
+ ((None, "Lightricks/LTX-2", None), False),
+ (("ltx-2-19b-undistilled.safetensors", "org/ltx", None), False),
+ ]
+ for ids, distilled in cases:
+ assert ltx2_distilled_ids(*ids) is distilled, ids
+ assert (default_video_generation_params(*ids) == (8, 1.0)) is distilled, ids
+
+
+def test_download_plan_stages_the_hosted_fp8_dit_for_the_ltx23_distilled_single_file(monkeypatch):
+ # The hosted DiT's repo is staged by the plan, not pulled inline by the load.
+ _plan_api(
+ monkeypatch,
+ {
+ "Lightricks/LTX-2.3": [
+ _PlanSibling("ltx-2.3-22b-distilled.safetensors", 46_000_000_000),
+ _PlanSibling("ltx-2.3-22b-dev.safetensors", 46_000_000_000),
+ ],
+ "unsloth/LTX-2.3-GGUF": _LTX23_REPO_SIBLINGS,
+ "unsloth/LTX-2.3-FP8": [
+ _PlanSibling("LTX-2.3-FP8.pt", 19_057_628_489),
+ _PlanSibling("LTX-2.3-INT8.pt", 19_000_000_000),
+ ],
+ "Lightricks/LTX-2": _LTX_BASE_SIBLINGS,
+ },
+ )
+ from core.inference import video as video_mod
+
+ supported = [True]
+ monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: supported[0])
+ _ltx23_fp8_card(monkeypatch)
+
+ def _plan(
+ filename,
+ quant,
+ memory_mode = None,
+ ):
+ return VideoBackend().download_plan(
+ "Lightricks/LTX-2.3",
+ gguf_filename = filename,
+ family_override = "ltx-2",
+ transformer_quant = quant,
+ memory_mode = memory_mode,
+ )
+
+ by_repo = {
+ e["repo_id"]: e for e in _plan("ltx-2.3-22b-distilled.safetensors", "fp8")["entries"]
+ }
+ assert by_repo["unsloth/LTX-2.3-FP8"]["files"] == ["LTX-2.3-FP8.pt"]
+ assert "ltx-2.3-22b-distilled.safetensors" in by_repo["Lightricks/LTX-2.3"]["files"]
+ for filename, quant in (
+ ("ltx-2.3-22b-distilled.safetensors", None),
+ ("ltx-2.3-22b-distilled.safetensors", "off"),
+ ("ltx-2.3-22b-dev.safetensors", "fp8"),
+ ):
+ repos = {e["repo_id"] for e in _plan(filename, quant)["entries"]}
+ assert "unsloth/LTX-2.3-FP8" not in repos, (filename, quant)
+ for memory_mode in ("balanced", "low_vram"):
+ repos = {
+ e["repo_id"]
+ for e in _plan("ltx-2.3-22b-distilled.safetensors", "fp8", memory_mode)["entries"]
+ }
+ assert "unsloth/LTX-2.3-FP8" not in repos, memory_mode
+ supported[0] = False
+ repos = {e["repo_id"] for e in _plan("ltx-2.3-22b-distilled.safetensors", "fp8")["entries"]}
+ assert "unsloth/LTX-2.3-FP8" not in repos
+
+
[email protected]("fp8", [False, True], ids = ["sm80", "sm90"])
+def test_download_plan_stages_the_hosted_fp8_dit_only_on_an_fp8_card(monkeypatch, fp8):
+ _plan_api(
+ monkeypatch,
+ {
+ "Lightricks/LTX-2.3": [
+ _PlanSibling("ltx-2.3-22b-distilled.safetensors", 46_149_345_038)
+ ],
+ "unsloth/LTX-2.3-GGUF": _LTX23_REPO_SIBLINGS,
+ "unsloth/LTX-2.3-FP8": [_PlanSibling("LTX-2.3-FP8.pt", 19_057_628_489)],
+ "Lightricks/LTX-2": _LTX_BASE_SIBLINGS,
+ },
+ )
+ _ampere_or_hopper(monkeypatch, fp8 = fp8)
+ plan = VideoBackend().download_plan(
+ "Lightricks/LTX-2.3",
+ gguf_filename = "ltx-2.3-22b-distilled.safetensors",
+ family_override = "ltx-2",
+ transformer_quant = "fp8",
+ )
+ assert ("unsloth/LTX-2.3-FP8" in {e["repo_id"] for e in plan["entries"]}) is fp8
+
+
+class _StopAfterPrefetch(Exception):
+ pass
+
+
+def test_the_ltx23_fp8_load_prefetches_the_hosted_dit_under_its_cancel_event(tmp_path, monkeypatch):
+ from core.inference import video as video_mod, video_ltx2
+
+ (tmp_path / "ltx-2.3-22b-distilled.safetensors").write_bytes(b"w")
+ backend = VideoBackend()
+ fetched: list = []
+
+ def _fetch(
+ sources,
+ hf_token,
+ *,
+ cancel_event = None,
+ local_files_only = False,
+ ):
+ fetched.append(([src.location for src in sources], cancel_event, local_files_only))
+
+ def _stop(*_a, **_k):
+ raise _StopAfterPrefetch()
+
+ monkeypatch.setattr(video_ltx2, "is_ltx23_checkpoint", lambda path: True)
+ _ltx23_official_file(monkeypatch)
+ supported = [True]
+ monkeypatch.setattr(video_mod, "dense_transformer_supported", lambda target: supported[0])
+ _ltx23_fp8_card(monkeypatch)
+ monkeypatch.setattr(backend, "_fetch_denoiser_prequant", _fetch)
+ monkeypatch.setattr(backend, "_estimate_download_bytes", lambda *a, **k: None)
+ monkeypatch.setattr(backend, "_predownload_base", _stop)
+ monkeypatch.setattr(video_mod, "clear_gpu_cache", lambda: None)
+ cancel = threading.Event()
+ backend._load_token = 7
+ backend._loading = types.SimpleNamespace(asset_repos = (), base_repo = None, expected_bytes = None)
+ backend._run_load(
+ repo_id = str(tmp_path),
+ gguf_filename = "ltx-2.3-22b-distilled.safetensors",
+ family_override = "ltx-2",
+ transformer_quant = "fp8",
+ local_files_only = True,
+ _load_token = 7,
+ _cancel_event = cancel,
+ )
+ assert fetched == [(["unsloth/LTX-2.3-FP8"], cancel, True)]
+ fetched.clear()
+ backend._load_token = 8
+ backend._run_load(
+ repo_id = str(tmp_path),
+ gguf_filename = "ltx-2.3-22b-distilled.safetensors",
+ family_override = "ltx-2",
+ local_files_only = True,
+ _load_token = 8,
+ _cancel_event = cancel,
+ )
+ assert fetched == []
+ for token, memory_mode, card_ok in (
+ (9, "balanced", True),
+ (10, "low_vram", True),
+ (11, None, False),
+ ):
+ supported[0] = card_ok
+ backend._load_token = token
+ backend._run_load(
+ repo_id = str(tmp_path),
+ gguf_filename = "ltx-2.3-22b-distilled.safetensors",
+ family_override = "ltx-2",
+ transformer_quant = "fp8",
+ memory_mode = memory_mode,
+ local_files_only = True,
+ _load_token = token,
+ _cancel_event = cancel,
+ )
+ assert fetched == [], (memory_mode, card_ok)
+
+
+def test_ltx23_fp8_under_a_forced_offload_prices_and_loads_the_bf16_dit(
+ fake_runtime, tmp_path, monkeypatch
+):
+ # balanced offloads regardless of size, so fallback runs bf16 and never seeds.
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
+ priced = _ltx23_fp8_plan_at(monkeypatch, fits_mib = 100_000)
+ backend, calls = _load_ltx23_single_file_fp8(
+ tmp_path, monkeypatch, (object(), None), memory_mode = "balanced"
+ )
+ assert "prequant" not in calls and calls["override"] is None
+ assert priced and all(mib >= 40_000 for mib in priced)
+ backend.unload()
+
+
+def test_ltx23_selective_read_skips_the_dit(tmp_path):
+ torch = pytest.importorskip("torch")
+ safetensors_torch = pytest.importorskip("safetensors.torch")
+ if not hasattr(torch, "zeros"):
+ pytest.skip("real torch required")
+ from core.inference.video_ltx2 import _load_checkpoint_without_dit, _split_checkpoint
+
+ state = {
+ "model.diffusion_model.transformer_blocks.0.attn1.to_q.weight": torch.zeros(2, 2),
+ "model.diffusion_model.video_embeddings_connector.x": torch.ones(1),
+ "vae.decoder.conv_in.weight": torch.ones(2),
+ "audio_vae.decoder.w": torch.ones(3),
+ "vocoder.w": torch.ones(4),
+ }
+ path = tmp_path / "ltx.safetensors"
+ safetensors_torch.save_file(state, str(path))
+ partial = _load_checkpoint_without_dit(path)
+ assert "model.diffusion_model.transformer_blocks.0.attn1.to_q.weight" not in partial
+ groups = _split_checkpoint(partial)
+ assert groups["dit"] == {} and set(groups["connectors"]) == {"video_embeddings_connector.x"}
+ assert list(groups["vae"]) == ["decoder.conv_in.weight"] and list(groups["vocoder"]) == ["w"]
+ assert _load_checkpoint_without_dit(tmp_path / "ltx.gguf") is None
+
+
+def test_ltx2_regional_compile_is_static(fake_runtime, tmp_path, monkeypatch):
+ from core.inference.diffusion_speed import compile_dynamic
+
+ dit = types.SimpleNamespace()
+ monkeypatch.setattr(_FakePipe, "transformer", dit, raising = False)
+ _load_ltx23_from_dir(tmp_path)
+ assert getattr(dit, "_unsloth_compile_static", False) is True
+ assert compile_dynamic(dit, True) is False
+ assert compile_dynamic(types.SimpleNamespace(), True) is True
+
+
+def test_ltx2_compiled_load_installs_the_stg_adapter(fake_runtime, tmp_path, monkeypatch):
+ from core.inference import video as video_mod, video_ltx2
+
+ dit = types.SimpleNamespace()
+ monkeypatch.setattr(_FakePipe, "transformer", dit, raising = False)
+ adapted = []
+ monkeypatch.setattr(video_ltx2, "install_stg_compile_adapter", lambda t: adapted.append(t) or 0)
+ for compiled, expected in ((True, [dit]), (False, [])):
+ adapted.clear()
+ monkeypatch.setattr(
+ video_mod, "apply_speed_optims", lambda *a, _c = compiled, **k: {"compiled": _c}
+ )
+ _load_ltx23_from_dir(tmp_path)
+ assert adapted == expected
+
+
+def test_ltx2_load_turns_cudnn_benchmark_back_off(fake_runtime, tmp_path, monkeypatch):
+ from core.inference import video as video_mod, video_ltx2
+
+ monkeypatch.setattr(
+ video_mod,
+ "apply_speed_optims",
+ lambda *a, **k: {"cudnn_benchmark": True, "compiled": False},
+ )
+ calls = []
+ monkeypatch.setattr(video_ltx2, "disable_cudnn_benchmark", lambda: calls.append(1) or True)
+ backend = _load_ltx23_from_dir(tmp_path)
+ assert calls == [1]
+ assert "cudnn_benchmark" not in backend.status()["speed_optims"]
diff --git a/studio/backend/tests/test_video_prequant.py b/studio/backend/tests/test_video_prequant.py
index 1a881e89a80..cdd64d4036b 100644
--- a/studio/backend/tests/test_video_prequant.py
+++ b/studio/backend/tests/test_video_prequant.py
@@ -1385,7 +1385,7 @@ def test_auto_is_handed_the_probe_that_lets_it_reach_a_prequant_only_scheme(monk
assert probe("int8") is False
half = _fam(is_moe = True, prequant_repos = (("nvfp4", "org/x"),))
assert _video_auto(monkeypatch, scheme = "nvfp4", fam = half) is None
- assert _video_auto.calls[-1]["has_prequant"]("nvfp4") is False
+ assert _video_auto.calls == []
def test_speed_off_and_the_modular_workflow_are_never_seeded_here(monkeypatch):
diff --git a/studio/backend/tests/test_video_routes.py b/studio/backend/tests/test_video_routes.py
index 3a833892133..86cdeb66525 100644
--- a/studio/backend/tests/test_video_routes.py
+++ b/studio/backend/tests/test_video_routes.py
@@ -1341,6 +1341,165 @@ def test_video_download_plan_forwards_the_denoiser_policy(client, monkeypatch):
assert seen["transformer_quant"] == "int8"
+def test_video_download_plan_does_not_stage_the_hosted_fp8_dit_for_an_offloaded_load(
+ client, monkeypatch
+):
+ # Precision fallback under balanced / low_vram loads bf16, so the FP8 artifact must not be staged (needs the route to forward the policy).
+ import types
+
+ import core.inference.diffusion_device as devmod
+ from core.inference.diffusion import DiffusionBackend
+
+ class _Sibling:
+ def __init__(self, rfilename, size):
+ self.rfilename = rfilename
+ self.size = size
+
+ repos = {
+ "Lightricks/LTX-2.3": [
+ _Sibling("ltx-2.3-22b-distilled.safetensors", 46_000_000_000),
+ _Sibling("ltx-2.3-22b-dev.safetensors", 46_000_000_000),
+ ],
+ "unsloth/LTX-2.3-FP8": [_Sibling("LTX-2.3-FP8.pt", 19_057_628_489)],
+ "unsloth/LTX-2.3-GGUF": [
+ _Sibling("vae/ltx-2.3-22b-distilled_video_vae.safetensors", 2_400_000_000),
+ _Sibling("vae/ltx-2.3-22b-distilled_audio_vae.safetensors", 200_000_000),
+ _Sibling(
+ "text_encoders/ltx-2.3-22b-distilled_embeddings_connectors.safetensors", 900_000_000
+ ),
+ ],
+ "Lightricks/LTX-2": [
+ _Sibling("model_index.json", 1000),
+ _Sibling("tokenizer/tokenizer.json", 5_000_000),
+ _Sibling("text_encoder/model-00001-of-00005.safetensors", 10_000_000_000),
+ _Sibling("transformer/diffusion_pytorch_model.safetensors", 37_800_000_000),
+ ],
+ }
+
+ class _Api:
+ def model_info(
+ self,
+ repo_id,
+ files_metadata = False,
+ token = None,
+ ):
+ return types.SimpleNamespace(siblings = repos[repo_id])
+
+ monkeypatch.setattr("huggingface_hub.HfApi", lambda *a, **k: _Api())
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_hub_file_is_cached",
+ staticmethod(lambda repo_id, filename, revision = None, expected_size = None, **kwargs: False),
+ )
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_ALLOW_PRECISION_FALLBACK", "1")
+ monkeypatch.setattr(
+ devmod, "resolve_diffusion_device_target", lambda **kw: types.SimpleNamespace(device = "cuda")
+ )
+ monkeypatch.setattr(video_module, "dense_transformer_supported", lambda target: True)
+ monkeypatch.setattr(
+ video_module,
+ "select_transformer_quant_scheme",
+ lambda target, mode, family = None, **_k: "fp8",
+ )
+ monkeypatch.setattr(
+ video_module, "assert_video_precision_available", lambda fam, **kw: None, raising = False
+ )
+ monkeypatch.setattr(video_routes, "_training_is_active", lambda: False)
+
+ def _staged(memory_mode):
+ body = {
+ "model_path": "Lightricks/LTX-2.3",
+ "gguf_filename": "ltx-2.3-22b-distilled.safetensors",
+ "model_kind": "single_file",
+ "family_override": "ltx-2",
+ "transformer_quant": "fp8",
+ }
+ if memory_mode is not None:
+ body["memory_mode"] = memory_mode
+ resp = client.post("/api/inference/video/download-plan", json = body)
+ assert resp.status_code == 200, resp.text
+ return {e["repo_id"] for e in resp.json()["entries"]}
+
+ assert "unsloth/LTX-2.3-FP8" in _staged(None)
+ assert "unsloth/LTX-2.3-FP8" in _staged("fast")
+ for memory_mode in ("balanced", "low_vram"):
+ assert "unsloth/LTX-2.3-FP8" not in _staged(memory_mode), memory_mode
+
+
+def test_video_download_plan_does_not_probe_fp8_while_training(client, monkeypatch):
+ # Trainer holds the GPU: the planner reads the cached verdict, never spawns the smoke probe.
+ import types
+
+ import core.inference.diffusion_device as devmod
+ import core.inference.diffusion_transformer_quant as tq
+ from core.inference.diffusion import DiffusionBackend
+
+ class _Sibling:
+ def __init__(self, rfilename, size):
+ self.rfilename = rfilename
+ self.size = size
+
+ repos = {
+ "Lightricks/LTX-2.3": [_Sibling("ltx-2.3-22b-distilled.safetensors", 46_000_000_000)],
+ "unsloth/LTX-2.3-FP8": [_Sibling("LTX-2.3-FP8.pt", 19_057_628_489)],
+ "unsloth/LTX-2.3-GGUF": [],
+ "Lightricks/LTX-2": [_Sibling("model_index.json", 1000)],
+ }
+
+ class _Api:
+ def model_info(
+ self,
+ repo_id,
+ files_metadata = False,
+ token = None,
+ ):
+ return types.SimpleNamespace(siblings = repos[repo_id])
+
+ monkeypatch.setattr("huggingface_hub.HfApi", lambda *a, **k: _Api())
+ monkeypatch.setattr(
+ DiffusionBackend,
+ "_hub_file_is_cached",
+ staticmethod(lambda repo_id, filename, revision = None, expected_size = None, **kwargs: False),
+ )
+ monkeypatch.setattr(
+ devmod, "resolve_diffusion_device_target", lambda **kw: types.SimpleNamespace(device = "cuda")
+ )
+ monkeypatch.setattr(video_module, "dense_transformer_supported", lambda target: True)
+ monkeypatch.setattr(tq, "dense_transformer_supported", lambda target: True)
+ monkeypatch.setattr(tq, "_smoke_cache_device_key", lambda device: "cuda:0")
+ monkeypatch.setattr(
+ video_module,
+ "select_transformer_quant_scheme",
+ lambda *a, **k: pytest.fail("the plan probed the fp8 scheme while training"),
+ )
+ monkeypatch.setattr(
+ video_module,
+ "assert_video_precision_available",
+ lambda *a, **k: pytest.fail("the precision gate ran while training"),
+ raising = False,
+ )
+ monkeypatch.setattr(video_routes, "_training_is_active", lambda: True)
+ monkeypatch.setattr(tq, "_SMOKE_CACHE", {})
+
+ def _staged():
+ resp = client.post(
+ "/api/inference/video/download-plan",
+ json = {
+ "model_path": "Lightricks/LTX-2.3",
+ "gguf_filename": "ltx-2.3-22b-distilled.safetensors",
+ "model_kind": "single_file",
+ "family_override": "ltx-2",
+ "transformer_quant": "fp8",
+ },
+ )
+ assert resp.status_code == 200, resp.text
+ return {e["repo_id"] for e in resp.json()["entries"]}
+
+ assert "unsloth/LTX-2.3-FP8" in _staged()
+ tq._SMOKE_CACHE[("fp8", "cuda:0")] = False
+ assert "unsloth/LTX-2.3-FP8" not in _staged()
+
+
def test_video_download_plan_forwards_the_h3_partition(client, monkeypatch):
# h3_task decides WHICH of the two 66.28 GB MiniMax-H3 denoiser folders is staged. It was
# swallowed by **load_kwargs, so a ref2va plan staged the fl2va partition and the one the load