Unified Cache Manager（UCM）SGLang集成指南：3步开启跨请求KV Cache持久化共享

Unified Cache ManagerUCMSGLang集成指南3步开启跨请求KV Cache持久化共享【免费下载链接】unified-cache-managementUnified Cache Manager推理记忆数据管理器是一款以KV Cache为中心的推理加速套件其融合了多类型缓存加速算法工具分级管理并持久化推理过程中产生的KV Cache记忆数据扩大推理上下文窗口以实现高吞吐、低时延的推理体验降低每Token推理成本。项目地址: https://gitcode.com/ModelEngine/unified-cache-managementUnified Cache ManagerUCM推理记忆数据管理器是一款以KV Cache为中心的推理加速套件能够将推理过程中产生的 KV Cache 记忆数据分级持久化存储并通过检索复用替代重复计算。本指南带你3 步完成 UCM 与 SGLang 的集成开启跨请求、跨实例的 KV Cache 持久化共享让多轮对话与长上下文推理显著提速降低每 Token 推理成本。传统部署中每个 SGLang 推理实例各自持有一份独立的 KV Cache图中左侧的 Decentralized KVCache相同前缀的请求到了不同实例就要重新计算而接入 UCM 后KV Cache 被统一写入集中式存储图中右侧的 Centralized KVCache任意实例都能命中历史缓存这正是跨请求 KV Cache 持久化共享的价值所在。一、UCM 是什么为什么适合 SGLangUCM 采用分层架构向上通过 Integration 层以插件形式对接 vLLM、SGLang、MindIE 等推理引擎向下通过 Store 层适配多种存储后端中间提供 Prefill/Decode 加速能力如 Prefix Cache、稀疏注意力等。对 SGLang 而言UCM 的价值可以概括为三点持久化共享KV Cache 落盘到集中存储实例重启、扩容后历史缓存不丢失零拷贝读写基于 HiCache 的batch_get_v1/batch_set_v1零拷贝接口降低存储 I/O 开销免改代码无需修改 SGLang 业务代码通过配置项即可启用。二、集成原理UCM 如何接入 SGLang 的 HiCacheUCM 通过实现 SGLang HiCache 的L3 存储后端接口来接入适配补丁 sglang-adapt.patch 向 SGLang 的StorageBackendFactory注册unifiedcache后端并启用零拷贝的page_get/page_set路径Python 侧由 unifiedcache_store.py 中的UnifiedCacheStore类承载读/写请求ucm_connector.py 中的SglangUcmConnector负责把 SGLang 的 Host KV Pool 映射为 UCM 存储配置自动计算page_size、block_size、device_id等参数最终落到UcmPipelineStore存储管线见上图架构。 前置要求SGLang v0.5.9CUDA 平台。三、3 步开启跨请求 KV Cache 持久化共享Step 1安装 UCM三选一推荐 Docker方式 A官方预构建镜像最快docker pull unifiedcachemanager/ucm-sglang:latest docker run --rm --gpus all --networkhost --ipchost \ -v path_to_your_models:/home/model \ -v path_to_your_storage:/home/storage \ --name name_of_your_container \ -it unifiedcachemanager/ucm-sglang:latest--ipchost用于保证共享内存足够大不可省略。方式 B从源码构建镜像git clone --depth 1 --branch branch_or_tag_name https://gitcode.com/ModelEngine/unified-cache-management cd unified-cache-management docker build -t ucm-sglang:latest -f ./docker/Dockerfile.ucm-sglang-cuda-v0.5.5 ./Dockerfile 会自动调用 build_sglang.sh 编译 wheel、安装依赖并应用 SGLang 集成补丁。方式 Cpip 安装在 SGLang 官方镜像环境内执行export PLATFORMcuda pip install uc-managerStep 2配置 KV Cache 持久化共享核心配置UCM 配置以 JSON 格式通过--hicache-storage-backend-extra-config传入 SGLangHICACHE_CONFIG{ backend_name:unifiedcache, module_path:ucm.integration.sglang.unifiedcache_store, class_name:UnifiedCacheStore, interface_v1:1, kv_connector_extra_config:{ ucm_connector_name:UcmPipelineStore, ucm_connector_config:{ storage_backends:/mnt/test } } }⚠️ 请把/mnt/test替换为你的实际存储目录多个目录可用冒号分隔。也可以将上述kv_connector_extra_config写入 YAML 文件并通过环境变量UNIFIEDCACHE_CONFIG_FILE指定免去每次拼 JSON 的麻烦。Step 3启动推理服务验证缓存命中启动 OpenAI 兼容在线服务python3 -m sglang.launch_server \ --model-path your_model_path \ --tensor-parallel-size 2 \ --page-size 128 \ --port 7800 \ --trust-remote-code \ --enable-hierarchical-cache \ --hicache-mem-layout page_first \ --hicache-write-policy write_through \ --hicache-storage-backend dynamic \ --hicache-storage-prefetch-policy wait_complete \ --hicache-storage-backend-extra-config $HICACHE_CONFIG看到Application startup complete.日志即启动成功随后可直接调用 APIcurl http://localhost:7800/v1/completions \ -H Content-Type: application/json \ -d {model: your_model_path, prompt: Hello!, max_tokens: 64, temperature: 0}离线批量推理同样的分层缓存参数也可直接传给 SGLang 的offline_batch_inference.py示例脚本无需任何 UCM 专属代码改动。四、关键参数速查与常见问题参数作用建议值--enable-hierarchical-cache开启 SGLang 分层缓存HiCache必选--hicache-mem-layoutHost 内存池布局page_firstUCM 强制要求--hicache-write-policy缓存写策略write_through--hicache-storage-backend存储后端类型dynamic动态加载 UCM 插件storage_backendsKV Cache 持久化目录建议指向高速盘或共享存储常见问题报错 requires --hicache-mem-layout page_firstUnifiedCacheStore仅支持 page_first 布局请检查启动参数。缓存不生效确认backend_name为unifiedcache、module_path拼写正确且 SGLang 版本已应用适配补丁。需要更大的 KV Cache 容量可参考项目内 KV Cache 容量计算器评估显存/内存需求。五、总结通过安装 → 配置 → 启动三步你已在 SGLang 上开启了由Unified Cache ManagerUCM驱动的跨请求 KV Cache 持久化共享相同前缀的重复请求将被集中存储命中重复 Prefill 计算被显著减少吞吐与时延表现随之改善。更多细节可查阅官方文档SGLang 快速上手quickstart_sglang.mdSGLang 集成源码ucm/integration/sglang/前缀缓存最佳实践user-guide/prefix-cache/支持矩阵support_matrix.md【免费下载链接】unified-cache-managementUnified Cache Manager推理记忆数据管理器是一款以KV Cache为中心的推理加速套件其融合了多类型缓存加速算法工具分级管理并持久化推理过程中产生的KV Cache记忆数据扩大推理上下文窗口以实现高吞吐、低时延的推理体验降低每Token推理成本。项目地址: https://gitcode.com/ModelEngine/unified-cache-management创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考