diffusers/main/tr/optimization/attention_backends.md

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, dikkat yönlendiricisi aracılığıyla daha az bellek ve hesaplama gerektiren çeşitli optimize edilmiş dikkat algoritmaları sunar. Yönlendirici, farklı dikkat uygulamaları arasında yönetimi ve geçişi sağlamak için bir yönlendirici olarak çalışır ve bunlarla etkileşim için birleşik bir arayüz sunar.

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.

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
PyTorch yerli	scaled_dot_product_attention kullanan yerleşik PyTorch uygulaması
xFormers	çeşitli dikkat çekirdekleri için destek içeren bellek-verimli dikkat

Bu kılavuz, farklı dikkat (attention) arka uçlarını (backends) nasıl ayarlayıp kullanacağınızı gösterecektir.

set_attention_backend

set_attention_backend() metodu, modeldeki tüm modülleri iterasyonla gezer ve kullanılacak uygun dikkat (attention) arka ucunu ayarlar. Dikkat arka ucu ayarı, reset_attention_backend() çağrılana kadar geçerliliğini korur.

Aşağıdaki örnek, kernels kütüphanesinden FlashAttention-3 için _flash_3_hub uygulamasını nasıl etkinleştirebileceğinizi gösterir; bu sayede herhangi bir kurulum gerektirmeden Hub'daki optimize edilmiş hesaplama çekirdeklerini anında kullanabilirsiniz.

FlashAttention-3 en az Ampere GPU'ları gerektirir.

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
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]

Varsayılan dikkat arka ucunu geri yüklemek için reset_attention_backend() çağrısını yapın.

pipeline.transformer.reset_attention_backend()

attention_backend bağlam yöneticisi

attention_backend bağlam yöneticisi, bir model için bir dikkat (attention) arka ucunu bağlam içinde geçici olarak ayarlar. Bağlam dışında, varsayılan dikkat (PyTorch'un yerel ölçekli nokta çarpımı dikkati) kullanılır. Bir iş akışının farklı bölümleri için farklı arka uçlar kullanmak veya farklı arka uçları test etmek istiyorsanız bu işe yarar.

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
    "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
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, grafik kırılmaları olmadan torch.compile destekler ve çıkarımı (inference) daha da hızlandırmak için kullanılabilir.

Uzak çekirdeklere güvenme

Hub arka uçları ve diğer çekirdek destekli özellikler (örneğin GGUF ve Nunchaku Lite), hesaplama çekirdeklerini kernels ile Hub'dan indirir ve kodlarını yerel olarak çalıştırır.

Varsayılan olarak kernels, yalnızca Hub'da güvenilir bir çekirdek yayıncısı tarafından yayınlandığında bir çekirdeği yükler. kernels-community kuruluşu altında yayınlanan çekirdekler güvenilirdir, bu nedenle Diffusers bunları ek bir yapılandırma gerektirmeden yükler. _flash_3_hub, flash_hub, sage_hub ve diğer Hub dikkat arka uçlarının tümü kernels-community depolarına çözümlenir.

Diğer yayıncılardan gelen çekirdekler denetlenmez. Bunlardan birini yüklemek, Diffusers'ın garantisi olmayan kodu indirir ve çalıştırır; bu nedenle Diffusers, DIFFUSERS_TRUST_REMOTE_KERNELS ortam değişkeniyle açıkça onay vermedikçe bu özelliği devre dışı bırakır. Bu değişken ayarlandığında, Diffusers kernels bileşenine trust_remote_code=True parametresini iletir ve böylece güvenilmeyen yayıncılardan da çekirdekler yüklenir.

export DIFFUSERS_TRUST_REMOTE_KERNELS=true

Bu ayarı, çekirdek deposunu inceledikten sonra etkinleştirin; çünkü indirilen kodun makinenizde çalışmasına izin verir. 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ü için de geçerlidir. 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 öncelik tanır.

Kontroller

Dikkat yönlendiricisi, sorunlara yol açmadan önce yaygın hataları yakalayan hata ayıklama kontrolleri içerir.

1. Device checks, sorgu, anahtar ve değer tensörlerinin aynı cihazda bulunduğunu doğrular.
2. Veri türü kontrolleri, tensörlerin eşleşen dtypes'a sahip olduğunu ve bfloat16 veya float16 kullanıldığını doğrular.
3. Shape checks, tensor boyutlarını doğrular ve dikkat maskelerinin nedensel bayraklarla karıştırılmasını önler.

Bu kontrolleri etkinleştirmek için DIFFUSERS_ATTN_CHECKS ortam değişkenini ayarlayın. Kontroller her dikkat işleminde ek yük oluşturduğundan varsayılan olarak devre dışıdır.

export DIFFUSERS_ATTN_CHECKS=yes

Kontroller artık her dikkat (attention) işleminden önce çalıştırılır.

import torch

query = torch.randn(1, 10, 8, 64, dtype=torch.bfloat16, device="cuda")  # or "mps", "xpu", "cpu"
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}")

Ayrıca kayıt defterini doğrudan yapılandırabilirsiniz.

from diffusers.models.attention_dispatch import _AttentionBackendRegistry

_AttentionBackendRegistry._checks_enabled = True

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.

Genişlet

Arka Uygulama Adı	Aile	Açıklama
native	PyTorch yerlisi	PyTorch'un scaled_dot_product_attention'ını kullanan varsayılan backend
flex	FlexAttention	PyTorch FlexAttention uygulaması
_native_cudnn	PyTorch yerlisi	CuDNN-optimize edilmiş dikkat
_native_efficient	PyTorch yerlisi	Hafıza-verimli dikkat
_native_flash	PyTorch yerlisi	PyTorch'un FlashAttention'ı
_native_math	PyTorch yerlisi	Matematik tabanlı dikkat (yedek)
_native_npu	PyTorch yerlisi	NPU-optimized dikkat
_native_xla	PyTorch yerlisi	XLA-optimize edilmiş dikkat
flash	FlashAttention	FlashAttention-2
flash_hub	FlashAttention	Çekirdeklerden FlashAttention-2
flash_varlen	FlashAttention	Değişken uzunluklu FlashAttention
flash_varlen_hub	FlashAttention	Çekirdeklerden değişken uzunluklu FlashAttention
aiter_fa2_hub	ROCm için AI Tensor Engine	kernels'ten AMD ROCm için FlashAttention-2
aiter_sage_hub	ROCm için AI Tensor Engine	kernels'ten AMD RDNA4 (gfx1201) için kuantize edilmiş dikkat (INT8 QK, FP8 PV)
flash_4_hub	FlashAttention	FlashAttention-4
_flash_3	FlashAttention	FlashAttention-3
_flash_varlen_3	FlashAttention	Değişken uzunluklu FlashAttention-3
_flash_3_hub	FlashAttention	kernels'ten FlashAttention-3
_flash_3_varlen_hub	FlashAttention	Çekirdeklerden değişken uzunluklu FlashAttention-3
sage	SageAttention	Kantize edilmiş dikkat (INT8 QK)
sage_hub	SageAttention	Çekirdeklerden kuantize edilmiş dikkat (INT8 QK)
sage_blackwell_hub	SageAttention	kernels'ten SM120 Blackwell GPU'lar için SageAttention3 FP4 dikkati
sage_varlen	SageAttention	Değişken uzunluklu SageAttention
_sage_qk_int8_pv_fp8_cuda	SageAttention	INT8 QK + FP8 PV (CUDA)
_sage_qk_int8_pv_fp8_cuda_sm90	SageAttention	INT8 QK + FP8 PV (SM90)
_sage_qk_int8_pv_fp16_cuda	SageAttention	INT8 QK + FP16 PV (CUDA)
_sage_qk_int8_pv_fp16_triton	SageAttention	INT8 QK + FP16 PV (Triton)
xformers	xFormers	Hafıza-verimli dikkat