Attention 백엔드 기능 지원

Attention 백엔드 기능 지원 (Attention Backend Feature Support)

이 페이지의 우선순위 및 기능 표는 attention 백엔드 레지스트리에서 docs/mkdocs/gen_files/generate_attention_backends.py가 AttentionBackend.validate_configuration()의 검사를 바탕으로 자동 생성한 것입니다.

출처: 문서

본문

Attention 백엔드 설정 (Setting the Attention Backend)

명령줄 (Command Line)

명령줄에서 백엔드를 지정하는 방법은 두 가지입니다.

방법 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",
)

백엔드 선택 동작 (Backend Selection Behavior)

Triton/FlashAttention 복합 (Triton/FlashAttention Composite)

Hopper에서 TRITON_FLASH_ATTN은 호환되는 멀티모달 프리픽스 구성에서 선호됩니다. 현재 쿼리에 양방향 이미지 attention이 필요하면 Triton을 사용하고, 인과(causal) 텍스트 prefill과 decode에는 FlashAttention을 사용하며 KV 캐시를 공유합니다. 인과 자식은 FA4로 해석(resolve)되어야 합니다. 이는 head size 512 같은 FA4 전용 형태와 Gemma 4를 포함해 모든 레이어를 FA4로 승격시키는 버전 정책을 가진 모델에서 자동으로 일어납니다. 버전 정책이 FA3를 선택하는 독립형 head-size-256 구성은 전체 레이어에 대해 Triton으로 폴백합니다.

지원되는 멀티모달 모델에는 attention 오버라이드가 필요 없습니다:

vllm serve google/gemma-4-31B-it

Triton/FlashInfer 복합 (Triton/FlashInfer Composite)

Blackwell에서 TRITON_FLASHINFER는 BF16 또는 FP8 KV 캐시를 사용하는 Gemma 4를 포함한 호환 멀티모달 프리픽스 구성에서 선호됩니다. 배치의 현재 쿼리에 양방향 이미지 attention이 필요하면 Triton을 사용하고, 인과 텍스트 prefill과 decode에는 FlashInfer를 사용합니다. 과거(historical) 이미지 토큰만으로는 Triton을 선택하지 않습니다.

이것은 vllm/v1/attention/backends/composite.py의 create_composite_attention_backend를 Triton, FlashInfer, MMPrefixAttentionRouting으로 인스턴스화합니다. 재사용 가능한 팩토리는 자식 구현, 메타데이터 디스패치, 호환 캐시 요구 사항, 워크스페이스 공유를 소유합니다. 라우팅 정책은 자식을 선택하고 graph 캡처 안전성을 정의합니다. 다른 조합도 같은 메커니즘을 재사용할 수 있습니다.

이 백엔드는 head 차원 256/512, FP16/BF16 및 FP8 KV 캐시, head-major 캐시 레이아웃을 가진 64-token 커널 페이지를 지원합니다. TRTLLM은 두 head 차원 모두에서 인과 attention을 처리하며, hdim512 커널은 128-token 페이지를 지원하지 않습니다. Gemma 4의 경우 전체 CUDA graph는 단일 토큰 배치를 다루고, 다중 토큰 배치는 non-full-graph 실행 경로를 사용합니다. 이미지 마스크가 슬라이딩 윈도우를 넘는 모델은 이 복합 방식으로 전체 attention graph를 사용할 수 없습니다. 컨텍스트 병렬, R-SWA, attention sink, 적응형 검증은 이 복합 방식에서 지원되지 않습니다.

명시적으로 선택할 수도 있습니다:

vllm serve google/gemma-4-31B-it \
    --attention-backend TRITON_FLASHINFER

수동 선택 (Manual Selection)

--attention-backend 또는 AttentionConfig로 백엔드를 명시적으로 설정하면:

  • 백엔드가 구성(모델 dtype, head size, compute capability 등)에 대해 검증됩니다.
  • 백엔드가 구성과 호환되지 않으면 구체적인 이유와 함께 오류가 발생합니다.
  • 유효하면 백엔드가 사용됩니다.

호환되지 않는 백엔드를 선택할 때의 오류 예:

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

자동 선택 (Automatic Selection)

백엔드를 지정하지 않으면(기본값):

  • vLLM은 우선순위 순서로 백엔드를 순회합니다(아래 표 참고).
  • 각 백엔드를 구성에 대해 검증합니다.
  • 호환되는 첫 번째 백엔드를 선택합니다.
  • 호환되는 백엔드가 없으면 모든 백엔드와 비호환 이유를 나열하며 오류가 발생합니다.

백엔드 우선순위 (CUDA) (Backend Priority)

명시적으로 선택하지 않으면 vLLM은 이 우선순위 순서 목록에서 호환되는 첫 번째 백엔드를 선택합니다. 우선순위 1 = 가장 높음(먼저 시도).

표준 Attention (MHA, MQA, GQA)

Blackwell (SM 10.x):

우선순위 백엔드
1 FLASHINFER
2 FLASH_ATTN
3 TRITON_ATTN
4 FLEX_ATTENTION
5 TURBOQUANT

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

우선순위 백엔드
1 FLASH_ATTN
2 FLASHINFER
3 TRITON_ATTN
4 FLEX_ATTENTION
5 TURBOQUANT

MLA Attention (DeepSeek 스타일)

Blackwell (SM 10.x):

우선순위 백엔드
1 FLASHINFER_MLA
2 TOKENSPEED_MLA
3 CUTLASS_MLA
4 FLASH_ATTN_MLA
5 FLASHMLA
6 TRITON_MLA
7 FLASHINFER_MLA_SPARSE *
8 FLASHMLA_SPARSE
  • 희소 MLA의 경우 FP8 KV 캐시는 항상 FLASHINFER_MLA_SPARSE를 선호합니다. BF16 KV 캐시에서는 낮은 query-head 수(<= 16)에 FLASHINFER_MLA_SPARSE를, 그 외에는 FLASHMLA_SPARSE를 선호합니다.

참고: ROCm과 CPU 플랫폼은 자체 선택 로직이 있습니다. 플랫폼별 문서를 참고하세요.

범례 (Legend)

열 설명
Dtypes 지원되는 모델 데이터 타입 (fp16, bf16, fp32)
KV Dtypes 지원되는 KV 캐시 데이터 타입 (auto, fp8, fp8_e4m3 등)
Block Sizes 지원되는 KV 캐시 블록 크기 (%N = N의 배수)
Head Sizes 지원되는 attention head 크기
Sink Attention sink 지원 (StreamingLLM용)
Non-Causal 디코더 모델의 비인과(양방향) attention 지원
Sparse 희소 attention 지원 (MLA 전용)
MM Prefix 멀티모달 프리픽스 전체 attention 지원
DCP Decode Context Parallelism 지원 (--decode-context-parallel-size)
Attention Types 지원되는 attention 패턴 (Decoder, Encoder, Enc-Dec)
Compute Cap. 요구되는 CUDA compute capability (비-CUDA 백엔드의 경우 N/A)

기호: ✅ = 지원, ❌ = 미지원

표준 Attention (MHA, MQA, GQA) 백엔드

백엔드 버전 Dtypes KV Dtypes Block Sizes Head Sizes Sink Non-Causal MM Prefix DCP Attention Types Compute Cap.
B12X bf16 auto Any 64, 128, 192, 256 ✅ ❌ ❌ ❌ Decoder Any
CPU_ATTN fp16, bf16, fp32 auto, fp8, fp8_e4m3, fp8_e5m2 %32 32, 64, 80, 96, 112, 128, 160, 192, 224, 256, 512 ❌ ✅ ❌ ❌ All N/A
CUTLASS_MSA fp16, bf16 auto Any Any ❌ ❌ ❌ ❌ Decoder Any
FLASHINFER Native† fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2, nvfp4_4over6 16, 32, 64, 128, 256, 512, 1024 64, 128, 256, 512 ❌ ✅ ❌ ✅ Decoder 8.x-9.x
FLASHINFER XQA† fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2, nvfp4_4over6 16, 32, 64, 128, 256, 512, 1024 64, 128, 256, 512 ❌ ❌ ❌ ✅ Decoder 9.0
FLASHINFER trtllm-gen† fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2, nvfp4, nvfp4_4over6 16, 32, 64, 128, 256, 512, 1024 64, 128, 256, 512 ✅ ✅ ❌ ✅ Decoder 10.x
FLASHMLA_MEGA_ATTN_DSV41 fp16, bf16 auto, fp8_ds_mla, fp8, nvfp4_ds_mla 128 Any ❌ ❌ ❌ ❌ Decoder 10.x
FLASHMLA_SPARSE_DSV41 fp16, bf16 auto Any Any ❌ ❌ ❌ ❌ Decoder Any
FLASH_ATTN FA2* fp16, bf16 auto, float16, bfloat16 %16 Any ❌ ✅ ❌ ✅ All ≥8.0
FLASH_ATTN FA3* fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3 %16 Any ✅ ✅ ❌ ✅ All 9.x
FLASH_ATTN FA4* fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3 %16 Any ✅ ✅ ❌ ✅ All ≥10.0
FLASH_ATTN_DIFFKV fp16, bf16 auto Any Any ❌ ❌ ❌ ✅ Decoder Any
FLEX_ATTENTION fp16, bf16, fp32 auto, float16, bfloat16 %16 Any ❌ ✅ ✅ ❌ Decoder, Encoder Only Any
HPC_ATTN fp16, bf16 auto, bfloat16, fp8_e4m3 64 128 ❌ ❌ ❌ ❌ Decoder Any
ROCM_AITER_FA fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2 16, 32 64, 128, 256 ✅ ✅ ❌ ❌ Decoder N/A
ROCM_AITER_UNIFIED_ATTN fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2 %16 Any ✅ ❌ ✅ ❌ All N/A
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 N/A
TRITON_ATTN fp16, bf16, fp32 auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2, int4_per_token_head, int8_per_token_head, fp8_per_token_head %16 Any ✅ ✅ ✅ ❌ All Any
TRITON_ATTN_DIFFKV fp16, bf16 auto, bfloat16 Any Any ❌ ❌ ❌ ❌ Decoder Any
TRITON_MSA fp16, bf16 auto Any Any ❌ ❌ ❌ ❌ Decoder Any
TURBOQUANT fp16, bf16 turboquant_k8v4, turboquant_4bit_nc, turboquant_k3v4_nc, turboquant_3bit_nc 16, 32, 64, 128 Any ❌ ❌ ❌ ❌ Decoder Any

† FlashInfer Native는 일반 FlashInfer 경로입니다. XQA는 FlashInfer의 TRTLLM decode API로 노출되는 SM90 decode 경로입니다. trtllm-gen은 SM100에서 사용되며 sink를 지원합니다. --attention-config.use_trtllm_attention=0으로 XQA/trtllm-gen을 비활성화하세요.

  • FlashAttention 버전은 --attention-config.flash_attn_version=2, 3, 4로 지정합니다. 기본값은 SM100+(Blackwell)에서 FA4, SM90(Hopper)에서 FA3, 그 외 FA2입니다.

Blackwell에서 FlashAttention 백엔드가 선택되면 head_size=256은 KV 캐시 블록 크기 128을 요구하는 전용 FA4 커널이 서빙합니다(--block-size가 고정되지 않았다면 자동으로 선택됨). 그리고 logit soft capping, attention sink, mm_prefix/R-SWA 마스킹, DCP, windowed encoder attention을 지원하지 않습니다. 그런 구성은 투명하게 FA2로 폴백됩니다. 128의 배수가 아닌 고정된 --block-size는 대신 그런 모델에서 FlashAttention을 부적격하게 만들며, 백엔드를 명시적으로 요청했다면 오류가 납니다.

b12x

선택적 b12x 백엔드는 NVIDIA SM120·SM121 GPU에서 인과 디코더 attention을 지원합니다. 다음과 같이 설치·선택합니다:

uv pip install "vllm[b12x]"
vllm serve <model> --attention-backend b12x

MiniMax M3 Sparse Attention 백엔드

MiniMax M3 sparse("lightning indexer") 레이어가 사용하는 block-sparse GQA 백엔드. 모델이 직접 연결하며 위 자동 우선순위 목록에는 포함되지 않습니다. lightning indexer가 KV 블록을 스코어링하고, top-k 블록(고정 init/local 블록 포함)을 선택하며, attention은 그 블록에만 주목합니다. 인덱스 키는 별도의 사이드 캐시에 있습니다.

백엔드 Dtypes KV Dtypes Block Sizes Head Sizes Sink Non-Causal MM Prefix DCP Attention Types Compute Cap.
MINIMAX_M3_SPARSE bf16, fp16 bfloat16, fp8, fp8_e4m3, fp8_e5m2 128 128 ❌ ❌ ❌ ❌ Decoder Any

MLA (Multi-head Latent Attention) 백엔드

MLA는 prefill과 decode 단계에 별도 백엔드를 사용합니다.

Prefill 백엔드

prefill 백엔드를 명시적으로 선택하려면 -ac.mla_prefill_backend=<BACKEND>(예: FLASH_ATTN, FLASHINFER)를 사용합니다. 그렇지 않으면 런타임에 하드웨어·구성에 따라 prefill 백엔드가 자동 선택됩니다.

백엔드 설명 Dtypes Compute Cap. 참고
FLASH_ATTN ‡ FlashAttention varlen (FA2/FA3/FA4) fp16, bf16 Any (qk_nope_head_dim=128, qk_rope_head_dim=64, v_head_dim=128) 또는 (qk_nope_head_dim=192, qk_rope_head_dim=64, v_head_dim=256) 또는 (qk_nope_head_dim=64, qk_rope_head_dim=64, v_head_dim=128) 또는 (qk_nope_head_dim=256, qk_rope_head_dim=0, v_head_dim=256) 만
TRTLLM_RAGGED TensorRT-LLM ragged attention fp16, bf16 10.x (qk_nope_head_dim=128, qk_rope_head_dim=64, v_head_dim=128) 또는 (qk_nope_head_dim=192, qk_rope_head_dim=64, v_head_dim=256) 만
FLASHINFER FlashInfer CUTLASS backend fp16, bf16 10.x (qk_nope_head_dim=128, qk_rope_head_dim=64, v_head_dim=128) 만
TOKENSPEED_MLA fp16, bf16 10.x (qk_nope_head_dim=128, qk_rope_head_dim=64, v_head_dim=128) 만

‡ 자동 선택은 FlashAttention을 먼저 시도합니다. Blackwell(SM100)에서 폴백 순서는 TRT-LLM Ragged, FlashInfer, TokenSpeed MLA입니다. (qk_nope_head_dim=192, qk_rope_head_dim=64, v_head_dim=256)의 경우 TRT-LLM Ragged가 FlashAttention보다 먼저 시도됩니다. 다른 GPU에서는 FlashAttention만 고려됩니다.

Decode 백엔드

MLA decode 백엔드는 표준 -ac.backend=<BACKEND> 인자(예: FLASHMLA, TRITON_MLA)로 선택합니다.

백엔드 Dtypes KV Dtypes Block Sizes Head Sizes Sink Non-Causal Sparse MM Prefix DCP Attention Types Compute Cap.
AMX_MLA bf16 auto %32 576 ❌ ❌ ❌ ❌ ❌ Decoder Any
CPU_MLA fp16, bf16, fp32 auto 16 576 ❌ ❌ ❌ ❌ ❌ Decoder N/A
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 Any ❌ ❌ ❌ ❌ ✅ Decoder 10.x
FLASHINFER_MLA_SPARSE_DSV41 bf16 auto, bfloat16, fp8, fp8_e4m3, fp8_ds_mla 128 512 ✅ ❌ ✅ ❌ ❌ Decoder 10.x, 12.x
FLASHINFER_MLA_SPARSE_SM120 bf16 auto, fp8, fp8_e4m3, fp8_ds_mla 64, 256 Any ❌ ❌ ❌ ❌ ❌ Decoder 12.x
FLASHINFER_MLA_SPARSE_SM90 bf16 auto, bfloat16, fp8, fp8_e4m3 %64 512, 576 ❌ ❌ ✅ ❌ ❌ Decoder 9.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, nvfp4_ds_mla 64 576, 512 ❌ ❌ ✅ ❌ ✅ Decoder 9.x-10.x
FLASH_ATTN_MLA fp16, bf16 auto, float16, bfloat16 %16 Any ❌ ❌ ❌ ❌ ✅ Decoder 9.x
FLASH_ATTN_MLA_SPARSE fp16, bf16 auto, float16, bfloat16 64 Any ❌ ❌ ✅ ❌ ❌ Decoder 9.x
ROCM_AITER_MLA fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3, fp8_e5m2 %1 Any ❌ ❌ ❌ ❌ ✅ Decoder N/A
ROCM_AITER_MLA_SPARSE fp16, bf16 auto, float16, bfloat16, fp8, fp8_e4m3 1, %16 Any ❌ ❌ ✅ ❌ ❌ Decoder N/A
ROCM_AITER_TRITON_MLA fp16, bf16 auto Any Any ❌ ❌ ❌ ❌ ✅ Decoder N/A
TOKENSPEED_MLA fp16, bf16 fp8, fp8_e4m3 32, 64 Any ❌ ✅ ❌ ❌ ✅ Decoder 10.x
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

DeepSeek V4 Decode 백엔드

DeepSeek V4 sparse MLA는 자체 decode 백엔드를 사용하며, --attention-backend=<BACKEND>(예: FLASHMLA_SPARSE_DSV4, FLASHINFER_MLA_SPARSE_DSV4)로 선택합니다. V4 sparse-index 파이프라인(compressor + SWA + indexer, 256-token 블록, head 512)을 공유합니다. NVIDIA 기본값은 SM12x에서 FLASHINFER_MLA_SPARSE_DSV4이고, 그 외 지원 CUDA 아키텍처에서는 FLASHMLA_SPARSE_DSV4입니다.

백엔드 Dtypes KV Dtypes Block Sizes Head Sizes Sink Non-Causal Sparse MM Prefix DCP Attention Types Compute Cap.
FLASHINFER_MLA_SPARSE_DSV4 bf16 auto, bfloat16, fp8, fp8_e4m3, fp8_ds_mla 256 512 ✅ ❌ ✅ ❌ ❌ Decoder 10.x, 12.x
FLASHMLA_SPARSE_DSV4 fp16, bf16 auto Any Any ❌ ❌ ❌ ❌ ❌ Decoder Any
ROCM_FLASHMLA_SPARSE_DSV4 fp16, bf16 auto Any Any ❌ ❌ ❌ ❌ ❌ Decoder N/A

더 알아보기 (Learn more)