# キャッシュ手法

Cacheメソッドは、attention層やfeedforward層などの特定の層の中間出力を保存して再利用することで、各推論ステップでの再計算を回避し、diffusion transformerを高速化します。

## CacheMixin[[diffusers.CacheMixin]]

#### diffusers.CacheMixin[[diffusers.CacheMixin]]

```python
diffusers.CacheMixin()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/cache_utils.py#L23)

拡散モデルにおけるキャッシュ技術の有効化/無効化を行うクラスです。

サポートされているキャッシュ技術:
- [ピラミッドアテンションブロードキャスト](https://huggingface.co/papers/2408.12588)
- [FasterCache](https://huggingface.co/papers/2410.19355)
- [FirstBlockCache](https://github.com/chengzeyi/ParaAttention/blob/7a266123671b55e7e5a2fe9af3121f07a36afc78/README.md#first-block-cache-our-dynamic-caching)
- [SeaCache](https://huggingface.co/papers/2602.18993)

#### cache_context[[diffusers.CacheMixin.cache_context]]

```python
cache_context(name: str, **kwargs)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/cache_utils.py#L181)

キャッシュ管理のための情報を提供するコンテキストマネージャー。

`name` はデノイジング呼び出しの名前で、通常は `"cond"` または `"uncond"` です。キーワード引数は、デノイジングループがどこにあるかを記述します。受け入れられるフィールドについては `CacheContext` を参照してください。例: `cache_context("cond", step_index=i, sigma=sigma)`。

#### enable_cache[[diffusers.CacheMixin.enable_cache]]

```python
enable_cache(config)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/cache_utils.py#L40)

**パラメータ:**

config (`PyramidAttentionBroadcastConfig | FasterCacheConfig | FirstBlockCacheConfig | SeaCacheConfig | TextKVCacheConfig`) : キャッシング手法を適用するための設定です。現在サポートされているキャッシング手法は以下の通りです: - [PyramidAttentionBroadcastConfig](/docs/diffusers/main/ja/api/cache#diffusers.PyramidAttentionBroadcastConfig) - [FasterCacheConfig](/docs/diffusers/main/ja/api/cache#diffusers.FasterCacheConfig) - [FirstBlockCacheConfig](/docs/diffusers/main/ja/api/cache#diffusers.FirstBlockCacheConfig) - [SeaCacheConfig](/docs/diffusers/main/ja/api/cache#diffusers.SeaCacheConfig) - [TextKVCacheConfig](/docs/diffusers/main/ja/api/cache#diffusers.TextKVCacheConfig)

モデルでキャッシュ技術を有効にします。

例:

```python
>>> import torch
>>> from diffusers import CogVideoXPipeline, PyramidAttentionBroadcastConfig

>>> pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-5b", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> config = PyramidAttentionBroadcastConfig(
...     spatial_attention_block_skip_range=2,
...     spatial_attention_timestep_skip_range=(100, 800),
...     current_timestep_callback=lambda: pipe.current_timestep,
... )
>>> pipe.transformer.enable_cache(config)
```

## PyramidAttentionBroadcastConfig[[diffusers.PyramidAttentionBroadcastConfig]]

#### diffusers.PyramidAttentionBroadcastConfig[[diffusers.PyramidAttentionBroadcastConfig]]

```python
diffusers.PyramidAttentionBroadcastConfig(spatial_attention_block_skip_range: int | None = None, temporal_attention_block_skip_range: int | None = None, cross_attention_block_skip_range: int | None = None, spatial_attention_timestep_skip_range: tuple[int, int] = (100, 800), temporal_attention_timestep_skip_range: tuple[int, int] = (100, 800), cross_attention_timestep_skip_range: tuple[int, int] = (100, 800), spatial_attention_block_identifiers: tuple[str, ...] = ('blocks', 'transformer_blocks', 'single_transformer_blocks', 'layers', 'visual_transformer_blocks'), temporal_attention_block_identifiers: tuple[str, ...] = ('temporal_transformer_blocks',), cross_attention_block_identifiers: tuple[str, ...] = ('blocks', 'transformer_blocks', 'layers'), current_timestep_callback: typing.Callable[[], int] = None)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/pyramid_attention_broadcast.py#L40)

**パラメータ:**

spatial_attention_block_skip_range (`int`, *任意*, デフォルトは `None`) : 再利用するアテンション状態を計算する前に、特定の空間アテンションブロードキャストがスキップされる回数です。この値が `N` に設定されている場合、新しいアテンション状態を再計算する前に、アテンションの計算が `N - 1` 回スキップされます（つまり、古いアテンション状態が再利用されます）。

temporal_attention_block_skip_range (`int`, *任意*, デフォルトは `None`) : 再利用するアテンション状態を計算する前に、特定の時間アテンションのブロードキャストがスキップされる回数です。この値が `N` に設定されている場合、新しいアテンション状態を再計算する前に、アテンションの計算が `N - 1` 回スキップされます（つまり、古いアテンション状態が再利用されます）。

cross_attention_block_skip_range (`int`、*任意*、デフォルトは`None`) : 再利用するアテンション状態を計算する前に、特定のクロスアテンションのブロードキャストがスキップされる回数です。この値が`N`に設定されている場合、新しいアテンション状態を再計算する前に、アテンションの計算が`N - 1`回スキップされます（つまり、古いアテンション状態が再利用されます）。

spatial_attention_timestep_skip_range (`tuple[int, int]`、デフォルトは`(100, 800)`) : 空間アテンション層でスキップするタイムステップの範囲です。現在のタイムステップが指定された範囲内にある場合、アテンションの計算は条件付きでスキップされます。

temporal_attention_timestep_skip_range (`tuple[int, int]`、デフォルトは`(100, 800)`) : 時間方向アテンション層でスキップするタイムステップの範囲です。現在のタイムステップが指定された範囲内にある場合、アテンションの計算は条件付きでスキップされます。

cross_attention_timestep_skip_range (`tuple[int, int]`、デフォルトは`(100, 800)`) : クロスアテンション層でスキップするタイムステップの範囲です。現在のタイムステップが指定された範囲内にある場合、アテンションの計算は条件付きでスキップされます。

spatial_attention_block_identifiers (`tuple[str, ...]`) : レイヤーが空間アテンションレイヤーかどうかを判定するために、レイヤー名と照合する識別子。

temporal_attention_block_identifiers (`tuple[str, ...]`) : 層が時間的アテンション層かどうかを判定するために、層名と照合する識別子。

cross_attention_block_identifiers (`tuple[str, ...]`) : レイヤー名と照合して、そのレイヤーがクロスアテンションレイヤーかどうかを判定するために使用する識別子。

Pyramid Attention Broadcastの設定

#### diffusers.apply_pyramid_attention_broadcast[[diffusers.apply_pyramid_attention_broadcast]]

```python
diffusers.apply_pyramid_attention_broadcast(module: Module, config: PyramidAttentionBroadcastConfig)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/pyramid_attention_broadcast.py#L181)

**パラメータ:**

module (`torch.nn.Module`) : Pyramid Attention Broadcast を適用するモジュール。

config (`PyramidAttentionBroadcastConfig | None`, `optional`, デフォルトは `None`) : Pyramid Attention Broadcast に使用する設定です。

指定されたパイプラインに[Pyramid Attention Broadcast](https://huggingface.co/papers/2408.12588)を適用します。

PABは、タイムステップ間のアテンション状態の類似性を活用して、アテンション計算の計算コストを削減するアテンション近似手法です。論文の要点は、タイムステップ間のクロスアテンション層におけるアテンションの類似性が最も高く、次に時間軸層と空間軸層の順に類似性が低くなるという点です。これにより、時間軸層や空間軸層よりも、クロスアテンション層のアテンション計算をより頻繁にスキップすることが可能になります。したがって、PABを適用することで、推論プロセスが高速化されます。

例:

```python
>>> import torch
>>> from diffusers import CogVideoXPipeline, PyramidAttentionBroadcastConfig, apply_pyramid_attention_broadcast
>>> from diffusers.utils import export_to_video

>>> pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-5b", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> config = PyramidAttentionBroadcastConfig(
...     spatial_attention_block_skip_range=2,
...     spatial_attention_timestep_skip_range=(100, 800),
...     current_timestep_callback=lambda: pipe.current_timestep,
... )
>>> apply_pyramid_attention_broadcast(pipe.transformer, config)
```

## FasterCacheConfig[[diffusers.FasterCacheConfig]]

#### diffusers.FasterCacheConfig[[diffusers.FasterCacheConfig]]

```python
diffusers.FasterCacheConfig(spatial_attention_block_skip_range: int = 2, temporal_attention_block_skip_range: int | None = None, spatial_attention_timestep_skip_range: tuple[int, int] = (-1, 681), temporal_attention_timestep_skip_range: tuple[int, int] = (-1, 681), low_frequency_weight_update_timestep_range: tuple[int, int] = (99, 901), high_frequency_weight_update_timestep_range: tuple[int, int] = (-1, 301), alpha_low_frequency: float = 1.1, alpha_high_frequency: float = 1.1, unconditional_batch_skip_range: int = 5, unconditional_batch_timestep_skip_range: tuple[int, int] = (-1, 641), spatial_attention_block_identifiers: tuple[str, ...] = ('^blocks.*attn', '^transformer_blocks.*attn', '^single_transformer_blocks.*attn'), temporal_attention_block_identifiers: tuple[str, ...] = ('^temporal_transformer_blocks.*attn',), attention_weight_callback: typing.Callable[[torch.nn.Module], float] = None, low_frequency_weight_callback: typing.Callable[[torch.nn.Module], float] = None, high_frequency_weight_callback: typing.Callable[[torch.nn.Module], float] = None, tensor_format: str = 'BCFHW', is_guidance_distilled: bool = False, current_timestep_callback: typing.Callable[[], int] = None, _unconditional_conditional_input_kwargs_identifiers: list[str] = ('hidden_states', 'encoder_hidden_states', 'timestep', 'attention_mask', 'encoder_attention_mask'))
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/faster_cache.py#L50)

**パラメータ:**

spatial_attention_block_skip_range (`int`、デフォルトは`2`) : `N`回ごとにアテンション状態を計算します。これを`N`に設定すると、新しいアテンション状態を再計算する前に、アテンションの計算が`N - 1`回スキップされます（つまり、キャッシュされたアテンション状態が再利用されます）。

temporal_attention_block_skip_range (`int`, *任意*, デフォルトは `None`) : `N` 回のイテレーションごとにアテンション状態を計算します。これを `N` に設定すると、新しいアテンション状態を再計算する前に、アテンションの計算が `N - 1` 回スキップされます（つまり、キャッシュされたアテンション状態が再利用されます）。

spatial_attention_timestep_skip_range (`tuple[float, float]`、デフォルトは `(-1, 681)`) : 品質に大きな損失を与えずに空間アテンションの計算をスキップできるタイムステップの範囲です。これは、使用するモデルに基づいてユーザーが決定する必要があります。タプルの最初の値は下限、2番目の値は上限です。一般的に、デノイジング用の拡散タイムステップは 0 から 1000 の逆順の範囲（つまり、デノイジングはタイムステップ 1000 で始まり、タイムステップ 0 で終わる）にあります。デフォルト値の場合、これはデノイジングのタイムステップ 681 に到達した後にのみ空間アテンションの計算スキップが適用され、デノイジングプロセスの終了まで継続されることを意味します。

temporal_attention_timestep_skip_range (`tuple[float, float]`、*optional*、デフォルトは`None`) : 品質に大きな損失を与えずに temporal attention の計算をスキップできるタイムステップの範囲です。これは、ベースとなるモデルに基づいてユーザーが決定する必要があります。タプルの最初の値は下限、2番目の値は上限です。一般的に、デノイジング用の拡散タイムステップは 0 から 1000 の逆順の範囲（つまり、デノイジングはタイムステップ 1000 で始まり、タイムステップ 0 で終わる）にあります。

low_frequency_weight_update_timestep_range (`tuple[int, int]`、デフォルトは`(99, 901)`) : 低周波数重みスケーリングの更新が適用されるタイムステップの範囲です。タプルの最初の値はタイムステップ範囲の下限、2番目の値は上限です。更新用のコールバック関数は、この範囲内でのみ呼び出されます。

high_frequency_weight_update_timestep_range (`tuple[int, int]`、デフォルトは`(-1, 301)`) : 高周波数重みスケーリングの更新が適用されるタイムステップの範囲です。タプルの最初の値はタイムステップ範囲の下限、2番目の値は上限です。更新用のコールバック関数は、この範囲内でのみ呼び出されます。

alpha_low_frequency (`float`、デフォルトは`1.1`) : 低周波数更新をスケーリングするための重みです。これは、条件付きブランチの出力から無条件ブランチを近似するために使用されます。

alpha_high_frequency (`float`、デフォルトは`1.1`) : 高周波更新をスケーリングするための重みです。これは、条件付きブランチの出力から無条件ブランチを近似するために使用されます。

unconditional_batch_skip_range (`int`、デフォルトは`5`) : 無条件分岐を`N`回ごとに処理します。これを`N`に設定すると、新しい無条件分岐の状態を再計算する前に、無条件分岐の計算が`N - 1`回スキップされます（つまり、キャッシュされた無条件分岐の状態が再利用されます）。

unconditional_batch_timestep_skip_range (`tuple[float, float]`、デフォルトは`(-1, 641)`) : 無条件ブランチの計算を、品質に大きな損失なしにスキップできるタイムステップの範囲です。これは、使用するモデルに基づいてユーザーが決定する必要があります。タプルの最初の値は下限、2番目の値は上限です。

spatial_attention_block_identifiers (`tuple[str, ...]`、デフォルトは`("blocks.*attn1", "transformer_blocks.*attn1", "single_transformer_blocks.*attn1")`) : モデル内の空間アテンションブロックに一致させる識別子です。ブロック名にこれらの識別子のいずれかが含まれている場合、FasterCache がそのブロックに適用されます。これは、完全なレイヤー名、部分レイヤー名、または正規表現パターンとして指定できます。一致判定は常に正規表現マッチングによって行われます。

temporal_attention_block_identifiers (`tuple[str, ...]`、デフォルトは`("temporal_transformer_blocks.*attn1",)`) : モデル内の時間的アテンションブロックに一致させる識別子です。ブロック名にこれらの識別子のいずれかが含まれている場合、そのブロックに FasterCache が適用されます。これは、完全なレイヤー名、部分レイヤー名、または正規表現パターンとして指定できます。一致判定は常に正規表現マッチングによって行われます。

attention_weight_callback (`Callable[[torch.nn.Module], float]`、デフォルトは `None`) : attention の出力をスケーリングするための重みを決定するコールバック関数です。この関数は attention モジュールを入力として受け取り、float 値を返す必要があります。これは、条件付きブランチの出力から無条件ブランチを近似するために使用されます。指定されない場合、すべてのタイムステップでデフォルトの重みは 0.5 になります。論文で説明されているように、通常、この重みは推論が進むにつれて 0 から 1 へ徐々に増加させるべきです。ユーザーには、デノイジングが進むにつれて推論ステップ数やベースとなるモデルの挙動を考慮した独自の重みスケジュールの実験と提供を推奨します。

low_frequency_weight_callback (`Callable[[torch.nn.Module], float]`、デフォルトは `None`) : 低周波数更新をスケーリングするための重みを決定するコールバック関数です。指定されない場合、デフォルトの重みは、論文で説明されている範囲内のタイムステップに対して 1.1 になります。

high_frequency_weight_callback (`Callable[[torch.nn.Module], float]`、デフォルトは `None`) : 高周波更新をスケーリングするための重みを決定するコールバック関数です。指定されない場合、デフォルトの重みは、論文で説明されている範囲内のタイムステップに対して 1.1 になります。

tensor_format (`str`、デフォルトは `"BCFHW"`) : 入力テンソルの形式です。`"BCFHW"`、`"BFCHW"`、または `"BCHW"` のいずれかである必要があります。この形式は、低周波数成分と高周波数成分を計算するために、個々の潜在フレームを分割する際に使用されます。

is_guidance_distilled (`bool`、デフォルトは`False`) : モデルがguidance distilledかどうかを指定します。モデルがguidance distilledの場合、FasterCacheはdenoiserレベルでは適用されません（unconditional branchの計算が存在しないため、スキップ対象がないためです）。

_unconditional_conditional_input_kwargs_identifiers (`list[str]`、デフォルトは `("hidden_states", "encoder_hidden_states", "timestep", "attention_mask", "encoder_attention_mask")`) : バッチ内で連結された無条件入力と条件付き入力を含む入力 kwargs を識別するための識別子です。入力 kwargs の名前がこれらの識別子のいずれかを含む場合、FasterCache は入力を無条件ブランチと条件付きブランチに分割します。これは、バッチ内で連結された無条件入力と条件付き入力を含む入力 kwargs の正確な名前のリストでなければなりません。

[FasterCache](https://huggingface.co/papers/2410.19355)の設定。

#### diffusers.apply_faster_cache[[diffusers.apply_faster_cache]]

```python
diffusers.apply_faster_cache(module: Module, config: FasterCacheConfig)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/faster_cache.py#L486)

**パラメータ:**

module (`torch.nn.Module`) : FasterCache を適用する PyTorch モジュールです。通常、Diffusers でサポートされている Transformer アーキテクチャ、例えば `CogVideoXTransformer3DModel` などが該当しますが、外部の実装でも動作する場合があります。

config (`FasterCacheConfig`) : FasterCache に使用する設定。

指定されたパイプラインに[FasterCache](https://huggingface.co/papers/2410.19355)を適用します。

例:
```python
>>> import torch
>>> from diffusers import CogVideoXPipeline, FasterCacheConfig, apply_faster_cache

>>> pipe = CogVideoXPipeline.from_pretrained("THUDM/CogVideoX-5b", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> config = FasterCacheConfig(
...     spatial_attention_block_skip_range=2,
...     spatial_attention_timestep_skip_range=(-1, 681),
...     low_frequency_weight_update_timestep_range=(99, 641),
...     high_frequency_weight_update_timestep_range=(-1, 301),
...     spatial_attention_block_identifiers=["transformer_blocks"],
...     attention_weight_callback=lambda _: 0.3,
...     tensor_format="BFCHW",
... )
>>> apply_faster_cache(pipe.transformer, config)
```

## FirstBlockCacheConfig[[diffusers.FirstBlockCacheConfig]]

#### diffusers.FirstBlockCacheConfig[[diffusers.FirstBlockCacheConfig]]

```python
diffusers.FirstBlockCacheConfig(threshold: float = 0.05)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/first_block_cache.py#L33)

**パラメータ:**

threshold (`float`、デフォルトは`0.05`) : モデルの全レイヤーをフォワードパスで処理する必要があるかどうかを判定するための閾値です。閾値を高くすると、フォワードパスで処理されるレイヤー数が少なくなり推論が高速化される傾向がありますが、生成品質が低下する可能性があります。一方、閾値を低くしても、生成速度の大幅な向上にはつながらない場合があります。この閾値は、最初の Transformer ブロックからの現在の出力とキャッシュされた出力の残差の absmean 差と比較されます。差が閾値未満の場合、フォワードパスはスキップされます。

[First Block Cache](https://github.com/chengzeyi/ParaAttention/blob/7a266123671b55e7e5a2fe9af3121f07a36afc78/README.md#first-block-cache-our-dynamic-caching)の設定。

#### diffusers.apply_first_block_cache[[diffusers.apply_first_block_cache]]

```python
diffusers.apply_first_block_cache(module: Module, config: FirstBlockCacheConfig)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/first_block_cache.py#L193)

**パラメータ:**

module (`torch.nn.Module`) : FBCache を適用する PyTorch モジュールです。通常、Diffusers でサポートされている Transformer アーキテクチャ、例えば `CogVideoXTransformer3DModel` などが該当しますが、外部の実装でも動作する場合があります。

config (`FirstBlockCacheConfig`) : FBCache手法を適用するために使用する設定。

指定されたモジュールに[First Block Cache](https://github.com/chengzeyi/ParaAttention/blob/4de137c5b96416489f06e43e19f2c14a772e28fd/README.md#first-block-cache-our-dynamic-caching)を適用します。

First Block Cache は [TeaCache](https://huggingface.co/papers/2411.19108) のアイデアを基に構築されています。幅広いモデルに対して汎用的に実装しやすく、まず実験目的で統合されました。

例:
```python
>>> import torch
>>> from diffusers import CogView4Pipeline
>>> from diffusers.hooks import apply_first_block_cache, FirstBlockCacheConfig

>>> pipe = CogView4Pipeline.from_pretrained("THUDM/CogView4-6B", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> apply_first_block_cache(pipe.transformer, FirstBlockCacheConfig(threshold=0.2))

>>> prompt = "A photo of an astronaut riding a horse on mars"
>>> image = pipe(prompt, generator=torch.Generator().manual_seed(42)).images[0]
>>> image.save("output.png")
```

## TaylorSeerCacheConfig[[diffusers.TaylorSeerCacheConfig]]

#### diffusers.TaylorSeerCacheConfig[[diffusers.TaylorSeerCacheConfig]]

```python
diffusers.TaylorSeerCacheConfig(cache_interval: int = 5, disable_cache_before_step: int = 3, disable_cache_after_step: int | None = None, max_order: int = 1, taylor_factors_dtype: typing.Optional[torch.dtype] = torch.bfloat16, skip_predict_identifiers: list[str] | None = None, cache_identifiers: list[str] | None = None, use_lite_mode: bool = False)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/taylorseer_cache.py#L26)

**パラメータ:**

cache_interval (`int`、デフォルトは`5`) : 完全な計算ステップ間の間隔です。完全な計算後、キャッシュされた（予測された）出力は、新しい完全なフォワードパスで更新されるまでの間、この回数分のデノイジングステップで再利用されます。

disable_cache_before_step (`int`、デフォルトは`3`) : キャッシングが無効化されるデノイジングステップのインデックスです。つまり、初期ステップ（0 から disable_cache_before_step - 1 まで）では、Taylor 級数近似のためのデータを収集するために完全な計算が実行されます。これらのステップでは、Taylor 係数が更新されますが、キャッシングや予測は適用されません。このステップからキャッシングが開始されます。

disable_cache_after_step (`int`, *任意*, デフォルトは `None`) : キャッシュが無効化されるデノイジングステップのインデックスです。設定した場合、この値以上のステップでは、予測や状態の更新を行わずにすべてのモジュールが完全な計算を実行し、必要に応じて後段の段階での精度を確保します。

max_order (`int`、デフォルトは`1`) : モジュールの出力を近似するための Taylor 展開の最高次数です。次数を高くすると近似精度は向上しますが、計算量とメモリ使用量が増加します。

taylor_factors_dtype (`torch.dtype`、デフォルトは `torch.bfloat16`) : Taylor 級数係数の保存と計算に使用されるデータ型です。精度を下げるとメモリ使用量は減りますが、安定性に影響が出る可能性があります。一方、精度を上げると精度は向上しますが、メモリ使用量が増加します。

skip_predict_identifiers (`list[str]`、*任意*、デフォルトは`None`) : "cache" モードで "skip" として配置するモジュール名の正規表現パターン（`re.fullmatch` を使用）。このモードでは、初期化ステップまたはリフレッシュステップではモジュールが完全に計算されますが、予測ステップでは記録された形状に一致するゼロテンソルを返すことで、計算を低コストでスキップします。

cache_identifiers (`list[str]`、*任意*、デフォルトは`None`) : Taylor 級数キャッシュモードに配置するモジュール名の正規表現パターン（`re.fullmatch` を使用）。このモードでは、出力が近似され、再利用のためにキャッシュされます。

use_lite_mode (`bool`、*任意*、デフォルトは`False`) : スキップとキャッシュに事前定義されたパターンを適用することでメモリ使用量を最小限に抑える軽量な TaylorSeer バリアントを有効にします（例：ブロックのスキップとプロジェクションのキャッシュ）。これにより、カスタムの`inactive_identifiers`や`active_identifiers`は上書きされます。

TaylorSeerキャッシュの設定。詳細は: https://huggingface.co/papers/2503.06923

注:
- パターンは、モジュール名に対して`re.fullmatch`を使用して照合されます。
- `skip_predict_identifiers`または`cache_identifiers`が指定されている場合、一致するモジュールのみがフックされます。
- どちらも指定されていない場合、デフォルトではすべてのアテンション類似モジュールがフックされます。

非アクティブとアクティブな使用の例:

```py
def forward(x):
    x = self.module1(x)  # inactive module: returns zeros tensor based on shape recorded during full compute
    x = self.module2(x)  # active module: caches output here, avoiding recomputation of prior steps
    return x
```

#### bfloat16[[diffusers.TaylorSeerCacheConfig.taylor_factors_dtype]]

```python
bfloat16(*args, **kwargs)
```

ドット区切りパス（例: `torch.float32`）に対するモック値: 属性アクセスのチェーン、呼び出しはパススルーデコレータとして動作し、`repr` はドット区切りパスを返し、ベースクラスとして使用するとプレーンな `type` ベースに置き換えられます（PEP 560 の `__mro_entries__`）。これにより、実際のサブクラスは通常のメタクラスを保持し、`inspect.signature` はモックのものではなく実際の `__init__` を読み取ります。

#### diffusers.apply_taylorseer_cache[[diffusers.apply_taylorseer_cache]]

```python
diffusers.apply_taylorseer_cache(module: Module, config: TaylorSeerCacheConfig)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/taylorseer_cache.py#L261)

**パラメータ:**

module (torch.nn.Module) : フックを適用するモデルのサブツリー。

config (TaylorSeerCacheConfig) : キャッシュの設定。

与えられたパイプライン（通常はtransformer / UNet）にTaylorSeerキャッシュを適用します。

この関数は、モデル内の選択されたモジュールにフックを設定し、提供された設定に基づいてキャッシュまたはスキップを有効にすることで、拡散デノイジングループにおける冗長な計算を削減します。

例:
```python
>>> import torch
>>> from diffusers import FluxPipeline, TaylorSeerCacheConfig

>>> pipe = FluxPipeline.from_pretrained(
...     "black-forest-labs/FLUX.1-dev",
...     torch_dtype=torch.bfloat16,
... )
>>> pipe.to("cuda")

>>> config = TaylorSeerCacheConfig(
...     cache_interval=5,
...     max_order=1,
...     disable_cache_before_step=3,
...     taylor_factors_dtype=torch.float32,
... )
>>> pipe.transformer.enable_cache(config)
```

## MagCacheConfig[[diffusers.MagCacheConfig]]

#### diffusers.MagCacheConfig[[diffusers.MagCacheConfig]]

```python
diffusers.MagCacheConfig(threshold: float = 0.06, max_skip_steps: int = 3, retention_ratio: float = 0.2, num_inference_steps: int = 28, mag_ratios: typing.Union[torch.Tensor, typing.List[float], NoneType] = None, calibrate: bool = False)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/mag_cache.py#L84)

**パラメータ:**

threshold (`float`、デフォルトは`0.06`) : 累積誤差の閾値です。累積誤差がこの閾値を下回る場合、ブロックの計算はスキップされます。閾値を高くすると、より積極的なスキップが可能になり（高速化されますが）、品質が低下する可能性があります。

max_skip_steps (`int`、デフォルトは`3`) : スキップ可能な連続ステップの最大数（論文におけるK）。

retention_ratio (`float`、デフォルトは`0.2`) : 安定性を確保するために、スキップが無効化される初期ステップの割合です。例えば、`num_inference_steps`が28で`retention_ratio`が0.2の場合、最初の6ステップは決してスキップされません。

num_inference_steps (`int`、デフォルトは`28`) : パイプラインで使用する推論ステップ数です。`mag_ratios`を正しく補間するために必要です。

mag_ratios (`torch.Tensor`, *任意*) : モデル用の事前計算済みマグニチュード比です。これらはチェックポイントに依存します。指定しない場合は、特定のモデルに対して計算するために `calibrate=True` を設定する必要があります。Flux モデルの場合、`diffusers.hooks.mag_cache.FLUX_MAG_RATIOS` を使用できます。

calibrate (`bool`、デフォルトは`False`) : True の場合、キャリブレーションモードを有効にします。このモードでは、ブロックのスキップは行われません。代わりに、フックが現在のランの magnitude ratios を計算し、終了時にログに記録します。新しいモデルやスケジューラーの`mag_ratios`を取得するために使用します。

[MagCache](https://github.com/Zehong-Ma/MagCache)の設定。

#### diffusers.apply_mag_cache[[diffusers.apply_mag_cache]]

```python
diffusers.apply_mag_cache(module: Module, config: MagCacheConfig)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/mag_cache.py#L398)

**パラメータ:**

module (`torch.nn.Module`) : MagCache を適用するモジュール。

config (`MagCacheConfig`) : MagCacheの設定です。

与えられたモジュール（通常は Transformer）に MagCache を適用します。

## SeaCacheConfig[[diffusers.SeaCacheConfig]]

#### diffusers.SeaCacheConfig[[diffusers.SeaCacheConfig]]

```python
diffusers.SeaCacheConfig(threshold: float = 0.25, residual_order: int = 1, retention_steps: int = 1, cache_end_steps: int = 1, max_consecutive_cached: int = 2, power_exp: float = 3.0, raw_vision_callback: typing.Callable[[torch.nn.Module, tuple[typing.Any, ...], dict[str, typing.Any]], list[torch.Tensor] | None] = None)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/sea_cache.py#L38)

**パラメータ:**

threshold (`float`、デフォルトは`0.25`) : 累積相対L1予算。値を大きくすると、キャッシュがより頻繁に再利用されます。

residual_order (`int`、デフォルトは`1`) : Transformer の残差を予測する際に使用する順序。`0`は最新の残差をそのまま再利用し、`1`は直近の2回の完全な実行から線形外挿を行います。

retention_steps (`int`、デフォルトは`1`) : 常に完全に実行される初期スケジューラステップの数。

cache_end_steps (`int`、デフォルトは`1`) : 常に完全に実行される最終スケジューラステップの数。

max_consecutive_cached (`int`、デフォルトは`2`) : 完全な実行を強制する前に、キャッシュコンテキスト内で残差を連続して再利用できる最大回数。`0`に設定すると、この制限が無効になります。

power_exp (`float`、デフォルトは`3.0`) : SEAクリーンシグナル電力事前分布の指数です。SeaCacheは動画特徴量に対して`3.0`を使用します。

raw_vision_callback (`Callable`、*省略可*) : 生成される出力を構成するビジュアル潜在変数を返す、高度なモデルアダプターです。各潜在変数の形状は `(C, T, H, W)` です。出力軌跡に含まれるクリーンな条件付けフレームは出力に含め、出力の一部ではない個別のビジュアルヒントは除外してください。省略した場合、利用可能な組み込みアダプターが使用されます。

[SeaCache](https://huggingface.co/papers/2602.18993)の設定。

SeaCache はデフォルトで無効化されており、この設定が `transformer.enable_cache(config)` に渡された後にのみ有効になります。

SeaCache は、スケジューラーステップ間で Spectral-Evolution-Aware (SEA) 指標を比較します。累積相対変化が `threshold` を下回る場合、繰り返しされる transformer ブロックスタックはキャッシュされた残差に置き換えられます。モデル固有のアダプターにより、残差境界をこれらのブロックを超えて拡張できます。その他の video transformer は、ブロックメタデータを登録し、`raw_vision_callback` を提供することで、汎用パスを利用できます。そのパイプラインは、各 transformer 軌跡に対して `cache_context` に入る必要があります。

例:
```python
>>> from diffusers import Cosmos3OmniPipeline, SeaCacheConfig

>>> pipe = Cosmos3OmniPipeline.from_pretrained("nvidia/Cosmos3-Nano")
>>> pipe.transformer.enable_cache(SeaCacheConfig())
```

#### diffusers.apply_sea_cache[[diffusers.apply_sea_cache]]

```python
diffusers.apply_sea_cache(module: Module, config: SeaCacheConfig)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/sea_cache.py#L980)

**パラメータ:**

module (`torch.nn.Module`) : キャッシュする Transformer モジュール。

config (`SeaCacheConfig`) : SeaCache の設定。

SeaCacheを対応するtransformerに適用します。

SeaCache は、transformer の繰り返しブロックスタックに対して、キャッシュされた残差を再利用します。モデルアダプターは、インジケーターの抽出と残差の境界をカスタマイズできます。汎用パスでは、登録済みのブロックメタデータと `raw_vision_callback` が使用されます。互換性とキャッシュのパラメータは、各モデルに対して検証する必要があります。

## TextKVCacheConfig[[diffusers.TextKVCacheConfig]]

#### diffusers.TextKVCacheConfig[[diffusers.TextKVCacheConfig]]

```python
diffusers.TextKVCacheConfig()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/text_kv_cache.py#L27)

Transformerモデルに対して、正確（ロスレス）なテキストK/Vキャッシュを有効にします。

デノイジングループの実行前に、ブロックごとのテキストのキーおよびバリューの射影を一度だけ事前計算し、すべてのステップで再利用します。正のプロンプトと負のプロンプトは、中間テンソルの割り当てが行われる前に、transformerレベルのフックによってキャプチャされた安定したキャッシュキーによって区別されます。

#### diffusers.apply_text_kv_cache[[diffusers.apply_text_kv_cache]]

```python
diffusers.apply_text_kv_cache(module: Module, config: TextKVCacheConfig)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/text_kv_cache.py#L157)