Buckets:

hf-doc-build
/

doc

Files
xet
hf-doc-build/doc / diffusers /main /ko /api /cache.md
mishig
about 7 hours ago
preview code
download
raw
34 kB
# 캐싱 방법

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`은 denoising 호출의 이름으로, 보통 `"cond"` 또는 `"uncond"`입니다. 키워드 인수는 denoising 루프의 현재 위치를 설명하며, 허용되는 필드는 `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/ko/api/cache#diffusers.PyramidAttentionBroadcastConfig) - [FasterCacheConfig](/docs/diffusers/main/ko/api/cache#diffusers.FasterCacheConfig) - [FirstBlockCacheConfig](/docs/diffusers/main/ko/api/cache#diffusers.FirstBlockCacheConfig) - [SeaCacheConfig](/docs/diffusers/main/ko/api/cache#diffusers.SeaCacheConfig) - `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 = (100, 800), temporal_attention_timestep_skip_range: tuple = (100, 800), cross_attention_timestep_skip_range: tuple = (100, 800), spatial_attention_block_identifiers: tuple = ('blocks', 'transformer_blocks', 'single_transformer_blocks', 'layers', 'visual_transformer_blocks'), temporal_attention_block_identifiers: tuple = ('temporal_transformer_blocks',), cross_attention_block_identifiers: tuple = ('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`) : 특정 temporal attention broadcast가 attention states를 재사용하기 위해 attention states를 계산하기 전에 건너뛰는 횟수입니다. 이 값이 `N`으로 설정되면, 새로운 attention states를 다시 계산하기 전에 attention 계산이 `N - 1`회 건너뛰어집니다(즉, 이전 attention states가 재사용됩니다).

cross_attention_block_skip_range (`int`, *선택 사항*, 기본값 `None`) : 주의 상태(attention states)를 재사용하기 위해 특정 크로스 어텐션 브로드캐스트가 계산되기 전에 건너뛰는 횟수입니다. 이 값이 `N`으로 설정되면, 새로운 주의 상태를 다시 계산하기 전에 주의 계산이 `N - 1`회 건너뛰어집니다(즉, 이전 주의 상태가 재사용됩니다).

spatial_attention_timestep_skip_range (`tuple[int, int]`, 기본값 `(100, 800)`) : 공간 주의력 레이어에서 건너뛸 타임스텝 범위입니다. 현재 타임스텝이 지정된 범위에 포함되면 주의력 계산이 조건부로 건너뛸 수 있습니다.

temporal_attention_timestep_skip_range (`tuple[int, int]`, 기본값 `(100, 800)`) : temporal attention layer에서 건너뛸 timestep 범위입니다. 현재 timestep이 지정된 범위 내에 있으면 attention 계산이 조건부로 건너뛸 수 있습니다.

cross_attention_timestep_skip_range (`tuple[int, int]`, 기본값 `(100, 800)`) : cross-attention 레이어에서 건너뛸 timestep 범위입니다. 현재 timestep이 지정된 범위에 포함되면 attention 계산이 조건부로 건너뛸 수 있습니다.

spatial_attention_block_identifiers (`tuple[str, ...]`) : 레이어가 공간적 어텐션 레이어인지 여부를 결정하기 위해 레이어 이름과 일치시킬 식별자입니다.
temporal_attention_block_identifiers (`tuple[str, ...]`) : 레이어가 시간적 어텐션 레이어인지 여부를 결정하기 위해 레이어 이름과 일치시킬 식별자입니다.

cross_attention_block_identifiers (`tuple[str, ...]`) : 레이어가 cross-attention 레이어인지 여부를 결정하기 위해 레이어 이름과 매칭할 식별자입니다.
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 = (-1, 681), temporal_attention_timestep_skip_range: tuple = (-1, 681), low_frequency_weight_update_timestep_range: tuple = (99, 901), high_frequency_weight_update_timestep_range: tuple = (-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 = (-1, 641), spatial_attention_block_identifiers: tuple = ('^blocks.*attn', '^transformer_blocks.*attn', '^single_transformer_blocks.*attn'), temporal_attention_block_identifiers: tuple = ('^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 = ('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`회 반복마다 attention 상태를 계산합니다. 이 값이 `N`으로 설정되면, 새로운 attention 상태를 다시 계산하기 전에 attention 계산이 `N - 1`회 건너뜁니다(즉, 캐시된 attention 상태가 재사용됩니다).
temporal_attention_block_skip_range (`int`, *선택 사항*, 기본값 `None`) : `N`회 반복마다 attention 상태를 계산합니다. 이 값이 `N`으로 설정되면, 새로운 attention 상태를 다시 계산하기 전에 attention 계산이 `N - 1`회 건너뜁니다(즉, 캐시된 attention 상태가 재사용됩니다).
spatial_attention_timestep_skip_range (`tuple[float, float]`, 기본값은 `(-1, 681)`) : 품질에 유의미한 손실 없이 공간적 어텐션 계산을 건너뛸 수 있는 타임스텝 범위입니다. 이는 사용자가 기반 모델에 따라 결정해야 합니다. 튜플의 첫 번째 값은 하한, 두 번째 값은 상한입니다. 일반적으로 디노이징을 위한 확산 타임스텝은 0에서 1000까지의 역방향 범위(즉, 디노이징이 타임스텝 1000에서 시작하여 타임스텝 0에서 종료)를 가집니다. 기본값의 경우, 이는 공간적 어텐션 계산 건너뛰기가 디노이징 타임스텝 681에 도달한 후에만 적용되고 디노이징 프로세스가 끝날 때까지 계속됨을 의미합니다.
temporal_attention_timestep_skip_range (`tuple[float, float]`, *선택 사항*, 기본값 `None`) : 품질에 유의미한 손실 없이 시간적 어텐션 계산을 건너뛸 수 있는 타임스텝 범위입니다. 이는 사용자가 기반 모델에 따라 결정해야 합니다. 튜플의 첫 번째 값은 하한, 두 번째 값은 상한입니다. 일반적으로 디노이징을 위한 diffusion 타임스텝은 0에서 1000까지의 역방향 범위(즉, 디노이징이 타임스텝 1000에서 시작하여 타임스텝 0에서 종료)를 가집니다.
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`) : `N`회 반복마다 무조건 분기를 처리합니다. 이 값이 `N`으로 설정되면, 새로운 무조건 분기 상태를 다시 계산하기 전에 무조건 분기 계산이 `N - 1`회 건너뜁니다(즉, 캐시된 무조건 분기 상태가 재사용됩니다).

unconditional_batch_timestep_skip_range (`tuple[float, float]`, 기본값은 `(-1, 641)`) : 품질에 유의미한 손실 없이 무조건 분기(unconditional branch) 계산을 건너뛸 수 있는 timestep 범위입니다. 이는 사용자가 기반 모델에 따라 결정해야 합니다. 튜플의 첫 번째 값은 하한, 두 번째 값은 상한입니다.

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",)`) : 모델의 temporal attention 블록을 일치시키기 위한 식별자입니다. 블록 이름에 이 식별자 중 하나가 포함되면 해당 블록에 FasterCache가 적용됩니다. 이는 전체 레이어 이름, 부분 레이어 이름 또는 정규식 패턴일 수 있습니다. 매칭은 항상 정규식 매칭을 사용하여 수행됩니다.
attention_weight_callback (`Callable[[torch.nn.Module], float]`, 기본값은 `None`) : attention 출력에 곱할 가중치를 결정하는 콜백 함수입니다. 이 함수는 attention 모듈을 입력으로 받아 float 값을 반환해야 합니다. 이는 조건부 분기 출력에서 무조건부 분기를 근사하는 데 사용됩니다. 제공되지 않으면 모든 timestep에 대해 기본 가중치는 0.5입니다. 일반적으로 논문에서 설명한 바와 같이, 이 가중치는 추론이 진행됨에 따라 0에서 1로 점진적으로 증가해야 합니다. 사용자는 추론 단계 수와 노이즈 제거가 진행됨에 따른 기본 모델 동작을 고려한 사용자 정의 가중치 스케줄을 실험하고 제공하도록 권장됩니다.
low_frequency_weight_callback (`Callable[[torch.nn.Module], float]`, 기본값은 `None`) : 저주파 업데이트를 스케일링할 가중치를 결정하는 콜백 함수입니다. 제공되지 않으면, 지정된 범위 내의 timesteps에 대해(논문에서 설명된 바와 같이) 기본 가중치는 1.1입니다.

high_frequency_weight_callback (`Callable[[torch.nn.Module], float]`, 기본값은 `None`) : 고주파 업데이트를 스케일링할 가중치를 결정하는 콜백 함수입니다. 제공되지 않으면, 지정된 범위 내의 timesteps에 대해(논문에서 설명된 바와 같이) 기본 가중치는 1.1입니다.
tensor_format (`str`, 기본값 `"BCFHW"`) : 입력 텐서의 형식입니다. 이는 `"BCFHW"`, `"BFCHW"`, 또는 `"BCHW"` 중 하나여야 합니다. 이 형식은 저주파 및 고주파 성분을 계산하기 위해 개별 잠재 프레임(latent frames)을 분리하는 데 사용됩니다.

is_guidance_distilled (`bool`, 기본값 `False`) : 모델이 guidance distilled인지 여부입니다. 모델이 guidance distilled인 경우, unconditional branch 계산이 없으므로 denoiser-level에서 FasterCache가 적용되지 않습니다.

_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에서 지원하는 트랜스포머 아키텍처, 예를 들어 `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`) : 모델의 모든 레이어를 통한 forward pass가 필요한지 여부를 결정하는 임계값입니다. 임계값이 높을수록 forward pass가 수행되는 레이어 수가 줄어들어 추론 속도가 빨라지지만, 생성 품질이 저하될 수 있습니다. 임계값이 낮으면 생성 속도 향상이 미미할 수 있습니다. 이 임계값은 첫 번째 transformer block의 현재 출력과 캐시된 출력 간 잔차의 absmean 차이와 비교됩니다. 차이가 임계값보다 작으면 forward pass가 건너뜁니다.
[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에서 지원하는 트랜스포머 아키텍처, 예를 들어 `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`) : 전체 계산 단계 사이의 간격입니다. 전체 계산이 완료된 후, 캐시된 (예측된) 출력은 새로운 전체 forward pass로 갱신되기 전까지 이 수만큼의 후속 denoising 단계에서 재사용됩니다.
disable_cache_before_step (`int`, 기본값 `3`) : 캐싱이 비활성화되는 디노이징 단계 인덱스입니다. 즉, 초기 단계(0부터 disable_cache_before_step - 1까지)에서는 Taylor series 근사를 위한 데이터를 수집하기 위해 전체 계산이 수행됩니다. 이 단계들에서는 Taylor factors가 업데이트되지만, 캐싱/예측은 적용되지 않습니다. 캐싱은 이 단계부터 시작됩니다.
disable_cache_after_step (`int`, *선택 사항*, 기본값 `None`) : 캐싱이 비활성화되는 디노이징 단계 인덱스입니다. 이 값이 설정되면, 해당 값 이상의 단계에서는 모든 모듈이 예측이나 상태 업데이트 없이 전체 계산을 수행하여, 필요 시 후반 단계의 정확성을 보장합니다.
max_order (`int`, 기본값 `1`) : 모듈 출력을 근사하기 위한 테일러 급수 전개에서 사용할 최대 차수입니다. 차수가 높을수록 근사 정확도가 높아지지만, 계산 및 메모리 사용량이 증가합니다.
taylor_factors_dtype (`torch.dtype`, 기본값은 `torch.bfloat16`) : Taylor series 요소를 저장하고 계산하는 데 사용되는 데이터 유형입니다. 정밀도가 낮으면 메모리가 줄어지지만 안정성에 영향을 줄 수 있으며, 정밀도가 높으면 정확도가 향상되지만 더 많은 메모리가 필요합니다.
skip_predict_identifiers (`list[str]`, *선택 사항*, 기본값 `None`) : "cache" 모드에서 "skip"으로 배치할 모듈 이름에 대한 정규식 패턴(`re.fullmatch` 사용). 이 모드에서는 모듈이 초기화 또는 새로고침 단계에서 완전히 계산되지만, 예측 단계에서는 기록된 형상과 일치하는 제로 텐서를 반환하여 계산 비용을 저렴하게 절약합니다.
cache_identifiers (`list[str]`, *선택 사항*, 기본값 `None`) : Taylor-series 캐싱 모드에 배치할 모듈 이름에 대한 정규식 패턴(`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`가 제공되면 일치하는 모듈에만 훅이 적용됩니다.
- 둘 다 제공되지 않으면 기본적으로 모든 attention 유사 모듈이 hook됩니다.
비활성 및 활성 사용 예시:
```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`)의 mock 값입니다: 속성 접근 체인, 호출은 pass-through 데코레이터처럼 동작하며, `repr`은 해당 점으로 구분된 경로입니다. 이를 베이스 클래스로 사용하면 plain-`type` 베이스로 대체됩니다(PEP 560 `__mro_entries__`). 따라서 실제 서브클래스는 일반적인 메타클래스를 유지하고, `inspect.signature`는 mock의 것이 아니라 실제 `__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) : 캐시에 대한 설정입니다.

pipeline(일반적으로 transformer / UNet)에 TaylorSeer 캐시를 적용합니다.

이 함수는 제공된 구성에 따라 캐싱 또는 스킵을 활성화하기 위해 모델의 선택된 모듈을 훅(hook)하여, 디퓨전 디노이징 루프에서 중복 계산을 줄입니다.

예:
```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`, *선택 사항*) : 모델에 대한 사전 계산된 magnitude 비율입니다. 이는 체크포인트에 따라 달라집니다. 제공되지 않은 경우, 특정 모델에 대해 이를 계산하려면 `calibrate=True`를 설정해야 합니다. Flux 모델의 경우 `diffusers.hooks.mag_cache.FLUX_MAG_RATIOS`를 사용할 수 있습니다.

calibrate (`bool`, 기본값은 `False`) : True인 경우 보정(calibration) 모드를 활성화합니다. 이 모드에서는 블록이 건너뛰지지 않습니다. 대신 훅이 현재 실행의 크기 비율을 계산하고 종료 시점에 기록합니다. 새로운 모델이나 스케줄러에 대해 `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의 설정입니다.

MagCache를 주어진 모듈(일반적으로 Transformer)에 적용합니다.

## 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`은 최근 두 번의 전체 실행에서 선형 외삽을 수행합니다.
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`, *선택 사항*) : 생성된 출력의 시각적 잠재 변수를 형성하는 고급 모델 어댑터로, 각 변수의 shape은 `(C, T, H, W)`입니다. 출력 궤적 내에 포함된 깨끗한 조건 프레임은 포함하되, 출력의 일부가 아닌 개별 시각적 힌트는 제외합니다. 생략된 경우, 사용 가능한 내장 어댑터가 사용됩니다.
[SeaCache](https://huggingface.co/papers/2602.18993)에 대한 구성입니다.
SeaCache는 기본적으로 비활성화되어 있으며, 이 구성이 `transformer.enable_cache(config)`에 전달된 후에만 활성화됩니다.

SeaCache는 스케줄러 단계 간에 Spectral-Evolution-Aware(SEA) 지표를 비교합니다. 누적 상대 변화가 `threshold` 미만으로 유지되면, 반복되는 transformer 블록 스택은 캐시된 잔차로 대체됩니다. 모델별 어댑터는 해당 블록을 넘어 잔차 경계를 확장할 수 있습니다. 다른 비디오 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 구성입니다.

지원되는 transformer에 SeaCache를 적용합니다.

SeaCache는 transformer의 반복되는 블록 스택에 대해 캐시된 잔차를 재사용합니다. 모델 어댑터는 지표 추출 및 잔차 경계를 사용자 정의할 수 있으며, 일반 경로는 등록된 블록 메타데이터와 `raw_vision_callback`를 사용합니다. 호환성 및 캐시 매개변수는 각 모델별로 검증되어야 합니다.
Xet Storage Details

Size:: 34 kB
Xet hash:: 7c0885e69be1d1a54889861a8e5e21a68f564ce18d665d2b103e8037d0cb3370
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.