# Backend perhatian

> [!NOTE]
> Dispatcher perhatian adalah fitur eksperimental. Silakan buka masalah jika Anda memiliki umpan balik atau mengalami masalah.

Diffusers menyediakan beberapa algoritma perhatian yang dioptimalkan, yang lebih hemat memori dan komputasi, melalui *attention dispatcher*-nya. Dispatcher ini berfungsi sebagai router untuk mengelola dan beralih antara berbagai implementasi perhatian, serta menyediakan antarmuka terpadu untuk berinteraksi dengan implementasi tersebut.

Lihat tabel di bawah ini untuk ringkasan keluarga perhatian yang tersedia dan bagian [Backend yang tersedia](#available-backends) untuk daftar yang lebih lengkap.

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

Panduan ini akan menunjukkan cara mengatur dan menggunakan berbagai backend perhatian.

## set_attention_backend

Metode [set_attention_backend()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.set_attention_backend) mengiterasi semua modul dalam model dan mengatur backend perhatian yang sesuai untuk digunakan. Pengaturan backend perhatian ini tetap berlaku hingga [reset_attention_backend()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.reset_attention_backend) dipanggil.

Contoh di bawah ini menunjukkan cara mengaktifkan implementasi `_flash_3_hub` untuk FlashAttention-3 dari pustaka [`kernels`](https://github.com/huggingface/kernels), yang memungkinkan Anda menggunakan kernel komputasi yang dioptimalkan dari Hub secara instan tanpa memerlukan konfigurasi apa pun.

> [!NOTE]
> FlashAttention-3 membutuhkan GPU Ampere sebagai minimum.

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

Untuk memulihkan backend perhatian default, panggil [reset_attention_backend()](/docs/diffusers/main/id/api/models/overview#diffusers.ModelMixin.reset_attention_backend).

```py
pipeline.transformer.reset_attention_backend()
```

## context manager attention_backend

Context manager [attention_backend](https://github.com/huggingface/diffusers/blob/5e181eddfe7e44c1444a2511b0d8e21d177850a0/src/diffusers/models/attention_dispatch.py#L225) secara sementara mengatur backend attention untuk sebuah model di dalam konteks tersebut. Di luar konteks, attention default (scaled dot product attention native dari PyTorch) akan digunakan. Hal ini berguna jika Anda ingin menggunakan backend yang berbeda untuk bagian-bagian berbeda dari sebuah pipeline atau jika Anda ingin menguji berbagai backend.

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

> [!TIP]
> Sebagian besar backend perhatian mendukung `torch.compile` tanpa pemutusan graf dan dapat digunakan untuk mempercepat inferensi lebih lanjut.

## Memercayai kernel jarak jauh

Backend Hub dan fitur lain yang didukung kernel (seperti [GGUF](../quantization/gguf) dan [Nunchaku Lite](../quantization/nunchaku)) mengunduh kernel komputasi dari Hub dengan [`kernels`](https://github.com/huggingface/kernels) dan mengeksekusi kodenya secara lokal.

Secara default, `kernels` hanya memuat kernel ketika penerbitnya adalah penerbit kernel yang tepercaya di Hub. Kernel yang diterbitkan di bawah organisasi [`kernels-community`](https://huggingface.co/kernels-community) tepercaya, sehingga Diffusers memuatnya tanpa konfigurasi tambahan. `_flash_3_hub`, `flash_hub`, `sage_hub`, dan backend perhatian Hub lainnya semuanya merujuk ke repositori `kernels-community`.

Kernel dari penerbit lain tidak melalui proses verifikasi. Memuat salah satunya akan mengunduh dan menjalankan kode yang tidak dapat dijamin keamanannya oleh Diffusers, sehingga Diffusers tetap menonaktifkannya kecuali Anda secara eksplisit mengaktifkannya dengan variabel lingkungan `DIFFUSERS_TRUST_REMOTE_KERNELS`. Jika disetel, Diffusers meneruskan `trust_remote_code=True` ke `kernels` sehingga kernel dari penerbit yang tidak tepercaya juga dimuat.

```bash
export DIFFUSERS_TRUST_REMOTE_KERNELS=true
```

Hanya aktifkan ini setelah memeriksa repositori kernel, karena hal ini memberikan kemampuan pada kode yang diunduh untuk dijalankan di mesin Anda. Tanpa ini, 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 mencakup pemeriksaan debug yang menangkap kesalahan umum sebelum menyebabkan masalah.

1. Periksa perangkat memverifikasi bahwa tensor query, key, dan value berada di perangkat yang sama.
2. Pemeriksaan tipe data memastikan tensor memiliki dtype yang cocok dan menggunakan bfloat16 atau float16.
3. Pemeriksaan bentuk memvalidasi dimensi tensor dan mencegah pencampuran masker perhatian dengan bendera kausal.

Aktifkan pemeriksaan ini dengan mengatur variabel lingkungan `DIFFUSERS_ATTN_CHECKS`. Pemeriksaan menambah overhead pada setiap operasi perhatian, sehingga dinonaktifkan secara default.

```bash
export DIFFUSERS_ATTN_CHECKS=yes
```

Pemeriksaan sekarang dijalankan sebelum setiap operasi perhatian.

```py
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}")
```

Anda juga dapat mengatur registry secara langsung.

```py
from diffusers.models.attention_dispatch import _AttentionBackendRegistry

_AttentionBackendRegistry._checks_enabled = True
```

## Backend yang tersedia

Lihat tabel di bawah ini untuk daftar lengkap backend perhatian yang tersedia beserta variasinya.

Perluas

| Nama Backend | Keluarga | Deskripsi |
|--------------|--------|-------------|
| `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 |
| `flex` | [FlexAttention](https://docs.pytorch.org/docs/stable/nn.attention.flex_attention.html#module-torch.nn.attention.flex_attention) | Implementasi PyTorch FlexAttention |
| `_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 |
| `_native_efficient` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Perhatian hemat memori |
| `_native_flash` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | FlashAttention dari PyTorch |
| `_native_math` | [PyTorch native](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Perhatian berbasis matematika (cadangan) |
| `_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 |
| `_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 |
| `flash` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-2 |
| `flash_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-2 dari kernel |
| `flash_varlen` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention dengan panjang variabel |
| `flash_varlen_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention dengan panjang variabel dari kernel |
| `aiter_fa2_hub` | [AI Tensor Engine untuk ROCm](https://github.com/ROCm/aiter) | FlashAttention-2 untuk AMD ROCm dari kernel |
| `aiter_sage_hub` | [AI Tensor Engine untuk ROCm](https://github.com/ROCm/aiter) | Perhatian terkuantisasi (INT8 QK, FP8 PV) untuk AMD RDNA4 (gfx1201) dari kernel |
| `flash_4_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-4 |
| `_flash_3` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 |
| `_flash_varlen_3` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 dengan panjang variabel |
| `_flash_3_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 dari kernel |
| `_flash_3_varlen_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 dengan panjang variabel dari kernel |
| `sage` | [SageAttention](https://github.com/thu-ml/SageAttention) | Perhatian terkuantisasi (INT8 QK) |
| `sage_hub` | [SageAttention](https://github.com/thu-ml/SageAttention) | Perhatian terkuantisasi (INT8 QK) dari kernel |
| `sage_blackwell_hub` | [SageAttention](https://github.com/thu-ml/SageAttention) | Perhatian SageAttention3 FP4 untuk GPU Blackwell SM120 dari kernel |
| `sage_varlen` | [SageAttention](https://github.com/thu-ml/SageAttention) | SageAttention dengan panjang variabel |
| `_sage_qk_int8_pv_fp8_cuda` | [SageAttention](https://github.com/thu-ml/SageAttention) | INT8 QK + FP8 PV (CUDA) |
| `_sage_qk_int8_pv_fp8_cuda_sm90` | [SageAttention](https://github.com/thu-ml/SageAttention) | INT8 QK + FP8 PV (SM90) |
| `_sage_qk_int8_pv_fp16_cuda` | [SageAttention](https://github.com/thu-ml/SageAttention) | INT8 QK + FP16 PV (CUDA) |
| `_sage_qk_int8_pv_fp16_triton` | [SageAttention](https://github.com/thu-ml/SageAttention) | INT8 QK + FP16 PV (Triton) |
| `xformers` | [xFormers](https://github.com/facebookresearch/xformers) | Perhatian hemat memori |