Add KV cache for paged/non-paged attention

[cyanguwa]

Description

This PR adds KV cache support for FusedAttention, FlashAttention, and UnfusedDotProductAttention backends in TE-PyTorch.

backend | precision | KV cache | architecture | qkv_format | page_size
---------------------------------------------------------------------------------------
Fused | FP16/BF16 | non-paged/paged | sm80+ | bshd,sbhd,thd | >= 1
Flash v2 | FP16/BF16 | non-paged/paged | sm80+ | bshd,sbhd,thd | >= 256
Flash v3 | FP16/BF16 | non-paged/paged | sm90 | bshd,sbhd,thd | >= 1
| FP8 | non-paged/paged | sm90 | thd | >= 1
Unfused | FP32/FP16/BF16 | non-paged/paged | all | bshd,sbhd,thd | >= 1

• KV cache is in bshd format, and incoming tokens can be in bshd, sbhd, or thd
• FusedAttention processes QKV in bshd, sbhd_2bshd, or thd_2bshd format directly
• FlashAttention v2 converts Q to thd and uses flash_attn_varlen_func for attention
• FlashAttention v3 (must be 39e7197 or after) converts Q to thd and uses flash_attn_with_kvcache for attention
• UnfusedDotProductAttention converts Q to bshd for attention; for paged, it converts the cache tensors to non-paged first, based on the page table
• All backends support pure context, pure generation, and mixed context/generation phases
• FusedAttention and FlashAttention support CUDA graph, UnfusedDotProductAttention doesn't
• K cache and V cache are expected to have the same page table
• For FP8, only fp8_dpa=True is supported (and the KV cache is still in FP16/BF16), fp8_mha=True is not supported as of yet
• Context parallelism is not supported
• RoPE will be fixed for inference in RoPE enhancements #1478
• This PR requires FE1.11 from Update FE to 1.11 #1580
• Please be aware of the fixes in [PyTorch] Minor fixes for TE 2.2 #1589

Type of change

• Documentation change (change only to the documentation, either a fix or a new content)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Infra/Build change
• Code refractor

Changes

Please list the changes introduced in this PR:

• Add KV caching support for FusedAttention, FlashAttention, and UnfusedDotProductAttention
• Add mixed q/kv format support to FusedAttention for F16
• Adapt to the new FA3 APIs from FA2.7.3+/hopper for CP and non-CP cases

Checklist:

• I have read and followed the contributing guidelines
• The functionality is complete
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[cyanguwa]

/te-ci pytorch L0

[cyanguwa]

/te-ci pytorch L0

[cyanguwa]

/te-ci pytorch L0 L1 L3

[sudhakarsingh27]

Summing up, most of my feedback turns out to be either asking for more comments or some renaming. I understand that we want to get this PR in this release so maybe you could go over the feedback once and we can discuss how much of it's reasonable to incorporate.

[ptrendx]

Is all the right function here or should it be any (or maybe we should return an error if there are some that training and some that are not)?

[cyanguwa]

I added an assert for the mixed training/inference case, because we haven't tested it. We can remove the assert if it's proven that the mixed case is fine with make_graphed_callables.

[cyanguwa]

Pipelines:

• Jax: 25433649 (all pass)
• PyTorch: 25585637 (in progress; regular CI is expected to have 14-15 test_paged_attn failures due to regression in cuDNN 9.8, e.g. 25446096; running with cuDNN 9.7 now)
  • previous pipeline 25531054 with 9.7 all passed, with expected failures in L0-cppunittest--B200_1GPU (time-out), L1_pytorch_distributed_unittest--H100_4GPU (unrelated to this PR), L1_pytorch_distributed_unittest--B200_8GPU (unrelated to this PR), L3_pytorch_FA_versions_tests--H100_1GPU (FA3 installation issue, is fixed in cb2d56e).

[sudhakarsingh27]

Lgtm.

But I'll note that I'm not fully convinced with the naming convention especially in inference.py and would like it to be revisited in the upcoming refactor. @KshitijLakhani fyi

[cyanguwa]

Pipeline 25585637: apart from the expected failures (unrelated to this PR), CI looks good. The L3_pytorch_FA_versions_tests--H100_1GPU didn't finish compiling for the last FA version, but local tests (both CP and non-CP) show that it's fine.