From 76ccf0850caf7e2fa996c06653070063a3872977 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wenbo=20Ji=E3=80=80=E5=B5=87=E6=96=87=E5=8D=9A?= <36562829+fusheng-ji@users.noreply.github.com> Date: Fri, 9 Oct 2026 17:20:13 +0200 Subject: [PATCH] [diffusion] fix: fix TeaCache CFG state lifecycle and skip boundaries (#42422) Co-authored-by: Mick Qian Co-authored-by: Mick --- .../multimodal_gen/configs/sample/teacache.py | 23 +-- .../multimodal_gen/runtime/cache/teacache.py | 7 +- .../runtime/models/dits/wanvideo.py | 9 +- .../sglang/multimodal_gen/test/test_utils.py | 2 +- .../test/unit/test_sampling_params.py | 21 +- .../test/unit/test_teacache_lifecycle.py | 186 ++++++++++++++++++ 6 files changed, 217 insertions(+), 31 deletions(-) create mode 100644 python/sglang/multimodal_gen/test/unit/test_teacache_lifecycle.py diff --git a/python/sglang/multimodal_gen/configs/sample/teacache.py b/python/sglang/multimodal_gen/configs/sample/teacache.py index e20df6e67b..36192b26ca 100644 --- a/python/sglang/multimodal_gen/configs/sample/teacache.py +++ b/python/sglang/multimodal_gen/configs/sample/teacache.py @@ -62,9 +62,14 @@ class TeaCacheParams(CacheParams): return self.coefficients_callback(self) return self.coefficients - def get_skip_boundaries( - self, num_inference_steps: int, do_cfg: bool - ) -> tuple[int, int]: + def get_skip_step_range(self, num_inference_steps: int) -> tuple[int, int]: + """Return the ``[start, end)`` range of denoising steps that may skip. + + Measured in denoising steps rather than forward calls, so the window does + not depend on how many CFG branches run locally per step (serial CFG, CFG + parallel, or CFG gating that stops running the negative branch). + """ + def _resolve_boundary(value: int | float) -> int: if isinstance(value, float): return int(num_inference_steps * value) @@ -72,11 +77,7 @@ class TeaCacheParams(CacheParams): return num_inference_steps + value return value - start_skipping = _resolve_boundary(self.start_skipping) - end_skipping = _resolve_boundary(self.end_skipping) - - if do_cfg: - start_skipping *= 2 - end_skipping *= 2 - - return start_skipping, end_skipping + return ( + _resolve_boundary(self.start_skipping), + _resolve_boundary(self.end_skipping), + ) diff --git a/python/sglang/multimodal_gen/runtime/cache/teacache.py b/python/sglang/multimodal_gen/runtime/cache/teacache.py index 6b71cd9f2f..dcac1d1eff 100644 --- a/python/sglang/multimodal_gen/runtime/cache/teacache.py +++ b/python/sglang/multimodal_gen/runtime/cache/teacache.py @@ -263,6 +263,7 @@ class TeaCacheMixin: from sglang.multimodal_gen.runtime.managers.forward_context import ( get_forward_context, ) + from sglang.multimodal_gen.runtime.server_args import get_global_server_args forward_context = get_forward_context() forward_batch = forward_context.forward_batch @@ -282,9 +283,11 @@ class TeaCacheMixin: num_inference_steps = forward_batch.num_inference_steps do_cfg = forward_batch.do_classifier_free_guidance is_cfg_negative = forward_batch.is_cfg_negative + is_cfg_parallel = bool(get_global_server_args().enable_cfg_parallel) - # Reset at first timestep - if current_timestep == 0 and not self.is_cfg_negative: + # Serial CFG resets once before the positive branch. CFG-parallel ranks + # each own a model instance and must reset their local state. + if current_timestep == 0 and (is_cfg_parallel or not is_cfg_negative): self.reset_teacache_state() return TeaCacheContext( diff --git a/python/sglang/multimodal_gen/runtime/models/dits/wanvideo.py b/python/sglang/multimodal_gen/runtime/models/dits/wanvideo.py index 01ea542dd7..39088fca35 100755 --- a/python/sglang/multimodal_gen/runtime/models/dits/wanvideo.py +++ b/python/sglang/multimodal_gen/runtime/models/dits/wanvideo.py @@ -1422,12 +1422,13 @@ class WanTransformer3DModel(CachableDiT, LayerwiseOffloadableModuleMixin): # Initialize Wan-specific parameters teacache_params = ctx.teacache_params use_ret_steps = teacache_params.use_ret_steps - start_skipping, end_skipping = teacache_params.get_skip_boundaries( - ctx.num_inference_steps, ctx.do_cfg + start_skipping, end_skipping = teacache_params.get_skip_step_range( + ctx.num_inference_steps ) - # Determine boundary step - is_boundary_step = self.cnt < start_skipping or self.cnt >= end_skipping + # Count the window in denoising steps: the number of local forwards per + # step varies with CFG parallel and CFG gating. + is_boundary_step = not start_skipping <= ctx.current_timestep < end_skipping timestep_proj = kwargs["timestep_proj"] temb = kwargs["temb"] diff --git a/python/sglang/multimodal_gen/test/test_utils.py b/python/sglang/multimodal_gen/test/test_utils.py index 6b7cde1725..5a29794e5e 100644 --- a/python/sglang/multimodal_gen/test/test_utils.py +++ b/python/sglang/multimodal_gen/test/test_utils.py @@ -37,7 +37,7 @@ logger = init_logger(__name__) # NPU/ascend) is read from sgl-project/ci-data-diffusion, where the GT-gen workflows # publish. SGL_TEST_FILES_CI_DATA_REPO = "sgl-project/ci-data-diffusion" -SGL_TEST_FILES_CI_DATA_REVISION = "31d8ad69f2434727aad518f0678fbd57823856fe" +SGL_TEST_FILES_CI_DATA_REVISION = "5d8eb22d16624817c62e06ce4cd69d36fbe7d456" # The NPU pin is kept as a separate branch so ascend GT can be bumped independently # when it's regenerated on its own cadence. diff --git a/python/sglang/multimodal_gen/test/unit/test_sampling_params.py b/python/sglang/multimodal_gen/test/unit/test_sampling_params.py index e33c739110..2a492007c9 100644 --- a/python/sglang/multimodal_gen/test/unit/test_sampling_params.py +++ b/python/sglang/multimodal_gen/test/unit/test_sampling_params.py @@ -297,26 +297,21 @@ class TestSamplingParamsSubclass(unittest.TestCase): self.assertEqual(params.get_coefficients(), [9.0, 8.0, 7.0, 6.0, 5.0]) - def test_wan_teacache_boundaries_match_legacy_behavior(self): - legacy_equivalent_cases = [ - (WanT2V_1_3B_SamplingParams().teacache_params, False, (5, 50)), - (WanT2V_1_3B_SamplingParams().teacache_params, True, (10, 100)), - (WanT2V_14B_SamplingParams().teacache_params, False, (1, 49)), - (WanT2V_14B_SamplingParams().teacache_params, True, (2, 98)), - (WanI2V_14B_480P_SamplingParam().teacache_params, False, (5, 50)), - (WanI2V_14B_480P_SamplingParam().teacache_params, True, (10, 100)), - (WanI2V_14B_720P_SamplingParam().teacache_params, False, (5, 50)), - (WanI2V_14B_720P_SamplingParam().teacache_params, True, (10, 100)), + def test_wan_teacache_skip_step_ranges(self): + cases = [ + (WanT2V_1_3B_SamplingParams().teacache_params, (5, 50)), + (WanT2V_14B_SamplingParams().teacache_params, (1, 49)), + (WanI2V_14B_480P_SamplingParam().teacache_params, (5, 50)), + (WanI2V_14B_720P_SamplingParam().teacache_params, (5, 50)), ] - for teacache_params, do_cfg, expected in legacy_equivalent_cases: + for teacache_params, expected in cases: with self.subTest( use_ret_steps=teacache_params.use_ret_steps, - do_cfg=do_cfg, expected=expected, ): self.assertEqual( - teacache_params.get_skip_boundaries(50, do_cfg), + teacache_params.get_skip_step_range(50), expected, ) diff --git a/python/sglang/multimodal_gen/test/unit/test_teacache_lifecycle.py b/python/sglang/multimodal_gen/test/unit/test_teacache_lifecycle.py new file mode 100644 index 0000000000..2c9c9747b2 --- /dev/null +++ b/python/sglang/multimodal_gen/test/unit/test_teacache_lifecycle.py @@ -0,0 +1,186 @@ +# SPDX-License-Identifier: Apache-2.0 +"""Regression tests for request and CFG branch isolation in TeaCache.""" + +import unittest +from types import SimpleNamespace +from unittest.mock import patch + +import torch + +from sglang.multimodal_gen.configs.sample.teacache import TeaCacheParams +from sglang.multimodal_gen.runtime.cache.teacache import TeaCacheMixin +from sglang.multimodal_gen.runtime.managers.forward_context import set_forward_context +from sglang.multimodal_gen.runtime.models.dits.wanvideo import WanTransformer3DModel +from sglang.test.test_utils import CustomTestCase + + +class TestTeaCache(CustomTestCase): + def setUp(self): + self.params = TeaCacheParams( + teacache_thresh=0.5, coefficients=[1.0, 0.0], start_skipping=1 + ) + self.batch = SimpleNamespace( + enable_teacache=True, + teacache_params=self.params, + num_inference_steps=5, + do_classifier_free_guidance=True, + is_cfg_negative=False, + ) + self.server_args = SimpleNamespace(enable_cfg_parallel=False) + server_args_patch = patch( + "sglang.multimodal_gen.runtime.server_args.get_global_server_args", + return_value=self.server_args, + ) + server_args_patch.start() + self.addCleanup(server_args_patch.stop) + + def _new_cache(self): + cache = TeaCacheMixin() + cache.prefix = "wan" + cache._init_teacache_state() + return cache + + def _step(self, cache, timestep, negative, modulated_input): + self.batch.is_cfg_negative = negative + with set_forward_context(timestep, None, self.batch): + should_skip = WanTransformer3DModel.should_skip_forward_for_cached_states( + cache, timestep_proj=modulated_input, temb=modulated_input + ) + cache.cnt += 1 + return not should_skip + + def test_serial_cfg_preserves_both_branches_at_first_timestep(self): + """The negative first step must not discard the positive branch cache.""" + cache = self._new_cache() + positive = torch.tensor([1.0, 2.0]) + negative = torch.tensor([4.0, 8.0]) + residual = torch.tensor([0.25, 0.5]) + self.assertTrue(self._step(cache, 0, False, positive)) + WanTransformer3DModel.maybe_cache_states( + cache, (positive + residual).unsqueeze(0), positive + ) + self.assertTrue(self._step(cache, 0, True, negative)) + WanTransformer3DModel.maybe_cache_states( + cache, (negative + residual * 2).unsqueeze(0), negative + ) + self.assertEqual(cache.cnt, 2) + torch.testing.assert_close(cache.previous_residual, residual) + torch.testing.assert_close(cache.previous_modulated_input, positive) + torch.testing.assert_close(cache.previous_modulated_input_negative, negative) + self.assertFalse(self._step(cache, 1, False, positive)) + torch.testing.assert_close( + WanTransformer3DModel.retrieve_cached_states(cache, positive), + positive + residual, + ) + self.assertFalse(self._step(cache, 1, True, negative)) + torch.testing.assert_close( + WanTransformer3DModel.retrieve_cached_states(cache, negative), + negative + residual * 2, + ) + + def test_new_request_clears_completed_or_interrupted_state(self): + """New requests must not inherit counters, residuals or L1 history.""" + for do_cfg, parallel, branches in ( + (True, False, (False, True)), + (True, True, (False,)), + (True, True, (True,)), + (False, False, (False,)), + ): + for num_steps in (2, self.batch.num_inference_steps): + with self.subTest( + do_cfg=do_cfg, parallel=parallel, branches=branches, steps=num_steps + ): + self.server_args.enable_cfg_parallel = parallel + self.batch.do_classifier_free_guidance = do_cfg + cache = self._new_cache() + for timestep in range(num_steps): + for negative in branches: + self._step( + cache, + timestep, + negative, + torch.tensor([1.0 + timestep * 0.01]), + ) + cache.previous_residual = torch.tensor([3.0]) + cache.previous_residual_negative = torch.tensor([7.0]) + self.assertGreater(cache.cnt, 0) + active_distance = ( + cache.accumulated_rel_l1_distance_negative + if branches == (True,) + else cache.accumulated_rel_l1_distance + ) + if num_steps == 2: + self.assertGreater(active_distance, 0) + + self.batch.is_cfg_negative = branches[0] + with set_forward_context(0, None, self.batch): + ctx = cache._get_teacache_context() + self.assertEqual(ctx.is_cfg_negative, branches[0]) + self.assertEqual(cache.cnt, 0) + self.assertIsNone(cache.previous_modulated_input) + self.assertIsNone(cache.previous_modulated_input_negative) + self.assertIsNone(cache.previous_residual) + self.assertIsNone(cache.previous_residual_negative) + self.assertEqual(cache.accumulated_rel_l1_distance, 0.0) + self.assertEqual(cache.accumulated_rel_l1_distance_negative, 0.0) + + fresh = self._new_cache() + for timestep in range(2): + for negative in branches: + inp = torch.tensor([10.0 + negative + timestep * 0.01]) + self.assertEqual( + self._step(cache, timestep, negative, inp), + self._step(fresh, timestep, negative, inp), + ) + self.assertEqual(cache.cnt, fresh.cnt) + + def test_wan_skip_window_matches_timesteps_on_each_cfg_rank(self): + """Serial and CFG-parallel ranks must see the same step-based skip window.""" + self.params.start_skipping = 2 + self.params.end_skipping = -1 + for parallel, branches in ( + (False, (False, True)), + (True, (False,)), + (True, (True,)), + ): + with self.subTest(parallel=parallel, branches=branches): + self.server_args.enable_cfg_parallel = parallel + cache = self._new_cache() + for timestep, expected_calc in enumerate( + (True, True, False, False, True) + ): + for negative in branches: + self.assertEqual( + self._step(cache, timestep, negative, torch.ones(2)), + expected_calc, + f"timestep={timestep}, negative={negative}", + ) + + def test_wan_skip_window_follows_timesteps_under_cfg_gating(self): + """CFG gating stops the negative forward, which must not shift the window.""" + self.params.start_skipping = 2 + self.params.end_skipping = -1 + for gate_step in (1, 3): + with self.subTest(gate_step=gate_step): + cache = self._new_cache() + for timestep, expected_calc in enumerate( + (True, True, False, False, True) + ): + branches = (False, True) if timestep < gate_step else (False,) + for negative in branches: + self.assertEqual( + self._step(cache, timestep, negative, torch.ones(2)), + expected_calc, + f"timestep={timestep}, negative={negative}", + ) + + def test_skip_window_is_measured_in_denoising_steps(self): + """Resolve integer, fractional and negative boundaries in denoising steps.""" + for start, end, expected in ((5, -1, (5, 49)), (0.1, 0.8, (5, 40))): + params = TeaCacheParams(start_skipping=start, end_skipping=end) + with self.subTest(start=start, end=end): + self.assertEqual(params.get_skip_step_range(50), expected) + + +if __name__ == "__main__": + unittest.main()