Skip to content

Conversation

xiezhq-hermann
Copy link
Collaborator

@xiezhq-hermann xiezhq-hermann commented Jun 18, 2025

Motivation

The primary limitation of the current HiCache implementation (introduced in PR #2693) lies in inefficient I/O between the CPU and GPU. This inefficiency stems from the fragmentation of KV caches in memory, which results in a large number of small I/O operations and consequently poor bandwidth utilization. The issue becomes particularly pronounced when using small page sizes. Similar performance degradation has been reported in multiple issues, including #7059 and #5372, among others.

Modifications

  • Introduced GPU-assisted KV cache transfer between CPU and GPU for small page sizes, implemented via custom CUDA kernels. This approach is extensible to different memory layouts. For large page sizes, a copy_-based implementation (looped in C++) is used.
  • Made minor modifications to the memory layout. @merrymercy @ByronHsu — please review these changes since they relate to recent changes you made.
  • Removed deprecated I/O logic to simplify the codebase.
  • Known limitation: This update is not compatible with FA3. Please use --attention-backend flashinfer for small page sizes (<64).
  • Will add a test into sgl-kernel.

Checklist

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary of Changes

Hello @xiezhq-hermann, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical performance bottleneck in the HiCache implementation by introducing highly efficient GPU-assisted KV cache I/O. My changes involve integrating custom CUDA kernels for data transfer, refactoring the underlying memory layout for better contiguity, and simplifying the overall I/O management by removing outdated mechanisms. The goal is to significantly improve bandwidth utilization, especially for workloads with small KV cache page sizes.

Highlights

  • Optimized KV Cache I/O: I've introduced GPU-assisted KV cache transfer using custom CUDA kernels. This new approach is specifically designed for small page sizes (less than 64), which previously suffered from inefficient I/O due to memory fragmentation. For larger page sizes, a copy_-based direct implementation is used as a fallback.
  • Memory Layout Refactoring: I've made significant modifications to the KV cache buffer memory layout. Instead of lists of individual tensors per layer, the K and V buffers (and combined KV buffer for MLA) are now stored as single contiguous tensors with an added layer dimension. This change facilitates more efficient data access and transfer by the new CUDA kernels.
  • Streamlined I/O Logic: I've removed deprecated and less efficient I/O buffering and direct transfer functions from the cache_controller.py and memory_pool_host.py modules. This simplification reduces code complexity and focuses the I/O architecture on the new, optimized transfer mechanisms.
  • New CUDA Kernels and Python Bindings: I've added new CUDA kernels in sgl-kernel/csrc/kvcacheio/transfer.cu that perform the core KV cache data transfers. These kernels are exposed to Python via new PyTorch custom operators, with high-level Python wrappers provided in sgl-kernel/python/sgl_kernel/kvcacheio.py to abstract the backend choice.
  • Dynamic I/O Backend Selection: The cache_controller.py now includes logic to dynamically select the appropriate I/O backend ('kernel' or 'direct') based on the configured page_size, ensuring the most efficient transfer method is used for different scenarios.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in issue comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces custom CUDA kernels for more efficient KV cache I/O, particularly for small page sizes, and refactors the memory layout of K/V buffers to be contiguous per layer. The changes simplify the existing I/O logic in the CacheController and MemoryPool classes. Key areas for review include the pass implementation for I/O methods in DoubleSparseTokenToKVPool and the magic number used for I/O backend selection.

@zhyncs
Copy link
Member

zhyncs commented Jun 18, 2025

Hi @xiezhq-hermann I think it's better to split this PR into two: one for the sgl-kernel and another for Python integration. Thank you.

@xiezhq-hermann xiezhq-hermann requested a review from ByronHsu as a code owner July 1, 2025 05:00
@xiezhq-hermann xiezhq-hermann force-pushed the xiezhq-hicache-upstream branch from 96e733c to fd74ed0 Compare July 4, 2025 23:22
@zhyncs zhyncs merged commit 2fc824b into main Jul 7, 2025
96 of 106 checks passed
@zhyncs zhyncs deleted the xiezhq-hicache-upstream branch July 7, 2025 05:53
chenxijun1029 pushed a commit to chenxijun1029/sglang that referenced this pull request Jul 17, 2025
shuaills pushed a commit to shuaills/sglang that referenced this pull request Jul 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants