Diffusers documentation

Attention 백엔드

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

and get access to the augmented documentation experience

to get started

Attention 백엔드

Attention dispatcher는 실험적 기능입니다. 피드백이 있거나 문제가 발생하면 이슈를 열어 주세요.

대부분의 Diffusers transformer 모델은 attention dispatcher를 통해 attention을 라우팅하여 하나의 API 뒤에 최적화된 백엔드를 전환할 수 있습니다. dispatcher는 등록된 구현체를 관리하고, 이를 위한 통합된 호출 경로를 노출합니다. 일부 모델은 내부 구조 때문에 dispatcher를 사용하지 않으며, 이러한 모델의 경우 백엔드를 전환해도 attention 레이어에 영향을 미치지 않습니다.

사용 가능한 어텐션 패밀리 개요는 아래 표를, 더 완전한 목록은 사용 가능한 백엔드 섹션을 참조하세요. 가장 빠른 백엔드는 모델, GPU, dtype, 입력 형상에 따라 달라집니다.

attention 계열주요 기능
FlashAttentiontiling과 recomputation을 통해 메모리 읽기/쓰기를 최소화합니다
ROCm용 AI Tensor EngineAMD ROCm 가속기를 위해 최적화된 FlashAttention 구현
SageAttentionquantizes attention to int8
FlexAttentionPyTorch FlexAttention
PyTorch 네이티브scaled_dot_product_attention를 사용하는 내장 PyTorch 구현
xFormersmemory-efficient attention 및 다양한 attention kernel 지원

Hub 백엔드(*_hub 이름)는 Kernels 라이브러리가 필요하며, 처음 사용할 때 커널을 다운로드합니다. SageAttention Hub 백엔드는 DIFFUSERS_TRUST_REMOTE_KERNELS=true도 필요합니다(자세한 내용은 Trusting remote kernels 참조). 다른 백엔드는 flash-attn 또는 sageattention와 같이 자체 패키지가 필요합니다. Available backends 테이블에는 백엔드를 활성화할 때 Diffusers가 확인하는 요구 사항을 나열합니다.

모델에 백엔드 설정

set_attention_backend() 메서드는 모델의 어텐션 레이어를 순회하며 각 레이어에 선택된 백엔드를 적용합니다. 또한 디스패처의 프로세스 전체 활성 백엔드도 동일한 값으로 설정합니다.

reset_attention_backend()은 attention 레이어의 backend만 초기화합니다. 프로세스 전체의 활성 backend는 초기화하지 않습니다. 종료 시 이전 활성 backend로 복원되는 일시적인 전환이 필요하면 attention_backend 컨텍스트 매니저를 사용하세요.

아래 예시에서는 device_map="cuda"와 함께 _flash_3_hub(Hub의 FlashAttention-3)를 활성화합니다.

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"
)
pipeline.transformer.set_attention_backend("_flash_3_hub")

prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
pipeline(prompt).images[0]

Hub가 아닌 FlashAttention-3 백엔드(_flash_3, _flash_varlen_3)는 FlashAttention-3를 소스에서 빌드해야 하며 곧 비추천(deprecated)될 예정입니다. 대신 _flash_3_hub 또는 _flash_3_varlen_hub를 사용하세요.

임시로 백엔드를 사용해 보세요

attention_backend() 컨텍스트 매니저는 블록 실행 동안 프로세스 전체의 활성 백엔드를 설정하고, 블록이 종료되면 이전 백엔드로 복원합니다. set_attention_backend()를 통해 영구적으로 백엔드가 적용되는 것을 피하면서, 한 번의 호출에 대해 특정 백엔드를 시도할 때 사용하세요.

import torch
from diffusers import QwenImagePipeline, attention_backend

pipeline = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""

with attention_backend("_flash_3_hub"):
    image = pipeline(prompt).images[0]

대부분의 attention 백엔드는 torch.compile과 함께 작동합니다. 파이프라인이 실제로 빨라지는지는 모델과 백엔드에 따라 달라집니다. 정밀도와 컴파일을 참고하세요.

원격 커널에 대한 신뢰

Hub 백엔드는 먼저 Kernels 라이브러리가 필요하며, Diffusers는 최초 사용 시 Hub 커널을 가져옵니다.

Hub attention backends는 Kernels 라이브러리를 사용하여 compute kernels를 다운로드하고 로컬에서 실행합니다. 대부분의 Hub attention 이름(_flash_3_hub, flash_hub 및 기타 *_hub backends)은 kernels-community 조직으로 해석됩니다. 해당 조직은 Kernels에서 신뢰할 수 있는 게시자(trusted publisher)이므로, Diffusers는 DIFFUSERS_TRUST_REMOTE_KERNELS를 설정하지 않고도 해당 attention kernels를 로드합니다.

SageAttention Hub 백엔드(sage_hub 및 sage_blackwell_hub)는 SageAttention 조직에서 로드합니다. 이를 사용하려면 DIFFUSERS_TRUST_REMOTE_KERNELS=true를 설정하세요.

Other kernel-backed features such as GGUF and Nunchaku Lite can pull kernels from publishers outside kernels-community. Those paths stay blocked unless you opt in with DIFFUSERS_TRUST_REMOTE_KERNELS. When set, Diffusers forwards trust_remote_code=True to Kernels so untrusted publishers can load too.

export DIFFUSERS_TRUST_REMOTE_KERNELS=true

커널 저장소를 검사한 후에만 이 기능을 활성화하세요. 이 기능이 비활성화되어 있으면 신뢰할 수 없는 게시자에서 커널을 로드할 때 오류가 발생합니다. Diffusers가 이 검사를 자체적으로 수행하므로, trust_remote_code 인자가 도입되기 이전인 kernels<0.14.0에도 적용됩니다. DIFFUSERS_DISABLE_REMOTE_CODE=true를 설정하면 원격 코드가 전역적으로 비활성화되며, DIFFUSERS_TRUST_REMOTE_KERNELS보다 우선합니다.

확인

attention dispatcher는 각 attention 호출을 디스패치하기 전에 디버깅 검사를 실행할 수 있습니다. 어떤 검사가 실행되는지는 활성 백엔드에 대해 등록된 제약 조건에 따라 달라집니다.

  1. Device checks는 query, key, value 텐서가 동일한 device에 존재하는지 확인합니다.
  2. 등록된 데이터 타입 체크는 일치하는 dtype를 확인하며, bfloat16 또는 float16를 요구하는 경우가 많습니다.
  3. Shape checks는 텐서 차원을 검증하고 attention mask와 causal flag의 혼합을 방지합니다.

DIFFUSERS_ATTN_CHECKS 환경 변수로 체크를 활성화합니다. 체크는 오버헤드를 유발하므로 기본적으로 비활성화되어 있습니다.

export DIFFUSERS_ATTN_CHECKS=yes

checks가 활성화된 상태에서 Diffusers는 모든 dispatched attention 호출 전에 해당 제약 조건을 실행합니다. 아래 저수준 예제는 dispatch_attention_fn을 직접 호출합니다. Pipeline 추론에는 해당 import가 필요하지 않습니다. set_attention_backend() 또는 attention_backend()를 통해 백엔드만 설정하면 됩니다.

import torch
from diffusers.models.attention_dispatch import attention_backend, dispatch_attention_fn

query = torch.randn(1, 10, 8, 64, dtype=torch.bfloat16, device="cuda")
key = torch.randn(1, 10, 8, 64, dtype=torch.bfloat16, device="cuda")
value = torch.randn(1, 10, 8, 64, dtype=torch.bfloat16, device="cuda")

try:
    with attention_backend("flash"):
        output = dispatch_attention_fn(query, key, value)
        print("✓ Flash Attention works with checks enabled")
except Exception as e:
    print(f"✗ Flash Attention failed: {e}")

사용 가능한 백엔드

사용 가능한 attention 백엔드와 그 변형의 전체 목록은 아래 표를 참조하세요. Diffusers는 백엔드를 활성화할 때 패키지 사용 가능 여부와 버전 고정 여부를 확인합니다.

백엔드 이름패밀리설명Prerequisite
nativePyTorch 네이티브PyTorch의 scaled_dot_product_attention를 사용하는 기본 백엔드None
flexFlexAttentionPyTorch FlexAttentiontorch>=2.5.0
_native_cudnnPyTorch 네이티브CuDNN 최적화 어텐션CUDA + CuDNN
_native_efficientPyTorch 네이티브메모리 효율적인 어텐션PyTorch를 제외하고 없음
_native_flashPyTorch 네이티브PyTorch의 FlashAttentionCUDA
_native_mathPyTorch 네이티브수학 기반 어텐션(폴백)None
_native_npuPyTorch 네이티브NPU 최적화 어텐션torch_npu
_native_xlaPyTorch 네이티브XLA 최적화 어텐션torch_xla>=2.2
flashFlashAttentionFlashAttention-2flash-attn>=2.6.3
flash_hubFlashAttentionHub 커널의 FlashAttention-2kernels>=0.12
flash_varlenFlashAttention가변 길이 FlashAttentionflash-attn>=2.6.3
flash_varlen_hubFlashAttentionHub 커널의 가변 길이 FlashAttentionkernels>=0.12
aiter_fa2_hubROCm용 AI Tensor EngineHub 커널의 AMD ROCm용 FlashAttention-2 (bfloat16)kernels>=0.12, ROCm
flash_4_hubFlashAttentionHub 커널의 FlashAttention-4kernels>=0.12.3
_flash_3FlashAttentionFlashAttention-3 (로컬; 곧 비추천 예정)FA3를 소스에서 빌드
_flash_varlen_3FlashAttention가변 길이 FlashAttention-3 (로컬; 곧 비추천 예정)FA3를 소스에서 빌드
_flash_3_hubFlashAttentionHub 커널의 FlashAttention-3kernels>=0.12
_flash_3_varlen_hubFlashAttentionHub 커널의 가변 길이 FlashAttention-3kernels>=0.12
sageSageAttention양자화 어텐션 (INT8 QK)sageattention>=2.1.1
sage_hubSageAttentionHub 커널의 양자화 어텐션(INT8 QK)kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true
sage_blackwell_hubSageAttentionHub 커널의 SM120 Blackwell GPU용 SageAttention3 FP4 어텐션kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true
sage_varlenSageAttention가변 길이 SageAttentionsageattention>=2.1.1
_sage_qk_int8_pv_fp8_cudaSageAttentionINT8 QK + FP8 PV (CUDA)sageattention>=2.1.1
_sage_qk_int8_pv_fp8_cuda_sm90SageAttentionINT8 QK + FP8 PV (SM90)sageattention>=2.1.1; SM90
_sage_qk_int8_pv_fp16_cudaSageAttentionINT8 QK + FP16 PV (CUDA)sageattention>=2.1.1
_sage_qk_int8_pv_fp16_tritonSageAttentionINT8 QK + FP16 PV (Triton)sageattention>=2.1.1
xformersxFormers메모리 효율적인 어텐션xformers>=0.0.29
Update on GitHub