# Backends de atención

> [!NOTE]
> El despachador de atención es una función experimental. Abra un problema si tiene algún comentario o encuentra algún problema.

Diffusers ofrece varios algoritmos de atención optimizados que son más eficientes en memoria y computación a través de su *attention dispatcher*. El dispatcher actúa como un enrutador para gestionar y cambiar entre diferentes implementaciones de atención y proporciona una interfaz unificada para interactuar con ellas.

Consulte la tabla siguiente para obtener un resumen de las familias de atención disponibles y consulte la sección [Backends disponibles](#available-backends) para obtener una lista más completa.

| familia de atención | característica principal |
|---|---|
| FlashAttention | minimiza las lecturas/escrituras de memoria mediante el uso de teselas y la recomputación |
| Motor de Tensor de IA para ROCm | Implementación de FlashAttention optimizada para aceleradores AMD ROCm |
| SageAttention | cuantiza la atención a int8 |
| PyTorch nativo | implementación integrada de PyTorch que utiliza [scaled_dot_product_attention](./fp16#scaled-dot-product-attention) |
| xFormers | atención eficiente en memoria con soporte para varios núcleos de atención |

Esta guía te mostrará cómo configurar y utilizar los distintos backends de atención.

## set_attention_backend

El método [set_attention_backend()](/docs/diffusers/main/es/api/models/overview#diffusers.ModelMixin.set_attention_backend) recorre todos los módulos del modelo y establece el backend de atención adecuado para usar. La configuración del backend de atención persiste hasta que se llama a [reset_attention_backend()](/docs/diffusers/main/es/api/models/overview#diffusers.ModelMixin.reset_attention_backend).

El siguiente ejemplo muestra cómo habilitar la implementación `_flash_3_hub` para FlashAttention-3 desde la biblioteca [`kernels`](https://github.com/huggingface/kernels), lo que permite usar de inmediato kernels de cálculo optimizados del Hub sin necesidad de ninguna configuración.

> [!NOTE]
> FlashAttention-3 requiere como mínimo GPUs Ampere.

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

Para restaurar el backend de atención predeterminado, llama a [reset_attention_backend()](/docs/diffusers/main/es/api/models/overview#diffusers.ModelMixin.reset_attention_backend).

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

## context manager attention_backend

El gestor de contexto [attention_backend](https://github.com/huggingface/diffusers/blob/5e181eddfe7e44c1444a2511b0d8e21d177850a0/src/diffusers/models/attention_dispatch.py#L225) establece temporalmente un backend de atención para un modelo dentro del contexto. Fuera del contexto, se utiliza la atención predeterminada (la atención de producto escalar de puntos nativa de PyTorch). Esto es útil si deseas usar backends diferentes para distintas partes de un pipeline o si quieres probar los distintos backends.

```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]
> La mayoría de los backends de atención admiten `torch.compile` sin interrupciones del grafo y pueden usarse para acelerar aún más la inferencia.

## Confianza en kernels remotos

Hub backends and other kernel-backed features (such as [GGUF](../quantization/gguf) and [Nunchaku Lite](../quantization/nunchaku)) download compute kernels from the Hub with [`kernels`](https://github.com/huggingface/kernels) and execute their code locally.

By default, `kernels` only loads a kernel when its publisher is a trusted kernel publisher on the Hub. Kernels published under the [`kernels-community`](https://huggingface.co/kernels-community) organization are trusted, so Diffusers loads them without any additional configuration. The `_flash_3_hub`, `flash_hub`, `sage_hub`, and the other Hub attention backends all resolve to `kernels-community` repositories.

Kernels from any other publisher are not vetted. Loading one downloads and runs code that Diffusers cannot vouch for, so Diffusers keeps it disabled unless you explicitly opt in with the `DIFFUSERS_TRUST_REMOTE_KERNELS` environment variable. When set, Diffusers forwards `trust_remote_code=True` to `kernels` so it loads kernels from untrusted publishers too.

```bash
export DIFFUSERS_TRUST_REMOTE_KERNELS=true
```

Solo habilita esto después de inspeccionar el repositorio del kernel, ya que otorga al código descargado la capacidad de ejecutarse en tu máquina. Sin ello, cargar un kernel de un editor no confiable genera un error. Diffusers realiza esta comprobación por sí mismo, por lo que también se aplica a `kernels<0.14.0`, que es anterior al argumento `trust_remote_code`. Establecer `DIFFUSERS_DISABLE_REMOTE_CODE=true` deshabilita el código remoto de forma global y tiene prioridad sobre `DIFFUSERS_TRUST_REMOTE_KERNELS`.

## Comprobaciones

El despachador de atención incluye comprobaciones de depuración que detectan errores comunes antes de que causen problemas.

1. Las comprobaciones de dispositivo verifican que los tensores de consulta, clave y valor estén en el mismo dispositivo.
2. Las comprobaciones de tipo de datos confirman que los tensores tienen dtypes coincidentes y que se utiliza bfloat16 o float16.
3. Las comprobaciones de forma validan las dimensiones de los tensores y evitan mezclar máscaras de atención con banderas causales.

Active estas comprobaciones estableciendo la variable de entorno `DIFFUSERS_ATTN_CHECKS`. Las comprobaciones añaden sobrecarga a cada operación de atención, por lo que están desactivadas de forma predeterminada.

```bash
export DIFFUSERS_ATTN_CHECKS=yes
```

Las comprobaciones se ejecutan ahora antes de cada operación de atención.

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

También puedes configurar el registro directamente.

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

_AttentionBackendRegistry._checks_enabled = True
```

## Backends disponibles

Consulte la tabla siguiente para obtener una lista completa de los backends de atención disponibles y sus variantes.

Expandir

| Nombre del backend | Familia | Descripción |
|--------------|--------|-------------|
| `native` | [PyTorch nativo](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Backend predeterminado que utiliza scaled_dot_product_attention de PyTorch |
| `flex` | [FlexAttention](https://docs.pytorch.org/docs/stable/nn.attention.flex_attention.html#module-torch.nn.attention.flex_attention) | Implementación de FlexAttention de PyTorch |
| `_native_cudnn` | [PyTorch nativo](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Atención optimizada con CuDNN |
| `_native_efficient` | [PyTorch nativo](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Atención eficiente en memoria |
| `_native_flash` | [PyTorch nativo](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | FlashAttention de PyTorch |
| `_native_math` | [PyTorch nativo](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Atención basada en matemáticas (alternativa) |
| `_native_npu` | [PyTorch nativo](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Atención optimizada para NPU |
| `_native_xla` | [PyTorch nativo](https://docs.pytorch.org/docs/stable/generated/torch.nn.attention.SDPBackend.html#torch.nn.attention.SDPBackend) | Atención optimizada con XLA |
| `flash` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-2 |
| `flash_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-2 desde kernels |
| `flash_varlen` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention de longitud variable |
| `flash_varlen_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention de longitud variable desde kernels |
| `aiter_fa2_hub` | [Motor de tensores de IA para ROCm](https://github.com/ROCm/aiter) | FlashAttention-2 para AMD ROCm desde kernels |
| `aiter_sage_hub` | [Motor de tensores de IA para ROCm](https://github.com/ROCm/aiter) | Atención cuantizada (INT8 QK, FP8 PV) para AMD RDNA4 (gfx1201) desde kernels |
| `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 de longitud variable |
| `_flash_3_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 de kernels |
| `_flash_3_varlen_hub` | [FlashAttention](https://github.com/Dao-AILab/flash-attention) | FlashAttention-3 de longitud variable desde kernels |
| `sage` | [SageAttention](https://github.com/thu-ml/SageAttention) | Atención cuantizada (INT8 QK) |
| `sage_hub` | [SageAttention](https://github.com/thu-ml/SageAttention) | Atención cuantizada (INT8 QK) desde kernels |
| `sage_blackwell_hub` | [SageAttention](https://github.com/thu-ml/SageAttention) | Atención SageAttention3 FP4 para GPUs Blackwell SM120 desde kernels |
| `sage_varlen` | [SageAttention](https://github.com/thu-ml/SageAttention) | SageAttention de longitud variable |
| `_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) | Atención eficiente en memoria |