SGLang HiCache 最佳实践

SGLang HiCache 最佳实践#

为什么 HiCache 很重要#

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

配置指南#

核心 HiCache 参数#

# 必需的 HiCache 标志
--page-size 64                        # 缓存管理的页面大小
--enable-hierarchical-cache           # 启用 HiCache
--hicache-ratio 2                     # 主机内存比例（GPU 内存的 2 倍）
--hicache-size 100                    # 主机内存大小（以 GB 为计），将覆盖上述比例
--hicache-io-backend kernel           # CPU 和 GPU 之间数据移动的 I/O 后端
--hicache-write-policy write_through  # 从 GPU 到 CPU 的缓存写入策略
--hicache-storage-backend             # 可选的存储后端（例如：hf3fs、mooncake 等）

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

内存布局优化#

# 页面优先：为 I/O 效率优化，支持零拷贝（与 kernel 后端一起使用时推荐）
--hicache-mem-layout page_first
# 页面优先直接：为直接 I/O 操作优化（兼容 fa3，与 page_first 具有相同的零拷贝性能）
--hicache-mem-layout page_first_direct
# 层优先
--hicache-mem-layout layer_first

布局兼容性：

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

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

预取策略#

# 尽力而为：在需要时终止预取
--hicache-storage-prefetch-policy best_effort
# 等待完成：确保完整预取，提高缓存重用率
--hicache-storage-prefetch-policy wait_complete
# 超时：在完成和尽力而为之间取得平衡
--hicache-storage-prefetch-policy timeout

与 PD 分离的集成#

HiCache 与 PD 分离无缝协作。您可以在两种配置中选择：

  1. 仅填充 HiCache：仅在填充节点上启用 HiCache，允许填充实例之间共享 KV 缓存

  2. 带有异步卸载的完整 HiCache：在填充节点上启用 HiCache，在解码节点上启用异步 KV 缓存卸载，允许填充节点在多轮对话场景中重用解码节点的 KV 缓存

# 在填充节点上启用 HiCache 以实现跨填充共享（适用于系统提示场景的理想选择）
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

# 解码节点启用异步卸载以供填充节点重用 KV 缓存（适用于多轮对话的理想选择）
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 \  # 在解码节点中启用异步 KV 缓存卸载
  --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 文档。

# 设置 Mooncake 环境变量
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

# 使用 Mooncake 后端启动 SGLang 服务器
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 问题：报告错误和功能请求

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

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

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

目录