[None][feat] Add vLLM KV Pool support for XQA mla kernel #8560
Conversation
Signed-off-by: Qidi Sang <200703406+qsang-nv@users.noreply.github.com>
|
/bot run --disable_fail_fast |
📝 WalkthroughWalkthroughChanges introduce support for a new KV cache layout (PAGED_KV_CACHE_LAYOUT == 1) with separate K/V cache pools, update KV cache indexing and tensor map creation logic, and add CUDA 13.0+ support for memory prefetching and clock rate queries across kernel implementations and test infrastructure. Changes
Sequence Diagram(s)sequenceDiagram
participant Caller as launchMLA Caller
participant Launcher as launchMLA
participant Loader as KVTilePartLoader
participant TensorMap as makeTensorMapForPagedKVCache
rect rgb(240, 248, 255)
Note over Launcher: PAGED_KV_CACHE_LAYOUT == 1 Path (VLLM)
Caller->>Launcher: kCacheVLLM, vCacheVLLM, kvCachePageList
Launcher->>Launcher: Construct KVCacheList from kCacheVLLM/vCacheVLLM
Launcher->>TensorMap: Create tensor maps with kCacheVLLM/vCacheVLLM
TensorMap-->>Launcher: K/V tensor maps
Launcher->>Loader: Initialize with layout 1 baseOffset<br/>(idxReq * maxNbPagesPerSeq)
Loader->>Loader: Load pages with layout 1 indexing
end
rect rgb(240, 255, 240)
Note over Launcher: Legacy Path (Layout 0 or Pool)
Caller->>Launcher: pool, kvCachePageList
Launcher->>Launcher: Construct KVCacheList from pool
Launcher->>TensorMap: Create tensor maps with pool
TensorMap-->>Launcher: K/V tensor maps
Launcher->>Loader: Initialize with layout 0 baseOffset<br/>(formula with beamWidth, 2)
Loader->>Loader: Load pages with layout 0 indexing
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes The changes span multiple files and introduce conditional logic for two distinct KV cache layouts plus CUDA version-specific paths, requiring verification of indexing formulas and page addressing across both layout branches. However, changes follow a consistent pattern of adding parallel conditional paths rather than heterogeneous modifications, and test file changes are localized to specific CUDA version blocks. Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
cpp/kernels/xqa/test/warmup.cu (1)
7-10: Warmup loop condition is inverted; the loop exits immediately.Busy‑wait should spin until
clock64()reachestic + cycles.Apply:
- while (tic + cycles < clock64()) + while (clock64() < tic + cycles) { }cpp/kernels/xqa/test/test.cpp (1)
569-587: Build break for layout 1 whenUSE_INPUT_KV==1: wrong page list shape and cache array used.This block indexes
pageList[i][0][kv][...]and writescacheHeads[...], but with layout 1 we havepageList[batch][page]and separatecacheKHeads/cacheVHeads. This will not compile whenUSE_INPUT_KV && USE_PAGED_KV_CACHE && PAGED_KV_CACHE_LAYOUT==1.Apply:
#if USE_INPUT_KV @@ - for (int kv = 0; kv < 2; kv++) - { - for (int j = 0; j < nbKHeads; j++) - { -#if USE_PAGED_KV_CACHE - uint32_t const pageIdx = pageList[i][0][kv][pos / tokensPerPage]; - uint32_t const idxHead = tokensPerPage * (nbKHeads * pageIdx + j) + pos % tokensPerPage; -#else - uint32_t const idxHead = maxSeqLen * (nbKHeads * i + j) + pos; -#endif - cacheHeads[idxHead].fill(CacheElem(128.F)); - } - } + for (int kv = 0; kv < 2; kv++) + { + for (int j = 0; j < nbKHeads; j++) + { +#if USE_PAGED_KV_CACHE +#if PAGED_KV_CACHE_LAYOUT == 1 + uint32_t const pageIdx = pageList[i][pos / tokensPerPage]; + uint32_t const idxHead = pageIdx * tokensPerPage * nbKHeads + + (pos % tokensPerPage) * nbKHeads + j; + auto& cacheRef = (kv == 0) ? cacheKHeads[idxHead] : cacheVHeads[idxHead]; + cacheRef.fill(CacheElem(128.F)); +#else + uint32_t const pageIdx = pageList[i][0][kv][pos / tokensPerPage]; + uint32_t const idxHead = tokensPerPage * (nbKHeads * pageIdx + j) + pos % tokensPerPage; + cacheHeads[idxHead].fill(CacheElem(128.F)); +#endif +#else + uint32_t const idxHead = maxSeqLen * (nbKHeads * i + j) + pos; + cacheHeads[idxHead].fill(CacheElem(128.F)); +#endif + } + }
🧹 Nitpick comments (1)
cpp/kernels/xqa/mla_sm120.cu (1)
1973-1980: Scratch layout depends on grid size; ensure caller‑providedscratchis large enough.
cgaXBufandpartialResultsare carved fromscratchusingnbCgas. Consider asserting/ documenting requiredscratchsize to avoid OOB on large grids.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
cpp/kernels/xqa/mha.h(1 hunks)cpp/kernels/xqa/mla_sm120.cu(6 hunks)cpp/kernels/xqa/test/test.cpp(6 hunks)cpp/kernels/xqa/test/warmup.cu(1 hunks)
🧰 Additional context used
📓 Path-based instructions (7)
**/*.{h,hpp,hh,hxx,cpp,cxx,cc,cu,cuh}
📄 CodeRabbit inference engine (CODING_GUIDELINES.md)
**/*.{h,hpp,hh,hxx,cpp,cxx,cc,cu,cuh}: Namespace closing braces must include a trailing comment with the namespace name (e.g., '} // namespace foo').
Prefer const or constexpr variables over #define for constants.
Declare variables that are not modified after initialization as const.
Avoid magic literals in code; except for 0, nullptr, true, false. Use named constants for comparisons and logic.
Use Allman brace style for formatting.
Place the semicolon of an empty for/while loop on a new line.
Bodies of switch/while/do-while/for must be compound statements (brace-delimited), and if/else must always be followed by brace-delimited statements.
Type names (e.g., classes) must be CamelCase starting with an uppercase letter (e.g., FooBar).
Local variables, methods, and namespaces use lowerCamelCase (e.g., localFooBar).
Non-magic-number global variables that are non-static and not in an anonymous namespace must be lowerCamelCase prefixed with 'g' (e.g., gDontUseGlobalFoos).
Non-magic-number globals that are static or in an anonymous namespace use lowerCamelCase prefixed with 's' (e.g., sMutableStaticGlobal).
Locally visible static variables use lowerCamelCase with 's' prefix (e.g., static std::once_flag sFlag).
Private/protected member variables use 'm' prefix with CamelCase (e.g., mNbFooValues). Public members may omit, but 'm' is encouraged for clarity.
Constants (enums, global constants, static constants, and function-scope magic/literal constants) use uppercase SNAKE_CASE with 'k' prefix (e.g., kDIGIT_NUM).
Function-scope constants that are not magic numbers or literals are named like non-constant variables (e.g., bool const pass = a && b).
If macros are necessary, name them in UPPER_SNAKE_CASE (e.g., FOO_VERSION) and prefer constants over #define.
Use LLVM clang-format; wrap lines at a maximum of 120 columns; use '// clang-format off/on' sparingly with justification.
Use smart pointers for heap allocations; prefer unique_ptr for sole ownership, shared_ptr for shared...
Files:
cpp/kernels/xqa/test/warmup.cucpp/kernels/xqa/test/test.cppcpp/kernels/xqa/mha.hcpp/kernels/xqa/mla_sm120.cu
**/*.{cpp,cxx,cc,cu,h,hpp,hh,hxx,cuh}
📄 CodeRabbit inference engine (CODING_GUIDELINES.md)
C++ filenames should be lowerCamelCase (first letter lowercase) and must be case-insensitive unique within a compilation target.
Files:
cpp/kernels/xqa/test/warmup.cucpp/kernels/xqa/test/test.cppcpp/kernels/xqa/mha.hcpp/kernels/xqa/mla_sm120.cu
**/*.{h,hpp,hh,hxx,cpp,cxx,cc,cu,cuh,py}
📄 CodeRabbit inference engine (CODING_GUIDELINES.md)
Use only spaces, no tabs; indent with 4 spaces.
Files:
cpp/kernels/xqa/test/warmup.cucpp/kernels/xqa/test/test.cppcpp/kernels/xqa/mha.hcpp/kernels/xqa/mla_sm120.cu
**/*.{cpp,cxx,cc,h,hpp,hh,hxx,cu,cuh,py}
📄 CodeRabbit inference engine (CODING_GUIDELINES.md)
Prepend the NVIDIA Apache-2.0 copyright header with current year to the top of all source files (e.g., .cpp, .h, .cu, .py).
Files:
cpp/kernels/xqa/test/warmup.cucpp/kernels/xqa/test/test.cppcpp/kernels/xqa/mha.hcpp/kernels/xqa/mla_sm120.cu
**/*.{h,hpp,hh,hxx,cpp,cxx,cc}
📄 CodeRabbit inference engine (CODING_GUIDELINES.md)
**/*.{h,hpp,hh,hxx,cpp,cxx,cc}: Prefer anonymous namespaces over 'static' for internal linkage of functions.
All templates (class/function/member/static) must be instantiated at least once; non-POD classes should have private data members.
Files:
cpp/kernels/xqa/test/test.cppcpp/kernels/xqa/mha.h
**/*.{h,hpp,hh,hxx}
📄 CodeRabbit inference engine (CODING_GUIDELINES.md)
Document new class interfaces and function prototypes with Doxygen; use //! for single-line and //!< for members.
Files:
cpp/kernels/xqa/mha.h
**/*.{h,hpp,hh,hxx,cuh}
📄 CodeRabbit inference engine (CODING_GUIDELINES.md)
Use include guards named 'TRTLLM_<FILE_NAME_IN_CAPS_WITH_UNDERSCORES>_H' (no leading or trailing underscore; directory names excluded).
Files:
cpp/kernels/xqa/mha.h
🧬 Code graph analysis (1)
cpp/kernels/xqa/mla_sm120.cu (1)
cpp/kernels/xqa/tma.h (2)
loadAsync(74-129)loadAsync(132-191)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Pre-commit Check
🔇 Additional comments (7)
cpp/kernels/xqa/test/test.cpp (3)
82-97: CUDA 13+ managed prefetch API usage looks correct.Using
cudaMemLocationwithcudaMemPrefetchAsync(ptr, size, location, flags=0, stream)is consistent with CUDA 13+. Fallback path retained for older CUDA.Please confirm our CI toolchains define CUDA_VERSION >= 13000 where this overload exists (e.g., R13+). If some builders use older CUDA headers, guard failures could occur.
235-241: KV page list shape and initialization for layout 1 (VLLM) look consistent.
- total pages, buffer sizing, and linear init/shuffle align with
[batchSize][nbPagesPerSeq]shape.pageListArgpointers match the expected kernel API per layout.Also applies to: 262-271, 309-336, 339-355
713-717: AlllaunchMLA/launchMHAcall sites are consistently updated; no additional action needed.Verification confirms both call sites (lines 713-717 for
launchMLAand lines 759-763 forlaunchMHA) correctly pass separate K/V cache heads (cacheKHeads.get(), cacheVHeads.get()) underPAGED_KV_CACHE_LAYOUT == 1, falling back to the single pool otherwise. Both match the function signature expectations inmha.hlines 174-176, where layout 1 expects two separate parameters (kCacheVLLM,vCacheVLLM). No inconsistencies found.cpp/kernels/xqa/mla_sm120.cu (3)
115-119: Correct base offset for layout 1 inKVTilePartLoader.For VLLM layout,
baseOffset = idxReq * maxNbPagesPerSeqmatches[batch][page]indexing. Good.
1936-1942: HostlaunchMLA: tensor map creation matches layout 1 vs pool paths.Separate K/V tensor maps for layout 1 are correctly used; pool fallback unchanged.
Also applies to: 1962-1971
146-151: No issues found—tensor map dimension orders are correctly matched to TMA loads.The verification confirms that both layout branches correctly map dimension indices to tensor coordinates:
- Layout 1:
{idxElemBeg, idxHeadGrp, offset, pages[i]}→ tensor dims{headElems, nbKHeads, tokensPerPage, pageId}✓- Layout 0:
{idxElemBeg, offset, idxHeadGrp, pages[i]}→ tensor dims{headElems, tokensPerPage, nbKHeads, pageId}✓Both single-page (lines 146–151) and multi-page (lines 160–167) cases are consistent with their respective tensor map encodings in
tensorMap.cpp.cpp/kernels/xqa/mha.h (1)
172-180: All function signatures match between declarations and definitions.Verified that
launchMLA,launchMHA, andlaunchHopperF8MHAhave consistent signatures across all files:
- launchMLA: mha.h:168 matches mla_sm120.cu:1874
- launchMHA: mha.h:88 matches mha.cu:2680
- launchHopperF8MHA: mha.h:128 matches mha_sm90.cu:3225
All three functions correctly use the same conditional structure for
PAGED_KV_CACHE_LAYOUT==1(takingkCacheVLLMandvCacheVLLMparameters) versus Layout 0 (takingpool). The public API extension is properly implemented.
|
PR_Github #22114 Bot args parsing error: usage: /bot [-h] |
|
/bot run --disable-fail-fast |
|
PR_Github #22115 [ run ] triggered by Bot. Commit: |
|
PR_Github #22115 [ run ] completed with state |
Signed-off-by: Qidi Sang <200703406+qsang-nv@users.noreply.github.com> Signed-off-by: yufeiwu-nv <230315618+yufeiwu-nv@users.noreply.github.com>
Signed-off-by: Qidi Sang <200703406+qsang-nv@users.noreply.github.com>
Signed-off-by: Qidi Sang <200703406+qsang-nv@users.noreply.github.com>
Signed-off-by: Qidi Sang <200703406+qsang-nv@users.noreply.github.com>
Signed-off-by: Qidi Sang <200703406+qsang-nv@users.noreply.github.com>
Summary by CodeRabbit
New Features
Refactor
Chores
Description
Add vllm kv layout for xqa mla kernel. Also add support in xqa unittest for cuda version >= 13.0.
Test Coverage
PR Checklist
Please review the following before submitting your PR:
PR description clearly explains what and why. If using CodeRabbit's summary, please make sure it makes sense.
PR Follows TRT-LLM CODING GUIDELINES to the best of your knowledge.
Test cases are provided for new code paths (see test instructions)
Any new dependencies have been scanned for license and vulnerabilities
CODEOWNERS updated if ownership changes
Documentation updated as needed
The reviewers assigned automatically/manually are appropriate for the PR.
Please check this after reviewing the above items as appropriate for this PR.
GitHub Bot Help
/bot [-h] ['run', 'kill', 'skip', 'reuse-pipeline'] ...Provide a user friendly way for developers to interact with a Jenkins server.
Run
/bot [-h|--help]to print this help message.See details below for each supported subcommand.
run [--reuse-test (optional)pipeline-id --disable-fail-fast --skip-test --stage-list "A10-PyTorch-1, xxx" --gpu-type "A30, H100_PCIe" --test-backend "pytorch, cpp" --add-multi-gpu-test --only-multi-gpu-test --disable-multi-gpu-test --post-merge --extra-stage "H100_PCIe-TensorRT-Post-Merge-1, xxx" --detailed-log --debug(experimental)]Launch build/test pipelines. All previously running jobs will be killed.
--reuse-test (optional)pipeline-id(OPTIONAL) : Allow the new pipeline to reuse build artifacts and skip successful test stages from a specified pipeline or the last pipeline if no pipeline-id is indicated. If the Git commit ID has changed, this option will be always ignored. The DEFAULT behavior of the bot is to reuse build artifacts and successful test results from the last pipeline.--disable-reuse-test(OPTIONAL) : Explicitly prevent the pipeline from reusing build artifacts and skipping successful test stages from a previous pipeline. Ensure that all builds and tests are run regardless of previous successes.--disable-fail-fast(OPTIONAL) : Disable fail fast on build/tests/infra failures.--skip-test(OPTIONAL) : Skip all test stages, but still run build stages, package stages and sanity check stages. Note: Does NOT update GitHub check status.--stage-list "A10-PyTorch-1, xxx"(OPTIONAL) : Only run the specified test stages. Examples: "A10-PyTorch-1, xxx". Note: Does NOT update GitHub check status.--gpu-type "A30, H100_PCIe"(OPTIONAL) : Only run the test stages on the specified GPU types. Examples: "A30, H100_PCIe". Note: Does NOT update GitHub check status.--test-backend "pytorch, cpp"(OPTIONAL) : Skip test stages which don't match the specified backends. Only support [pytorch, cpp, tensorrt, triton]. Examples: "pytorch, cpp" (does not run test stages with tensorrt or triton backend). Note: Does NOT update GitHub pipeline status.--only-multi-gpu-test(OPTIONAL) : Only run the multi-GPU tests. Note: Does NOT update GitHub check status.--disable-multi-gpu-test(OPTIONAL) : Disable the multi-GPU tests. Note: Does NOT update GitHub check status.--add-multi-gpu-test(OPTIONAL) : Force run the multi-GPU tests in addition to running L0 pre-merge pipeline.--post-merge(OPTIONAL) : Run the L0 post-merge pipeline instead of the ordinary L0 pre-merge pipeline.--extra-stage "H100_PCIe-TensorRT-Post-Merge-1, xxx"(OPTIONAL) : Run the ordinary L0 pre-merge pipeline and specified test stages. Examples: --extra-stage "H100_PCIe-TensorRT-Post-Merge-1, xxx".--detailed-log(OPTIONAL) : Enable flushing out all logs to the Jenkins console. This will significantly increase the log volume and may slow down the job.--debug(OPTIONAL) : Experimental feature. Enable access to the CI container for debugging purpose. Note: Specify exactly one stage in thestage-listparameter to access the appropriate container environment. Note: Does NOT update GitHub check status.For guidance on mapping tests to stage names, see
docs/source/reference/ci-overview.mdand the
scripts/test_to_stage_mapping.pyhelper.kill
killKill all running builds associated with pull request.
skip
skip --comment COMMENTSkip testing for latest commit on pull request.
--comment "Reason for skipping build/test"is required. IMPORTANT NOTE: This is dangerous since lack of user care and validation can cause top of tree to break.reuse-pipeline
reuse-pipelineReuse a previous pipeline to validate current commit. This action will also kill all currently running builds associated with the pull request. IMPORTANT NOTE: This is dangerous since lack of user care and validation can cause top of tree to break.