Diffusers documentation
Dikkat arka uçları
Dikkat arka uçları
Dikkat yönlendirici (attention dispatcher) deneysel bir özelliktir. Herhangi bir geri bildiriminiz varsa veya sorunlarla karşılaşırsanız lütfen bir sorun (issue) açın.
Diffusers transformer modellerinin çoğu, tek bir API arkasında optimize edilmiş arka uçlar arasında geçiş yapmanıza olanak tanımak için dikkati bir attention dispatcher üzerinden yönlendirir. Dispatcher, kayıtlı uygulamaları yönetir ve bunlar için birleşik bir çağrı yolu sunar. Birçok otoencoder gibi bazı modeller, iç yapıları nedeniyle dispatcher kullanmaz ve arka uç değiştirme, bu modellerin dikkat katmanları üzerinde hiçbir etki yaratmaz.
Mevcut dikkat ailelerinin genel bir bakış için aşağıdaki tabloya, daha eksiksiz bir liste için ise Mevcut arka uçlar bölümüne başvurun. En hızlı arka uç, modele, GPU'ya, veri türüne ve girdi şekline bağlıdır.
| attention ailesi | ana özellik |
|---|---|
| FlashAttention | döşeme ve yeniden hesaplama yoluyla bellek okuma/yazma işlemlerini en aza indirir |
| ROCm için AI Tensor Motoru | AMD ROCm hızlandırıcıları için optimize edilmiş FlashAttention uygulaması |
| SageAttention | dikkati int8'e kuantize eder |
| FlexAttention | PyTorch FlexAttention |
| PyTorch yerli | scaled_dot_product_attention kullanan yerleşik PyTorch uygulaması |
| xFormers | çeşitli dikkat çekirdekleri için destek içeren bellek-verimli dikkat |
Hub arka uçları (*_hub adları) Kernels kütüphanesini gerektirir ve çekirdeği ilk kullanımda indirir. SageAttention Hub arka uçları ayrıca DIFFUSERS_TRUST_REMOTE_KERNELS=true değerini gerektirir (bkz. Uzak çekirdekleri güvenme). Diğer arka uçlar, flash-attn veya sageattention gibi kendi paketlerini gerektirir. Kullanılabilir arka uçlar tablosu, bir arka ucu etkinleştirdiğinizde Diffusers'ın kontrol ettiği gereksinimleri listeler.
Modelde bir arka uç ayarlayın
set_attention_backend() metodu, modelin dikkat katmanlarını gezerek seçilen arka ucu her birine uygular. Ayrıca dağıtıcının (dispatcher) süreç genelindeki etkin arka ucunu da aynı değere ayarlar.
reset_attention_backend() yalnızca dikkat katmanlarındaki backend'i temizler. İşlem genelindeki etkin backend'i temizlemez. Çıkışta önceki etkin backend'i geri yükleyen geçici bir geçiş için attention_backend bağlam yöneticisini kullanın.
Aşağıdaki örnek, device_map="cuda" ile _flash_3_hub (Hub'dan FlashAttention-3) etkinleştirir.
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 dışı FlashAttention-3 arka uçları (
_flash_3,_flash_varlen_3) FlashAttention-3'ün kaynak kodundan derlenmesini gerektirir ve yakında kullanımdan kaldırılacaktır. Bunun yerine_flash_3_hubveya_flash_3_varlen_hubkullanın.
Geçici olarak bir arka uç deneyin
attention_backend() bağlam yöneticisi, blok süresince işlem genelinde etkin arka ucu belirler ve blok sonlandığında önceki arka uca geri döner. set_attention_backend() ile kalıcı bir arka uç uygulanmadan, bir arka ucu tek bir çağrı için denemek amacıyla kullanın.
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]Çoğu dikkat (attention) arka ucu
torch.compileile çalışır. Bunun iş akışınızı hızlandırıp hızlandırmayacağı modele ve arka uca bağlıdır. Hassasiyet ve derleme bölümüne bakın.
Uzak çekirdeklere güvenme
Hub arka uçları önce Kernels kütüphanesine ihtiyaç duyar, ardından Diffusers Hub çekirdeğini ilk kullanımda alır.
Hub dikkat (attention) arka uçları, hesaplama çekirdeklerini Kernels kütüphanesiyle indirir ve bunları yerel olarak çalıştırır. Hub dikkat adlarının çoğu (_flash_3_hub, flash_hub ve diğer *_hub arka uçları) kernels-community kuruluşuna çözümlenir. Bu kuruluş, Kernels içinde güvenilir bir yayıncı olduğundan Diffusers, DIFFUSERS_TRUST_REMOTE_KERNELS ayarlamadan bu dikkat çekirdeklerini yükler.
SageAttention Hub arka uçları (
sage_hubvesage_blackwell_hub) bunun yerine SageAttention kuruluşundan yüklenir. Bunları kullanmak içinDIFFUSERS_TRUST_REMOTE_KERNELS=truedeğerini ayarlayın.
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=trueBu ayarı yalnızca çekirdek deposunu inceledikten sonra etkinleştirin. Bu ayar olmadan, güvenilir olmayan bir yayıncıdan çekirdek yüklenmeye çalışıldığında bir hata oluşur. Diffusers bu kontrolü kendisi yaptığından, bu kural trust_remote_code argümanından önce gelen kernels<0.14.0 sürümüne de uygulanır. DIFFUSERS_DISABLE_REMOTE_CODE=true değerini ayarlamak, uzak kodu küresel olarak devre dışı bırakır ve DIFFUSERS_TRUST_REMOTE_KERNELS değişkenine göre önceliklidir.
Kontroller
Dikkat yönlendiricisi, her yönlendirilen dikkat çağrısından önce hata ayıklama kontrolleri çalıştırabilir. Hangi kontrollerin çalışacağı, etkin arka uç için kayıtlı kısıtlamalara bağlıdır.
- Device checks, sorgu, anahtar ve değer tensörlerinin aynı cihazda bulunduğunu doğrular.
- Kayıtlı olan veri türü kontrolleri, eşleşen dtypes'leri doğrular ve genellikle
bfloat16veyafloat16gerektirir. - Shape checks, tensor boyutlarını doğrular ve dikkat maskelerinin nedensel bayraklarla karıştırılmasını önler.
Kontrolleri DIFFUSERS_ATTN_CHECKS ortam değişkeniyle etkinleştirin. Kontroller ek yük oluşturduğundan varsayılan olarak devre dışıdır.
export DIFFUSERS_ATTN_CHECKS=yesKontroller açıkken Diffusers, her yönlendirilen dikkat çağrısından önce bu kısıtlamaları çalıştırır. Aşağıdaki düşük seviyeli örnek dispatch_attention_fn fonksiyonunu doğrudan çağırır. Pipeline çıkarımı için bu içe aktarma gerekmez. Sadece set_attention_backend() veya attention_backend() ile arka ucun ayarlanması yeterlidir.
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}")Kullanılabilir arka uçlar
Mevcut dikkat (attention) arka uçlarının ve varyantlarının tam listesi için aşağıdaki tabloya bakın. Bir arka ucu etkinleştirdiğinizde Diffusers, paket kullanılabilirliğini ve sürüm sabitlemelerini kontrol eder.
| Arka Uygulama Adı | Aile | Açıklama | Ön koşul |
|---|---|---|---|
native | PyTorch yerlisi | PyTorch'un scaled_dot_product_attention'ını kullanan varsayılan backend | None |
flex | FlexAttention | PyTorch FlexAttention | torch>=2.5.0 |
_native_cudnn | PyTorch yerlisi | CuDNN-optimize edilmiş dikkat | CUDA + CuDNN |
_native_efficient | PyTorch yerlisi | Hafıza-verimli dikkat | PyTorch dışında yok |
_native_flash | PyTorch yerlisi | PyTorch’un FlashAttention’ı | CUDA |
_native_math | PyTorch yerlisi | Matematik tabanlı dikkat (yedek) | None |
_native_npu | PyTorch yerlisi | NPU-optimized dikkat | torch_npu |
_native_xla | PyTorch yerlisi | XLA-optimize edilmiş dikkat | torch_xla>=2.2 |
flash | FlashAttention | FlashAttention-2 | flash-attn>=2.6.3 |
flash_hub | FlashAttention | Hub çekirdeklerinden FlashAttention-2 | kernels>=0.12 |
flash_varlen | FlashAttention | Değişken uzunluklu FlashAttention | flash-attn>=2.6.3 |
flash_varlen_hub | FlashAttention | Hub çekirdeklerinden değişken uzunluklu FlashAttention | kernels>=0.12 |
aiter_fa2_hub | ROCm için AI Tensor Engine | Hub çekirdeklerinden AMD ROCm için FlashAttention-2 (bfloat16) | kernels>=0.12, ROCm |
flash_4_hub | FlashAttention | Hub çekirdeklerinden FlashAttention-4 | kernels>=0.12.3 |
_flash_3 | FlashAttention | FlashAttention-3 (yerel; yakında kaldırılacak) | FA3'ü kaynak kodundan derleyin |
_flash_varlen_3 | FlashAttention | Değişken uzunluklu FlashAttention-3 (yerel; yakında kaldırılacak) | FA3'ü kaynak kodundan derleyin |
_flash_3_hub | FlashAttention | Hub çekirdeklerinden FlashAttention-3 | kernels>=0.12 |
_flash_3_varlen_hub | FlashAttention | Hub çekirdeklerinden değişken uzunluklu FlashAttention-3 | kernels>=0.12 |
sage | SageAttention | Kantize edilmiş dikkat (INT8 QK) | sageattention>=2.1.1 |
sage_hub | SageAttention | Hub çekirdeklerinden kuantize edilmiş dikkat (INT8 QK) | kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true |
sage_blackwell_hub | SageAttention | Hub çekirdeklerinden SM120 Blackwell GPU'lar için SageAttention3 FP4 dikkati | kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true |
sage_varlen | SageAttention | Değişken uzunluklu SageAttention | 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 | Hafıza-verimli dikkat | xformers>=0.0.29 |