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

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

【免费下载链接】unified-cache-managementUnified Cache Manager（推理记忆数据管理器），是一款以KV Cache为中心的推理加速套件，其融合了多类型缓存加速算法工具，分级管理并持久化推理过程中产生的KV Cache记忆数据，扩大推理上下文窗口，以实现高吞吐、低时延的推理体验，降低每Token推理成本。项目地址: https://gitcode.com/ModelEngine/unified-cache-management

Unified Cache Manager（UCM，推理记忆数据管理器）是一款以KV Cache为中心的推理加速套件，能够将推理过程中产生的 KV Cache 记忆数据分级持久化存储，并通过检索复用替代重复计算。本指南带你3 步完成 UCM 与 SGLang 的集成，开启跨请求、跨实例的 KV Cache 持久化共享，让多轮对话与长上下文推理显著提速，降低每 Token 推理成本。

传统部署中，每个 SGLang 推理实例各自持有一份独立的 KV Cache（图中左侧的 Decentralized KVCache），相同前缀的请求到了不同实例就要重新计算；而接入 UCM 后，KV Cache 被统一写入集中式存储（图中右侧的 Centralized KVCache），任意实例都能命中历史缓存，这正是跨请求 KV Cache 持久化共享的价值所在。

一、UCM 是什么？为什么适合 SGLang

UCM 采用分层架构：向上通过 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 的 HiCache

UCM 通过实现 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.9，CUDA 平台。

三、3 步开启跨请求 KV Cache 持久化共享

Step 1：安装 UCM（三选一，推荐 Docker）

方式 A：官方预构建镜像（最快）

docker pull unifiedcachemanager/ucm-sglang:latest docker run --rm --gpus all --network=host --ipc=host \ -v <path_to_your_models>:/home/model \ -v <path_to_your_storage>:/home/storage \ --name <name_of_your_container> \ -it unifiedcachemanager/ucm-sglang:latest

💡--ipc=host用于保证共享内存足够大，不可省略。

方式 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 集成补丁。

方式 C：pip 安装

在 SGLang 官方镜像环境内执行：

export PLATFORM=cuda pip install uc-manager

Step 2：配置 KV Cache 持久化共享（核心配置）

UCM 配置以 JSON 格式通过--hicache-storage-backend-extra-config传入 SGLang：

HICACHE_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.日志即启动成功，随后可直接调用 API：

curl 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-layout`	Host 内存池布局	`page_first`（UCM 强制要求）
`--hicache-write-policy`	缓存写策略	`write_through`
`--hicache-storage-backend`	存储后端类型	`dynamic`（动态加载 UCM 插件）
`storage_backends`	KV Cache 持久化目录	建议指向高速盘或共享存储

常见问题

报错 "requires --hicache-mem-layout page_first"：UnifiedCacheStore仅支持 page_first 布局，请检查启动参数。
缓存不生效：确认backend_name为unifiedcache、module_path拼写正确，且 SGLang 版本已应用适配补丁。
需要更大的 KV Cache 容量：可参考项目内 KV Cache 容量计算器评估显存/内存需求。