SGLang HiCache 最佳实践

SGLang HiCache 最佳实践#

为什么 HiCache 至关重要#

SGLang HiCache 通过三级分层 KV 缓存系统扩展了传统的 RadixAttention，显著提升了长文本和多轮对话场景下的性能。通过智能管理 GPU 显存、主机内存和外部存储后端之间的 KV 缓存，HiCache 解决了限制传统系统缓存命中率的根本容量瓶颈问题。

配置指南#

HiCache 核心参数#

# Essential HiCache flags
--page-size 64                        # Page size for cache management
--enable-hierarchical-cache           # Enable HiCache
--hicache-ratio 2                     # Host memory ratio (2x GPU memory)
--hicache-size 100                    # Host memory size in GBs, will override the above ratio
--hicache-io-backend kernel           # The I/O backend of moving data between CPU and GPU
--hicache-write-policy write_through  # Cache write policy from GPU to CPU
--hicache-storage-backend             # Optional storage backend (e.g., hf3fs, mooncake, etc.)

启用存储后端时的关键配置#

内存布局优化#

# Page-first: Optimized for I/O efficiency with zero-copy (recommended with kernel backend)
--hicache-mem-layout page_first
# Page-first-direct: Optimized for direct I/O operations (Compatible with fa3 and same zero-copy performance as page_first)
--hicache-mem-layout page_first_direct
# Layer-first
--hicache-mem-layout layer_first

布局兼容性

  • page_first：仅与 kernel I/O 后端兼容，在使用 direct 后端时会自动切换为 layer_first

  • page_first_direct：专为 direct I/O 后端设计，具有优化的内存组织方式

预取策略#

# Best-effort: Terminate prefetch when needed
--hicache-storage-prefetch-policy best_effort
# Wait-complete: Ensure complete prefetch, higher cache reuse
--hicache-storage-prefetch-policy wait_complete
# Timeout: Balance between completion and best-effort
--hicache-storage-prefetch-policy timeout

与 PD 分离架构集成#

HiCache 可以与 PD 分离架构（Prefill-Decode Disaggregation）无缝协作。您可以从以下两种配置中选择：

  1. 仅 Prefill 开启 HiCache：仅在 Prefill 节点上启用 HiCache，允许在多个 Prefill 实例之间共享 KV 缓存

  2. 全量 HiCache 配合异步卸载：在 Prefill 节点上启用 HiCache，并在 Decode 节点上开启异步 KV 缓存卸载（offloading），从而允许 Prefill 节点在多轮对话场景中重用来自 Decode 节点的 KV 缓存

# Prefill node with HiCache enabled for cross-prefill sharing (ideal for SystemPrompt scenarios)
python3 -m sglang.launch_server \
  --model-path /xxx/DeepSeek-R1/ \
  --tp 8 \
  --host 0.0.0.0 \
  --port 10000 \
  --enable-metrics \
  --enable-cache-report \
  --mem-fraction-static 0.85 \
  --page-size 64 \
  --enable-hierarchical-cache \
  --hicache-ratio 2 \
  --hicache-size 0 \
  --hicache-mem-layout page_first_direct \
  --hicache-io-backend direct \
  --hicache-write-policy write_through \
  --hicache-storage-backend hf3fs \
  --hicache-storage-prefetch-policy wait_complete \
  --disaggregation-ib-device mlx5_0 \
  --disaggregation-mode prefill \
  --disaggregation-transfer-backend mooncake

# Decode node with async offloading enabled for KV cache reuse by Prefill (ideal for multi-turn conversations)
python3 -m sglang.launch_server \
  --model-path /xxx/DeepSeek-R1/ \
  --tp 8 \
  --host 0.0.0.0 \
  --port 10000 \
  --enable-metrics \
  --enable-cache-report \
  --page-size 64 \
  --hicache-ratio 2 \
  --hicache-size 0 \
  --hicache-mem-layout page_first_direct \
  --hicache-io-backend direct \
  --hicache-write-policy write_through \
  --hicache-storage-backend hf3fs \
  --hicache-storage-prefetch-policy wait_complete \
  --disaggregation-decode-enable-offload-kvcache \  # Enable async KV cache offloading in decode node
  --disaggregation-ib-device mlx5_0 \
  --disaggregation-mode decode \
  --disaggregation-transfer-backend mooncake

结合 HF3FS 部署#

以下是使用 HiCache-HF3FS 部署 DeepSeek-R1 的示例。更多详情请参阅 HF3FS 文档。

python3 -m sglang.launch_server \
  --model-path /xxx/DeepSeek-R1/ \
  --log-level info \
  --tp 8 \
  --host 0.0.0.0 \
  --port 10000 \
  --enable-metrics \
  --enable-cache-report \
  --page-size 64 \
  --mem-fraction-static 0.85 \
  --enable-hierarchical-cache \
  --hicache-ratio 2 \
  --hicache-size 0 \
  --hicache-mem-layout page_first_direct \
  --hicache-io-backend direct \
  --hicache-write-policy write_through \
  --hicache-storage-backend hf3fs \
  --hicache-storage-prefetch-policy wait_complete \

结合 Mooncake 部署#

以下是使用 Mooncake 部署 Qwen3-235B-A22B-Instruct-2507 的示例。更多详情请参阅 Mooncake 文档。

# Set Mooncake environment variables
export MOONCAKE_TE_META_DATA_SERVER="http://127.0.0.1:8080/metadata"
export MOONCAKE_GLOBAL_SEGMENT_SIZE=816043786240
export MOONCAKE_PROTOCOL="rdma"
export MOONCAKE_DEVICE="$DEVICE_LIST"
export MOONCAKE_MASTER=127.0.0.1:50051

# Launch SGLang server with Mooncake backend
python3 -m sglang.launch_server \
  --model-path $MODEL_PATH \
  --tp 8 \
  --page-size 64 \
  --enable-hierarchical-cache \
  --hicache-ratio 2 \
  --hicache-mem-layout page_first_direct \
  --hicache-io-backend direct \
  --hicache-storage-backend mooncake \
  --hicache-write-policy write_through \
  --hicache-storage-prefetch-policy timeout

自定义存储后端集成#

要集成新的存储后端：

  1. 实现三个核心方法：

    • get(key)：通过键获取值

    • exists(key)：检查键是否存在

    • set(key, value)：存储键值对

  2. 注册您的后端： 将您的存储后端添加到 HiCache 的 BackendFactory 中

HiCache 控制器会自动处理所有的调度和同步工作。

动态后端加载#

或者，您可以使用动态加载来避免在代码仓库中硬编码您的后端：

python3 -m sglang.launch_server \
  --model-path your-model \
  --enable-hierarchical-cache \
  --hicache-storage-backend dynamic \
  --hicache-storage-backend-extra-config '{"backend_name":"custom_backend_name", "module_path": "your_module_path", "class_name": "YourHiCacheClassName"}'

配置参数

  • --hicache-storage-backend：设置为 dynamic

  • --hicache-storage-backend-extra-config：JSON 配置，包含：

    • backend_name：自定义后端标识符

    • module_path：指向您实现的 Python 模块路径

    • class_name：您的 HiCache 实现类名

    • interface_v1：0（禁用）或 1（启用），用于控制 batch_get_v1 和 batch_set_v1 方法的使用

社区与支持#

  • GitHub Issues：报告 bug 和功能需求

  • Slack 频道：加入 #sgl-kv-cache-store 参与社区讨论

  • 文档：参考特定存储后端的指南

本文档将根据社区反馈和新功能持续更新。欢迎提出贡献和建议！

目录