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.

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.