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: close the LTX-2.5 two-stage speed gaps in a shared multi-stage layer (#13508)

Daniel Han0f7bdbb62386
diff --git a/studio/backend/core/inference/diffusion_multistage.py b/studio/backend/core/inference/diffusion_multistage.py
new file mode 100644
index 00000000000..8320ff83e2b
--- /dev/null
+++ b/studio/backend/core/inference/diffusion_multistage.py
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Family-agnostic helpers for a render that calls its pipeline more than once per request (a multi-stage recipe:
+LTX-2.5's half-size stage, latent upsample, full-size stage). Each helper keys on what the pipeline object carries
+(its offload hook list, its denoiser, its ``encode_prompt``), never on a family name, so any multi-stage render can wrap
+its calls in them.
+
+``encode_once``: every stage encodes the same prompt; the later stages take the first one's device tensors.
+``hold_denoiser_between_calls``: under model CPU offload a pipeline call ends by offloading every component, so the
+next stage would upload the whole denoiser again; hold it when the work in between still fits beside it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any, Iterable
+
+# Headroom kept free beside a held denoiser while the modules between two calls run next to it.
+HOLD_MARGIN_BYTES = 2 * 2**30
+
+
+def module_bytes(module: Any) -> int:
+ try:
+ return sum(p.numel() * p.element_size() for p in module.parameters())
+ except Exception: # noqa: BLE001 -- not a module (tests / absent component)
+ return 0
+
+
+def _denoisers(pipe: Any) -> list:
+ try:
+ from .diffusion_cuda_graph import _denoiser_modules
+
+ return list(_denoiser_modules(pipe))
+ except Exception: # noqa: BLE001 -- no denoiser found: nothing to hold
+ return []
+
+
+def companions_fit_beside_denoiser(pipe: Any, companions: Iterable[Any]) -> bool:
+ """Whether the denoiser a call onloaded can stay while ``companions`` (the modules that run before it is needed
+ again) are onloaded beside it: free memory plus the allocator's idle cache covers them with a margin."""
+ try:
+ import torch
+
+ dits = _denoisers(pipe)
+ param = next(dits[0].parameters()) if dits else None
+ if param is None or param.device.type != "cuda":
+ return False
+ free, _total = torch.cuda.mem_get_info(param.device)
+ idle = torch.cuda.memory_reserved(param.device) - torch.cuda.memory_allocated(param.device)
+ except Exception: # noqa: BLE001 -- no CUDA / no denoiser: keep the stock offload
+ return False
+ need = sum(module_bytes(m) for m in companions if m is not None) + HOLD_MARGIN_BYTES
+ return free + max(0, idle) >= need
+
+
+def hold_denoiser_between_calls(pipe: Any, runner: Any, companions: Iterable[Any] = ()):
+ """Around a pipeline call that another call of the same request follows. ``pipe`` owns the offload hooks
+ (``enable_model_cpu_offload``); ``runner`` is the pipeline actually called (``pipe`` or a pipeline derived from
+ its modules, which has no hook list of its own and so never offloads at its end). Without hooks: a no-op.
+
+ runner is pipe: its end-of-call ``maybe_free_model_hooks`` keeps the stateful-cache reset and skips the offload
+ when the companions fit. Derived runner: pipe's hooks are freed after the call only when they do not fit."""
+ companions = tuple(companions)
+ if not getattr(pipe, "_all_hooks", None):
+ yield
+ return
+ if runner is not pipe:
+ try:
+ yield
+ finally:
+ if not companions_fit_beside_denoiser(pipe, companions):
+ pipe.maybe_free_model_hooks()
+ return
+ original = pipe.maybe_free_model_hooks
+ had_own = "maybe_free_model_hooks" in getattr(pipe, "__dict__", {})
+
+ def at_call_end() -> None:
+ if not companions_fit_beside_denoiser(pipe, companions):
+ original()
+ return
+ for component in getattr(pipe, "components", {}).values():
+ if hasattr(component, "_reset_stateful_cache"):
+ component._reset_stateful_cache()
+
+ pipe.maybe_free_model_hooks = at_call_end
+ try:
+ yield
+ finally:
+ if had_own:
+ pipe.maybe_free_model_hooks = original
+ else:
+ del pipe.maybe_free_model_hooks
+
+
+def encode_once(runner: Any):
+ """For the span of one request: identical keyword-only ``encode_prompt`` calls (what the diffusers pipelines make)
+ after the first get a device copy of the first one's outputs (taken right after it, so its in-place edits never
+ reach them) instead of encoding or uploading again. Later calls share that copy: diffusers' pipelines build new
+ tensors from it (cat / repeat) and never write it. Calls with tensors or positional arguments pass through.
+ Restores the attribute it found."""
+ encode = getattr(runner, "encode_prompt", None)
+ if not callable(encode):
+ yield
+ return
+ had_own = "encode_prompt" in getattr(runner, "__dict__", {})
+ memo: dict[str, Any] = {}
+
+ def encode_prompt(*args: Any, **kwargs: Any) -> Any:
+ import torch
+
+ if args or any(isinstance(v, torch.Tensor) for v in kwargs.values()):
+ return encode(*args, **kwargs)
+ key = repr(sorted((k, repr(v)) for k, v in kwargs.items()))
+ if key in memo:
+ return memo[key]
+ out = encode(**kwargs)
+ if isinstance(out, tuple):
+ # A device copy: the first call may edit its own tensors in place.
+ memo[key] = tuple(t.clone() if isinstance(t, torch.Tensor) else t for t in out)
+ return out
+
+ runner.encode_prompt = encode_prompt
+ try:
+ yield
+ finally:
+ memo.clear()
+ if had_own:
+ runner.encode_prompt = encode
+ else:
+ try:
+ del runner.encode_prompt
+ except AttributeError:
+ pass
diff --git a/studio/backend/core/inference/diffusion_preview.py b/studio/backend/core/inference/diffusion_preview.py
index 4f1a8537be0..8064c534886 100644
--- a/studio/backend/core/inference/diffusion_preview.py
+++ b/studio/backend/core/inference/diffusion_preview.py
@@ -228,6 +228,7 @@ class LatentPreviewer:
self.spec = spec
self.height, self.width = int(height), int(width)
+ self._alloc_size = (self.height, self.width)
self.device = torch.device(device)
self.max_side = int(max_side)
self.min_interval_s = float(min_interval_s)
@@ -315,6 +316,20 @@ class LatentPreviewer:
self.failed = True
logger.debug("diffusion.preview: stopped after an error (%s)", exc)
+ def set_render_size(self, height: int, width: int) -> None:
+ """The size the NEXT steps denoise at, for a multi-stage render (LTX-2.5 runs its first stage at half size):
+ packed tokens take their grid from it. Never above the size the slots were sized for; a new stage also drops
+ the previous step, whose grid no longer matches."""
+ height, width = int(height), int(width)
+ if height <= 0 or width <= 0:
+ return
+ alloc_h, alloc_w = getattr(self, "_alloc_size", (self.height, self.width))
+ if height > alloc_h or width > alloc_w:
+ return
+ self.height, self.width = height, width
+ self._prev = None
+ self._prev_index = None
+
def _on_step(self, latents: Any, scheduler: Any, final: bool) -> None:
import torch
if getattr(latents, "device", None) is None or latents.device.type != "cuda":
diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.py
index b99cdfedac6..f556f5e53d1 100644
--- a/studio/backend/core/inference/video.py
+++ b/studio/backend/core/inference/video.py
@@ -1078,6 +1078,13 @@ def _i2v_state_call_kwargs(fam: VideoFamily, state: Any) -> dict[str, Any]:
)
+def _bg_i2v_render(first_pil: Any, i2v_active: bool) -> bool:
+ """An image-conditioned render for the background compile, however the family conditions (a swapped i2v pipeline,
+ or a pipeline its own render derives): its denoiser inputs (per-token timesteps) are never a text-to-video sample,
+ so it neither seeds the compile nor counts as an eager text render."""
+ return bool(i2v_active) or first_pil is not None
+
+
def _settle_bg_compile(bg: Any, *, i2v: bool) -> None:
if not i2v:
bg.note_eager_generation()
@@ -9945,6 +9952,9 @@ class VideoBackend:
kwargs[fam.cfg2_kwarg] = float(guidance_2)
if fam.modular_workflow:
kwargs["output"] = ["videos", "audio", "sampling_rate"]
+ if bg_eager and not i2v_active and _bg_i2v_render(first_pil, i2v_active):
+ # Same as the i2v swap above, for a family that conditions without one (its own render).
+ i2v_swap.enter_context(bg_compile.no_record())
# Auto-blocks distinguish omitted conditioning from empty conditioning.
# LTX-2.5 conditions through its own render (LTX2ConditionPipeline), not an image kwarg.
if first_pil is not None and fam.name != "ltx-2.5":
@@ -9986,6 +9996,10 @@ class VideoBackend:
upsampler = getattr(pipe, "_unsloth_ltx25_upsampler", None),
on_step = kwargs.get("callback_on_step_end"),
cancel = cancel,
+ # Stage 1 denoises at half size: the live preview unpacks its tokens with that grid.
+ on_stage = lambda w, h: (
+ previewer.set_render_size(h, w) if previewer is not None else None
+ ),
)
started = time.monotonic()
@@ -10286,7 +10300,7 @@ class VideoBackend:
if self._active_generate_cancel is cancel:
self._active_generate_cancel = None
if bg_eager:
- _settle_bg_compile(bg, i2v = i2v_active)
+ _settle_bg_compile(bg, i2v = _bg_i2v_render(first_pil, i2v_active))
reclaim_offload_host_memory(state.offload_policy, logger = logger)
return {
"mp4_bytes": mp4_bytes,
diff --git a/studio/backend/core/inference/video_ltx25.py b/studio/backend/core/inference/video_ltx25.py
index 050d831941d..3b636742bba 100644
--- a/studio/backend/core/inference/video_ltx25.py
+++ b/studio/backend/core/inference/video_ltx25.py
@@ -896,12 +896,16 @@ class Ltx25TextEncoderClient:
prompts: list[str],
max_sequence_length: int,
cancel: Optional[threading.Event] = None,
+ *,
+ copy: bool = True,
) -> tuple[Any, Any]:
+ """``copy=False`` returns the cached host tensors themselves, for a caller that only reads them: a 385 MB host
+ clone per call is ~40 ms on a B200 host."""
key = (tuple(prompts), int(max_sequence_length))
with self._lock:
for cached_key, value in self._cache:
if cached_key == key:
- return value[0].clone(), value[1].clone()
+ return (value[0].clone(), value[1].clone()) if copy else value
if not self.alive():
logger.warning("video.ltx25_te: encoder worker not running; restarting it")
self.start()
@@ -932,7 +936,7 @@ class Ltx25TextEncoderClient:
)
self._cache.append((key, (embeds, mask)))
del self._cache[: -self._CACHE_ENTRIES]
- return embeds.clone(), mask.clone()
+ return (embeds.clone(), mask.clone()) if copy else (embeds, mask)
def install_remote_encode_prompt(pipe: Any, client: Ltx25TextEncoderClient) -> None:
@@ -958,7 +962,8 @@ def install_remote_encode_prompt(pipe: Any, client: Ltx25TextEncoderClient) -> N
dtype = dtype or getattr(getattr(pipe, "transformer", None), "dtype", None)
def _one(texts: list[str]) -> tuple[Any, Any]:
- embeds, mask = client.encode(texts, max_sequence_length)
+ # The client's own cached tensors (read only): every op below returns a new tensor.
+ embeds, mask = client.encode(texts, max_sequence_length, copy = False)
batch = embeds.shape[0]
embeds = embeds.to(device = device, dtype = dtype)
mask = mask.to(device = device)
@@ -1218,18 +1223,33 @@ def render(
upsampler: Any = None,
on_step: Optional[Callable[..., Any]] = None,
cancel: Optional[threading.Event] = None,
+ on_stage: Optional[Callable[[int, int], Any]] = None,
) -> Any:
"""Run one LTX-2.5 request. ``kwargs`` is the generic video call (prompt, size, frames, steps, guidance,
- frame_rate, generator, negative_prompt, callback); returns the final pipeline output (``.frames`` / ``.audio``)."""
+ frame_rate, generator, negative_prompt, callback); returns the final pipeline output (``.frames`` / ``.audio``).
+ ``on_stage(width, height)`` runs before each denoise stage with the size that stage denoises at (live previews
+ unpack the packed latents with it)."""
+ failed = False
try:
return _render(
- pipe, kwargs, dev = dev, image = image, upsampler = upsampler, on_step = on_step, cancel = cancel
+ pipe,
+ kwargs,
+ dev = dev,
+ image = image,
+ upsampler = upsampler,
+ on_step = on_step,
+ cancel = cancel,
+ on_stage = on_stage,
)
+ except BaseException:
+ failed = True
+ raise
finally:
- if image is not None:
+ if image is not None or failed:
# The condition pipeline shares pipe's modules but not its offload-hook list, so on every exit (dev,
# single stage, two stage, cancel) pipe's own hooks are reset here, or its last onloaded module stays on
- # the card.
+ # the card. A text render that stops between its stages (cancel, error) may hold the DiT stage 1
+ # onloaded (diffusion_multistage.hold_denoiser_between_calls): reset it too.
free = getattr(pipe, "maybe_free_model_hooks", None)
if callable(free):
try:
@@ -1247,6 +1267,7 @@ def _render(
upsampler: Any = None,
on_step: Optional[Callable[..., Any]] = None,
cancel: Optional[threading.Event] = None,
+ on_stage: Optional[Callable[[int, int], Any]] = None,
) -> Any:
import inspect
@@ -1313,6 +1334,11 @@ def _render(
}
def _keep(stage_width: int, stage_height: int, frames: int) -> None:
+ if on_stage is not None:
+ try:
+ on_stage(stage_width, stage_height)
+ except Exception: # noqa: BLE001 -- a preview hint must never fail a render
+ pass
if not hasattr(scheduler, "keep_tokens"):
return
if image is None:
@@ -1355,60 +1381,65 @@ def _render(
"LTX-2.5's two-stage recipe needs the latent upsampler (latent_upsampler/ of the base pack), which "
"is not loaded."
)
- half_w, half_h = width // 2, height // 2
- stage1 = dict(
- base,
- width = half_w,
- height = half_h,
- output_type = "latent",
- return_dict = False,
- **guidance_off,
- )
- if distilled_sigmas:
- stage1["sigmas"] = list(LTX25_STAGE1_SIGMAS)
- else:
- stage1["num_inference_steps"] = steps
- stage1.update(_conditions(LTX25_STAGE1_IMAGE_STRENGTH))
- cb = _callback(0)
- if cb is not None:
- stage1["callback_on_step_end"] = cb
- _keep(half_w, half_h, frames)
- with ltx23_verbatim_sigmas(pipe):
- video_latents, audio_latents = runner(**stage1)
- if cancel is not None and cancel.is_set():
- from .video_families import VIDEO_CANCELLED_MSG
- raise RuntimeError(VIDEO_CANCELLED_MSG)
-
- with torch.inference_mode() if torch.is_inference_mode_enabled() else torch.no_grad():
- param = next(upsampler.parameters())
- # Saved before the move: Module.to() swaps the parameter's storage in place, so param.device follows it.
- home = param.device
- moved = home != video_latents.device
- if moved:
- upsampler.to(video_latents.device)
- try:
- upsampled = upsampler(video_latents.to(param.dtype))
- finally:
+ from .diffusion_multistage import encode_once, hold_denoiser_between_calls
+
+ with encode_once(runner):
+ half_w, half_h = width // 2, height // 2
+ stage1 = dict(
+ base,
+ width = half_w,
+ height = half_h,
+ output_type = "latent",
+ return_dict = False,
+ **guidance_off,
+ )
+ if distilled_sigmas:
+ stage1["sigmas"] = list(LTX25_STAGE1_SIGMAS)
+ else:
+ stage1["num_inference_steps"] = steps
+ stage1.update(_conditions(LTX25_STAGE1_IMAGE_STRENGTH))
+ cb = _callback(0)
+ if cb is not None:
+ stage1["callback_on_step_end"] = cb
+ _keep(half_w, half_h, frames)
+ # The connectors and the upsampler run before the DiT is needed again.
+ companions = (getattr(pipe, "connectors", None), upsampler)
+ with ltx23_verbatim_sigmas(pipe), hold_denoiser_between_calls(pipe, runner, companions):
+ video_latents, audio_latents = runner(**stage1)
+ if cancel is not None and cancel.is_set():
+ from .video_families import VIDEO_CANCELLED_MSG
+ raise RuntimeError(VIDEO_CANCELLED_MSG)
+
+ with torch.inference_mode() if torch.is_inference_mode_enabled() else torch.no_grad():
+ param = next(upsampler.parameters())
+ # Saved before the move: Module.to() swaps the parameter's storage in place, so param.device follows it.
+ home = param.device
+ moved = home != video_latents.device
if moved:
- upsampler.to(home)
- if cancel is not None and cancel.is_set():
- from .video_families import VIDEO_CANCELLED_MSG
- raise RuntimeError(VIDEO_CANCELLED_MSG)
-
- stage2 = dict(
- base,
- width = half_w * 2,
- height = half_h * 2,
- latents = upsampled,
- audio_latents = audio_latents,
- sigmas = list(LTX25_STAGE2_SIGMAS),
- noise_scale = LTX25_STAGE2_SIGMAS[0],
- **guidance_off,
- )
- stage2.update(_conditions(LTX25_STAGE2_IMAGE_STRENGTH))
- cb = _callback(steps)
- if cb is not None:
- stage2["callback_on_step_end"] = cb
- _keep(half_w * 2, half_h * 2, frames)
- with ltx23_verbatim_sigmas(pipe):
- return runner(**stage2)
+ upsampler.to(video_latents.device)
+ try:
+ upsampled = upsampler(video_latents.to(param.dtype))
+ finally:
+ if moved:
+ upsampler.to(home)
+ if cancel is not None and cancel.is_set():
+ from .video_families import VIDEO_CANCELLED_MSG
+ raise RuntimeError(VIDEO_CANCELLED_MSG)
+
+ stage2 = dict(
+ base,
+ width = half_w * 2,
+ height = half_h * 2,
+ latents = upsampled,
+ audio_latents = audio_latents,
+ sigmas = list(LTX25_STAGE2_SIGMAS),
+ noise_scale = LTX25_STAGE2_SIGMAS[0],
+ **guidance_off,
+ )
+ stage2.update(_conditions(LTX25_STAGE2_IMAGE_STRENGTH))
+ cb = _callback(steps)
+ if cb is not None:
+ stage2["callback_on_step_end"] = cb
+ _keep(half_w * 2, half_h * 2, frames)
+ with ltx23_verbatim_sigmas(pipe):
+ return runner(**stage2)
diff --git a/studio/backend/tests/test_diffusion_multistage.py b/studio/backend/tests/test_diffusion_multistage.py
new file mode 100644
index 00000000000..bf88e6951fb
--- /dev/null
+++ b/studio/backend/tests/test_diffusion_multistage.py
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Family-agnostic multi-call render helpers: one encode per request, and the denoiser held across calls under model
+offload only when the work between the calls fits beside it."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from core.inference import diffusion_multistage as MS
+
+
+class _Pipe:
+ def __init__(self):
+ self.encodes = 0
+ self.freed = 0
+ self.resets = 0
+ self._all_hooks = ["h"]
+ self.components = {"transformer": SimpleNamespace(_reset_stateful_cache = self._reset)}
+
+ def _reset(self):
+ self.resets += 1
+
+ def encode_prompt(self, **kw):
+ self.encodes += 1
+ return torch.full((1, 2), float(self.encodes)), None
+
+ def maybe_free_model_hooks(self):
+ self.freed += 1
+
+
+def test_encode_once_shares_the_first_encode_and_isolates_in_place_edits():
+ pipe = _Pipe()
+ with MS.encode_once(pipe):
+ a = pipe.encode_prompt(prompt = "p", device = "cpu")
+ a[0].add_(5)
+ b = pipe.encode_prompt(prompt = "p", device = "cpu")
+ c = pipe.encode_prompt(prompt = "p", device = "cpu")
+ other = pipe.encode_prompt(prompt = "q", device = "cpu")
+ tensor_arg = pipe.encode_prompt(prompt = "p", prompt_embeds = torch.zeros(1))
+ assert pipe.encodes == 3 and torch.equal(b[0], torch.ones(1, 2)) and c is b
+ assert torch.equal(other[0], torch.full((1, 2), 2.0)) and torch.equal(tensor_arg[0], torch.full((1, 2), 3.0))
+ assert "encode_prompt" not in pipe.__dict__
+ # an instance attribute (a remote encoder, a cache wrapper) comes back as it was
+ own = lambda **kw: (torch.zeros(1), None) # noqa: E731
+ pipe.encode_prompt = own
+ with MS.encode_once(pipe):
+ pipe.encode_prompt(prompt = "p")
+ assert pipe.__dict__["encode_prompt"] is own
+
+
[email protected]("fits", [True, False])
+def test_hold_on_the_pipe_itself_skips_only_the_offload(monkeypatch, fits):
+ monkeypatch.setattr(MS, "companions_fit_beside_denoiser", lambda pipe, companions: fits)
+ pipe = _Pipe()
+ with MS.hold_denoiser_between_calls(pipe, pipe, ()):
+ pipe.maybe_free_model_hooks() # what a diffusers call does at its end
+ assert pipe.freed == (0 if fits else 1) and pipe.resets == (1 if fits else 0)
+ assert "maybe_free_model_hooks" not in pipe.__dict__
+
+
[email protected]("fits", [True, False])
+def test_hold_with_a_derived_runner_frees_the_owner_only_when_it_does_not_fit(monkeypatch, fits):
+ monkeypatch.setattr(MS, "companions_fit_beside_denoiser", lambda pipe, companions: fits)
+ pipe = _Pipe()
+ with MS.hold_denoiser_between_calls(pipe, object(), ()):
+ pass
+ assert pipe.freed == (0 if fits else 1)
+
+
+def test_no_offload_hooks_means_no_check(monkeypatch):
+ monkeypatch.setattr(MS, "companions_fit_beside_denoiser", lambda *a: pytest.fail("checked"))
+ pipe = _Pipe()
+ pipe._all_hooks = []
+ with MS.hold_denoiser_between_calls(pipe, pipe, ()):
+ pipe.maybe_free_model_hooks()
+ assert pipe.freed == 1
+
+
+def test_fit_check_declines_off_cuda_and_counts_module_bytes():
+ pipe = SimpleNamespace(transformer = torch.nn.Linear(2, 2))
+ assert MS.companions_fit_beside_denoiser(pipe, (torch.nn.Linear(4, 4),)) is False
+ assert MS.module_bytes(torch.nn.Linear(4, 4)) == (16 + 4) * 4 and MS.module_bytes(None) == 0
diff --git a/studio/backend/tests/test_diffusion_preview.py b/studio/backend/tests/test_diffusion_preview.py
index 27afc82609b..8d833ced7d2 100644
--- a/studio/backend/tests/test_diffusion_preview.py
+++ b/studio/backend/tests/test_diffusion_preview.py
@@ -322,3 +322,36 @@ def test_smoothing_removes_the_period_two_patch_grid():
# A smooth ramp passes through (interior; edges are replicated).
ramp = torch.linspace(0, 1, w).expand(h, w)[..., None].expand(h, w, 3).contiguous()
assert torch.allclose(DP.smooth_patch_grid(ramp)[2:-2, 2:-2], ramp[2:-2, 2:-2], atol = 1e-6)
+
+
[email protected](not torch.cuda.is_available(), reason = "needs CUDA")
+def test_a_half_size_stage_unpacks_with_its_own_grid(monkeypatch):
+ # LTX-2.5's first stage denoises at half size: unpacked with the full-size grid its tokens tile 4 frames into one
+ # scrambled picture, so the render names each stage's size before it runs.
+ monkeypatch.delenv(DP.PREVIEW_ENV, raising = False)
+ prev = DP.LatentPreviewer.create(
+ family = "ltx-2.5",
+ requested = None,
+ height = 704,
+ width = 1280,
+ device = "cuda",
+ publish = lambda url, seq: None,
+ min_interval_s = 0.0,
+ )
+ assert prev is not None
+ try:
+ half = torch.randn(1, 16 * 11 * 20, 128, device = "cuda")
+ # Full-size grid: 880 tokens per frame divides the 3520 of 16 half-size frames, so it "fits" but is wrong.
+ assert tuple(DP.latent_grid(half, prev.spec, prev.height, prev.width).shape) == (22, 40, 128)
+ prev._prev = object()
+ prev.set_render_size(352, 640)
+ assert (prev.height, prev.width) == (352, 640) and prev._prev is None
+ grid = DP.latent_grid(half, prev.spec, prev.height, prev.width)
+ assert torch.equal(grid.reshape(220, 128), half[0, :220])
+ # Never above the size the slots were sized for; back to full size for stage 2.
+ prev.set_render_size(1408, 2560)
+ assert (prev.height, prev.width) == (352, 640)
+ prev.set_render_size(704, 1280)
+ assert (prev.height, prev.width) == (704, 1280)
+ finally:
+ prev.finish()
diff --git a/studio/backend/tests/test_video_ltx25.py b/studio/backend/tests/test_video_ltx25.py
index 81df117f75c..b40ca4fd277 100644
--- a/studio/backend/tests/test_video_ltx25.py
+++ b/studio/backend/tests/test_video_ltx25.py
@@ -17,6 +17,7 @@ from types import SimpleNamespace
import pytest
from core.inference import diffusion_content as dc
+from core.inference import diffusion_multistage as MS
from core.inference import video_ltx25 as v25
from core.inference.video_families import (
LTX25_FAMILY,
@@ -914,10 +915,12 @@ class _FakeClient:
texts,
max_len,
cancel = None,
+ copy = True,
):
import torch
self.calls.append((list(texts), max_len))
+ self.copies = getattr(self, "copies", []) + [copy]
n = len(texts)
embeds = torch.arange(n, dtype = torch.float32).view(n, 1, 1).expand(n, max_len, 6).clone()
return embeds, torch.ones(n, max_len, dtype = torch.long)
@@ -939,6 +942,8 @@ def test_remote_encode_prompt_keeps_diffusers_semantics():
max_sequence_length = 4,
)
assert client.calls == [(["a fox"], 4)]
+ # The stage calls read the client's cached tensors without a host clone; every op makes a new tensor.
+ assert client.copies == [False]
assert pe.shape == (2, 4, 6) and pe.dtype == torch.bfloat16 and pm.shape == (2, 4)
assert ne is None and nm is None
client.calls.clear()
@@ -983,6 +988,10 @@ def test_client_caches_recent_encodes_and_reports_a_dead_worker(monkeypatch):
a = client.encode(["p"], 2)
b = client.encode(["p"], 2)
assert client._seq == 1 and torch.equal(a[0], b[0])
+ # A read-only hit hands back the cached tensors; the default still returns private copies.
+ shared = client.encode(["p"], 2, copy = False)
+ assert shared is client._cache[-1][1] and client.encode(["p"], 2, copy = False)[0] is shared[0]
+ assert a[0] is not shared[0] and b[0] is not shared[0]
client._proc = SimpleNamespace(is_alive = lambda: False, exitcode = -9)
client._cmd.put = lambda msg: None
monkeypatch.setattr(client, "start", lambda: None)
@@ -1219,6 +1228,145 @@ def test_two_stage_t2v_follows_the_reference_recipe():
assert v25.stage_steps(8, dev = False) == (8, 3)
+def test_each_stage_names_its_size_before_it_runs(monkeypatch):
+ # Live previews unpack the packed latents with the stage size: half for stage 1, full for stage 2.
+ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))
+ stages = []
+ v25.render(pipe, _kwargs(), dev = False, upsampler = _Upsampler(), on_stage = lambda w, h: stages.append((w, h)))
+ assert stages == [(640, 352), (1280, 704)]
+ # dev: one full-size stage
+ stages.clear()
+ v25.render(pipe, dict(_kwargs(), num_inference_steps = 30), dev = True, on_stage = lambda w, h: stages.append((w, h)))
+ assert stages == [(1280, 704)]
+
+ # a failing hint never fails the render
+ def _boom(w, h):
+ raise RuntimeError("preview")
+
+ pipe = _FakePipe(SimpleNamespace(keep_tokens = None))
+ out = v25.render(pipe, _kwargs(), dev = False, upsampler = _Upsampler(), on_stage = _boom)
+ assert out.frames == ["final"] and len(pipe.calls) == 2
+
+
+class _OffloadedPipe(_FakePipe):
+ """A model-offloaded pipe: like diffusers, every call ends by resetting the offload hooks."""
+
+ def __init__(self, scheduler):
+ super().__init__(scheduler)
+ self._all_hooks = ["hook"]
+ self.components = {}
+ self.free_log = []
+
+ def __call__(self, **kw):
+ out = super().__call__(**kw)
+ self.maybe_free_model_hooks()
+ return out
+
+ def maybe_free_model_hooks(self):
+ self.freed += 1
+ self.free_log.append(len(self.calls))
+
+
[email protected]("fits", [True, False])
+def test_model_offload_holds_the_dit_across_the_stage_boundary_only_when_stage_two_fits(monkeypatch, fits):
+ # Stage 1's call ends by offloading every component; stage 2 then re-uploaded the whole DiT.
+ monkeypatch.setattr(MS, "companions_fit_beside_denoiser", lambda pipe, companions: fits)
+ pipe = _OffloadedPipe(SimpleNamespace(keep_tokens = None))
+ v25.render(pipe, _kwargs(), dev = False, upsampler = _Upsampler())
+ assert len(pipe.calls) == 2
+ # Held: only stage 2's own reset ran. Not held: both stages reset, as before.
+ assert pipe.free_log == ([2] if fits else [1, 2])
+ assert "maybe_free_model_hooks" not in pipe.__dict__
+ # No model offload: nothing is patched or checked.
+ plain = _FakePipe(SimpleNamespace(keep_tokens = None))
+ monkeypatch.setattr(MS, "companions_fit_beside_denoiser", lambda *a: pytest.fail("checked without offload"))
+ v25.render(plain, _kwargs(), dev = False, upsampler = _Upsampler())
+ assert plain.freed == 0
+
+
[email protected]("fits", [True, False])
+def test_image_to_video_frees_between_stages_only_when_stage_two_does_not_fit(monkeypatch, fits):
+ pytest.importorskip("diffusers") # the image path builds diffusers' LTX2VideoCondition
+ # The condition pipeline has no hook list, so it never offloads at its stage end: pipe's hooks are reset there
+ # when stage 2 would not fit beside the DiT.
+ monkeypatch.setattr(MS, "companions_fit_beside_denoiser", lambda pipe, companions: fits)
+ pipe = _OffloadedPipe(SimpleNamespace(keep_tokens = None))
+ cond = _FakePipe(pipe.scheduler)
+ pipe._unsloth_ltx25_condition_pipe = cond
+ v25.render(pipe, _kwargs(), dev = False, image = object(), upsampler = _Upsampler())
+ assert pipe.calls == [] and len(cond.calls) == 2
+ assert pipe.freed == (1 if fits else 2)
+
+
+def test_a_text_render_cancelled_between_stages_resets_the_offload_hooks(monkeypatch):
+ import threading
+
+ monkeypatch.setattr(MS, "companions_fit_beside_denoiser", lambda pipe, companions: True)
+ cancel = threading.Event()
+
+ class _CancellingUpsampler(_Upsampler):
+ def __call__(self, latents):
+ cancel.set()
+ return super().__call__(latents)
+
+ pipe = _OffloadedPipe(SimpleNamespace(keep_tokens = None))
+ with pytest.raises(RuntimeError, match = "cancelled"):
+ v25.render(pipe, _kwargs(), dev = False, upsampler = _CancellingUpsampler(), cancel = cancel)
+ # Stage 1 held the DiT; the cancel resets the hooks instead of leaving it on the card.
+ assert pipe.freed == 1 and len(pipe.calls) == 1
+
+
+def test_the_hold_passes_the_connectors_and_the_upsampler_as_companions(monkeypatch):
+ seen = []
+ monkeypatch.setattr(MS, "companions_fit_beside_denoiser", lambda pipe, companions: seen.append(companions) or True)
+ pipe = _OffloadedPipe(SimpleNamespace(keep_tokens = None))
+ pipe.connectors = object()
+ up = _Upsampler()
+ v25.render(pipe, _kwargs(), dev = False, upsampler = up)
+ assert seen and seen[0] == (pipe.connectors, up)
+
+
+class _EncodingPipe(_FakePipe):
+ """Calls encode_prompt like the LTX-2 pipelines (keywords only) and records what each stage got."""
+
+ def __init__(self, scheduler):
+ super().__init__(scheduler)
+ self.encodes = 0
+ self.got = []
+
+ def encode_prompt(self, **kw):
+ import torch
+
+ self.encodes += 1
+ return torch.full((1, 2, 3), float(self.encodes)), torch.ones(1, 2), None, None
+
+ def __call__(self, prompt = None, **kw):
+ embeds = self.encode_prompt(prompt = prompt, negative_prompt = None, device = "cpu", prompt_embeds = None)
+ self.got.append(embeds[0].clone())
+ embeds[0].add_(100) # a stage editing its own tensors in place must not reach the next stage
+ return super().__call__(prompt = prompt, **kw)
+
+
+def test_both_stages_share_one_encode():
+ import torch
+
+ pipe = _EncodingPipe(SimpleNamespace(keep_tokens = None))
+ v25.render(pipe, _kwargs(), dev = False, upsampler = _Upsampler())
+ assert pipe.encodes == 1 and len(pipe.got) == 2
+ assert torch.equal(pipe.got[0], pipe.got[1]) and torch.equal(pipe.got[1], torch.full((1, 2, 3), 1.0))
+ assert "encode_prompt" not in pipe.__dict__
+ # A later request encodes again (the memo lives for one render), and a dev render never memoises.
+ v25.render(pipe, _kwargs(), dev = False, upsampler = _Upsampler())
+ assert pipe.encodes == 2
+ v25.render(pipe, dict(_kwargs(), num_inference_steps = 30), dev = True)
+ assert pipe.encodes == 3
+ # An instance-level encode_prompt (the remote encoder / prompt cache wrapper) is restored as it was.
+ own = pipe.encode_prompt
+ pipe.encode_prompt = own
+ v25.render(pipe, _kwargs(), dev = False, upsampler = _Upsampler())
+ assert pipe.__dict__["encode_prompt"] is own and pipe.encodes == 4
+
+
def test_two_stage_i2v_conditions_both_stages(monkeypatch):
pytest.importorskip("diffusers") # Backend CI has no diffusers; this path runs on it
pipe = _FakePipe(SimpleNamespace(keep_tokens = None))
@@ -2211,3 +2359,16 @@ def test_encoder_worker_starts_while_the_latch_is_clear(monkeypatch):
client.start()
(proc,) = spawned
assert adopted == [proc.pid] and client.alive() and not proc.terminated
+
+
+def test_an_ltx25_image_render_counts_as_image_to_video_for_the_background_compile():
+ # LTX-2.5 conditions through its own render, never the i2v swap, so the swap flag alone would let its per-token
+ # timesteps seed the background compile and leave an image-only session pending. The check is family-agnostic.
+ from core.inference import diffusion_bg_compile as bgc
+ from core.inference.video import _bg_i2v_render, _settle_bg_compile
+
+ assert _bg_i2v_render(object(), False) is True and _bg_i2v_render(object(), True) is True
+ assert _bg_i2v_render(None, False) is False
+ bg = bgc.BackgroundCompile(object())
+ _settle_bg_compile(bg, i2v = _bg_i2v_render(object(), False))
+ assert not bg.pending() and bg.state == "failed"