[diffusion] fix: fix TeaCache CFG state lifecycle and skip boundaries (#42422)

Co-authored-by: Mick Qian <mickqian@users.noreply.github.com>
Co-authored-by: Mick <mickjagger19@icloud.com>
This commit is contained in:
Wenbo Ji 嵇文博
2026-10-09 23:20:13 +08:00
committed by GitHub
co-authored by Mick Qian Mick
parent 121aa8dcc7
commit 76ccf0850c
6 changed files with 217 additions and 31 deletions
@@ -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),
)
+5 -2
View File
@@ -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(
@@ -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"]
@@ -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.
@@ -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,
)
@@ -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()