[Perf] diffusion: Run LTX-2 stage 2 on a premerged resident DiT (#46108)

Co-authored-by: Mick Qian <mickqian@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Mick
2026-10-24 09:23:08 +08:00
committed by GitHub
co-authored by Mick Qian Claude Opus 5.5
parent e66c9e981d
commit a08bb0ec9e
5 changed files with 76 additions and 9 deletions
@@ -75,7 +75,7 @@ Other deployment flags:
- `--lora-weight-name`: Select the exact safetensors file when the LoRA repository contains multiple weight files.
<Note>
For native LTX-2.3 two-stage serving without a user LoRA, `resident` is the fastest high-VRAM path. LTX-2 still applies the distilled LoRA during the stage switch, so `--ltx2-two-stage-device-mode` is mainly an LTX-2.3 optimization. When you pass `--lora-path`, SGLang still applies the user LoRA during the two-stage switch, so use `resident` on H200-class GPUs for enough VRAM, but do not expect the same premerged-stage2 benefit as the no-user-LoRA path.
For LTX-2 and LTX-2.3 two-stage serving without a user LoRA, `resident` is the fastest high-VRAM path: stage 2 runs a second DiT with the distilled LoRA merged in, and it is the default on GPUs with at least 130 GiB. When you pass `--lora-path`, SGLang still applies the user LoRA during the two-stage switch, so use `resident` on H200-class GPUs for enough VRAM, but do not expect the same premerged-stage2 benefit as the no-user-LoRA path.
</Note>
### 3.3 Fast multi-GPU presets
@@ -546,7 +546,7 @@ class LTX2ResidentResidencyStrategy(LTX2TwoStageResidencyStrategy):
self._ensure_on_gpu("transformer")
self._ensure_on_gpu("transformer_2")
logger.info(
"Using resident LTX-2.3 two-stage transformers mode (both DiTs stay on GPU)"
"Using resident LTX-2 two-stage transformers mode (both DiTs stay on GPU)"
)
self.manager._active_phase = "stage1"
self.manager._sync_refinement_stage_transformer("stage1")
@@ -607,14 +607,15 @@ class LTX2TwoStageResidencyController:
@property
def should_use_premerged(self) -> bool:
"""Whether to keep a pre-merged stage-2 DiT for LTX-2.3 two-stage.
"""Whether to keep a second DiT with the distilled LoRA merged in for stage 2.
We only enable this optimization for resident native LTX-2.3 two-stage
and when users did not explicitly provide a stage-1 LoRA path
Resident mode keeps both DiTs on the GPU, so stage 2 runs merged weights
like the official two-stage pipelines instead of a per-layer dynamic LoRA;
it needs the distilled LoRA and no user-provided stage-1 LoRA
"""
return (
self.mode == "resident"
and self.pipeline._should_merge_stage2_distilled_lora(self.server_args)
and self.pipeline._distilled_lora_path is not None
and self.pipeline._stage1_lora_path is None
)
@@ -1096,7 +1096,7 @@ class ServerArgs(DisaggServerArgsMixin):
)
def _adjust_ltx2_two_stage_device_mode(self):
if not self._is_ltx23_two_stage_pipeline():
if not self._is_ltx2_distilled_lora_two_stage_pipeline():
return
mode = self.ltx2_two_stage_device_mode
@@ -1171,6 +1171,13 @@ class ServerArgs(DisaggServerArgsMixin):
)
return "original"
def _is_ltx2_distilled_lora_two_stage_pipeline(self) -> bool:
# LTX-2 and LTX-2.3 refine with a distilled LoRA; LTX-2.5 ships a distilled DiT
return (
is_ltx2_two_stage_pipeline_name(self.pipeline_class_name)
and not self.pipeline_config.default_sigmas
)
def _is_ltx23_two_stage_pipeline(self) -> bool:
return is_ltx2_two_stage_pipeline_name(self.pipeline_class_name) and (
self._is_ltx23_model_path(self.model_path)
@@ -2919,9 +2926,10 @@ class ServerArgs(DisaggServerArgsMixin):
choices=LTX2_TWO_STAGE_DEVICE_MODE_CHOICES,
default=ServerArgs.ltx2_two_stage_device_mode,
help=(
"LTX-2.3 two-stage device residency mode: "
"LTX-2 / LTX-2.3 two-stage device residency mode: "
"'original' keeps official two-stage semantics without premerged stage2, "
"'resident' keeps both transformers resident on GPU. "
"'resident' keeps both transformers resident on GPU and runs stage 2 "
"on the one with the distilled LoRA merged in. "
"Default is auto: resident on H200/high-memory CUDA GPUs, otherwise original."
),
)
@@ -0,0 +1,45 @@
import unittest
from types import SimpleNamespace
from sglang.multimodal_gen.runtime.pipelines.ltx_2_pipeline import (
LTX2TwoStageResidencyController,
)
def _controller(
mode: str, *, distilled_lora: str | None, stage1_lora: str | None = None
) -> LTX2TwoStageResidencyController:
controller = object.__new__(LTX2TwoStageResidencyController)
controller.mode = mode
controller.pipeline = SimpleNamespace(
_distilled_lora_path=distilled_lora, _stage1_lora_path=stage1_lora
)
return controller
class TestLTX2PremergedStage2(unittest.TestCase):
def test_resident_mode_premerges_the_distilled_lora(self):
self.assertTrue(
_controller("resident", distilled_lora="lora").should_use_premerged
)
def test_original_mode_keeps_one_dit(self):
self.assertFalse(
_controller("original", distilled_lora="lora").should_use_premerged
)
def test_no_distilled_lora_or_a_user_lora_keeps_one_dit(self):
# a pre-distilled DiT (LTX-2.5) has nothing to merge; a user stage-1 LoRA
# still switches per request
self.assertFalse(
_controller("resident", distilled_lora=None).should_use_premerged
)
self.assertFalse(
_controller(
"resident", distilled_lora="lora", stage1_lora="user"
).should_use_premerged
)
if __name__ == "__main__":
unittest.main()
@@ -2711,6 +2711,19 @@ class TestOffloadDefaults(_CudaPlatformTestCase):
self.assertFalse(args.vae_cpu_offload)
self.assertIsNone(args.layerwise_offload_components)
def test_auto_ltx2_two_stage_device_mode_follows_device_memory(self):
for memory_gb, mode in ((140, "resident"), (80, "original")):
args = self._from_dict_with_pipeline_config(
LTX2PipelineConfig(),
memory_gb=memory_gb,
kwargs={
"model_path": "Lightricks/LTX-2",
"num_gpus": 2,
"pipeline_class_name": "LTX2TwoStagePipeline",
},
)
self.assertEqual(args.ltx2_two_stage_device_mode, mode)
def test_auto_high_memory_ltx23_original_keeps_default_layerwise_components(self):
args = self._from_dict_with_pipeline_config(
LTX2PipelineConfig(),