Diffusers documentation

Dikkat arka uçları

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

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 ailesiana özellik
FlashAttentiondöşeme ve yeniden hesaplama yoluyla bellek okuma/yazma işlemlerini en aza indirir
ROCm için AI Tensor MotoruAMD ROCm hızlandırıcıları için optimize edilmiş FlashAttention uygulaması
SageAttentiondikkati int8'e kuantize eder
FlexAttentionPyTorch FlexAttention
PyTorch yerliscaled_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_hub veya _flash_3_varlen_hub kullanı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.compile ile ç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_hub ve sage_blackwell_hub) bunun yerine SageAttention kuruluşundan yüklenir. Bunları kullanmak için DIFFUSERS_TRUST_REMOTE_KERNELS=true değ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=true

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

  1. Device checks, sorgu, anahtar ve değer tensörlerinin aynı cihazda bulunduğunu doğrular.
  2. Kayıtlı olan veri türü kontrolleri, eşleşen dtypes'leri doğrular ve genellikle bfloat16 veya float16 gerektirir.
  3. 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=yes

Kontroller 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ıAileAçıklamaÖn koşul
nativePyTorch yerlisiPyTorch'un scaled_dot_product_attention'ını kullanan varsayılan backendNone
flexFlexAttentionPyTorch FlexAttentiontorch>=2.5.0
_native_cudnnPyTorch yerlisiCuDNN-optimize edilmiş dikkatCUDA + CuDNN
_native_efficientPyTorch yerlisiHafıza-verimli dikkatPyTorch dışında yok
_native_flashPyTorch yerlisiPyTorch’un FlashAttention’ıCUDA
_native_mathPyTorch yerlisiMatematik tabanlı dikkat (yedek)None
_native_npuPyTorch yerlisiNPU-optimized dikkattorch_npu
_native_xlaPyTorch yerlisiXLA-optimize edilmiş dikkattorch_xla>=2.2
flashFlashAttentionFlashAttention-2flash-attn>=2.6.3
flash_hubFlashAttentionHub çekirdeklerinden FlashAttention-2kernels>=0.12
flash_varlenFlashAttentionDeğişken uzunluklu FlashAttentionflash-attn>=2.6.3
flash_varlen_hubFlashAttentionHub çekirdeklerinden değişken uzunluklu FlashAttentionkernels>=0.12
aiter_fa2_hubROCm için AI Tensor EngineHub çekirdeklerinden AMD ROCm için FlashAttention-2 (bfloat16)kernels>=0.12, ROCm
flash_4_hubFlashAttentionHub çekirdeklerinden FlashAttention-4kernels>=0.12.3
_flash_3FlashAttentionFlashAttention-3 (yerel; yakında kaldırılacak)FA3'ü kaynak kodundan derleyin
_flash_varlen_3FlashAttentionDeğişken uzunluklu FlashAttention-3 (yerel; yakında kaldırılacak)FA3'ü kaynak kodundan derleyin
_flash_3_hubFlashAttentionHub çekirdeklerinden FlashAttention-3kernels>=0.12
_flash_3_varlen_hubFlashAttentionHub çekirdeklerinden değişken uzunluklu FlashAttention-3kernels>=0.12
sageSageAttentionKantize edilmiş dikkat (INT8 QK)sageattention>=2.1.1
sage_hubSageAttentionHub çekirdeklerinden kuantize edilmiş dikkat (INT8 QK)kernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true
sage_blackwell_hubSageAttentionHub çekirdeklerinden SM120 Blackwell GPU'lar için SageAttention3 FP4 dikkatikernels>=0.12, DIFFUSERS_TRUST_REMOTE_KERNELS=true
sage_varlenSageAttentionDeğişken uzunluklu 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
xformersxFormersHafıza-verimli dikkatxformers>=0.0.29
Update on GitHub