Unified Cache Management 前缀缓存(Prefix Cache)架构与多级存储后端实战指南
Unified Cache Management 前缀缓存(Prefix Cache)架构与多级存储后端实战指南
导读
本指南围绕 Unified Cache Management(UCM,即 unified-cache-management 开源仓库)中 KV Cache 最基础、最核心的加速能力——**Prefix Cache(前缀缓存)**展开,涵盖其架构选型逻辑(集中式 vs 分散式)、五类存储后端(PipelineStore / NFS / Ds3fs / Mooncake / Compress)的配置与启动方法,以及基于 vLLM 的端到端性能验证流程。读完本文,你将掌握如何通过修改 UCM 配置文件把 KV Cache 分级卸载到 SSD、本地磁盘、NFS、3FS 或分布式内存池,并用 vllm bench 实测 Prefix Cache 带来的 TTFT(首 token 时延)收益。
一、Prefix Cache:KV Cache 最基础的加速组件
Prefix Cache 是 KV Cache 最简单、最基础的一项加速能力,在业界已形成共识。随着大语言模型(LLM)应用范围扩大、序列长度增长以及 Agent 类应用的普及,Prefix Cache 带来的性能收益愈发显著。在 UCM 中,Prefix Cache 不仅是 KV Cache 应用的默认能力,还为 UCM 的 PD Disaggregation(Prefill/Decode 分离) 提供了基础支撑,同时它也要求稀疏(Sparse)算法必须兼容 Prefix Cache。
Prefix Cache 的核心性能指标是 命中率(hit rate),缓存容量与命中率之间存在直接的正相关关系。以 DeepSeek、Kimi 公开发布的数据为例,需要相对较大的缓存容量才能达到“命中率甜点区”。在输入/输出(I/O)特征上,Prefix Cache 主要需要带宽密集型 I/O,因此非常适合存放在**固态硬盘(SSD)**上。
Prefix Cache 可以利用多种存储介质:
| 存储介质 | 说明 |
|---|---|
| HBM(High-Bandwidth Memory) | GPU/NPU 高带宽显存,速度最快、容量最小 |
| DRAM(Dynamic Random-Access Memory) | 服务器主存,作为高速缓存层级 |
| SSD | 本地固态盘,带宽密集型 I/O 的理想载体 |
| 专用存储系统 | 例如 DeepSeek 为 KV Cache 专门开发的 3fs 存储系统 |
其基本设计哲学是使用 HBM、DRAM、本地 SSD 与远端存储构建 多级缓存(multi-level cache) 层级。在实现上,该层级大致可归为两种架构方向:
- 分散式架构(Decentralized Architecture):每个推理实例独立部署 KV Cache,各 KV Cache 分区隶属于不同推理实例(或服务器)。这种分布式 KV Cache 部署通常与上层 KVCache-aware 亲和性调度(affinity scheduling) 搭配使用,目标是让请求路由到命中率更高的实例,从而最大化整体性能。
- 集中式架构(Centralized Architecture):KV Cache 存储在集中式外部存储系统中,供所有计算节点共享。该架构天然简单,DeepSeek 的 3fs 采用的就是这种设计范式,UCM 的 Prefix Cache 模块同样倾向于优先采用集中式方案。
两种架构的差异本质不在“是否使用远端存储”,而在优先级排序:分散式设计中亲和性调度是最高优先级需求(因为它直接影响命中率);而集中式设计中,亲和性调度被降级为低优先级考量,只影响 TTFT,而不影响核心的命中率指标。
二、为何采用 DeepSeek 式集中式架构而非 Dynamo 式分散式方案
UCM 选择集中式架构而非分散式方案,主要基于以下考量,这些考量与 UCM 的核心设计原则保持一致:
- 遵守 UCM 第一基础原则:“简单性(Simplicity)”。UCM 设计的核心信条是“避免在不带来实质收益的特性上做不必要的投入”。而亲和性调度并非一个简单模块:大多数分散式实现要求每个推理实例向调度器反馈 KV Cache 管理状态,使调度器能预测请求被路由到不同实例时的命中率;同时调度器还需在这些命中率与各实例负载之间做平衡,引入显著的复杂度。
- 符合 UCM 第一派生原则:“解耦(Decoupling)”。在分散式架构中,推理实例需要向调度器上报 KV Cache 状态,这会破坏单个实例的独立性,在上层调度与底层推理组件之间引入耦合。UCM 的设计只受两条原则约束:“简单性”是唯一公理,“解耦”被视为第一条派生定理。
- 成本收益分析:收益不足以抵消原则违背。UCM 的评估表明,分散式 KV Cache 带来的收益不足以抵消违背“简单性”与“解耦”原则的代价。分散式 KV Cache 宣称的主要优势是降低 KV Cache 网络带宽消耗与时延,但在 PD 分离架构下这两个收益都难以实现;而且相比 TTFT 的提升,分散化的时延收益是边际性的。
- 支撑商用级推理方案。分散式 KV Cache 在实现容错与多实例部署时引入额外复杂度。为迈向“商用可行的推理方案”,UCM 优先选择结构简单、对异常鲁棒的架构。
- 缓解数据孤岛(Data Silo)。分散式 KV Cache 天然造成数据孤岛:冗余的 KV Cache 数据在隔离实例间累积,单个孤岛的容量限制又制约整体 Prefix Cache 命中率,削弱关键性能目标。
- 与 PD 分离和大规模部署更好的兼容性。集中式架构与 PD 分离范式兼容性更优,更易于大规模推理部署扩展,这是工业级 LLM 应用的硬性需求。
需要强调:分散式与集中式的区别并非绝对。例如,某些分散式实现会整合远端存储来扩充容量;UCM 同样利用 DRAM 作为高速缓存层级。核心区别在于架构优先级:分散式设计中亲和性调度是刚需,集中式设计中亲和性调度仅是影响 TTFT 的次要考量。
三、存储后端全景:PipelineStore 链式架构
UCM 通过 PipelineStore(流水线存储) 把多个 Store 实现“链式串联”成数据传输管道,实现多级缓存的分层卸载。从源码 ucm/store/pipeline/connector.py 可以看到,所有合法的管道名都注册在 UcmPipelineStoreBuilder 的注册表中(即文档中所说的 PIPELINE_REGISTRY),当前已注册的管道包括:
Cache|Ds3fs、Cache|Empty、Cache|Posix、Cache|Compress|Posix、Cache|FakeEmpty、Fake、Posix、ASU、Mooncake、Mooncake|Posix、Delegator、YuanRong、YuanRong|Posix、Dram
其中与 Prefix Cache 场景直接相关的链路如下:
| 管道 | 职责划分 | 典型用途 |
|---|---|---|
Cache|Posix |
Cache Store 负责 Device↔Host 传输;数据到达 Host 后由 Posix Store 负责 Host↔POSIX 持久存储(本地盘/SSD/NFS 挂载点) | 本地磁盘/SSD 前缀缓存 |
Cache|Ds3fs |
Cache Store 负责 Device↔Host;Ds3fs Store 负责 Host↔3FS | DeepSeek 3FS 分布式存储 |
Mooncake |
KV 块只写入/读取 Mooncake 分布式内存池,无持久化兜底 | 纯分布式内存池 |
Mooncake|Posix |
Mooncake 作为高速 DRAM 层级,Posix 提供持久化 SSD 兜底 | 生产环境推荐配置 |
Cache|Compress|Posix |
Cache→Compress(KVfold 压缩/解压)→Posix 持久化 | SSD 命中场景下降低 I/O、优化 TTFT |
从源码 ucm/store/pipeline/connector.py 可以看到,UcmPipelineStore 在初始化时根据 store_pipeline 字段查找对应 builder,并通过 pipeline.Stack(...) 自底向上依次加载各 Store 的动态库(如 libposixstore.so、libcachestore.so、libcompressor.so、libmooncakestore.so、libds3fsstore.so),由此构成真正的数据通路。
健康检查与熔断
在 Cache|Posix、Mooncake|Posix 等链路中,若配置 store_health.enabled: true,UCM 会用 HealthBreakerStore 包装管道中的每个 Store,提供自动健康探测、熔断(circuit breaking)与恢复能力。该实现位于 ucm/store/pipeline/cc/health_breaker_store.h,它通过 CheckHealth()、ProbeLoop() 等机制周期探测后端状态,并在失败时记录被动结果、触发熔断以保护推理主链路。设置为 false 可关闭自动健康探测与熔断;注意该开关不控制由自定义 Pipeline 实现显式添加的 Breaker。
四、PipelineStore(Cache|Posix):本地磁盘与 SSD 前缀缓存
PipelineStore 是一个复合 Store,通过把多个 Store 实现链式串联形成数据传输管道。当前支持的链路为 Cache Store + Posix Store 组合:
- Cache Store 负责 Device 与 Host 之间的数据传输;
- 数据从 Device 流到 Host 后,Posix Store 负责 Host 与 POSIX 兼容的持久存储(本地磁盘、SSD、远端 NFS(含 NFS over RDMA)挂载点)之间的传输。
最小配置示例
直接修改示例配置文件 examples/ucm_config_example.yaml:
ucm_connectors:
- ucm_connector_name: "UcmPipelineStore"
ucm_connector_config:
store_pipeline: "Cache|Posix"
store_health:
enabled: true
storage_backends: "/mnt/test"
io_direct: false
# cache_buffer_capacity_gb: 256
# posix_capacity_gb: 1024
use_gdr: false
enable_event_sync: true
use_layerwise: true
enable_record_traces: false
use_lite: false
persist_token_threshold: 0
必填参数
ucm_connector_name:指定UcmPipelineStore作为 UCM connector。store_pipeline: "Cache|Posix":指定由 Cache Store 与 Posix Store 链式构建的管道,该管道必须预先在 ucm/store/pipeline/connector.py 的注册表中登记。目前仅支持该 Store 链。storage_backends:KV 块存储目录,可以是本地路径或 NFS 挂载路径。⚠️ 请将"/mnt/test"替换为实际存储目录。
可选参数(位于 ucm_connector_config 内)
| 参数 | 默认值 | 说明 |
|---|---|---|
store_health.enabled |
true |
是否用 HealthBreakerStore 包装管道中的每个 Store;设为 false 可关闭自动健康探测、熔断与恢复。该开关不控制自定义 Pipeline 显式添加的 Breaker |
io_direct |
false |
是否启用直接 I/O。对 Posix Store,启用后读写文件绕过 OS 页缓存 |
cache_buffer_capacity_gb |
256 |
Cache Store Host 侧缓冲容量(GB)。默认 256 GB 大多数场景足够;使用 MLA 类模型时请确保 /dev/shm 空间充足,或调小该值。注意:同一节点上多个数据并行(DP)实例会各自创建独立的 Cache Store 缓冲 |
posix_capacity_gb |
0 |
Posix Store 最大存储容量(GB)。大于 0 时启用垃圾回收(GC),达到阈值后回收磁盘空间;为 0(默认)时无容量限制与 GC |
posix_io_engine |
"psync" |
Posix Store 的 I/O 引擎类型,支持 "psync"(pread/pwrite)、"aio"(libaio) |
use_gdr |
false |
为 Cache Store/Pc Store 的 H2D 与 D2H 拷贝启用 GPUDirect RDMA。需要支持 RDMA 的网卡、可用的 GPUDirect RDMA 环境,并以 ENABLE_GDR=1 编译 UCM |
waiting_queue_depth |
8192 |
Cache Store 传输任务等待队列深度 |
running_queue_depth |
524288 |
Cache Store 传输任务运行队列深度 |
timeout_ms |
30000 |
外部接口超时时间(毫秒),同时适用于 Cache Store 与 Posix Store |
可选参数(顶层,位于 ucm_connector_config 之外)
| 参数 | 默认值 | 说明 |
|---|---|---|
enable_event_sync |
true |
是否启用事件同步。使用 UcmNfsStore 时应设为 false |
use_layerwise |
true |
是否使用 KV cache 块的逐层(layerwise)加载/保存。UCMConnector 默认启用 |
hit_ratio |
无 | 设置后,将命中 token 数限制为 hit_ratio × num_prompt_tokens,用于控制实际加载的缓存 token 比例 |
enable_record_traces |
false |
是否记录请求轨迹。启用后按请求记录(时间戳、input_length、output_length、hash_ids)。每个 hash_id 占 32 字节,仅按需开启,并相应配置 UCM_LOG_MAX_FILES 与 UCM_LOG_MAX_SIZE |
use_lite |
false |
是否使用 UCM Lite Connector。Lite Connector 配合 Fake Store 跳过实际 KV dump/load 操作,只收集命中率统计,建议先收集命中率数据并与相关项目成员确认后再决定是否采用 UCM |
persist_token_threshold |
0 |
KV 持久化的最小 token 阈值,token 数低于该阈值的请求跳过 KV load 与 dump 操作 |
metrics_config_path |
无 | UCM 指标配置 YAML 文件路径。设置后启用 UCM 指标,可通过 Grafana 与 Prometheus 在线监控 |
补充:启用共享缓冲(
share_buffer_enable)时,Cache Store 缓冲由/dev/shm(tmpfs)承载。源码 ucm/integration/vllm/ucm_connector.py 会在初始化时提前校验/dev/shm容量是否足以容纳cache_buffer_capacity_gb,不足时会直接报错并提示扩 tmpfs 或调小参数,避免在 C++ 底层深处失败。
五、NFS Store(UcmNfsStore):KV Cache 卸载到 SSD 或本地磁盘
NFS Connector 用于把 KV Cache 从 GPU HBM 卸载到 SSD 或本地磁盘,帮助降低显存压力、支撑更大模型或更大 batch size。
功能特性
| 接口 | 说明 |
|---|---|
dump |
将 KV cache 块从 HBM 卸载到 SSD 或本地磁盘 |
load |
将 KV cache 块从 SSD 或本地磁盘加载回 HBM |
lookup |
按块哈希查询存储在 SSD/本地磁盘中的 KV 块 |
wait |
确保所有 dump/load 操作完成 |
最小配置示例
ucm_connectors:
- ucm_connector_name: "UcmNfsStore"
ucm_connector_config:
storage_backends: "/mnt/test"
io_direct: false
必填参数:ucm_connector_name 指定 UcmNfsStore;storage_backends 为 KV 块存储目录(本地路径或 NFS 挂载路径),⚠️ 请替换 "/mnt/test"。
可选参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
io_direct |
false |
是否启用直接 I/O |
stream_number |
8 |
数据传输使用的并发流数量 |
timeout_ms |
30000 |
外部接口超时时间(毫秒) |
buffer_number |
4096 |
数据传输的中间缓冲数量 |
shard_data_dir |
true |
文件是否分散到子目录,还是存放在单一目录 |
从源码看,UcmNfsStore(实现于 ucm/store/nfsstore/nfsstore_connector.py)会把 storage_backends 按 : 拆分为多个后端路径,并仅在工作节点(role == "worker")上启用传输能力;stream_number、buffer_number、use_direct 等参数会透传给底层 NFSStore.Config。值得注意的是,注册表中名为 UcmNfsStore 的 connector 实际映射到 ucm/store/factory_v1.py 中的 UcmPcStoreV1 实现(即 Pc Store),旧版 ucm.store.pcstore.pcstore_connector 中的 UcmNfsStore 为其前身,两者接口保持一致。
六、Ds3fs Store(Cache|Ds3fs):基于 3FS 的分布式 KV 存储
Ds3fs Store 通过 PipelineStore 与 Cache Store 链式串联,形成数据传输管道:
- Cache Store 负责 Device 与 Host 之间的数据传输;
- 数据到达 Host 后,Ds3fs Store 负责 Host 与 3FS 之间的数据传输。
3FS 的部署请遵循其官方文档进行编译与安装(⚠️ 推荐将 3FS 源码编译安装路径设为 /usr/local)。
配置示例
ucm_connectors:
- ucm_connector_name: "UcmPipelineStore"
ucm_connector_config:
store_pipeline: "Cache|Ds3fs"
storage_backends: "/mount/3fs"
必填参数:store_pipeline: "Cache|Ds3fs"(需预先在 ucm/store/pipeline/connector.py 注册表中登记);storage_backends 为 3FS 挂载路径,⚠️ 请替换 "/mount/3fs"。
可选参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
io_direct |
true |
是否启用直接 I/O |
stream_number |
32 |
数据传输并发流数量 |
waiting_queue_depth |
1024 |
传输任务等待队列深度 |
running_queue_depth |
32768 |
传输任务运行队列深度 |
timeout_ms |
30000 |
外部接口超时时间(毫秒) |
buffer_size |
64GB |
单个 worker 进程使用的 DRAM 固定内存(pinned memory)大小 |
从源码结构看,ucm/store/ds3fs/cc/ds3fs_store.h 的 Ds3fsStore 实现 StoreV1 接口(Lookup/Load/Dump/Wait 等),配合 ucm/store/ds3fs/cc/space_manager.cc、ds3fs_file.cc 等实现面向 3FS 文件系统的空间管理与数据搬运。同时在 builder 中,若配置了 device_id,还会按 shard_size 为 Ds3fs 设置 tensor_size,以保证 Host 侧与 3FS 侧的 I/O 尺寸对齐(见 ucm/store/pipeline/connector.py)。
七、Mooncake Store:基于 RDMA/HCCL 的分布式内存池
Mooncake Store 将 Mooncake(高性能分布式 KV Cache 传输引擎)集成进 UCM 存储管道。它使用 RDMA(或 Ascend HCCL)在设备内存与跨节点的分布式共享内存池之间直接搬运 KV cache 块,时延显著低于基于磁盘的后端。
支持两种管道模式:
Mooncake(独立模式):KV 块只写入/读取 Mooncake 分布式内存池,无持久化兜底;Mooncake|Posix(链式模式):Mooncake 作为高速 DRAM 层级,Posix 提供持久化 SSD 兜底,这是生产环境的推荐配置。
功能特性
| 接口 | 说明 |
|---|---|
dump |
将 KV cache 块从设备(HBM/DRAM)卸载到 Mooncake 分布式内存池 |
load |
从 Mooncake 分布式内存池取回 KV cache 块到设备内存 |
lookup |
按块哈希检查 KV 块是否存在于 Mooncake store |
wait |
阻塞直至所有在途 dump/load 操作完成 |
前置条件:启动 Mooncake master 服务
mooncake_master --port 50088 --eviction_high_watermark_ratio 0.9 --eviction_ratio 0.1 --default_kv_lease_ttl 60000
| Flag | 说明 |
|---|---|
--port |
master 服务监听端口 |
--eviction_high_watermark_ratio |
触发 GC 的缓存池填充比例(如 0.9 = 90%) |
--eviction_ratio |
每轮 GC 回收的缓存比例(如 0.1 = 10%) |
--default_kv_lease_ttl |
KV 条目的租约 TTL(毫秒) |
推荐配置(Mooncake|Posix 管道)
直接修改示例配置 examples/ucm_mooncake_config.yaml:
ucm_connectors:
- ucm_connector_name: "UcmPipelineStore"
ucm_connector_config:
store_pipeline: "Mooncake|Posix"
store_health:
enabled: true
local_hostname: "127.0.0.1"
master_server_address: "127.0.0.1:50088"
metadata_server: "P2PHANDSHAKE"
protocol: "ascend"
global_segment_size_gb: 30
replica_num: 1
storage_backends: "/mnt/test"
io_direct: true
posix_io_engine: "aio"
share_buffer_capacity_gb: 64
enable_event_sync: true
use_layerwise: false
独立配置(仅 Mooncake)
ucm_connectors:
- ucm_connector_name: "UcmPipelineStore"
ucm_connector_config:
store_pipeline: "Mooncake"
store_health:
enabled: true
local_hostname: "127.0.0.1"
master_server_address: "127.0.0.1:50088"
metadata_server: "P2PHANDSHAKE"
protocol: "ascend"
global_segment_size_gb: 30
replica_num: 1
share_buffer_capacity_gb: 64
enable_event_sync: true
use_layerwise: false
必填参数
| 参数 | 说明 |
|---|---|
ucm_connector_name |
必须设为 "UcmPipelineStore" |
store_pipeline |
使用 `"Mooncake |
local_hostname |
本节点 IP,不能包含端口号。⚠️ 请将 "127.0.0.1" 替换为本节点实际 IP |
master_server_address |
Mooncake master 服务地址,host:port 格式,默认 "127.0.0.1:50088" |
protocol |
Mooncake 使用的传输协议:Ascend NPU 环境用 "ascend",纯 CPU 测试用 "tcp",InfiniBand/RoCE 环境用 "rdma" |
storage_backends |
(Mooncake|Posix 必填)Posix 持久化 SSD 层级路径。⚠️ 请替换 "/mnt/test" |
可选参数
| 参数 | 默认值 | 说明 |
|---|---|---|
metadata_server |
"P2PHANDSHAKE" |
元数据服务器地址,使用 "P2PHANDSHAKE" 表示点对点握手模式(无需独立元数据服务器) |
global_segment_size_gb |
~30 GiB | 全局分布式内存段大小(GiB);也可用字节单位 global_segment_size |
local_buffer_size_gb |
1 GiB | 本地传输缓冲大小(GiB);也可用字节单位 local_buffer_size |
replica_num |
1 |
Mooncake 池中每个 KV 块的副本数,必须 ≥ 1 |
device_name |
"" |
使用的 RDMA 或 Ascend 设备名(如 RDMA 用 "mlx5_0"),留空使用默认设备 |
stream_number |
4 |
并发传输流数量 |
io_direct |
false |
是否对 Posix 层级启用直接 I/O(仅 Mooncake|Posix 管道适用) |
posix_io_engine |
"sync" |
Posix 层级的 I/O 引擎,可选 "sync"、"aio",推荐 "aio" |
timeout_ms |
0(无超时) |
传输操作超时时间(毫秒),0 表示无限等待 |
enable_event_sync |
false(顶层配置键) |
设为 true 时,UCM 在每次 dump 前插入设备事件同步屏障,确保 NPU/GPU 计算完成后再让 Mooncake 读取设备内存。Ascend NPU 环境必须启用 |
从源码看,Python 侧 UcmMooncakeStore(ucm/store/mooncakestore/mooncake_connector.py)将配置转换为 MooncakeStoreConfig,底层调用 MooncakeDistributedStore 的 setup/get/put/is_exist 接口,通过独立事件循环线程以异步方式执行 dump/load;而 ucm/store/pipeline/connector.py 中的 Mooncake 与 Mooncake|Posix builder 则加载 C++ 侧 libmooncakestore.so,二者共同构成 UCM 对 Mooncake 的接入。
八、Compress Store(Cache|Compress|Posix):KVfold 压缩模块
Compress Store 是 UCM 的存储压缩模块,基于 KVfold 压缩算法实现 KV cache 张量的压缩/解压能力,可无缝集成进 UCM 存储管道。通过降低磁盘 I/O 开销,它在 SSD 缓存命中场景下显著优化 TTFT。当前版本对 BF16 张量支持 2.0x 压缩。
核心特性
- 基于 KVfold 编码的完整 KV cache 压缩/解压管道,当前版本支持 BF16 张量 2.0x 压缩;
- 多线程并行解压能力,线程数可灵活配置,适配不同硬件环境与业务场景;
- 与现有 UCM 存储管道无缝集成,通过 Pipeline 配置一键开启/关闭压缩功能;
- 全参数 YAML 配置支持,可灵活调优压缩参数;
- 同时兼容逐层(layer-wise)与逐块(block-wise)缓存模式。
完整配置示例
ucm_connectors:
- ucm_connector_name: "UcmPipelineStore"
ucm_connector_config:
# 必填:启用压缩管道,固定配置为 Cache|Compress|Posix
store_pipeline: "Cache|Compress|Posix"
# 存储路径,支持本地路径或 NFS 挂载路径
storage_backends: "/home/lyj/temp/kv"
# 压缩比配置:16=2.0x 压缩,32=1.0x 不压缩,暂不支持其他值
compress_ratio: 16
# 数据类型配置:0=BF16,100=INVALID,暂不支持其他值
data_type: 0
# 并行解压线程数
decompress_thread_num: 48
# 是否启用直接 I/O
io_direct: true
# Cache 缓冲容量(GB)
cache_buffer_capacity_gb: 64
# POSIX IO 引擎
posix_io_engine: "aio"
# 全局配置
use_layerwise: true
enable_record_traces: false
参数说明
必填参数:
| 参数 | 说明 |
|---|---|
store_pipeline |
固定配置为 Cache|Compress|Posix 才能启用压缩管道;缺少该配置压缩功能不生效 |
压缩专属可选参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
compress_ratio |
16 |
压缩比配置:16 = 2.0x 无损压缩(推荐);32 = 1.0x 不压缩;其他值暂不支持 |
data_type |
0 |
张量数据类型:0 = BF16(当前唯一支持类型);100 = INVALID;其他值暂不支持 |
decompress_thread_num |
6 |
并行解压线程数。use_layerwise: false 时可用默认值;use_layerwise: true 时建议提升至 40+,需按服务器硬件配置压测调优 |
从源码看,压缩核心位于 ucm/store/compress/cc/compress_lib/tunstall_bf16.h:TunstallCompressBF16 把 n_bf16 个 BF16 值压缩为 n_bf16 字节(固定 2x 压缩率),TunstallDecompressBF16 与之对应解压;ucm/store/compress/cc/global_config.h 中 Config 结构确认了 compressRatio(默认 32)、dataType(默认 100)与 decompressThreadNum(默认 6)等参数的 C++ 侧默认值。此外,在 ucm/store/pipeline/connector.py 的 _build_cache_compress_posix_pipeline 中,启用压缩后会按 compress_ratio 对 Posix 层级的 shard_size 做压缩换算(shard_size × compress_ratio / 32 并对齐到 4096 字节),并校验 block_size 能被 shard_size 整除,从而保证压缩前后的 I/O 尺寸一致。
九、启动 vLLM 在线推理(UCMConnector)
以下以 vLLM + UCM connector 部署 OpenAI 兼容在线服务为例。为获得 UCM 最佳性能,推荐将 block_size 设为 128。
以 Qwen/Qwen2.5-14B-Instruct 为例的启动命令:
vllm serve Qwen/Qwen2.5-14B-Instruct \
--max-model-len 20000 \
--tensor-parallel-size 2 \
--gpu_memory_utilization 0.87 \
--block_size 128 \
--trust-remote-code \
--port 7800 \
--enforce-eager \
--no-enable-prefix-caching \
--kv-transfer-config \
'{
"kv_connector": "UCMConnector",
"kv_role": "kv_both",
"kv_connector_module_path": "ucm.integration.vllm.ucm_connector",
"kv_connector_extra_config": {"UCM_CONFIG_FILE": "/vllm-workspace/unified-cache-management/examples/ucm_config_example.yaml"}
}'
⚠️ 请将 "/vllm-workspace/unified-cache-management/examples/ucm_config_example.yaml" 替换为你机器上实际的配置路径。
也可以通过在 UCM_CONFIG_FILE 中添加 "use_layerwise": true 使用 Layerwise Connector,例如:
ucm_connectors:
- ucm_connector_name: "UcmPipelineStore"
ucm_connector_config:
store_pipeline: "Cache|Posix"
store_health:
enabled: true
storage_backends: "/mnt/test"
io_direct: false
# cache_buffer_capacity_gb: 256
# posix_capacity_gb: 1024
use_gdr: false
enable_event_sync: true
use_layerwise: true
enable_record_traces: false
use_lite: false
persist_token_threshold: 0
启动成功标志(看到以下日志即表示 vLLM + UCM connector 启动成功):
INFO: Started server process [1049932]
INFO: Waiting for application startup.
INFO: Application startup complete.
多节点 DP 场景(Mooncake 示例)
Mooncake 文档以 GLM4.7-W8A8 模型、DP2 + TP8(两节点) 为例给出了完整启动命令。主节点与工作节点均需先导出 Ascend 环境变量(如 ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7、HCCL_INTRA_ROCE_ENABLE=1、ENABLE_UCM_PATCH=1、UC_LOGGER_LEVEL=info 等),随后各自启动 vllm serve。两节点的关键差异在 --data-parallel-start-rank(主节点为 0,工作节点为 1)、--data-parallel-address(对端节点 IP)以及工作节点额外添加 --headless 参数;--kv-transfer-config 中 UCM_CONFIG_FILE 指向 examples/ucm_mooncake_config.yaml。⚠️ 请将示例中的节点 IP、模型路径与 UCM 配置文件路径替换为实际值。
十、性能验证:用 vllm bench 两次执行实测 Prefix Cache 效果
启动启用 UCMConnector 的 vLLM 服务后,观察 Prefix Cache 效果最简便的方式是运行 vLLM 内置的 vllm bench CLI。在另一个终端中连续执行两次相同命令,改善效果一目了然:
vllm bench serve \
--backend vllm \
--model Qwen/Qwen2.5-14B-Instruct \
--host 127.0.0.1 \
--port 7800 \
--dataset-name random \
--num-prompts 12 \
--random-input-len 16000 \
--random-output-len 2 \
--request-rate inf \
--seed 123456 \
--percentile-metrics "ttft,tpot,itl,e2el" \
--metric-percentiles "90,99" \
--ignore-eos
第一次执行(冷启动基线)
vllm bench 终端输出基准结果,例如:
---------------Time to First Token----------------
Mean TTFT (ms): 15001.64
查看 vLLM 服务端日志,可看到类似条目(不同后端版本日志行号略有差异,例如 ucm_connector.py:317 或 ucm_connector.py:228):
INFO ucm_connector.py:317: request_id: xxx, total_blocks_num: 125, hit hbm: 0, hit external: 0
这表示第一次推理请求时,UCM 没有命中任何缓存 KV 块,完整的 16K token prefill 必须全部计算,因此 TTFT 较大。
第二次执行(缓存命中)
再次运行相同基准,输出变为:
---------------Time to First Token----------------
Mean TTFT (ms): 2874.21
vLLM 服务端日志中出现:
INFO ucm_connector.py:317: request_id: xxx, total_blocks_num: 125, hit hbm: 0, hit external: 125
表示第二次请求时,UCM 从存储后端成功取回了全部 125 个缓存的 KV 块。得益于完全命中的缓存前缀,模型观测到的初始时延显著降低,TTFT 相比首轮大约提升 5×。
该日志来自 ucm/integration/vllm/ucm_connector.py 中的请求级统计:
hit hbm为 HBM 命中块数,hit external为外部存储命中块数(total_hit_block_num - hbm_hit_block_num),可用于快速判断缓存命中来源。
压缩模块的验证流程(需重启清 DRAM 缓存)
若验证 Compress Store 的压缩收益,需严格执行“控制变量”流程,排除 DRAM 内存缓存干扰,确保 KV cache 只从 SSD 读取:
- 第一次执行(冷启动、无缓存基线):先重启 vLLM 服务清空历史缓存,执行压测命令。日志显示
hit hbm: 0, hit external: 0,无 SSD 缓存命中;观察COMPRESS DUMP相关日志,确认本次请求生成的 KV cache 已被压缩并持久化到 SSD。 - 第二次执行前重启服务以清空 DRAM 缓存:必须重启 vLLM 服务彻底清空进程内 DRAM 内存缓存,确保后续请求无法从内存命中缓存、只能读取已 dump 到 SSD 的压缩 KV cache。这是测试的核心控制变量操作。
- 第二次执行(SSD 缓存命中、压缩效果验证):重启后立即执行与第一次完全相同的压测命令。日志显示
hit hbm: 0, hit external: 125(SSD 全命中、无内存命中);观察COMPRESS LOAD相关解压加载日志,验证压缩模块完整工作链路。
十一、性能数据参考
以下为 UCM 官方文档中 Prefix Cache 场景(CUDA 环境)的多并发性能测试结果。测试期间均禁用了 HBM 缓存,KV Cache 仅从 SSD/存储后端检索与匹配。其中 “Full Compute” 指纯 vLLM 推理,“SSD80% / Disk80% / Ds3fs80%” 表示经 UCM 池化后 KV cache 的 SSD/磁盘/Ds3fs 命中率为 80%。
PipelineStore(Cache|Posix)场景
QwQ-32B 模型(4 × H100 GPUs):
| QwQ-32B | ||||
|---|---|---|---|---|
| Input length | Concurrent | Full Compute (ms) | SSD80% (ms) | Speedup (%) |
| 4 000 | 1 | 223.05 | 156.54 | +42.5% |
| 8 000 | 1 | 350.47 | 228.27 | +53.5% |
| 16 000 | 1 | 708.94 | 349.17 | +103.0% |
| 32 000 | 1 | 1512.04 | 635.18 | +138.0% |
| 4 000 | 8 | 908.52 | 625.92 | +45.1% |
| 8 000 | 8 | 1578.72 | 955.25 | +65.3% |
| 16 000 | 8 | 3139.03 | 1647.72 | +90.5% |
| 32 000 | 8 | 6735.25 | 3025.23 | +122.6% |
| 4 000 | 16 | 1509.79 | 919.53 | +64.2% |
| 8 000 | 16 | 2602.34 | 1480.30 | +75.8% |
| 16 000 | 16 | 5732.49 | 2393.54 | +139.5% |
| 32 000 | 16 | 11891.61 | 4790.00 | +148.3% |
DeepSeek-R1-awq 模型(8 × H100 GPUs):
| DeepSeek-R1-awq | ||||
|---|---|---|---|---|
| Input length | Concurrent | Full Compute (ms) | SSD80% (ms) | Speedup (%) |
| 4 000 | 1 | 429.30 | 261.34 | +64.3% |
| 8 000 | 1 | 762.23 | 363.37 | +109.8% |
| 16 000 | 1 | 1426.06 | 586.17 | +143.3% |
| 32 000 | 1 | 3086.85 | 1073.25 | +187.6% |
| 4 000 | 8 | 1823.55 | 1017.72 | +79.2% |
| 8 000 | 8 | 3214.76 | 1511.16 | +112.7% |
| 16 000 | 8 | 6417.81 | 2596.70 | +147.2% |
| 32 000 | 8 | 14278.00 | 5111.67 | +179.3% |
| 4 000 | 16 | 3205.22 | 1534.00 | +108.9% |
| 8 000 | 16 | 5813.09 | 2208.60 | +163.2% |
| 16 000 | 16 | 11752.48 | 4000.46 | +193.8% |
| 32 000 | 16 | 38643.73 | 19910.41 | +94.1% |
NFS Store 场景
QwQ-32B 模型(1 台 H20 服务器,2 GPUs):
| QwQ-32B | ||||
|---|---|---|---|---|
| Input length | Concurrent | Full Compute(s) | Disk80%(s) | Speedup |
| 2 000 | 1 | 0.5311 | 0.2053 | +158.7 % |
| 4 000 | 1 | 1.0269 | 0.3415 | +200.7 % |
| 8 000 | 1 | 2.0902 | 0.6429 | +225.1 % |
| 16 000 | 1 | 4.4852 | 1.3598 | +229.8 % |
| 32 000 | 1 | 10.2037 | 3.0713 | +232.2 % |
| 2 000 | 2 | 0.7938 | 0.3039 | +161.2 % |
| 4 000 | 2 | 1.5383 | 0.4968 | +209.6 % |
| 8 000 | 2 | 3.1323 | 0.9544 | +228.2 % |
| 16 000 | 2 | 6.7984 | 2.0149 | +237.4 % |
| 32 000 | 2 | 15.3395 | 4.5619 | +236.3 % |
| 2 000 | 4 | 1.6572 | 0.5998 | +176.3 % |
| 4 000 | 4 | 2.8173 | 1.2657 | +122.6 % |
| 8 000 | 4 | 5.2643 | 1.9829 | +165.5 % |
| 16 000 | 4 | 11.3651 | 3.9776 | +185.7 % |
| 32 000 | 4 | 25.6718 | 8.2881 | +209.7 % |
| 2 000 | 8 | 2.8559 | 1.2250 | +133.1 % |
| 4 000 | 8 | 5.0003 | 2.0995 | +138.2 % |
| 8 000 | 8 | 9.5365 | 3.6584 | +160.7 % |
| 16 000 | 8 | 20.3839 | 6.8949 | +195.6 % |
| 32 000 | 8 | 46.2107 | 14.8704 | +210.8 % |
DeepSeek-V3 模型(2 台 H20 服务器,16 GPUs):
| DeepSeek-V3 | ||||
|---|---|---|---|---|
| Input length | Concurrent | Full Compute(s) | Disk80%(s) | Speedup |
| 2 000 | 1 | 0.66971 | 0.33960 | +97.2 % |
| 4 000 | 1 | 1.73146 | 0.48720 | +255.4 % |
| 8 000 | 1 | 3.33155 | 0.86782 | +283.9 % |
| 16 000 | 1 | 6.71235 | 2.09067 | +221.1 % |
| 32 000 | 1 | 14.16003 | 4.26111 | +232.3 % |
| 2 000 | 2 | 0.94628 | 0.50635 | +86.9 % |
| 4 000 | 2 | 2.56590 | 0.71750 | +257.6 % |
| 8 000 | 2 | 4.98428 | 1.32238 | +276.9 % |
| 16 000 | 2 | 10.08294 | 3.10009 | +225.2 % |
| 32 000 | 2 | 21.11799 | 6.35784 | +232.2 % |
| 2 000 | 4 | 2.86674 | 0.84273 | +240.2 % |
| 4 000 | 4 | 5.42761 | 1.35695 | +300.0 % |
| 8 000 | 4 | 10.90076 | 3.02942 | +259.8 % |
| 16 000 | 4 | 22.43841 | 6.59230 | +240.4 % |
| 32 000 | 4 | 43.29353 | 14.51481 | +198.3 % |
| 2 000 | 8 | 5.69329 | 1.82275 | +212.3 % |
| 4 000 | 8 | 11.80801 | 3.36708 | +250.7 % |
| 8 000 | 8 | 23.93016 | 7.01634 | +241.1 % |
| 16 000 | 8 | 42.04222 | 14.78947 | +184.3 % |
| 32 000 | 8 | 78.55850 | 35.63042 | +120.5 % |
Ds3fs Store 场景
部署说明:使用两个节点部署 3FS 服务,其中 MGMTD、META、Storage1 部署在同一节点,Storage2 部署在另一节点,每个 Storage 节点聚合 两块 NVME 磁盘。
QwQ-32B 模型(2 × H100 GPUs):
| QwQ-32B | ||||
|---|---|---|---|---|
| Input length | Concurrent | Full Compute (ms) | Ds3fs80% (ms) | Speedup (%) |
| 4 000 | 1 | 268.28 | 116.19 | +131% |
| 8 000 | 1 | 533.62 | 222.95 | +139% |
| 16 000 | 1 | 1144.92 | 493.03 | +132% |
| 32 000 | 1 | 2544.43 | 1032.93 | +146% |
| 4 000 | 2 | 402.22 | 231.55 | +74% |
| 8 000 | 2 | 800.22 | 461.20 | +74% |
| 16 000 | 2 | 1656.04 | 760.39 | +118% |
| 32 000 | 2 | 3691.84 | 1490.49 | +148% |
| 4 000 | 4 | 776.34 | 453.37 | +71% |
| 8 000 | 4 | 1596.00 | 757.66 | +111% |
| 16 000 | 4 | 3413.29 | 1489.32 | +129% |
| 32 000 | 4 | 6922.88 | 3022.35 | +129% |
| 4 000 | 8 | 1616.54 | 805.95 | +101% |
| 8 000 | 8 | 3357.11 | 1528.08 | +120% |
| 16 000 | 8 | 5970.69 | 2707.25 | +121% |
| 32 000 | 8 | 12114.44 | 5578.02 | +117% |
DeepSeek-R1-awq 模型(8 × H100 GPUs):
| DeepSeek-R1-awq | ||||
|---|---|---|---|---|
| Input length | Concurrent | Full Compute (ms) | Ds3fs80% (ms) | Speedup (%) |
| 4 000 | 1 | 376.96 | 246.79 | +53% |
| 8 000 | 1 | 699.60 | 354.76 | +97% |
| 16 000 | 1 | 1389.29 | 595.04 | +133% |
| 32 000 | 1 | 2937.73 | 987.10 | +198% |
| 4 000 | 2 | 567.43 | 417.65 | +36% |
| 8 000 | 2 | 1000.06 | 581.51 | +72% |
| 16 000 | 2 | 1989.25 | 990.39 | +101% |
| 32 000 | 2 | 4261.70 | 1688.59 | +152% |
| 4 000 | 4 | 1038.78 | 742.64 | +40% |
| 8 000 | 4 | 1993.80 | 1023.65 | +95% |
| 16 000 | 4 | 4066.21 | 1893.01 | +115% |
| 32 000 | 4 | 8210.61 | 3588.30 | +129% |
| 4 000 | 8 | 2098.07 | 1232.56 | +70% |
| 8 000 | 8 | 4157.40 | 2001.83 | +108% |
| 16 000 | 8 | 7270.95 | 3493.18 | +108% |
| 32 000 | 8 | 14542.17 | 6913.94 | +110% |
Mooncake Store 场景(GLM4.7-W8A8)
| Input | Output | Hit Rate | Concurrent | Requests | Full Compute TTFT (s) | Full Compute TPOT (s) | Full Compute E2E (s) | UCM+Mooncake TTFT (s) | UCM+Mooncake TPOT (s) | UCM+Mooncake E2E (s) | TTFT Speedup |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 2 000 | 512 | 50% | 64 | 200 | 4.164 | 0.076 | 42.808 | 3.342 | 0.074 | 41.311 | +20% |
| 4 000 | 512 | 50% | 64 | 100 | 9.828 | 0.091 | 56.322 | 7.089 | 0.084 | 50.193 | +28% |
| 8 000 | 512 | 50% | 32 | 50 | 11.518 | 0.090 | 57.568 | 8.532 | 0.081 | 48.910 | +26% |
| 16 000 | 512 | 50% | 16 | 25 | 12.889 | 0.087 | 57.434 | 8.415 | 0.081 | 49.820 | +35% |
| 32 000 | 512 | 50% | 8 | 13 | 16.705 | 0.100 | 67.686 | 11.481 | 0.086 | 55.271 | +31% |
| 64 000 | 512 | 50% | 4 | 7 | 27.141 | 0.114 | 85.421 | 18.623 | 0.101 | 70.430 | +31% |
| 128 000 | 512 | 50% | 2 | 4 | 56.878 | 0.120 | 118.100 | 39.876 | 0.123 | 102.517 | +30% |
| 2 000 | 512 | 90% | 64 | 200 | 4.164 | 0.076 | 42.808 | 2.353 | 0.065 | 35.647 | +43% |
| 4 000 | 512 | 90% | 64 | 100 | 9.828 | 0.091 | 56.322 | 3.240 | 0.068 | 37.843 | +67% |
| 8 000 | 512 | 90% | 32 | 50 | 11.518 | 0.090 | 57.568 | 3.289 | 0.062 | 35.149 | +71% |
| 16 000 | 512 | 90% | 16 | 25 | 12.889 | 0.087 | 57.434 | 3.623 | 0.060 | 34.167 | +72% |
| 32 000 | 512 | 90% | 8 | 13 | 16.705 | 0.100 | 67.686 | 4.421 | 0.068 | 38.356 | +74% |
| 64 000 | 512 | 90% | 4 | 7 | 27.141 | 0.114 | 85.421 | 6.548 | 0.088 | 51.265 | +76% |
| 128 000 | 512 | 90% | 2 | 4 | 56.878 | 0.120 | 118.100 | 13.528 | 0.121 | 75.386 | +76% |
Compress Store 场景(Qwen2.5-14B-Instruct,鲲鹏 920 5250 + 4 × Ascend 910B4,TP=4,禁用 DRAM 缓存)
Layer-wise 模式(use_layerwise: true):
| input tokens | output tokens | batch size | odirect | TTFT/ms, 50% hit, w/o compression | TTFT/ms, 50% hit, with compression | TTFT reduction | TTFT/ms, 80% hit, w/o compression | TTFT/ms, 80% hit, with compression | TTFT reduction | TTFT/ms, 100% hit, w/o compression | TTFT/ms, 100% hit, with compression | TTFT reduction |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4000 | 1 | 1 | TRUE | 357.99 | 341.97 | 4.47% | 207.02 | 225.74 | -9.04% | 208.37 | 193.22 | 7.27% |
| 8000 | 1 | 1 | TRUE | 531.6 | 578.86 | -8.89% | 304.06 | 321.29 | -5.67% | 350.01 | 331.22 | 5.37% |
| 16000 | 1 | 1 | TRUE | 1236.44 | 1284.19 | -3.86% | 800.25 | 720.4 | 9.98% | 611.74 | 532.57 | 12.94% |
| 32000 | 1 | 1 | TRUE | 3278.62 | 3152.37 | 3.85% | 2077.46 | 1807.59 | 12.99% | 1204.62 | 959.57 | 20.34% |
| 4000 | 1 | 8 | TRUE | 1339.06 | 1396.03 | -4.25% | 868.46 | 839.52 | 3.33% | 1056.99 | 829.89 | 21.49% |
| 8000 | 1 | 8 | TRUE | 2353.23 | 2373.6 | -0.87% | 1436.33 | 1356.39 | 5.57% | 2024.04 | 1421.53 | 29.77% |
| 16000 | 1 | 8 | TRUE | 5311.28 | 5548.89 | -4.47% | 3433.49 | 2829.16 | 17.60% | 3808.22 | 2906.72 | 23.67% |
| 32000 | 1 | 8 | TRUE | 13796.04 | 13660.42 | 0.98% | 8353.08 | 7851.27 | 6.01% | 6939.55 | 5274.13 | 24.00% |
| 4000 | 1 | 16 | TRUE | 2280.48 | 2343.98 | -2.78% | 1428.27 | 1232.16 | 13.73% | 2154.65 | 1342.75 | 37.68% |
| 8000 | 1 | 16 | TRUE | 4414.05 | 4436.29 | -0.50% | 2639.71 | 2388.07 | 9.53% | 4170.57 | 2646 | 36.56% |
| 16000 | 1 | 16 | TRUE | 10144.97 | 9960.42 | 1.82% | 6167.56 | 5084.08 | 17.57% | 7170.8 | 4005.21 | 44.15% |
| 32000 | 1 | 16 | TRUE | 25967.02 | 24714.92 | 4.82% | 15550.23 | 12950.47 | 16.72% | 12261.77 | 7504.62 | 38.80% |
Block-wise 模式(use_layerwise: false):
| input tokens | output tokens | batch size | odirect | TTFT/ms, 50% hit, w/o compression | TTFT/ms, 50% hit, with compression | TTFT reduction | TTFT/ms, 80% hit, w/o compression | TTFT/ms, 80% hit, with compression | TTFT reduction | TTFT/ms, 100% hit, w/o compression | TTFT/ms, 100% hit, with compression | TTFT reduction |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4000 | 1 | 1 | TRUE | 423.87 | 406.85 | 4.02% | 307.49 | 253.9 | 17.43% | 260.84 | 198.13 | 24.04% |
| 8000 | 1 | 1 | TRUE | 688.38 | 665.83 | 3.28% | 507.52 | 419.18 | 17.41% | 460.22 | 352.85 | 23.33% |
| 16000 | 1 | 1 | TRUE | 1528.11 | 1479.79 | 3.16% | 1083.55 | 874.61 | 19.28% | 617.35 | 446.64 | 27.65% |
| 32000 | 1 | 1 | TRUE | 3678.05 | 3426.42 | 6.84% | 2327.42 | 2039.48 | 12.37% | 1387.85 | 832.33 | 40.03% |
| 4000 | 1 | 8 | TRUE | 1801.28 | 1673.41 | 7.10% | 1261.3 | 1025.12 | 18.73% | 1117.65 | 745.11 | 33.33% |
| 8000 | 1 | 8 | TRUE | 3262.38 | 2952.3 | 9.50% | 2344.01 | 1880.82 | 19.76% | 2381.43 | 1314.63 | 44.80% |
| 16000 | 1 | 8 | TRUE | 6982.66 | 6343.26 | 9.16% | 4897.66 | 3862.16 | 21.14% | 4157.12 | 2060.17 | 50.44% |
| 32000 | 1 | 8 | TRUE | 16615.58 | 14960.37 | 9.96% | 10797.82 | 8443.65 | 21.80% | 7872.14 | 3896.58 | 50.50% |
| 4000 | 1 | 16 | TRUE | 3181.24 | 2928.33 | 7.95% | 2228.06 | 1775.39 | 20.32% | 2402.1 | 1152.3 | 52.03% |
| 8000 | 1 | 16 | TRUE | 6082.47 | 5437.54 | 10.60% | 4213.28 | 3197.17 | 24.12% | 4381.51 | 2386.19 | 45.54% |
| 16000 | 1 | 16 | TRUE | 12832.2 | 11805.53 | 8.00% | 8489.46 | 6721.34 | 20.83% | 6231.51 | 3555.04 | 42.95% |
| 32000 | 1 | 16 | TRUE | 29728.23 | 28228.75 | 5.04% | 18745.21 | 15293.23 | 18.42% | 13077.52 | 6831.96 | 47.76% |
十二、日志解读:定位 KV 传输路径与命中来源
如需查看详细传输信息,可将环境变量 UC_LOGGER_LEVEL 设为 debug。
PipelineStore(Cache|Posix)日志
Cache Store 任务下发/完成日志:
[UC][D] Cache task({task_id},{operation},{subtask_number},{size}) dispatching. [PID,TID]
[UC][D] Cache task({task_id},{operation},{subtask_number},{size}) finished, cost {time}ms. [PID,TID]
| 字段 | 说明 |
|---|---|
task_id |
Cache Store 任务唯一标识 |
operation |
DUMP:Dump 到 Host(Device → Host);LOAD:从 Host 加载(Host → Device) |
subtask_number |
该操作执行的子任务数 |
size |
传输数据总字节数(跨所有任务) |
time |
任务完成耗时(毫秒) |
Posix Store 任务下发/完成日志:
[UC][D] Posix task({task_id},{operation},{subtask_number},{size}) dispatching. [PID,TID]
[UC][D] Posix task({task_id},{operation},{subtask_number},{size}) finished, cost {time}ms. [PID,TID]
| 字段 | 说明 |
|---|---|
task_id |
Posix Store 任务唯一标识 |
operation |
Cache2Backend:从 Cache Store Dump 数据到 Posix Store;Backend2Cache:从 Posix Store 加载数据回 Cache Store |
subtask_number |
该操作执行的子任务数 |
size |
传输数据总字节数(跨所有任务) |
time |
任务完成耗时(毫秒) |
NFS/Pc Store 日志
[UC][D] Task(<task_id>,<direction>,<task_count>,<size>) finished, costs=<time>s, bw={speed}GB/s
| 字段 | 说明 |
|---|---|
task_id |
任务唯一标识 |
direction |
PC::D2S:Dump 到存储(Device → SSD);PC::S2D:从存储加载(SSD → Device) |
task_count |
该操作执行的任务数 |
size |
传输数据总字节数(跨所有任务) |
time |
完整操作耗时(秒) |
speed |
设备与存储间的任务传输速度 |
Mooncake Store 日志
Dump 路径:
[UC][D] Mooncake task(<task_id>) start running, wait <wait_ms>ms.
[UC][D] Mooncake task(<task_id>) exists check: <missing>/<total> keys missing.
[UC][D] Mooncake task(<task_id>) dump done, cost=<cost_ms>ms.
| 字段 | 说明 |
|---|---|
task_id |
任务唯一标识 |
wait_ms |
任务在队列中等待的时间(毫秒) |
missing |
尚未存在于 Mooncake 池中的 KV 块数(将被写入) |
total |
本 dump 任务的 KV 块总数 |
cost_ms |
dump 操作完成耗时(毫秒) |
Load 路径:
[UC][D] Mooncake task(<task_id>) all hit(<shard_count>), wait=<wait_ms>ms, cost=<cost_ms>ms.
表示所有 KV 块均在 Mooncake 池中命中,无需回退到 Posix 后端。
[UC][D] Mooncake task(<task_id>) dispatch shards(<total>, miss=<miss_count>), wait=<wait_ms>ms, cost=<cost_ms>ms.
表示部分未命中:miss_count 个分片未在 Mooncake 池中找到,已分派到 Posix 后端取回。
| 字段 | 说明 |
|---|---|
task_id |
任务唯一标识 |
shard_count |
load 任务中的 KV 块分片总数 |
total |
load 任务中的 KV 块分片总数 |
miss_count |
未在 Mooncake 中找到、回退到 Posix 后端的分片数 |
wait_ms |
任务在分派前排队等待的时间(毫秒) |
cost_ms |
Mooncake 查找与分派阶段耗时(毫秒) |
Compress Store 日志
压缩 Dump 相关日志:
[UC][D] COMPRESS DUMP START | task_id: xx
[UC][D] COMPRESS DUMP | shard: xx, done, compressed_size: xx
[UC][D] COMPRESS DUMP END | task_id: xx
解压 Load 相关日志:
[UC][D] COMPRESS LOAD START | task_id: xx
[UC][D] COMPRESS LOAD | shard: xx, done, decompressed_size: xx
[UC][D] COMPRESS LOAD END | task_id: xx
压缩模块成功加载的启动标志日志示例:
[UC][I] Using UCM with config: {'ucm_connectors': [{'ucm_connector_name': 'UcmPipelineStore', 'ucm_connector_config': {'store_pipeline': 'Cache|Compress|Posix', 'storage_backends': './kv', 'compress_ratio': 16, 'data_type': 0, 'decompress_thread_num': 48, 'io_direct': True, 'cache_buffer_capacity_gb': 64, 'posix_io_engine': 'aio'}}], 'use_layerwise': True, 'enable_record_traces': False}
十三、Compress Store 的适用场景边界
启用压缩的强制前置条件
以下条件全部满足时压缩功能才能稳定启用:
- 软件栈约束:必须基于集成 vLLM 推理引擎的 UCM 统一缓存管理框架使用,且配置中必须设置
store_pipeline: "Cache|Compress|Posix"启用压缩管道; - 数据类型约束:当前版本仅支持 BF16 格式的 KV cache 张量(对应
data_type: 0),FP16、FP8、INT8、INT4 等其他类型暂不支持; - 压缩比约束:当前版本仅支持 2.0x 无损压缩(对应
compress_ratio: 16),compress_ratio: 32为 1.0x 不压缩模式,其他值暂不支持; - 存储后端约束:必须配合 Posix 兼容的本地文件系统、SSD 或 NFS 挂载存储使用(兼容 UCM 的 Posix IO 引擎,如 aio),不能单独用于纯 HBM 缓存场景;
- 硬件兼容性:已在鲲鹏 920 CPU + Ascend 910B4 NPU 部署环境完成验证适配,同时兼容 x86 CPU + NVIDIA GPU 通用推理环境,需要充足 CPU 核数支撑多线程并行解压。
推荐启用场景
- 超长上下文推理:输入 token ≥ 16K,尤其 32K 超长上下文。磁盘 I/O 是该场景 TTFT 的核心瓶颈,2.0x 压缩可将 I/O 数据量直接减少 50%,全 SSD 命中场景下带来最高 40%+ 的 TTFT 降低,block-wise 模式下最高 50%+。
- 高并发在线服务:并发 ≥ 8,尤其并发 ≥ 16 的高负载场景。高并发下 I/O 请求密集,压缩可显著降低磁盘带宽压力;layer-wise 模式在 16 并发、32K 上下文下 TTFT 最大降低 38.8%,block-wise 模式最高 47.76%。
- 高 SSD 缓存命中率场景:前缀缓存命中率 ≥ 80%(尤其 100% 全命中),典型如 RAG、多轮对话、固定模板推理等场景,频繁复用的前缀 KV cache 压缩后可大幅缩短加载时间,直接转化为 TTFT 优化。
- 存储资源受限场景:GPU/NPU HBM 紧张、需要大量 KV cache 卸载到磁盘的环境。2.0x 压缩可直接减少 50% 磁盘空间占用,同时降低 I/O 开销。
- Layer-wise 缓存长序列场景:
use_layerwise: true且输入长度 ≥ 16K,配合decompress_thread_num调至 40+,可充分发挥多线程解压的并行优势。
不建议启用场景
- 短上下文、低并发场景:输入 token ≤ 8K 且并发 ≤ 2 的轻负载场景,I/O 占比低,解压的 CPU 开销可能超过 I/O 减少带来的收益(实测部分场景 TTFT 为负优化);
- 低 SSD 命中率场景:SSD 命中率 < 50% 时,大部分 KV cache 需重新计算生成,压缩无法发挥作用,额外的压缩计算开销反而带来无意义损耗;
- CPU 算力/核数受限环境:多线程解压会抢占推理服务的 CPU 资源,导致推理调度时延上升、端到端性能下降;
- 内存带宽受限环境:压缩/解压过程中的内存拷贝会加剧内存带宽瓶颈;
- 非 BF16 精度推理场景:FP16、INT8、FP8 等精度暂不支持压缩,无法启用该功能;
- 纯 HBM 缓存场景:KV cache 完全存放于 HBM/DRAM、无需磁盘卸载的场景,启用压缩无收益且增加不必要计算开销。
十四、小结
UCM 的 Prefix Cache 以“简单性”与“解耦”为设计原则,选择集中式外部存储架构,通过 PipelineStore 将 Cache Store 与多种后端(Posix、NFS、Ds3fs、Mooncake、Compress)链式组合,形成覆盖 HBM → DRAM → SSD → 分布式存储的多级缓存层级。本文涉及的配置示例与启动命令可直接参考 examples/ucm_config_example.yaml、examples/ucm_mooncake_config.yaml,管道注册与底层实现可查阅 ucm/store/pipeline/connector.py 与 ucm/store/factory_v1.py,端到端命中统计与日志位于 ucm/integration/vllm/ucm_connector.py,相关 e2e 测试可参考 ucm/store/test/e2e 下的 cache_on_posix_hit_test.py、mooncake_on_posix_test.py、ds3fs_test.py 等用例。按本文流程配置并运行 vllm bench 两次,即可直观验证前缀缓存带来的 TTFT 数量级提升。
