Skip to content

Add a (rolling) KV cache for Wan models to enable autoregressive rollouts ("SelfForcing"). #13681

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gueraf wants to merge 28 commits into
base: main
Choose a base branch
from
Draft

Add a (rolling) KV cache for Wan models to enable autoregressive rollouts ("SelfForcing"). #13681

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
2ba0504
Add WanRollingKVCache for autoregressive video generation
gueraf May 4, 2026
c1ae837
Add WanRollingKVCache tests
gueraf May 4, 2026
cfba9c4
Refactor WanAttnProcessor and consolidate rolling KV cache tests
gueraf May 4, 2026
7333aed
Fix wasted Q projection, add type annotations, export cache classes, …
gueraf May 4, 2026
249ea24
Convert rolling KV cache tests from unittest.TestCase to plain pytest
gueraf May 5, 2026
d367b55
Trim rolling KV cache tests: remove low-value cases, localize helpers
gueraf May 5, 2026
896d81d
Consolidate rolling KV cache tests into single class
gueraf May 5, 2026
3cdeaaa
Clean up TestWanRollingKVCache for readability
gueraf May 5, 2026
457b05d
Test via public interface: remove private helper imports and trim/sli…
gueraf May 5, 2026
ec5fe30
Fix docstring example: drop explicit window_size=8000 (default is alr…
gueraf May 5, 2026
89705c4
Assert actual key content in rolling KV cache tests; add docstrings
gueraf May 5, 2026
c97fe68
Rewrite cache tests: snapshot/diff pattern, rolled-out loops, assert …
gueraf May 5, 2026
e589a9c
Cover full token range in each test with both _assert_changed and _as…
gueraf May 5, 2026
9f57c6c
Rename _run -> _denoise_chunk
gueraf May 5, 2026
8c16391
Refactor assert helpers to take from_token/to_token ints; clean up ca…
gueraf May 5, 2026
b3ebea0
Remove bogus _assert_changed from append test; only assert prefix pre…
gueraf May 5, 2026
b3d97b1
Restructure cache tests around (mode, window_size); add overwrite chu…
gueraf May 5, 2026
8a82df9
Narrow rolling KV cache API: append + overwrite_end (drop arbitrary o…
gueraf May 5, 2026
b976daf
Test windowed cache with multiple chunks; per-test caches; simplify d…
gueraf May 5, 2026
6a48748
Inline _new_cache helper
gueraf May 6, 2026
6796fa5
Make append mode explicit in append-mode tests
gueraf May 6, 2026
3bb6bba
Rename _chunk -> _make_chunk
gueraf May 6, 2026
3db8298
Assert cache_start_token_offset stays at 0 while filling the window
gueraf May 6, 2026
af366cb
Unify equality assertions on _assert_equal / _assert_not_equal helpers
gueraf May 6, 2026
69462b4
Drop unused should_update flag from WanRollingKVCache
gueraf May 6, 2026
7d658e5
Apply make fixup: ruff formatting and lint fixes
gueraf May 6, 2026
223937e
Drop "self-attention" from docstrings — these classes are not strictl…
gueraf May 6, 2026
3140a38
Match diffusers docstring convention: single-colon Example with markd…
gueraf May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions src/diffusers/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,8 @@
"UVit2DModel",
"VQModel",
"WanAnimateTransformer3DModel",
"WanRollingKVBlockCache",
"WanRollingKVCache",
"WanTransformer3DModel",
"WanVACETransformer3DModel",
"ZImageControlNetModel",
Expand Down Expand Up @@ -1117,6 +1119,8 @@
UVit2DModel,
VQModel,
WanAnimateTransformer3DModel,
WanRollingKVBlockCache,
WanRollingKVCache,
WanTransformer3DModel,
WanVACETransformer3DModel,
ZImageControlNetModel,
Expand Down
8 changes: 7 additions & 1 deletion src/diffusers/models/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,11 @@
_import_structure["transformers.transformer_sd3"] = ["SD3Transformer2DModel"]
_import_structure["transformers.transformer_skyreels_v2"] = ["SkyReelsV2Transformer3DModel"]
_import_structure["transformers.transformer_temporal"] = ["TransformerTemporalModel"]
_import_structure["transformers.transformer_wan"] = ["WanTransformer3DModel"]
_import_structure["transformers.transformer_wan"] = [
"WanRollingKVBlockCache",
"WanRollingKVCache",
"WanTransformer3DModel",
]
_import_structure["transformers.transformer_wan_animate"] = ["WanAnimateTransformer3DModel"]
_import_structure["transformers.transformer_wan_vace"] = ["WanVACETransformer3DModel"]
_import_structure["transformers.transformer_z_image"] = ["ZImageTransformer2DModel"]
Expand Down Expand Up @@ -261,6 +265,8 @@
Transformer2DModel,
TransformerTemporalModel,
WanAnimateTransformer3DModel,
WanRollingKVBlockCache,
WanRollingKVCache,
WanTransformer3DModel,
WanVACETransformer3DModel,
ZImageTransformer2DModel,
Expand Down
2 changes: 1 addition & 1 deletion src/diffusers/models/transformers/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@
from .transformer_sd3 import SD3Transformer2DModel
from .transformer_skyreels_v2 import SkyReelsV2Transformer3DModel
from .transformer_temporal import TransformerTemporalModel
from .transformer_wan import WanTransformer3DModel
from .transformer_wan import WanRollingKVBlockCache, WanRollingKVCache, WanTransformer3DModel
from .transformer_wan_animate import WanAnimateTransformer3DModel
from .transformer_wan_vace import WanVACETransformer3DModel
from .transformer_z_image import ZImageTransformer2DModel
Loading
Loading