# Backend perhatian

> [!NOTE]
> 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](#available-backends) untuk daftar yang lebih lengkap. Backend tercepat bergantung pada model, GPU, dtype, dan bentuk input.

| keluarga attention | fitur utama |
|---|---|
| FlashAttention | meminimalkan pembacaan/penulisan memori melalui tiling dan komputasi ulang |
| AI Tensor Engine untuk ROCm | Implementasi FlashAttention yang dioptimalkan untuk akselerator AMD ROCm |
| SageAttention | mengkuantisasi perhatian ke int8 |
| FlexAttention | PyTorch FlexAttention |
| PyTorch native | implementasi PyTorch bawaan menggunakan [scaled_dot_product_attention](./fp16#scaled-dot-product-attention) |
| xFormers | perhatian hemat memori dengan dukungan untuk berbagai kernel perhatian |

Backend Hub (nama `*_hub`) memerlukan pustaka [Kernels](https://github.com/huggingface/kernels) dan mengunduh kernel pada penggunaan pertama. Backend Hub SageAttention juga memerlukan `DIFFUSERS_TRUST_REMOTE_KERNELS=true` (lihat [Mempercayai kernel jarak jauh](#trusting-remote-kernels)). Backend lain memerlukan paketnya masing-masing, seperti `flash-attn` atau `sageattention`. Tabel [Backend yang tersedia](#available-backends) mencantumkan persyaratan yang diperiksa Diffusers saat Anda mengaktifkan backend.

## Atur backend pada model

Metode [set_attention_backend()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.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()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.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](#try-a-backend-temporarily).

Contoh di bawah ini mengaktifkan `_flash_3_hub` (FlashAttention-3 dari Hub) dengan `device_map="cuda"`.

```py
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]
```

> [!NOTE]
> 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()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.set_attention_backend).

```py
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]
```

> [!TIP]
> Sebagian besar backend attention bekerja dengan `torch.compile`. Apakah hal itu mempercepat pipeline Anda bergantung pada model dan backend. Lihat [Precision and compilation](./fp16#torchcompile).

## Memercayai kernel jarak jauh

Backend Hub memerlukan pustaka [Kernels](https://github.com/huggingface/kernels) terlebih dahulu, dan kemudian Diffusers mengambil kernel Hub saat pertama kali digunakan.

Backend perhatian Hub mengunduh kernel komputasi dengan pustaka [Kernels](https://github.com/huggingface/kernels) dan menjalankannya secara lokal. Sebagian besar nama perhatian Hub (`_flash_3_hub`, `flash_hub`, dan backend `*_hub` lainnya) merujuk ke organisasi [kernels-community](https://huggingface.co/kernels-community). Organisasi tersebut adalah penerbit tepercaya di Kernels, sehingga Diffusers memuat kernel perhatian tersebut tanpa mengatur `DIFFUSERS_TRUST_REMOTE_KERNELS`.

> [!NOTE]
> Backend SageAttention Hub (`sage_hub` dan `sage_blackwell_hub`) memuat dari organisasi [SageAttention](https://huggingface.co/SageAttention) sebagai gantinya. Atur `DIFFUSERS_TRUST_REMOTE_KERNELS=true` untuk menggunakannya.

Fitur lain yang didukung kernel, seperti [GGUF](../quantization/gguf) dan [Nunchaku Lite](../quantization/nunchaku), 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.

```bash
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.

```bash
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()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.set_attention_backend) atau `attention_backend()`.

```py
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.

| Nama Backend | Keluarga | Deskripsi | Prasyarat |
|--------------|--------|-------------|--------------|
| `native` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Backend default menggunakan scaled_dot_product_attention dari PyTorch | None |
| `flex` | [FlexAttention](https://docs.pytorch.org/docs/stable/nn.attention.flex_attention.html#module-torch.nn.attention.flex_attention) | PyTorch FlexAttention | `torch>=2.5.0` |
| `_native_cudnn` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Perhatian yang dioptimalkan dengan CuDNN | CUDA + CuDNN |
| `_native_efficient` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Perhatian hemat memori | Tidak ada selain PyTorch |
| `_native_flash` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | FlashAttention dari PyTorch | CUDA |
| `_native_math` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Perhatian berbasis matematika (cadangan) | None |
| `_native_npu` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Perhatian yang dioptimalkan untuk NPU | `torch_npu` |
| `_native_xla` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Perhatian yang dioptimalkan dengan XLA | `torch_xla>=2.2` |
| `flash` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-2 | `flash-attn>=2.6.3` |
| `flash_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-2 dari kernel Hub | `kernels>=0.12` |
| `flash_varlen` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention dengan panjang variabel | `flash-attn>=2.6.3` |
| `flash_varlen_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention dengan panjang variabel dari kernel Hub | `kernels>=0.12` |
| `aiter_fa2_hub` | [AI Tensor Engine untuk ROCm](https://github.com/ROCm/aiter) | FlashAttention-2 untuk AMD ROCm dari Hub kernels (`bfloat16`) | `kernels>=0.12`, ROCm |
| `flash_4_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-4 dari kernel Hub | `kernels>=0.12.3` |
| `_flash_3` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 (lokal; segera tidak didukung) | Build FA3 dari sumber |
| `_flash_varlen_3` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 dengan panjang variabel (lokal; segera tidak didukung) | Build FA3 dari sumber |
| `_flash_3_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 dari kernel Hub | `kernels>=0.12` |
| `_flash_3_varlen_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 dengan panjang variabel dari kernel Hub | `kernels>=0.12` |
| `sage` | [SageAttention](https://github.com/thu-ml/SageAttention) | Perhatian terkuantisasi (INT8 QK) | `sageattention>=2.1.1` |
| `sage_hub` | [SageAttention](https://github.com/thu-ml/SageAttention) | Perhatian terkuantisasi (INT8 QK) dari kernel Hub | `kernels>=0.12`, `DIFFUSERS_TRUST_REMOTE_KERNELS=true` |
| `sage_blackwell_hub` | [SageAttention](https://github.com/thu-ml/SageAttention) | Perhatian SageAttention3 FP4 untuk GPU Blackwell SM120 dari kernel Hub | `kernels>=0.12`, `DIFFUSERS_TRUST_REMOTE_KERNELS=true` |
| `sage_varlen` | [SageAttention](https://github.com/thu-ml/SageAttention) | SageAttention dengan panjang variabel | `sageattention>=2.1.1` |
| `_sage_qk_int8_pv_fp8_cuda` | [SageAttention](https://github.com/thu-ml/SageAttention) | INT8 QK + FP8 PV (CUDA) | `sageattention>=2.1.1` |
| `_sage_qk_int8_pv_fp8_cuda_sm90` | [SageAttention](https://github.com/thu-ml/SageAttention) | INT8 QK + FP8 PV (SM90) | `sageattention>=2.1.1`; SM90 |
| `_sage_qk_int8_pv_fp16_cuda` | [SageAttention](https://github.com/thu-ml/SageAttention) | INT8 QK + FP16 PV (CUDA) | `sageattention>=2.1.1` |
| `_sage_qk_int8_pv_fp16_triton` | [SageAttention](https://github.com/thu-ml/SageAttention) | INT8 QK + FP16 PV (Triton) | `sageattention>=2.1.1` |
| `xformers` | [xFormers](https://github.com/facebookresearch/xformers) | Perhatian hemat memori | `xformers>=0.0.29` |