Attention 后端功能支持

本文档由 tools/pre_commit/generate_attention_backend_docs.py 自动生成。它展示了基于 AttentionBackend.validate_configuration() 检查的每个已注册 Attention 后端的功能支持情况。

请勿手动编辑此文件。 运行以下命令重新生成：

python tools/pre_commit/generate_attention_backend_docs.py

设置 Attention 后端

命令行

可以通过两种方式在命令行指定后端：

选项 1：使用 --attention-backend (简单模式)

vllm serve <model> --attention-backend FLASH_ATTN

选项 2：使用 --attention-config.backend / -ac.backend (结构化配置)

# Dot notation
vllm serve <model> --attention-config.backend FLASH_ATTN
vllm serve <model> -ac.backend FLASH_ATTN

# JSON format
vllm serve <model> --attention-config '{"backend": "FLASH_ATTN"}'
vllm serve <model> -ac '{"backend": "FLASH_ATTN"}'

注意： --attention-backend 和 --attention-config.backend 是互斥的。请使用其中一种，不能同时使用。

Python API

在使用 AttentionConfig 的 LLM 类时使用。

from vllm import LLM
from vllm.config import AttentionConfig
from vllm.v1.attention.backends.registry import AttentionBackendEnum

# Method 1: Using AttentionConfig with enum
llm = LLM(
    model="Qwen/Qwen3-0.6B",
    attention_config=AttentionConfig(backend=AttentionBackendEnum.FLASH_ATTN),
)

# Method 2: Using attention_backend parameter with string
llm = LLM(
    model="Qwen/Qwen3-0.6B",
    attention_backend="FLASH_ATTN",
)

后端选择行为

手动选择

当您通过 --attention-backend 或 AttentionConfig 显式设置后端时：

1. 后端将根据您的配置（模型数据类型、头大小、计算能力等）进行验证。
2. 如果后端不支持您的配置，将抛出错误并给出具体原因。
3. 如果验证通过，则使用该后端。

选择不兼容后端时的错误示例：

ValueError: Selected backend FLASHMLA is not valid for this configuration.
Reason: ['compute capability not supported']

自动选择

当未指定后端（默认情况）时：

1. vLLM 会按照优先级顺序遍历后端（参见下表）。
2. 每个后端都会根据您的配置进行验证。
3. 选择第一个兼容的后端。
4. 如果没有后端兼容，将抛出错误，列出所有后端及其不兼容的原因。

后端优先级 (CUDA)

当未显式选择后端时，vLLM 会从这些按优先级排序的列表中选择第一个兼容的后端。

优先级 1 = 最高（最先尝试）。

标准 Attention (MHA, MQA, GQA)

Blackwell (SM 10.x)

优先级	Backend
1	FLASHINFER
2	FLASH_ATTN
3	TRITON_ATTN
4	FLEX_ATTENTION

Ampere/Hopper (SM 8.x-9.x)

优先级	Backend
1	FLASH_ATTN
2	FLASHINFER
3	TRITON_ATTN
4	FLEX_ATTENTION

MLA Attention (DeepSeek 风格)

Blackwell (SM 10.x)

优先级	Backend
1	FLASHINFER_MLA
2	CUTLASS_MLA
3	FLASH_ATTN_MLA
4	FLASHMLA
5	TRITON_MLA
6	FLASHINFER_MLA_SPARSE*
7	FLASHMLA_SPARSE

Ampere/Hopper (SM 8.x-9.x)

优先级	Backend
1	FLASH_ATTN_MLA
2	FLASHMLA
3	FLASHINFER_MLA
4	TRITON_MLA
5	FLASHMLA_SPARSE

* 对于稀疏 MLA，FP8 KV 缓存总是首选 FLASHINFER_MLA_SPARSE。对于 BF16 KV 缓存，如果查询头数较少 (<= 16)，首选 FLASHINFER_MLA_SPARSE，否则首选 FLASHMLA_SPARSE。

注意： ROCm 和 CPU 平台有其各自的选择逻辑。详情请参阅特定平台的文档。

图例

列	描述
Dtypes (数据类型)	支持的模型数据类型 (fp16, bf16, fp32)
KV Dtypes	支持的 KV 缓存数据类型 (auto, fp8, fp8_e4m3 等)
Block Sizes (块大小)	支持的 KV 缓存块大小 (%N 表示 N 的倍数)
Head Sizes (头大小)	支持的 Attention 头大小
Sink	Attention Sink 支持 (用于 StreamingLLM)
Sparse	稀疏 Attention 支持 (仅限 MLA)
MM Prefix	多模态前缀全 Attention 支持
DCP	解码上下文并行 (Decode Context Parallelism) 支持 (--decode-context-parallel-size)
Attention Types	支持的 Attention 模式 (Decoder, Encoder, Enc-Dec)
Compute Cap. (计算能力)	所需的 CUDA 计算能力 (非 CUDA 后端为 N/A)

符号： ✅ = 支持，❌ = 不支持

标准 Attention (MHA, MQA, GQA) 后端

Backend	版本	Dtypes (数据类型)	KV Dtypes	Block Sizes (块大小)	Head Sizes (头大小)	Sink	MM Prefix	DCP	Attention Types	Compute Cap. (计算能力)
CPU_ATTN		fp16, bf16, fp32	auto	Any	32, 64, 80, 96, 112, 128, 160, 192, 224, 256, 512	❌	❌	❌	All	不适用
FLASHINFER	Native†	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2	16, 32, 64	64, 128, 256	❌	❌	✅	Decoder	7.x-9.x
FLASHINFER	TRTLLM†	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2	16, 32, 64	64, 128, 256	✅	❌	✅	Decoder	10.0
FLASH_ATTN	FA2*	fp16, bf16	auto, float16, bfloat16	%16	Any	❌	❌	✅	All	≥8.0
FLASH_ATTN	FA3*	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2	%16	Any	✅	❌	✅	All	9.x
FLASH_ATTN	FA4*	fp16, bf16	auto, float16, bfloat16	%16	Any	❌	❌	✅	All	≥10.0
FLASH_ATTN_DIFFKV		fp16, bf16	auto	Any	Any	❌	❌	✅	Decoder	Any
FLEX_ATTENTION		fp16, bf16, fp32	auto, float16, bfloat16	Any	Any	❌	✅	❌	Decoder, Encoder Only	Any
ROCM_AITER_FA		fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2	16, 32	64, 128, 256	❌	❌	❌	Decoder	不适用
ROCM_AITER_UNIFIED_ATTN		fp16, bf16	auto	%16	Any	✅	✅	❌	All	不适用
ROCM_ATTN		fp16, bf16, fp32	auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2	%16	32, 64, 80, 96, 128, 160, 192, 224, 256	❌	✅	❌	Decoder, Encoder, Encoder Only	不适用
TREE_ATTN		fp16, bf16	auto, float16, bfloat16	%16	32, 64, 96, 128, 160, 192, 224, 256	❌	❌	❌	Decoder	Any
TRITON_ATTN		fp16, bf16, fp32	auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2, int8_per_token_head, fp8_per_token_head	%16	Any	✅	✅	❌	All	Any

† FlashInfer 在 Blackwell (SM100) 上使用 TRTLLM attention，该后端支持 Sinks。可通过 --attention-config.use_trtllm_attention=0 禁用。

* 通过 --attention-config.flash_attn_version=2, 3 或 4 指定 FlashAttention 版本。默认值：SM100+ (Blackwell) 为 FA4，SM90 (Hopper) 为 FA3，其余情况为 FA2。

MLA (Multi-head Latent Attention) 后端

MLA 在预填充和解码阶段使用不同的后端。

预填充 (Prefill) 后端

预填充后端在运行时根据硬件和配置进行选择。

Backend	描述	Compute Cap. (计算能力)	启用	禁用	注意事项
TRT-LLM Ragged‡	TensorRT-LLM 锯齿状 (ragged) attention	10.x	SM100 默认	-ac.use_trtllm_ragged_deepseek_prefill=0	仅限 DeepSeek R1 维度
FlashInfer	FlashInfer CUTLASS 后端	10.x	-ac.disable_flashinfer_prefill=0	-ac.disable_flashinfer_prefill=1	仅限 DeepSeek R1 维度
cuDNN	基于 cuDNN 的 attention	10.x	-ac.use_cudnn_prefill=1	-ac.use_cudnn_prefill=0
FlashAttention	FlashAttention 变长 (FA2/FA3)	Any	默认回退	使用其他后端	SM90 为 FA3，其余情况为 FA2

‡ TRT-LLM Ragged 是 Blackwell (SM100) 的默认设置。在其他 GPU 上，默认使用 FlashAttention。

解码 (Decode) 后端

Backend	Dtypes (数据类型)	KV Dtypes	Block Sizes (块大小)	Head Sizes (头大小)	Sink	Sparse	MM Prefix	DCP	Attention Types	Compute Cap. (计算能力)
CUTLASS_MLA	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3	128	Any	❌	❌	❌	✅	Decoder	10.x
FLASHINFER_MLA	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3	32, 64	Any	❌	❌	❌	❌	Decoder	10.x
FLASHINFER_MLA_SPARSE	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3	32, 64	576	❌	✅	❌	❌	Decoder	10.x
FLASHMLA	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3	64	Any	❌	❌	❌	✅	Decoder	9.x-10.x
FLASHMLA_SPARSE	bf16	auto, bfloat16, fp8_ds_mla	64	576	❌	✅	❌	❌	Decoder	9.x-10.x
FLASH_ATTN_MLA	fp16, bf16	auto, float16, bfloat16	%16	Any	❌	❌	❌	✅	Decoder	9.x
ROCM_AITER_MLA	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2	1	Any	❌	❌	❌	❌	Decoder	不适用
ROCM_AITER_MLA_SPARSE	fp16, bf16	auto, float16, bfloat16	1	Any	❌	✅	❌	❌	Decoder	不适用
ROCM_AITER_TRITON_MLA	fp16, bf16	auto	Any	Any	❌	❌	❌	❌	Decoder	不适用
TRITON_MLA	fp16, bf16	auto, float16, bfloat16, fp8, fp8_e4m3	%16	Any	❌	❌	❌	✅	Decoder	Any
XPU_MLA_SPARSE	fp16, bf16	auto, float16, bfloat16	Any	576	❌	✅	❌	❌	Decoder	Any