cache-dit 0.2.17__py3-none-any.whl → 0.2.19__py3-none-any.whl

cache_dit/__init__.py

@@ -11,6 +11,7 @@ from cache_dit.cache_factory import default_options
 from cache_dit.cache_factory import block_range
 from cache_dit.cache_factory import CacheType
 from cache_dit.compile import set_compile_configs
+from cache_dit.utils import summary
 from cache_dit.logger import init_logger
 
 NONE = CacheType.NONE

cache_dit/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.17'
-__version_tuple__ = version_tuple = (0, 2, 17)
+__version__ = version = '0.2.19'
+__version_tuple__ = version_tuple = (0, 2, 19)
 
 __commit_id__ = commit_id = None

cache_dit/cache_factory/__init__.py

@@ -11,22 +11,31 @@ logger = init_logger(__name__)
 
 
 def load_options(path: str):
-    """cache_dit.load_options(cache_config.yaml)"""
     return load_cache_options_from_yaml(path)
 
 
-def cache_type(type_hint: "CacheType | str") -> CacheType:
+def cache_type(
+    type_hint: "CacheType | str",
+) -> CacheType:
     return CacheType.type(cache_type=type_hint)
 
 
-def default_options(cache_type: CacheType = None) -> Dict:
-    if cache_type is None:
-        return CacheType.default_options(CacheType.DBCache)
+def default_options(
+    cache_type: CacheType = CacheType.DBCache,
+) -> Dict:
     return CacheType.default_options(cache_type)
 
 
-def block_range(start: int, end: int, step: int = 1) -> List[int]:
-    return CacheType.block_range(start, end, step)
+def block_range(
+    start: int,
+    end: int,
+    step: int = 1,
+) -> List[int]:
+    return CacheType.block_range(
+        start,
+        end,
+        step,
+    )
 
 
 def enable_cache(

cache_dit/cache_factory/cache_adapters.py

@@ -464,6 +464,7 @@ class UnifiedCacheAdapter:
 
         pipe.__class__.__call__ = new_call
         pipe.__class__._is_cached = True
+        pipe.__class__._cache_options = cache_kwargs
         return pipe
 
     @classmethod
@@ -630,7 +631,8 @@ class UnifiedCacheAdapter:
                 pattern_id = list(unique_pattern_ids)[0]
                 pattern = selected_patterns[pattern_id]
                 logger.info(
-                    f"Match cache pattern: IN({pattern['IN']}, OUT({pattern['OUT']}))"
+                    f"Match Block Forward Pattern: {transformer_blocks[0].__class__.__name__}"
+                    f"\n IN({pattern['IN']}, \nOUT({pattern['OUT']}))"
                 )
 
         return pattern_matched

cache_dit/cache_factory/patch/flux.py

@@ -230,7 +230,7 @@ def maybe_patch_flux_transformer(
     for block in blocks:
         if isinstance(block, FluxSingleTransformerBlock):
             forward_parameters = inspect.signature(
-                blocks.forward
+                block.forward
             ).parameters.keys()
             if "encoder_hidden_states" not in forward_parameters:
                 block.forward = __patch_single_forward__.__get__(block)

cache_dit/utils.py

@@ -1,7 +1,132 @@
 import torch
+import dataclasses
 import diffusers
+import numpy as np
+from pprint import pprint
+from diffusers import DiffusionPipeline
+
+from cache_dit.logger import init_logger
+
+logger = init_logger(__name__)
 
 
 @torch.compiler.disable
 def is_diffusers_at_least_0_3_5() -> bool:
     return diffusers.__version__ >= "0.35.0"
+
+
+@dataclasses.dataclass
+class CacheStats:
+    cache_options: dict = dataclasses.field(default_factory=dict)
+    cached_steps: list[int] = dataclasses.field(default_factory=list)
+    residual_diffs: dict[str, float] = dataclasses.field(default_factory=dict)
+    cfg_cached_steps: list[int] = dataclasses.field(default_factory=list)
+    cfg_residual_diffs: dict[str, float] = dataclasses.field(
+        default_factory=dict
+    )
+
+
+def summary(pipe: DiffusionPipeline, details: bool = False):
+    cache_stats = CacheStats()
+    pipe_cls_name = pipe.__class__.__name__
+
+    if hasattr(pipe, "_cache_options"):
+        cache_options = pipe._cache_options
+        cache_stats.cache_options = cache_options
+        print(f"\n🤗Cache Options: {pipe_cls_name}\n\n{cache_options}")
+
+    if hasattr(pipe.transformer, "_cached_steps"):
+        cached_steps: list[int] = pipe.transformer._cached_steps
+        residual_diffs: dict[str, float] = pipe.transformer._residual_diffs
+        cache_stats.cached_steps = cached_steps
+        cache_stats.residual_diffs = residual_diffs
+
+        if residual_diffs:
+            diffs_values = list(residual_diffs.values())
+            q0 = np.percentile(diffs_values, 0)
+            q1 = np.percentile(diffs_values, 25)
+            q2 = np.percentile(diffs_values, 50)
+            q3 = np.percentile(diffs_values, 75)
+            q4 = np.percentile(diffs_values, 95)
+
+            print(
+                f"\n⚡️Cache Steps and Residual Diffs Statistics: {pipe_cls_name}\n"
+            )
+
+            print(
+                "| Cache Steps | Diffs P00 | Diffs P25 | Diffs P50 | Diffs P75 | Diffs P95 |"
+            )
+            print(
+                "|-------------|-----------|-----------|-----------|-----------|-----------|"
+            )
+            print(
+                f"| {len(cached_steps):<11} | {round(q0, 3):<9} | {round(q1, 3):<9} "
+                f"| {round(q2, 3):<9} | {round(q3, 3):<9} | {round(q4, 3):<9} |"
+            )
+            print("")
+
+            if details:
+                print(
+                    f"📚Cache Steps and Residual Diffs Details: {pipe_cls_name}\n"
+                )
+                print("-" * 200)
+                pprint(
+                    f"Cache Steps: {len(cached_steps)}, {cached_steps}",
+                    width=200,
+                )
+                pprint(
+                    f"Residual Diffs: {len(residual_diffs)}, {residual_diffs}",
+                    compact=True,
+                    width=200,
+                )
+                print("-" * 200)
+
+    if hasattr(pipe.transformer, "_cfg_cached_steps"):
+        cfg_cached_steps: list[int] = pipe.transformer._cfg_cached_steps
+        cfg_residual_diffs: dict[str, float] = (
+            pipe.transformer._cfg_residual_diffs
+        )
+        cache_stats.cfg_cached_steps = cfg_cached_steps
+        cache_stats.cfg_residual_diffs = cfg_residual_diffs
+
+        if cfg_residual_diffs:
+            cfg_diffs_values = list(cfg_residual_diffs.values())
+            q0 = np.percentile(cfg_diffs_values, 0)
+            q1 = np.percentile(cfg_diffs_values, 25)
+            q2 = np.percentile(cfg_diffs_values, 50)
+            q3 = np.percentile(cfg_diffs_values, 75)
+            q4 = np.percentile(cfg_diffs_values, 95)
+
+            print(
+                f"\n⚡️CFG Cache Steps and Residual Diffs Statistics: {pipe_cls_name}\n"
+            )
+
+            print(
+                "| CFG Cache Steps | Diffs P00 | Diffs P25 | Diffs P50 | Diffs P75 | Diffs P95 |"
+            )
+            print(
+                "|-----------------|-----------|-----------|-----------|-----------|-----------|"
+            )
+            print(
+                f"| {len(cfg_cached_steps):<15} | {round(q0, 3):<9} | {round(q1, 3):<9} "
+                f"| {round(q2, 3):<9} | {round(q3, 3):<9} | {round(q4, 3):<9} |"
+            )
+            print("")
+
+            if details:
+                print(
+                    f"📚CFG Cache Steps and Residual Diffs Details: {pipe_cls_name}\n"
+                )
+                print("-" * 200)
+                pprint(
+                    f"CFG Cache Steps: {len(cfg_cached_steps)}, {cfg_cached_steps}",
+                    width=200,
+                )
+                pprint(
+                    f"CFG Residual Diffs: {len(cfg_residual_diffs)}, {cfg_residual_diffs}",
+                    compact=True,
+                    width=200,
+                )
+                print("-" * 200)
+
+    return cache_stats

{cache_dit-0.2.17.dist-info → cache_dit-0.2.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cache_dit
-Version: 0.2.17
+Version: 0.2.19
 Summary: 🤗 CacheDiT: An Unified and Training-free Cache Acceleration Toolbox for Diffusion Transformers
 Author: DefTruth, vipshop.com, etc.
 Maintainer: DefTruth, vipshop.com, etc
@@ -61,15 +61,15 @@ Dynamic: requires-python
   </p>
 </div> 
 
-
 ## 🔥News  
 
+- [2025-08-19] 🔥[**Qwen-Image-Edit**](https://github.com/QwenLM/Qwen-Image) **2x⚡️** speedup! Check example [run_qwen_image_edit.py](./examples/run_qwen_image_edit.py).
 - [2025-08-18] 🎉Early **[Unified Cache APIs](#unified)** released! Check [Qwen-Image w/ UAPI](./examples/run_qwen_image_uapi.py) as an example.
 - [2025-08-12] 🎉First caching mechanism in [QwenLM/Qwen-Image](https://github.com/QwenLM/Qwen-Image) with **[cache-dit](https://github.com/vipshop/cache-dit)**, check the [PR](https://github.com/QwenLM/Qwen-Image/pull/61). 
-- [2025-08-11] 🔥[Qwen-Image](https://github.com/QwenLM/Qwen-Image) is supported now! Please refer [run_qwen_image.py](./examples/run_qwen_image.py) as an example.
-- [2025-08-10] 🔥[FLUX.1-Kontext-dev](https://huggingface.co/black-forest-labs/FLUX.1-Kontext-dev) is supported! Please refer [run_flux_kontext.py](./examples/run_flux_kontext.py) as an example.
+- [2025-08-11] 🔥[**Qwen-Image**](https://github.com/QwenLM/Qwen-Image) **1.8x⚡️** speedup! Please refer [run_qwen_image.py](./examples/run_qwen_image.py) as an example.
+- [2025-08-10] 🔥[**FLUX.1-Kontext-dev**](https://huggingface.co/black-forest-labs/FLUX.1-Kontext-dev) is supported! Please refer [run_flux_kontext.py](./examples/run_flux_kontext.py) as an example.
 - [2025-07-18] 🎉First caching mechanism in [🤗huggingface/flux-fast](https://github.com/huggingface/flux-fast) with **[cache-dit](https://github.com/vipshop/cache-dit)**, check the [PR](https://github.com/huggingface/flux-fast/pull/13). 
-- [2025-07-13] **[🤗flux-faster](https://github.com/xlite-dev/flux-faster)** is released! **3.3x** speedup for FLUX.1 on NVIDIA L20 with `cache-dit`.
+- [2025-07-13] **[🤗flux-faster](https://github.com/xlite-dev/flux-faster)** is released! **3.3x** speedup for FLUX.1 on NVIDIA L20 with **[cache-dit](https://github.com/vipshop/cache-dit)**.
 
 ## 📖Contents 
 
@@ -105,6 +105,7 @@ pip3 install git+https://github.com/vipshop/cache-dit.git
 
 Currently, **cache-dit** library supports almost **Any** Diffusion Transformers (with **Transformer Blocks** that match the specific Input and Output **patterns**). Please check [🎉Unified Cache APIs](#unified) for more details. Here are just some of the tested models listed:
 
+- [🚀Qwen-Image-Edit](https://github.com/vipshop/cache-dit/raw/main/examples)  
 - [🚀Qwen-Image](https://github.com/vipshop/cache-dit/raw/main/examples)  
 - [🚀FLUX.1-dev](https://github.com/vipshop/cache-dit/raw/main/examples)  
 - [🚀FLUX.1-Fill-dev](https://github.com/vipshop/cache-dit/raw/main/examples)  
@@ -128,34 +129,51 @@ Currently, **cache-dit** library supports almost **Any** Diffusion Transformers
 
 <div id="unified"></div>  
 
+Currently, for any **Diffusion** models with **Transformer Blocks** that match the specific **Input/Output patterns**, we can use the **Unified Cache APIs** from **cache-dit**, namely, the `cache_dit.enable_cache(...)` API. The supported patterns are listed as follows:
 
-Currently, for any **Diffusion** models with **Transformer Blocks** that match the specific **Input/Output pattern**, we can use the **Unified Cache APIs** from **cache-dit**. The supported patterns are listed as follows:
-
-```bash
+```python
 (IN: hidden_states, encoder_hidden_states, ...) -> (OUT: hidden_states, encoder_hidden_states)  
 (IN: hidden_states, encoder_hidden_states, ...) -> (OUT: encoder_hidden_states, hidden_states)  
 (IN: hidden_states, encoder_hidden_states, ...) -> (OUT: hidden_states)
 (IN: hidden_states, ...) -> (OUT: hidden_states) # TODO, DiT, Lumina2, etc. 
 ```
 
-Please refer to [Qwen-Image w/ UAPI](./examples/run_qwen_image_uapi.py) as an example. The `pipe` parameter can be **Any** Diffusion Pipelines. The **Unified Cache APIs** are currently in the experimental phase, please stay tuned for updates. 
+After the `cache_dit.enable_cache(...)` API is called, you just need to call the pipe as normal. The `pipe` param can be **any** Diffusion Pipeline. Please refer to [Qwen-Image](./examples/run_qwen_image_uapi.py) as an example. The **Unified Cache APIs** are currently in the experimental phase; please stay tuned for updates.
 
 ```python
 import cache_dit
-from diffusers import DiffusionPipeline # Can be [Any] Diffusion Pipeline
+from diffusers import DiffusionPipeline 
 
+# can be any diffusion pipeline
 pipe = DiffusionPipeline.from_pretrained("Qwen/Qwen-Image")
 
-# Just use the one line code with default cache options.
+# one line code with default cache options.
 cache_dit.enable_cache(pipe) 
 
-# Or, enable cache with custom setting according to your models.
+# or, enable cache with custom settings.
 cache_dit.enable_cache(
     pipe, transformer=pipe.transformer,
     blocks=pipe.transformer.transformer_blocks,
     return_hidden_states_first=False,
     **cache_dit.default_options(),
 )
+
+# just call the pipe as normal.
+output = pipe(...)
+
+# then, summary the cache stats.
+stats = cache_dit.summary(pipe)
+```
+
+After finishing each inference of `pipe(...)`, you can call the `cache_dit.summary(...)` API on pipe to get the details of the cache stats for the current inference (markdown table format). You can set `details` param as `True` to show more details of cache stats.
+
+```python
+⚡️Cache Steps and Residual Diffs Statistics: QwenImagePipeline
+
+| Cache Steps | Diffs P00 | Diffs P25 | Diffs P50 | Diffs P75 | Diffs P95 |
+|-------------|-----------|-----------|-----------|-----------|-----------|
+| 23          | 0.04      | 0.082     | 0.115     | 0.152     | 0.245     |
+...
 ```
 
 ## ⚡️DBCache: Dual Block Cache  

{cache_dit-0.2.17.dist-info → cache_dit-0.2.19.dist-info}/RECORD

@@ -1,17 +1,17 @@
-cache_dit/__init__.py,sha256=gRJrSVrj-700qjgjwHfcHkiIHKbGm2cutP1TybxQZk4,605
-cache_dit/_version.py,sha256=sRnPbdnyLakHrE7uBPRC_AQNPiFphtVIa4BPaftkqk4,706
+cache_dit/__init__.py,sha256=TvZI861ipGnYaOEHJA0Og-ksRUGNCld-PGy_NgjcKZE,641
+cache_dit/_version.py,sha256=32XF9c5EeiOUdyiWeKcwkXTWZQBgtvbmKx8wZoDEW0o,706
 cache_dit/logger.py,sha256=0zsu42hN-3-rgGC_C29ms1IvVpV4_b4_SwJCKSenxBE,4304
 cache_dit/primitives.py,sha256=A2iG9YLot3gOsZSPp-_gyjqjLgJvWQRx8aitD4JQ23Y,3877
-cache_dit/utils.py,sha256=4cFNh0asch6Zgsixq0bS1ElfwBu_6BG5ZSmaa1khjyg,144
+cache_dit/utils.py,sha256=yybhUTGPfeCoIVZzpoefZ2ypvH8de-10UhPls81ceG4,4800
 cache_dit/cache_factory/.gitignore,sha256=5Cb-qT9wsTUoMJ7vACDF7ZcLpAXhi5v-xdcWSRit988,23
-cache_dit/cache_factory/__init__.py,sha256=2td8ivq0DDzu00Kq1oPvq0Bh5C76w_gwsMfyUo2xW9U,1652
-cache_dit/cache_factory/cache_adapters.py,sha256=ECYRvgx6ePX6Jd6sqUXmXi6kbWaqlOdvm6aZLhpedW0,23455
+cache_dit/cache_factory/__init__.py,sha256=f4IUOgEALTEBb9UOHtXoGwqKrDb2ZhI_dHkiIrni1Xc,1586
+cache_dit/cache_factory/cache_adapters.py,sha256=-bFMOfIPdfWKTAfF533PuLYaDl1wq8RNUAXJn--Rm7I,23587
 cache_dit/cache_factory/cache_blocks.py,sha256=9jgK2IT0Y_AlbhJLnhgA47lOxQNwNizDgHve45818gg,18390
 cache_dit/cache_factory/cache_context.py,sha256=f-ihx14NXIZNakN2b_dduegRpJr5SwcPtc2PqnpDdUY,39818
 cache_dit/cache_factory/taylorseer.py,sha256=LKSNo2ode69EVo9xrxjxAMEjz0yDGiGADeDYnEqddA8,3987
 cache_dit/cache_factory/utils.py,sha256=iQg3dqBfQTGkvMdKeO5-YmzkQO5LBSoZ8sYKwQA_7_I,1805
 cache_dit/cache_factory/patch/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cache_dit/cache_factory/patch/flux.py,sha256=eTdq-3limKHgwtVCILkZTwt9FwYUhH7_VlhKnfu55BU,8999
+cache_dit/cache_factory/patch/flux.py,sha256=iNQ-1RlOgXupZ4uPiEvJ__Ro6vKT_fOKja9JrpMrO78,8998
 cache_dit/compile/__init__.py,sha256=FcTVzCeyypl-mxlc59_ehHL3lBNiDAFsXuRoJ-5Cfi0,56
 cache_dit/compile/utils.py,sha256=ugHrv3QRieG1xKwcg_pi3yVZF6EpSOEJjRmbnfa7VG0,3779
 cache_dit/custom_ops/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -22,9 +22,9 @@ cache_dit/metrics/fid.py,sha256=9Ivtazl6mW0Bon2VXa-Ia5Xj2ewxRD3V1Qkd69zYM3Y,1706
 cache_dit/metrics/inception.py,sha256=pBVe2X6ylLPIXTG4-GWDM9DWnCviMJbJ45R3ulhktR0,12759
 cache_dit/metrics/lpips.py,sha256=I2qCNi6qJh5TRsaIsdxO0WoRX1DN7U_H3zS0oCSahYM,1032
 cache_dit/metrics/metrics.py,sha256=8jvM1sF-nDxUuwCRy44QEoo4dYVLCQVh1QyAMs4eaQY,27840
-cache_dit-0.2.17.dist-info/licenses/LICENSE,sha256=Dqb07Ik2dV41s9nIdMUbiRWEfDqo7-dQeRiY7kPO8PE,3769
-cache_dit-0.2.17.dist-info/METADATA,sha256=HqEAEr08N7whWcxOMOVJKThQPglCW_GAj-LcynXmIDI,19804
-cache_dit-0.2.17.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-cache_dit-0.2.17.dist-info/entry_points.txt,sha256=FX2gysXaZx6NeK1iCLMcIdP8Q4_qikkIHtEmi3oWn8o,65
-cache_dit-0.2.17.dist-info/top_level.txt,sha256=ZJDydonLEhujzz0FOkVbO-BqfzO9d_VqRHmZU-3MOZo,10
-cache_dit-0.2.17.dist-info/RECORD,,
+cache_dit-0.2.19.dist-info/licenses/LICENSE,sha256=Dqb07Ik2dV41s9nIdMUbiRWEfDqo7-dQeRiY7kPO8PE,3769
+cache_dit-0.2.19.dist-info/METADATA,sha256=cCnv_b_F06xdttqdHhnbmPDpF_xRgz-O03tYfvzGGrI,20910
+cache_dit-0.2.19.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cache_dit-0.2.19.dist-info/entry_points.txt,sha256=FX2gysXaZx6NeK1iCLMcIdP8Q4_qikkIHtEmi3oWn8o,65
+cache_dit-0.2.19.dist-info/top_level.txt,sha256=ZJDydonLEhujzz0FOkVbO-BqfzO9d_VqRHmZU-3MOZo,10
+cache_dit-0.2.19.dist-info/RECORD,,