Hugging Face's logo

Diffusers documentation

캐싱 방법

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

캐싱 방법

Cache 메서드는 attention 및 feedforward 레이어와 같은 특정 레이어의 중간 출력을 저장하고 재사용하여 매 추론 단계마다 다시 계산하는 것을 방지함으로써 diffusion transformer의 속도를 높입니다.

CacheMixin

class diffusers.CacheMixin

< >

( )

확산 모델에서 캐싱 기법을 활성화/비활성화하는 클래스입니다.

지원되는 캐싱 기법:

cache_context

< >

( name: str**kwargs )

캐시 관리에 필요한 정보를 제공하는 컨텍스트 매니저입니다.

name은 노이즈 제거 호출의 이름으로, 보통 "cond" 또는 "uncond"입니다. 키워드 인수는 노이즈 제거 루프의 현재 위치를 설명하며, 허용되는 필드는 CacheContext를 참고하세요. 예를 들어 cache_context("cond", step_index=i, sigma=sigma)와 같습니다.

enable_cache

< >

( config )

매개변수

모델에 캐싱 기법을 활성화합니다.

예:

>>> 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

< >

( spatial_attention_block_skip_range: int | None = Nonetemporal_attention_block_skip_range: int | None = Nonecross_attention_block_skip_range: int | None = Nonespatial_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 )

매개변수

  • spatial_attention_block_skip_range (int, 선택 사항, 기본값 None) — 재사용할 attention states를 계산하기 전에 특정 spatial attention broadcast가 건너뛰어지는 횟수입니다. 이 값이 N으로 설정되면, 새로운 attention states를 다시 계산하기 전에 attention 계산이 N - 1회 건너뛰어집니다(즉, 이전 attention states가 재사용됩니다).
  • temporal_attention_block_skip_range (int, 선택 사항, 기본값 None) — 재사용할 attention states를 계산하기 전에 특정 temporal attention broadcast가 건너뛰어지는 횟수입니다. 이 값이 N으로 설정되면, 새로운 attention states를 다시 계산하기 전에 attention 계산이 N - 1회 건너뛰어집니다(즉, 이전 attention states가 재사용됩니다).
  • cross_attention_block_skip_range (int, 선택 사항, 기본값 None) — 재사용할 attention states를 계산하기 전에 특정 cross-attention broadcast가 건너뛰어지는 횟수입니다. 이 값이 N으로 설정되면, 새로운 attention states를 다시 계산하기 전에 attention 계산이 N - 1회 건너뛰어집니다(즉, 이전 attention states가 재사용됩니다).
  • spatial_attention_timestep_skip_range (tuple[int, int], 기본값 (100, 800)) — 공간 주의력 레이어에서 건너뛸 타임스텝 범위입니다. 현재 타임스텝이 지정된 범위에 포함되면 주의력 계산이 조건부로 건너뛸 수 있습니다.
  • temporal_attention_timestep_skip_range (tuple[int, int], 기본값 (100, 800)) — temporal attention 레이어에서 건너뛸 timestep 범위입니다. 현재 timestep이 지정된 범위 내에 있으면 attention 계산이 조건부로 건너뛸 수 있습니다.
  • cross_attention_timestep_skip_range (tuple[int, int], 기본값 (100, 800)) — cross-attention 레이어에서 건너뛸 timestep 범위입니다. 현재 timestep이 지정된 범위 내에 있으면 attention 계산이 조건부로 건너뛸 수 있습니다.
  • spatial_attention_block_identifiers (tuple[str, ...]) — 레이어가 공간 주의력(spatial attention) 레이어인지 여부를 결정하기 위해 레이어 이름과 매칭할 식별자입니다.
  • temporal_attention_block_identifiers (tuple[str, ...]) — 레이어가 temporal attention 레이어인지 여부를 결정하기 위해 레이어 이름과 매칭할 식별자입니다.
  • cross_attention_block_identifiers (tuple[str, ...]) — 레이어가 cross-attention 레이어인지 여부를 결정하기 위해 레이어 이름과 매칭할 식별자입니다.

Pyramid Attention Broadcast 설정

diffusers.apply_pyramid_attention_broadcast

< >

( module: Moduleconfig: PyramidAttentionBroadcastConfig )

매개변수

  • module (torch.nn.Module) — Pyramid Attention Broadcast를 적용할 모듈입니다.
  • config (PyramidAttentionBroadcastConfig | None, optional, 기본값 None) — Pyramid Attention Broadcast에 사용할 설정입니다.

주어진 파이프라인에 Pyramid Attention Broadcast를 적용합니다.

PAB은 타임스텝 간 어텐션 상태의 유사성을 활용하여 어텐션 계산의 계산 비용을 줄이는 어텐션 근사화 방법입니다. 해당 논문에서 핵심으로 가져갈 점은, 타임스텝 간 크로스 어텐션 레이어의 어텐션 유사도가 가장 높고, 그 다음으로 시간적 및 공간적 레이어의 유사도가 낮다는 것입니다. 이를 통해 크로스 어텐션 레이어에서 시간적 및 공간적 레이어보다 더 자주 어텐션 계산을 건너뛸 수 있습니다. 따라서 PAB를 적용하면 추론 과정이 빨라집니다.

예:

>>> 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

< >

( spatial_attention_block_skip_range: int = 2temporal_attention_block_skip_range: int | None = Nonespatial_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.1alpha_high_frequency: float = 1.1unconditional_batch_skip_range: int = 5unconditional_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] = Nonelow_frequency_weight_callback: typing.Callable[[torch.nn.Module], float] = Nonehigh_frequency_weight_callback: typing.Callable[[torch.nn.Module], float] = Nonetensor_format: str = 'BCFHW'is_guidance_distilled: bool = Falsecurrent_timestep_callback: typing.Callable[[], int] = None_unconditional_conditional_input_kwargs_identifiers: list = ('hidden_states', 'encoder_hidden_states', 'timestep', 'attention_mask', 'encoder_attention_mask') )

매개변수

  • 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)) — 품질에 유의미한 손실 없이 공간 주의력(spatial attention) 계산을 생략할 수 있는 타임스텝 범위입니다. 이는 사용자가 기반 모델에 따라 결정해야 합니다. 튜플의 첫 번째 값은 하한, 두 번째 값은 상한입니다. 일반적으로 디노이징을 위한 디퓨전 타임스텝은 0에서 1000까지의 역순 범위(즉, 디노이징이 타임스텝 1000에서 시작하여 타임스텝 0에서 종료)를 가집니다. 기본값의 경우, 이는 공간 주의력 계산 생략이 디노이징 타임스텝 681에 도달한 후에만 적용되고 디노이징 프로세스가 끝날 때까지 계속됨을 의미합니다.
  • temporal_attention_timestep_skip_range (tuple[float, float], 선택 사항, 기본값 None) — 품질에 유의미한 손실 없이 temporal attention 계산을 건너뛸 수 있는 timestep 범위입니다. 이는 사용자가 기반 모델에 따라 결정해야 합니다. 튜플의 첫 번째 값은 하한, 두 번째 값은 상한입니다. 일반적으로 노이즈 제거를 위한 diffusion timestep은 0에서 1000까지의 역순 범위(즉, timestep 1000에서 시작하여 timestep 0에서 종료)를 가집니다.
  • low_frequency_weight_update_timestep_range (tuple[int, int], 기본값 (99, 901)) — 저주파 가중치 스케일링 업데이트가 적용되는 timestep 범위입니다. 튜플의 첫 번째 값은 timestep 범위의 하한, 두 번째 값은 상한입니다. 업데이트를 위한 콜백 함수는 이 범위 내에서만 호출됩니다.
  • high_frequency_weight_update_timestep_range (tuple[int, int], 기본값 (-1, 301)) — 고주파 가중치 스케일링 업데이트가 적용되는 timestep 범위입니다. 튜플의 첫 번째 값은 timestep 범위의 하한, 두 번째 값은 상한입니다. 업데이트를 위한 콜백 함수는 이 범위 내에서만 호출됩니다.
  • alpha_low_frequency (float, 기본값 1.1) — 저주파 업데이트를 스케일링할 가중치입니다. 이는 조건부 분기 출력에서 무조건 분기를 근사하는 데 사용됩니다.
  • alpha_high_frequency (float, 기본값 1.1) — 고주파 업데이트를 스케일링할 가중치입니다. 이는 조건부 분기 출력에서 무조건 분기를 근사하는 데 사용됩니다.
  • unconditional_batch_skip_range (int, 기본값 5) — N회 반복마다 unconditional branch를 처리합니다. 이 값을 N으로 설정하면, 새로운 unconditional branch 상태를 다시 계산하기 전에 unconditional branch 계산이 N - 1회 건너뜁니다(즉, 캐시된 unconditional branch 상태를 재사용합니다).
  • 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 block을 일치시키기 위한 식별자입니다. 블록 이름에 이 식별자 중 하나가 포함되면 해당 블록에 FasterCache가 적용됩니다. 이는 전체 레이어 이름, 부분 레이어 이름 또는 정규식 패턴일 수 있습니다. 매칭은 항상 정규식 매칭을 사용하여 수행됩니다.
  • attention_weight_callback (Callable[[torch.nn.Module], float], 기본값 None) — Attention 출력에 곱할 가중치를 결정하는 콜백 함수입니다. 이 함수는 attention 모듈을 입력으로 받아 float 값을 반환해야 합니다. 이는 조건부 분기 출력에서 무조건부 분기를 근사하는 데 사용됩니다. 제공되지 않으면 모든 timestep에 대해 기본 가중치는 0.5입니다. 일반적으로 논문에서 설명한 바와 같이, 이 가중치는 추론이 진행됨에 따라 0에서 1로 점진적으로 증가해야 합니다. 사용자는 추론 단계 수와 denoising이 진행됨에 따른 기본 모델 동작을 고려한 사용자 정의 가중치 스케줄을 실험하고 제공하도록 권장됩니다.
  • 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")) — 배치 단위 연결된 unconditional 및 conditional 입력을 포함하는 입력 kwargs와 일치시키기 위한 식별자입니다. 입력 kwargs의 이름에 이 식별자 중 하나가 포함되면 FasterCache는 입력을 unconditional 및 conditional 분기로 분리합니다. 이는 배치 단위 연결된 unconditional 및 conditional 입력을 포함하는 정확한 입력 kwargs 이름의 목록이어야 합니다.

FasterCache에 대한 구성입니다.

diffusers.apply_faster_cache

< >

( module: Moduleconfig: FasterCacheConfig )

매개변수

  • module (torch.nn.Module) — FasterCache를 적용할 PyTorch 모듈입니다. 일반적으로 Diffusers에서 지원하는 transformer 아키텍처, 예를 들어 CogVideoXTransformer3DModel과 같은 모델이어야 하지만 외부 구현도 작동할 수 있습니다.
  • config (FasterCacheConfig) — FasterCache에 사용할 구성입니다.

주어진 파이프라인에 FasterCache를 적용합니다.

예:

>>> 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

< >

( threshold: float = 0.05 )

매개변수

  • threshold (float, 기본값 0.05) — 모델의 모든 레이어를 통한 forward pass가 필요한지 여부를 결정하는 임계값입니다. 임계값이 높을수록 forward pass가 수행되는 레이어 수가 적어지고 추론 속도가 빨라지지만, 생성 품질이 저하될 수 있습니다. 임계값이 낮으면 생성 속도 향상이 미미할 수 있습니다. 이 임계값은 첫 번째 transformer block의 현재 출력과 캐시된 출력 사이의 잔차(residual)의 absmean 차이와 비교됩니다. 차이가 임계값보다 작으면 forward pass가 건너뜁니다.

First Block Cache에 대한 구성입니다.

diffusers.apply_first_block_cache

< >

( module: Moduleconfig: FirstBlockCacheConfig )

매개변수

  • module (torch.nn.Module) — FBCache를 적용할 PyTorch 모듈입니다. 일반적으로 Diffusers에서 지원하는 트랜스포머 아키텍처, 예를 들어 CogVideoXTransformer3DModel이어야 하지만 외부 구현도 작동할 수 있습니다.
  • config (FirstBlockCacheConfig) — FBCache 방법을 적용하는 데 사용할 구성입니다.

주어진 모듈에 First Block Cache를 적용합니다.

First Block Cache는 TeaCache의 아이디어를 기반으로 합니다. 다양한 모델 범위에 대해 범용적으로 구현하는 것이 훨씬 간단하며, 실험적 목적으로 먼저 통합되었습니다.

예:

>>> 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

< >

( cache_interval: int = 5disable_cache_before_step: int = 3disable_cache_after_step: int | None = Nonemax_order: int = 1taylor_factors_dtype: typing.Optional[torch.dtype] = torch.bfloat16skip_predict_identifiers: list[str] | None = Nonecache_identifiers: list[str] | None = Noneuse_lite_mode: bool = False )

매개변수

  • cache_interval (int, 기본값 5) — 완전 계산 단계 사이의 간격입니다. 완전 계산이 완료된 후, 캐시된(예측된) 출력은 새로운 완전 순전파로 갱신되기 전까지 이 수만큼의 후속 디노이징 단계에서 재사용됩니다.
  • 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 사용). 이 모드에서는 초기화 또는 새로고침 단계에서 모듈이 완전히 계산되지만, 예측 단계에서는 기록된 shape와 일치하는 zero tensor를 반환하여 계산 비용을 저렴하게 절약합니다.
  • 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됩니다.

비활성 및 활성 사용 예시:

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

( *args**kwargs )

점으로 구분된 경로(예: torch.float32)에 대한 mock 값: 속성 접근 체인, 호출은 pass-through 데코레이터처럼 동작하며, repr은 해당 점으로 구분된 경로입니다. 이를 베이스 클래스로 사용하면 plain-type 베이스로 대체됩니다(PEP 560 __mro_entries__). 따라서 실제 서브클래스는 일반적인 메타클래스를 유지하고, inspect.signature는 mock의 __init__가 아닌 실제 __init__를 읽습니다.

diffusers.apply_taylorseer_cache

< >

( module: Moduleconfig: TaylorSeerCacheConfig )

매개변수

  • module (torch.nn.Module) — 훅을 적용할 모델 서브트리입니다.
  • config (TaylorSeerCacheConfig) — 캐시에 대한 설정입니다.

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

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

예:

>>> 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

class diffusers.MagCacheConfig

< >

( threshold: float = 0.06max_skip_steps: int = 3retention_ratio: float = 0.2num_inference_steps: int = 28mag_ratios: typing.Union[torch.Tensor, typing.List[float], NoneType] = Nonecalibrate: bool = False )

매개변수

  • 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인 경우 보정(calibration) 모드를 활성화합니다. 이 모드에서는 블록이 건너뛰지 않습니다. 대신 훅이 현재 실행의 크기 비율을 계산하고 종료 시점에 기록합니다. 새로운 모델이나 스케줄러에 대해 mag_ratios를 얻으려면 이 옵션을 사용하세요.

MagCache에 대한 구성입니다.

diffusers.apply_mag_cache

< >

( module: Moduleconfig: MagCacheConfig )

매개변수

  • module (torch.nn.Module) — MagCache를 적용할 모듈입니다.
  • config (MagCacheConfig) — MagCache의 설정입니다.

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

SeaCacheConfig

class diffusers.SeaCacheConfig

< >

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

매개변수

  • threshold (float, 기본값 0.25) — 누적 상대 L1 예산입니다. 값이 클수록 캐시를 더 자주 재사용합니다.
  • residual_order (int, 기본값 1) — transformer residual을 예측하는 데 사용되는 순서입니다. 0은 가장 최근 residual을 그대로 재사용하고, 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에 대한 구성입니다.

SeaCache는 기본적으로 비활성화되어 있으며, 이 구성이 transformer.enable_cache(config)에 전달된 후에만 활성화됩니다.

SeaCache는 스케줄러 단계 간에 Spectral-Evolution-Aware(SEA) 지표를 비교합니다. 누적 상대 변화가 threshold 미만으로 유지되면, 반복되는 transformer 블록 스택은 캐시된 잔차로 대체됩니다. 모델별 어댑터는 해당 블록을 넘어 잔차 경계를 확장할 수 있습니다. 다른 비디오 transformer는 블록 메타데이터를 등록하고 raw_vision_callback을 제공하여 일반 경로를 사용할 수 있으며, 각 transformer 궤적에 대해 파이프라인은 cache_context에 진입해야 합니다.

예:

>>> from diffusers import Cosmos3OmniPipeline, SeaCacheConfig

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

diffusers.apply_sea_cache

< >

( module: Moduleconfig: SeaCacheConfig )

매개변수

  • module (torch.nn.Module) — 캐시할 Transformer 모듈.
  • config (SeaCacheConfig) — SeaCache 구성입니다.

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

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

Update on GitHub

←사용자 정의 활성화 함수 사용자 정의 정규화 레이어→