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.

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 yerleşik ö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.