diff --git a/docs/cookbook/diffusion/LTX/LTX2 & LTX2.3.mdx b/docs/cookbook/diffusion/LTX/LTX2 & LTX2.3.mdx index 9a08eaed72..36359a4924 100644 --- a/docs/cookbook/diffusion/LTX/LTX2 & LTX2.3.mdx +++ b/docs/cookbook/diffusion/LTX/LTX2 & LTX2.3.mdx @@ -75,7 +75,7 @@ Other deployment flags: - `--lora-weight-name`: Select the exact safetensors file when the LoRA repository contains multiple weight files. -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. ### 3.3 Fast multi-GPU presets diff --git a/python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py b/python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py index aa1ee266bf..650eb042b6 100644 --- a/python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py +++ b/python/sglang/multimodal_gen/runtime/pipelines/ltx_2_pipeline.py @@ -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 ) diff --git a/python/sglang/multimodal_gen/runtime/server_args/server_args.py b/python/sglang/multimodal_gen/runtime/server_args/server_args.py index 20044ec8c4..dede3cdb72 100644 --- a/python/sglang/multimodal_gen/runtime/server_args/server_args.py +++ b/python/sglang/multimodal_gen/runtime/server_args/server_args.py @@ -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." ), ) diff --git a/python/sglang/multimodal_gen/test/unit/test_ltx2_premerged_stage2.py b/python/sglang/multimodal_gen/test/unit/test_ltx2_premerged_stage2.py new file mode 100644 index 0000000000..c4d187db92 --- /dev/null +++ b/python/sglang/multimodal_gen/test/unit/test_ltx2_premerged_stage2.py @@ -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() diff --git a/python/sglang/multimodal_gen/test/unit/test_server_args.py b/python/sglang/multimodal_gen/test/unit/test_server_args.py index 5c15e361f7..506f29aa18 100644 --- a/python/sglang/multimodal_gen/test/unit/test_server_args.py +++ b/python/sglang/multimodal_gen/test/unit/test_server_args.py @@ -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(),