Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: 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.pynew file mode 100644index 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:+ passdiff --git a/studio/backend/core/inference/diffusion_preview.py b/studio/backend/core/inference/diffusion_preview.pyindex 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 = specself.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 = Truelogger.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 torchif 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.pyindex 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 = Noneif 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.pyindex 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 valueif 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) -> Ndtype = 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 = Falsetry: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+ raisefinally:- 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+ passif not hasattr(scheduler, "keep_tokens"):returnif 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.deviceif 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.pynew file mode 100644index 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) == 0diff --git a/studio/backend/tests/test_diffusion_preview.py b/studio/backend/tests/test_diffusion_preview.pyindex 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.pyindex 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 SimpleNamespaceimport pytestfrom core.inference import diffusion_content as dc+from core.inference import diffusion_multistage as MSfrom core.inference import video_ltx25 as v25from core.inference.video_families import (LTX25_FAMILY,@@ -914,10 +915,12 @@ class _FakeClient:texts,max_len,cancel = None,+ copy = True,):import torchself.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 Noneclient.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: Nonemonkeypatch.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 itpipe = _FakePipe(SimpleNamespace(keep_tokens = None))@@ -2211,3 +2359,16 @@ def test_encoder_worker_starts_while_the_latch_is_clear(monkeypatch):client.start()(proc,) = spawnedassert 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"