diffusers/main/id/optimization/attention_backends.md

Backend perhatian

Dispatcher perhatian adalah fitur eksperimental. Silakan buka masalah jika Anda memiliki umpan balik atau mengalami masalah.

Sebagian besar model transformer Diffusers merutekan perhatian melalui attention dispatcher sehingga Anda dapat mengganti backend yang dioptimalkan di balik satu API. Dispatcher mengelola implementasi yang terdaftar dan memaparkan jalur pemanggilan yang terpadu untuk mereka. Beberapa model, seperti banyak autoencoder, tidak menggunakan dispatcher karena bagian internalnya, dan mengganti backend tidak berdampak pada lapisan perhatian mereka.

Lihat tabel di bawah ini untuk ringkasan keluarga attention yang tersedia dan bagian Backends yang tersedia untuk daftar yang lebih lengkap. Backend tercepat bergantung pada model, GPU, dtype, dan bentuk input.

keluarga attention	fitur utama
FlashAttention	meminimalkan pembacaan/penulisan memori melalui tiling dan komputasi ulang
AI Tensor Engine untuk ROCm	Implementasi FlashAttention yang dioptimalkan untuk akselerator AMD ROCm
SageAttention	mengkuantisasi perhatian ke int8
FlexAttention	PyTorch FlexAttention
PyTorch native	implementasi PyTorch bawaan menggunakan scaled_dot_product_attention
xFormers	perhatian hemat memori dengan dukungan untuk berbagai kernel perhatian

Backend Hub (nama *_hub) memerlukan pustaka Kernels dan mengunduh kernel pada penggunaan pertama. Backend Hub SageAttention juga memerlukan DIFFUSERS_TRUST_REMOTE_KERNELS=true (lihat Mempercayai kernel jarak jauh). Backend lain memerlukan paketnya masing-masing, seperti flash-attn atau sageattention. Tabel Backend yang tersedia mencantumkan persyaratan yang diperiksa Diffusers saat Anda mengaktifkan backend.

Atur backend pada model

Metode set_attention_backend() menelusuri lapisan perhatian model dan menerapkan backend yang dipilih pada masing-masing lapisan. Metode ini juga mengatur backend aktif dispatcher untuk seluruh proses ke nilai yang sama.

reset_attention_backend() hanya membersihkan backend pada lapisan attention. Fungsi ini tidak membersihkan backend aktif yang berlaku untuk seluruh proses. Untuk peralihan sementara yang memulihkan backend aktif sebelumnya saat keluar, gunakan context manager attention_backend.

Contoh di bawah ini mengaktifkan _flash_3_hub (FlashAttention-3 dari Hub) dengan device_map="cuda".

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]

Backend FlashAttention-3 non-Hub (_flash_3, _flash_varlen_3) memerlukan pembangunan FlashAttention-3 dari sumber dan akan segera dihentikan. Gunakan _flash_3_hub atau _flash_3_varlen_hub sebagai gantinya.

Coba backend secara sementara

Context manager attention_backend() mengatur backend aktif untuk seluruh proses selama blok berjalan dan memulihkan backend sebelumnya saat blok berakhir. Gunakan ini untuk mencoba backend pada satu panggilan tanpa meninggalkan backend permanen yang diterapkan dari 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]

Sebagian besar backend attention bekerja dengan torch.compile. Apakah hal itu mempercepat pipeline Anda bergantung pada model dan backend. Lihat Precision and compilation.

Memercayai kernel jarak jauh

Backend Hub memerlukan pustaka Kernels terlebih dahulu, dan kemudian Diffusers mengambil kernel Hub saat pertama kali digunakan.

Backend perhatian Hub mengunduh kernel komputasi dengan pustaka Kernels dan menjalankannya secara lokal. Sebagian besar nama perhatian Hub (_flash_3_hub, flash_hub, dan backend *_hub lainnya) merujuk ke organisasi kernels-community. Organisasi tersebut adalah penerbit tepercaya di Kernels, sehingga Diffusers memuat kernel perhatian tersebut tanpa mengatur DIFFUSERS_TRUST_REMOTE_KERNELS.

Backend SageAttention Hub (sage_hub dan sage_blackwell_hub) memuat dari organisasi SageAttention sebagai gantinya. Atur DIFFUSERS_TRUST_REMOTE_KERNELS=true untuk menggunakannya.

Fitur lain yang didukung kernel, seperti GGUF dan Nunchaku Lite, dapat menarik kernel dari penerbit di luar kernels-community. Jalur tersebut tetap diblokir kecuali Anda mengaktifkannya dengan DIFFUSERS_TRUST_REMOTE_KERNELS. Jika disetel, Diffusers meneruskan trust_remote_code=True ke Kernels sehingga penerbit yang tidak tepercaya juga dapat dimuat.

export DIFFUSERS_TRUST_REMOTE_KERNELS=true

Hanya aktifkan ini setelah memeriksa repositori kernel. Tanpanya, memuat kernel dari penerbit yang tidak tepercaya akan memicu error. Diffusers melakukan pemeriksaan ini sendiri, sehingga juga berlaku untuk kernels<0.14.0, yang mendahului argumen trust_remote_code. Mengatur DIFFUSERS_DISABLE_REMOTE_CODE=true akan menonaktifkan kode jarak jauh secara global dan memiliki prioritas lebih tinggi daripada DIFFUSERS_TRUST_REMOTE_KERNELS.

Pemeriksaan

Dispatcher perhatian dapat menjalankan pemeriksaan debugging sebelum setiap panggilan perhatian yang didispatch. Pemeriksaan yang dijalankan bergantung pada kendala yang terdaftar untuk backend aktif.

1. Periksa perangkat memverifikasi bahwa tensor query, key, dan value berada di perangkat yang sama.
2. Pemeriksaan tipe data, jika terdaftar, memastikan kecocokan dtype dan sering kali memerlukan bfloat16 atau float16.
3. Pemeriksaan bentuk memvalidasi dimensi tensor dan mencegah pencampuran masker perhatian dengan bendera kausal.

Aktifkan pemeriksaan dengan variabel lingkungan DIFFUSERS_ATTN_CHECKS. Pemeriksaan menambah overhead, sehingga dinonaktifkan secara default.

export DIFFUSERS_ATTN_CHECKS=yes

Dengan pengecekan aktif, Diffusers menjalankan constraint tersebut sebelum setiap panggilan perhatian yang di-dispatch. Contoh tingkat rendah di bawah ini memanggil dispatch_attention_fn secara langsung. Inferensi pipeline tidak memerlukan impor tersebut. Yang dibutuhkan hanyalah backend yang diatur melalui set_attention_backend() atau 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}")

Backend yang tersedia

Lihat tabel di bawah untuk daftar lengkap backend perhatian yang tersedia beserta variannya. Diffusers memeriksa ketersediaan paket dan versi pin saat Anda mengaktifkan backend.

Nama Backend	Keluarga	Deskripsi	Prasyarat
native	PyTorch native	Backend default menggunakan scaled_dot_product_attention dari PyTorch	None
flex	FlexAttention	PyTorch FlexAttention	torch>=2.5.0
_native_cudnn	PyTorch native	Perhatian yang dioptimalkan dengan CuDNN	CUDA + CuDNN
_native_efficient	PyTorch native	Perhatian hemat memori	Tidak ada selain PyTorch
_native_flash	PyTorch native	FlashAttention dari PyTorch	CUDA
_native_math	PyTorch native	Perhatian berbasis matematika (cadangan)	None
_native_npu	PyTorch native	Perhatian yang dioptimalkan untuk NPU	torch_npu
_native_xla	PyTorch native	Perhatian yang dioptimalkan dengan XLA	torch_xla>=2.2
flash	FlashAttention	FlashAttention-2	flash-attn>=2.6.3
flash_hub	FlashAttention	FlashAttention-2 dari kernel Hub	kernels>=0.12
flash_varlen	FlashAttention	FlashAttention dengan panjang variabel	flash-attn>=2.6.3
flash_varlen_hub	FlashAttention	FlashAttention dengan panjang variabel dari kernel Hub	kernels>=0.12
aiter_fa2_hub	AI Tensor Engine untuk ROCm	FlashAttention-2 untuk AMD ROCm dari Hub kernels (bfloat16)	kernels>=0.12, ROCm
flash_4_hub	FlashAttention	FlashAttention-4 dari kernel Hub	kernels>=0.12.3
_flash_3	FlashAttention	FlashAttention-3 (lokal; segera tidak didukung)	Build FA3 dari sumber
_flash_varlen_3	FlashAttention	FlashAttention-3 dengan panjang variabel (lokal; segera tidak didukung)	Build FA3 dari sumber
_flash_3_hub	FlashAttention	FlashAttention-3 dari kernel Hub	kernels>=0.12
_flash_3_varlen_hub	FlashAttention	FlashAttention-3 dengan panjang variabel dari kernel Hub	kernels>=0.12
sage	SageAttention	Perhatian terkuantisasi (INT8 QK)	sageattention>=2.1.1
sage_hub	SageAttention	Perhatian terkuantisasi (INT8 QK) dari kernel Hub	kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true
sage_blackwell_hub	SageAttention	Perhatian SageAttention3 FP4 untuk GPU Blackwell SM120 dari kernel Hub	kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true
sage_varlen	SageAttention	SageAttention dengan panjang variabel	sageattention>=2.1.1
_sage_qk_int8_pv_fp8_cuda	SageAttention	INT8 QK + FP8 PV (CUDA)	sageattention>=2.1.1
_sage_qk_int8_pv_fp8_cuda_sm90	SageAttention	INT8 QK + FP8 PV (SM90)	sageattention>=2.1.1; SM90
_sage_qk_int8_pv_fp16_cuda	SageAttention	INT8 QK + FP16 PV (CUDA)	sageattention>=2.1.1
_sage_qk_int8_pv_fp16_triton	SageAttention	INT8 QK + FP16 PV (Triton)	sageattention>=2.1.1
xformers	xFormers	Perhatian hemat memori	xformers>=0.0.29