解决 LLM 算力浪费，一套统一 KV 管理层实现缓存复用

大模型推理服务中，KV Cache 的重复计算正在成为不可忽视的成本瓶颈。Agent 工作流反复检索相同上下文、多轮对话不断重放历史轮次、多模态应用反复处理同一批视觉特征------这些场景下，如果每次都要重新计算 KV Cache，算力浪费惊人。

本文拆解一个面向 LLM 推理的 KV Cache 统一管理方案，它不做模型推理本身，而是站在推理引擎和存储之间，做一层"缓存管理层"：管缓存的复用、放置和移动，让兼容的请求和推理实例可以共享已有计算结果。

一、项目释义：为什么需要 KV Cache 统一管理？

1.1 推理引擎的"缓存孤岛"问题

当前主流的 LLM 推理引擎（如 vLLM、SGLang 等）各自维护自己的 KV Cache。缓存的生命周期绑定在单个推理进程内：进程死了，缓存就没了；换一个引擎，缓存就用不了。

这在实际业务中会引发一系列问题：

• 多轮对话场景：用户每一轮对话都需要把历史轮次的 KV Cache 重新计算一遍，因为不同请求可能落在不同的推理实例上
• Agent 工作流：一个 Agent 任务可能调用多个子任务，每个子任务都要重复处理相同的系统提示词和工具描述
• 多模态应用：同一张图片的视觉特征被多个推理请求复用，但每个请求都要重新走一遍视觉编码器
• 推理引擎迁移：从 vLLM 迁移到 SGLang 时，已有的缓存全部作废

1.2 统一缓存管理层的定位

该方案的核心定位是：在推理引擎和存储之间插入一层统一的 KV Cache 管理层。它不替代推理引擎，而是作为推理引擎的"外挂缓存层"工作：

+--------------------------------------------------+
|  应用层：Agent 工作流 / 多轮对话 / 多模态应用     |
+------------------+-------------------------------+
                   |
                   v
+------------------+-------------------------------+
|  推理引擎层：vLLM / SGLang / MindIE (可插拔)     |
+------------------+-------------------------------+
                   |
                   v
+------------------+-------------------------------+
|  UCM 统一缓存管理层                              |
|  - 缓存生命周期管理 (创建/命中/淘汰/迁移)          |
|  - 缓存放置策略 (HBM / DRAM / SSD)               |
|  - Prefill/Decode 传输                           |
+------------------+-------------------------------+
                   |
                   v
+------------------+-------------------------------+
|  全局 KV Store (可插拔后端)                        |
|  - DRAM Store / POSIX / NFS / 对象存储 / ...      |
+--------------------------------------------------+

这一层做三件事：

1. 缓存复用：判断新请求能否命中已有缓存，避免重复计算
2. 缓存放置：根据访问热度和硬件特性，决定 KV Cache 放在 HBM、DRAM 还是 SSD
3. 缓存移动：在 Prefill 和 Decode 阶段之间、在不同推理实例之间迁移缓存

1.3 设计哲学：可插拔优于硬编码

该项目最核心的设计哲学是可插拔。它定义了三个层面的抽象接口：

• 引擎适配器：推理引擎可以独立演进，新增引擎只需实现适配接口
• 缓存机制：缓存策略（如过期策略、淘汰算法）可以热切换
• 存储后端：底层存储可以独立演进，新增存储类型不影响上层逻辑

这种设计使得团队可以"按需组装"：生产环境用 NFS 做持久化存储，开发环境用内存做快速验证，研究场景用自定义后端做实验。

二、行业技术知识点

2.1 KV Cache 复用原理

Transformer 的注意力计算中，Key 和 Value 矩阵一旦算出就不会再变（自回归生成时只追加不修改）。这意味着：

• 同一个 prompt 被多次请求时，KV Cache 可以完全复用
• 多轮对话中，历史轮次的 KV Cache 可以跨请求复用
• 共享前缀（如系统提示词）可以被多个不同对话复用

UCM 的核心价值就是把这种"理论上可以复用"变成"工程上确实复用"。它通过全局缓存目录和语义哈希，让不同推理引擎、不同请求能够找到并复用已有的 KV Cache。

2.2 缓存放置策略：三级存储层次

大模型的 KV Cache 体积庞大。以 7B 模型、上下文 32K 为例，FP16 精度下单序列的 KV Cache 约需数百 MB。当并发请求增多时，HBM（GPU 高带宽内存）远远不够。

UCM 实现了三级存储层次：

存储层级	位置	访问延迟	适用场景
L1 - HBM	GPU 显存	~100ns	热数据，当前活跃请求
L2 - DRAM	主机内存	~100ns	温数据，近期可能访问
L3 - SSD/NFS	持久化存储	~100us	冷数据，历史对话归档

放置策略的核心挑战在于何时搬、搬什么、往哪搬。UCM 通过可插拔的缓存管理器实现 LRU/LFU 等淘汰策略，并根据访问频率自动在三级存储间迁移。

2.3 Prefill/Decode 传输（PD Transfer）

在 LLM 推理中，Prefill 阶段一次性处理整个 prompt，Decode 阶段逐个生成 token。这两个阶段的计算模式和内存访问模式差异很大：

• Prefill：计算密集，可以并行处理所有 token
• Decode：内存带宽受限，每次只生成一个 token

UCM 的 PD 传输模块负责在 Prefill 完成后，将计算好的 KV Cache 高效传输到 Decode 阶段使用的推理引擎中。它实现了一个轻量级代理服务器，通过 P2P 传输避免经过 CPU 中转，减少延迟。

2.4 可插拔存储后端

UCM 的存储层（store）是其最丰富的模块，实现了多种后端：

• posix：基于本地 POSIX 文件系统的存储，简单可靠
• nfsstore：基于 NFS 网络文件系统的分布式存储
• ds3fs：兼容 S3 协议的对象存储适配
• dram：纯内存存储，用于测试和开发
• cache：带缓存层次的存储，内部维护 DRAM 热缓存
• compress：带压缩功能的存储，以空间换时间
• pipeline：管道式存储，支持异步写入
• mooncakestore：特定硬件加速存储
• yuanrongstore：特定厂商存储适配
• asu：另一种持久化存储方案
• pcstore：持久化内存存储
• delegator：委托模式存储，用于组合多个后端

所有后端都实现统一的 C++ 接口（ucmstore.h）和 Python 接口（ucmstore.py），通过工厂模式（factory.py）按需创建。

2.5 稀疏注意力与 KV Cache 协同

UCM 还包含了稀疏注意力（sparse）模块。传统注意力复杂度随序列长度呈二次增长，而稀疏注意力通过只计算重要的 token 对来降低复杂度。UCM 的稀疏注意力模块与 KV Cache 管理层协同工作：

• 稀疏计算产生的 KV 值仍然写入统一缓存
• 缓存管理器感知稀疏结构，避免存储和传输被裁剪掉的 token 的 KV
• 可插拔的检索策略支持基于内容的 KV Cache 预取

---

三、架构设计思路

3.1 整体架构

UCM 的逻辑架构分为三层：

+---------------------------------------------------------------+
|  应用与推理引擎层                                              |
|  - vLLM 适配器    - SGLang 适配器    - MindIE 适配器           |
|  - Agent 工作流    - 多轮对话服务     - 多模态应用              |
+--------------------------+------------------------------------+
                           |
                           v
+---------------------------------------------------------------+
|  统一缓存生命周期管理层                                         |
|  - 缓存创建/查找/更新/淘汰                                     |
|  - Prefill/Decode 传输调度                                     |
|  - 稀疏注意力管理                                              |
|  - 可观测性 (指标/日志/追踪)                                   |
+--------------------------+------------------------------------+
                           |
                           v
+---------------------------------------------------------------+
|  全局 KV Store (可插拔后端)                                    |
|  - C++ 存储接口 (ucmstore.h)                                   |
|  - Python 存储接口 (ucmstore.py)                               |
|  - DRAM / POSIX / NFS / S3 / 压缩 / 管道 / ...                |
|  - 存储工厂 (factory.py / factory_v1.py)                       |
+---------------------------------------------------------------+

3.2 目录结构全景

project/
├── benchmarks/                 # 性能基准测试
├── charts/                     # Helm Charts (K8s 部署)
├── docker/                     # Docker 镜像配置
├── docs/                       # 文档 (ReadTheDocs)
├── examples/                   # 使用示例
├── kv_semantics/               # KV 语义定义
├── scripts/                    # 运维脚本
├── test/                       # 测试套件
├── toolkit/                    # 开发工具集
├── ucm/                        # 核心源码
│   ├── CMakeLists.txt          # C++ 构建配置
│   ├── __init__.py             # Python 包入口
│   ├── default_metrics_config.py # 默认指标配置
│   ├── logger.py               # 日志模块
│   ├── metrics_config.py       # 指标配置
│   ├── metrics_dispatcher.py   # 指标分发器
│   ├── observability.py        # 可观测性
│   ├── utils.py                # 工具函数
│   ├── integration/            # 推理引擎适配层
│   │   ├── mindie/             # 华为昇腾 MindIE
│   │   ├── sglang/             # SGLang
│   │   └── vllm/               # vLLM
│   ├── pd/                     # Prefill/Decode 传输
│   │   └── toy_proxy_server.py # 代理服务器
│   ├── sandbox/                # 沙箱环境
│   ├── shared/                 # 共享组件
│   ├── sparse/                 # 稀疏注意力
│   ├── store/                  # 存储后端 (核心)
│   │   ├── asu/                # ASU 存储
│   │   ├── cache/              # 缓存存储
│   │   ├── compress/           # 压缩存储
│   │   ├── delegator/          # 委托存储
│   │   ├── detail/             # 内部实现
│   │   ├── dram/               # DRAM 存储
│   │   ├── ds3fs/              # S3 兼容存储
│   │   ├── empty/              # 空存储 (测试)
│   │   ├── factory.py          # 存储工厂
│   │   ├── factory_v1.py       # V1 工厂
│   │   ├── fake/               # 模拟存储 (测试)
│   │   ├── mooncakestore/      # Mooncake 存储
│   │   ├── nfsstore/           # NFS 存储
│   │   ├── pcstore/            # 持久化内存
│   │   ├── pipeline/           # 管道存储
│   │   ├── posix/              # POSIX 文件存储
│   │   ├── test/               # 存储测试
│   │   ├── ucmstore.h          # C++ 接口头文件
│   │   ├── ucmstore.py         # Python 接口
│   │   ├── ucmstore_v1.h       # C++ V1 接口
│   │   ├── ucmstore_v1.py      # Python V1 接口
│   │   └── yuanrongstore/      # 元融存储
│   ├── transport/              # 传输层
│   │   └── p2p/                # P2P 传输
│   └── v2/                     # v2 API
├── CMakeLists.txt              # 根构建配置
├── pyproject.toml              # Python 项目配置
├── setup.py                    # Python 安装脚本
├── install.sh                  # 一键安装
├── format.sh                   # 代码格式化
├── requirements.txt            # 运行时依赖
├── requirements-build.txt      # 构建依赖
├── requirements-lint.txt       # Lint 依赖

If you need the complete source code, please add the WeChat number (c17865354792)

3.3 构建系统：CMake + Python 混合

该项目采用 CMake 管理 C++ 核心库，同时通过 setup.py 和 pyproject.toml 发布 Python 包。这种混合构建方式的好处是：

• C++ 层负责高性能存储和传输
• Python 层负责 API 暴露和引擎集成
• 两者通过 pybind11 或 ctypes 绑定

根目录的 CMakeLists.txt 负责总控，ucm/CMakeLists.txt 负责 C++ 子库的编译。Python 包通过 setup.py 的 CMakeBuild 扩展实现编译时自动调用 CMake。

四、全套代码实现原理

4.1 Python 入口：包初始化

ucm/init.py 是 Python 包的入口，负责暴露核心 API 和初始化全局配置。典型结构如下：

# ucm/__init__.py
'''Unified Cache Manager - Persist and reuse KV Cache to speedup your LLM.'''

from ucm.store.ucmstore import KVCacheStore
from ucm.store.factory import create_store
from ucm.metrics_config import MetricsConfig
from ucm.observability import setup_observability
from ucm.logger import get_logger

__version__ = '0.1.0'
__all__ = [
    'KVCacheStore',
    'create_store',
    'MetricsConfig',
    'setup_observability',
    'get_logger',
]

这个入口文件做了四件事：

1. 导出核心存储接口 KVCacheStore
2. 导出存储工厂函数 create_store
3. 导出指标配置和可观测性工具
4. 导出日志工具

4.2 存储工厂模式

ucm/store/factory.py 实现了存储后端的工厂模式，根据配置字符串动态创建对应的存储实例：

# ucm/store/factory.py
'''Store factory - create store instances based on configuration.'''

from ucm.store.posix import PosixStore
from ucm.store.dram import DramStore
from ucm.store.nfsstore import NFSStore
from ucm.store.cache import CachedStore
from ucm.store.compress import CompressedStore
from ucm.store.pipeline import PipelineStore
from ucm.store.empty import EmptyStore
from ucm.store.fake import FakeStore

# 存储类型注册表
_STORE_REGISTRY = {
    'posix': PosixStore,
    'dram': DramStore,
    'nfs': NFSStore,
    'cache': CachedStore,
    'compress': CompressedStore,
    'pipeline': PipelineStore,
    'empty': EmptyStore,
    'fake': FakeStore,
}


def create_store(store_type, **kwargs):
    '''Create a store instance by type name.
    
    Args:
        store_type: Store type identifier (e.g., posix, nfs, dram)
        **kwargs: Backend-specific configuration parameters
    
    Returns:
        Store instance
    
    Raises:
        ValueError: If store_type is not registered
    '''
    store_cls = _STORE_REGISTRY.get(store_type)
    if store_cls is None:
        available = ', '.join(_STORE_REGISTRY.keys())
        raise ValueError(
            f"Unknown store type: '{store_type}'. "
            f"Available types: {available}"
        )
    return store_cls(**kwargs)


def list_available_stores():
    '''List all available store types.'''
    return list(_STORE_REGISTRY.keys())

工厂模式的核心优势在于开闭原则：新增存储后端只需两步：

1. 在 store/ 目录下新建子目录实现新存储
2. 在 factory.py 的 _STORE_REGISTRY 中注册

不需要修改任何现有代码。

4.3 C++ 存储接口抽象

ucm/store/ucmstore.h 定义了 C++ 层的存储抽象接口：

// ucm/store/ucmstore.h
// Core storage interface for KV Cache persistence

#pragma once

#include <string>
#include <vector>
#include <cstdint>
#include <memory>

namespace ucm {

// KV Cache block metadata
struct CacheBlockMeta {
    uint64_t block_id;
    uint64_t sequence_id;
    uint64_t timestamp;
    size_t data_size;
    std::string checksum;
};

// Abstract storage interface
class KVStore {
public:
    virtual ~KVStore() = default;

    // Write KV cache block
    virtual Status Write(const CacheBlockMeta& meta, 
                         const uint8_t* data, 
                         size_t size) = 0;

    // Read KV cache block
    virtual Status Read(const CacheBlockMeta& meta,
                        uint8_t* buffer, 
                        size_t buffer_size) = 0;

    // Delete KV cache block
    virtual Status Delete(const CacheBlockMeta& meta) = 0;

    // Check if block exists
    virtual bool Exists(const CacheBlockMeta& meta) = 0;

    // Get store statistics
    virtual StoreStats GetStats() = 0;

    // Initialize/cleanup
    virtual Status Init(const std::string& config) = 0;
    virtual void Shutdown() = 0;
};

// Factory function
using KVStoreFactory = std::function<std::unique_ptr<KVStore>()>;

void RegisterStoreFactory(const std::string& type, KVStoreFactory factory);
std::unique_ptr<KVStore> CreateKVStore(const std::string& type, 
                                        const std::string& config);

} // namespace ucm

这个接口定义了存储后端必须实现的五个核心方法：Write、Read、Delete、Exists、GetStats，以及初始化和关闭生命周期方法。所有具体存储实现（POSIX、NFS、DRAM 等）都继承这个抽象类。

4.4 Python 存储接口封装

ucm/store/ucmstore.py 在 C++ 接口之上提供了 Pythonic 的封装：

# ucm/store/ucmstore.py
'''Python interface for KV Cache store.'''

import os
import hashlib
from typing import Optional, Dict, Any
from dataclasses import dataclass, field


@dataclass
class CacheBlockMeta:
    '''KV Cache block metadata.'''
    block_id: str
    sequence_id: str
    timestamp: float
    data_size: int
    checksum: str = ''

    def compute_checksum(self, data):
        '''Compute SHA-256 checksum for data integrity.'''
        return hashlib.sha256(data).hexdigest()


class KVCacheStore:
    '''High-level KV Cache store interface.'''

    def __init__(self, backend, config=None):
        self._backend = backend
        self._config = config or {}
        self._store = self._create_backend()
        self._metrics = self._init_metrics()

    def _create_backend(self):
        '''Create backend store instance via factory.'''
        from ucm.store.factory import create_store
        return create_store(self._backend, **self._config)

    def _init_metrics(self):
        '''Initialize metrics collection.'''
        from ucm.metrics_dispatcher import MetricsDispatcher
        return MetricsDispatcher('kv_cache_store', {
            'backend': self._backend,
            **self._config
        })

    def put(self, key, value, meta=None):
        '''Store a KV cache block.'''
        start_time = self._metrics.start_timer('put_latency')
        try:
            if meta is None:
                meta = CacheBlockMeta(
                    block_id=key,
                    sequence_id='',
                    timestamp=__import__('time').time(),
                    data_size=len(value)
                )
            result = self._store.write(meta, value)
            self._metrics.increment('put_success')
            return result
        except Exception as e:
            self._metrics.increment('put_error')
            raise e
        finally:
            start_time.stop()

    def get(self, key):
        '''Retrieve a KV cache block.'''
        start_time = self._metrics.start_timer('get_latency')
        try:
            result = self._store.read(key)
            if result is not None:
                self._metrics.increment('get_hit')
            else:
                self._metrics.increment('get_miss')
            return result
        finally:
            start_time.stop()

    def delete(self, key):
        '''Delete a KV cache block.'''
        return self._store.delete(key)

    def exists(self, key):
        '''Check if a KV cache block exists.'''
        return self._store.exists(key)

    def get_stats(self):
        '''Get store statistics.'''
        return {
            'backend': self._backend,
            'store': self._store.get_stats(),
            'metrics': self._metrics.get_snapshot()
        }

这个封装层做了三件有价值的事：

1. 统一接口：无论底层是 POSIX 文件还是 NFS，上层调用方式一致
2. 指标收集：自动记录 put/get 的延迟和命中率
3. 元数据管理：自动计算 checksum 保证数据完整性

4.5 引擎适配器设计

ucm/integration/ 目录下分别实现了 vLLM、SGLang、MindIE 的适配器。以 vLLM 适配器为例，其核心思路是钩子注入：

# ucm/integration/vllm/adapter.py (概念性代码)
'''vLLM adapter - integrate UCM with vLLM inference engine.'''

import asyncio
from typing import Optional


class KVCacheAdapter:
    '''Adapter that hooks into vLLM KV Cache lifecycle.'''

    def __init__(self, store_config):
        from ucm.store.factory import create_store
        self._store = create_store('cache', **store_config)
        self._cache_index = {}  # local index for fast lookup

    def on_prefill_complete(self, request_id, kv_caches):
        '''Called when prefill phase completes.
        
        Persist the computed KV caches to the global store.
        '''
        cache_key = self._compute_cache_key(request_id)
        for layer_idx, cache in enumerate(kv_caches):
            block_meta = CacheBlockMeta(
                block_id=f'{cache_key}/layer_{layer_idx}',
                sequence_id=request_id,
                timestamp=__import__('time').time(),
                data_size=cache.numel() * cache.element_size()
            )
            self._store.put(
                block_meta.block_id,
                cache.cpu().numpy().tobytes(),
                block_meta
            )

    def on_decode_request(self, request_id, prompt_len):
        '''Called when a new decode request arrives.
        
        Try to load KV caches from global store.
        Returns cached KV caches if hit, None otherwise.
        '''
        cache_key = self._compute_cache_key(request_id)
        cached = []
        for layer_idx in range(self._num_layers):
            block_id = f'{cache_key}/layer_{layer_idx}'
            data = self._store.get(block_id)
            if data is not None:
                cache_tensor = self._reconstruct_tensor(data)
                cached.append(cache_tensor)
            else:
                return None  # Cache miss, need to compute
        return cached

    def _compute_cache_key(self, request_id):
        '''Compute a deterministic cache key from request content.'''
        return request_id

适配器的设计精髓在于最小侵入：它不修改推理引擎的核心代码，而是通过回调钩子函数在关键生命周期节点（prefill 完成、decode 开始）插入缓存存取逻辑。

4.6 PD 传输代理

ucm/pd/toy_proxy_server.py 实现了一个轻量级的 Prefill/Decode 传输代理服务器：

# ucm/pd/toy_proxy_server.py (概念性代码)
'''Toy proxy server for Prefill/Decode KV cache transfer.'''

import asyncio
import json
from http.server import HTTPServer, BaseHTTPRequestHandler
from typing import Dict, Any


class PDTransferHandler(BaseHTTPRequestHandler):
    '''HTTP handler for PD transfer operations.'''

    def do_POST(self):
        if self.path == '/transfer':
            content_length = int(self.headers['Content-Length'])
            payload = json.loads(self.rfile.read(content_length))
            
            request_id = payload['request_id']
            cache_data = payload['cache_data']
            target_engine = payload['target_engine']
            
            self._store_cache(request_id, cache_data)
            result = self._forward_to_engine(target_engine, request_id)
            self._send_response(200, result)
        elif self.path == '/health':
            self._send_response(200, {'status': 'ok'})

    def _store_cache(self, request_id, cache_data):
        '''Store prefilled KV cache to global store.'''
        from ucm.store.factory import create_store
        store = create_store('cache', backend='dram')
        for layer_key, layer_data in cache_data.items():
            store.put(f'{request_id}/{layer_key}', layer_data)

    def _forward_to_engine(self, engine_url, request_id):
        '''Forward cache lookup to target inference engine.'''
        return {'status': 'forwarded', 'request_id': request_id}

    def _send_response(self, status, body):
        self.send_response(status)
        self.send_header('Content-Type', 'application/json')
        self.end_headers()
        self.wfile.write(json.dumps(body).encode())


def run_server(host='0.0.0.0', port=8080):
    server = HTTPServer((host, port), PDTransferHandler)
    print(f'PD Transfer proxy listening on {host}:{port}')
    server.serve_forever()

这个代理服务器的作用是解耦 Prefill 引擎和 Decode 引擎：Prefill 端把计算好的 KV Cache 发送到代理，Decode 端从代理获取。这样两个阶段可以部署在不同的机器上，通过 P2P 传输层高效传输大体积的张量数据。

4.7 可观测性系统

ucm/observability.py 和 ucm/metrics_dispatcher.py 实现了完整的可观测性基础设施：

# ucm/metrics_dispatcher.py
'''Metrics dispatcher - collect and export runtime metrics.'''

import time
import threading
from typing import Dict, Any, Optional
from collections import defaultdict


class MetricsDispatcher:
    '''Dispatches metrics to multiple backends.'''

    def __init__(self, prefix, tags=None):
        self._prefix = prefix
        self._tags = tags or {}
        self._counters = defaultdict(int)
        self._timers = defaultdict(list)
        self._lock = threading.Lock()

    def increment(self, metric_name, amount=1):
        '''Increment a counter metric.'''
        with self._lock:
            full_name = f'{self._prefix}.{metric_name}'
            self._counters[full_name] += amount

    def start_timer(self, metric_name):
        '''Start a timer metric.'''
        return Timer(f'{self._prefix}.{metric_name}', self._timers)

    def get_snapshot(self):
        '''Get current metrics snapshot.'''
        with self._lock:
            return {
                'prefix': self._prefix,
                'tags': self._tags,
                'counters': dict(self._counters),
                'timers': {k: self._compute_stats(v) for k, v in self._timers.items()}
            }

    def _compute_stats(self, values):
        if not values:
            return {'count': 0}
        return {
            'count': len(values),
            'min': min(values),
            'max': max(values),
            'avg': sum(values) / len(values),
            'p50': sorted(values)[len(values) // 2],
            'p99': sorted(values)[int(len(values) * 0.99)],
        }


class Timer:
    '''Context manager for timing operations.'''

    def __init__(self, name, timers_dict):
        self._name = name
        self._timers_dict = timers_dict
        self._start_time = None

    def __enter__(self):
        self._start_time = time.perf_counter()
        return self

    def stop(self):
        if self._start_time is not None:
            elapsed = (time.perf_counter() - self._start_time) * 1000
            self._timers_dict[self._name].append(elapsed)
            self._start_time = None

可观测性系统让运维人员可以实时监控：

• 缓存命中率（get_hit / get_miss 比率）
• 存储读写延迟（put_latency / get_latency）
• 存储用量和吞吐
• 各后端的健康状态

4.8 存储后端实现示例：POSIX 存储

ucm/store/posix/ 目录下实现了基于本地文件系统的存储后端：

# ucm/store/posix/__init__.py (概念性代码)
'''POSIX filesystem store implementation.'''

import os
import shutil
from typing import Optional
from ..ucmstore import BaseStore, CacheBlockMeta


class PosixStore(BaseStore):
    '''KV Cache store backed by POSIX filesystem.'''

    def __init__(self, root_path, create_dir=True):
        self._root = root_path
        if create_dir:
            os.makedirs(self._root, exist_ok=True)
        super().__init__(backend='posix')

    def write(self, meta, data):
        '''Write data to a file under root_path/block_id.'''
        file_path = os.path.join(self._root, meta.block_id)
        os.makedirs(os.path.dirname(file_path), exist_ok=True)
        
        with open(file_path, 'wb') as f:
            f.write(data)
        
        meta_path = file_path + '.meta'
        import json
        with open(meta_path, 'w') as f:
            json.dump({
                'sequence_id': meta.sequence_id,
                'timestamp': meta.timestamp,
                'data_size': meta.data_size,
            }, f)
        
        self._increment_write()
        return True

    def read(self, block_id):
        '''Read data from file.'''
        file_path = os.path.join(self._root, block_id)
        if not os.path.exists(file_path):
            return None
        
        with open(file_path, 'rb') as f:
            data = f.read()
        
        self._increment_read()
        return data

    def delete(self, block_id):
        '''Delete a cache block.'''
        file_path = os.path.join(self._root, block_id)
        meta_path = file_path + '.meta'
        
        removed = False
        if os.path.exists(file_path):
            os.remove(file_path)
            removed = True
        if os.path.exists(meta_path):
            os.remove(meta_path)
            removed = True
        
        return removed

    def exists(self, block_id):
        '''Check if a cache block exists.'''
        return os.path.exists(os.path.join(self._root, block_id))

    def get_stats(self):
        '''Get filesystem stats.'''
        total, used, free = shutil.disk_usage(self._root)
        return {
            'type': 'posix',
            'root': self._root,
            'total_bytes': total,
            'used_bytes': used,
            'free_bytes': free,
        }

POSIX 存储是最基础的实现，它把每个 KV Cache block 存储为一个文件，附带一个 .meta 元数据文件。虽然简单，但在 SSD 上表现不错，而且天然支持跨进程共享（多个推理实例挂载同一目录即可共享缓存）。

五、环境配置与运行测试教程

5.1 基础依赖

运行该项目需要以下环境：

依赖项	版本要求	说明
CMake	3.20+	C++ 构建系统
GCC	8+	C++17 编译器
Python	3.8+	Python 绑定和工具
PyTorch	2.0+	张量操作（测试用）
CUDA	11.8+	GPU 加速（可选）
Ninja	最新	快速构建

5.2 源码编译安装

cd unified-cache

# 2. 编译 C++ 核心库
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

# 3. 安装 Python 包
cd ..
pip install -e .

# 或使用一键安装脚本
./install.sh

5.3 Docker 快速体验

# 拉取预构建镜像
docker pull <registry>/ucm:latest

# 运行交互式容器
docker run -it <registry>/ucm:latest /bin/bash

# 进入容器后验证安装
python3 -c "import ucm; print(ucm.__version__)"

5.4 配置存储后端

使用 YAML 配置文件指定存储后端：

# ucm_config.yaml
store:
  type: cache
  backend:
    disk:
      type: posix
      root_path: /data/kvcache
    memory:
      type: dram
      max_size_mb: 4096

metrics:
  enabled: true
  port: 9090
  endpoint: /metrics

pd_transfer:
  enabled: true
  proxy_port: 8080

5.5 与推理引擎集成

在推理引擎启动脚本中注入 UCM 适配器：

# run_with_ucm.py
import os
os.environ['UCM_CONFIG'] = '/path/to/ucm_config.yaml'

# 注入适配器
from ucm.integration.vllm import KVCacheAdapter
adapter = KVCacheAdapter({
    'store_type': 'cache',
    'disk_path': '/data/kvcache',
    'memory_mb': 4096,
})

# 启动推理服务（适配器钩子会自动注入）
# ... 引擎启动代码 ...

5.6 运行测试

# 运行 Python 测试
python3 -m pytest test/ -v

# 运行存储后端测试
python3 -m pytest test/store/ -v

# 运行 C++ 测试（需编译）
cd build
make test
ctest --output-on-failure

# 运行性能基准测试
python3 benchmarks/kv_cache_benchmark.py --store-type cache --num-requests 1000

5.7 验证缓存命中

# verify_cache_hit.py
from ucm import create_store
from ucm.store.factory import list_available_stores

# 列出可用存储后端
print('Available stores:', list_available_stores())

# 创建存储实例
store = create_store('cache', disk_path='/tmp/kvcache_test', memory_mb=512)

# 写入测试数据
test_data = b'hello kv cache'
store.put('test-key-1', test_data)

# 读取验证
result = store.get('test-key-1')
assert result == test_data, 'Cache read failed'
print('Cache hit: OK')

# 检查不存在的 key
miss = store.get('non-existent-key')
assert miss is None, 'Cache should miss for non-existent key'
print('Cache miss: OK')

# 查看指标
stats = store.get_stats()
print('Store stats:', stats)

5.8 常见问题排查

问题	可能原因	解决方案
CMake 编译失败	缺少 C++17 支持	升级 GCC 到 8+
Python 导入报错	C++ 库未编译	先运行 cmake + make
缓存写入失败	磁盘空间不足	检查磁盘空间
NFS 存储超时	网络延迟高	调整超时参数或使用本地缓存
内存占用过高	缓存未设置上限	配置 memory.max_size_mb
指标不输出	metrics.enabled 未开启	检查配置文件

---

六、落地用途

6.1 大模型推理服务加速

在生产环境中，大量请求会重复处理相同的系统提示词、工具描述或知识库内容。通过 UCM 全局缓存层，这些公共部分的 KV Cache 只需计算一次，后续请求直接命中，首 Token 延迟可显著降低。

6.2 多轮对话系统

客服、聊天机器人等场景下，每轮对话都需要携带完整的历史上下文。UCM 可以将历史轮次的 KV Cache 持久化存储，新请求到来时直接加载，避免重复计算整个对话历史。

6.3 Agent 工作流

Agent 框架中，一个任务可能拆解为多个子步骤，每个步骤都要读取相同的工具描述和上下文。UCM 让 Agent 的不同步骤共享 KV Cache，减少重复推理开销。

6.4 长上下文处理

对于文档摘要、代码分析等长上下文场景，KV Cache 体积巨大。UCM 的三级存储层次（HBM、DRAM、SSD）和可插拔存储后端让超大上下文也能高效管理，不会因显存不足而崩溃。

6.5 跨引擎缓存共享

团队可能同时使用 vLLM 和 SGLang 部署不同模型。UCM 的统一接口让两个引擎共享同一份缓存，避免各自维护一份导致存储浪费和缓存不一致。

---

七、总结

UCM 的核心价值在于把 KV Cache 从推理引擎的私有财产变成可共享的基础设施。它不做推理计算，而是专注于缓存的生命周期管理：什么时候创建、在哪里存放、何时淘汰、如何在不同组件间迁移。

该项目的可插拔设计哲学贯穿始终：

• 引擎侧：新增推理引擎只需实现适配器接口，不影响现有代码
• 存储侧：新增存储后端只需实现统一接口，通过工厂注册即可使用
• 策略侧：缓存淘汰策略、放置策略均可热切换，适应不同场景

未来，随着多模态大模型和 Agent 工作的普及，KV Cache 的管理将变得更加重要。该项目的方向也清晰可见：

• 更智能的缓存放置策略（基于 ML 的访问预测）
• 更高效的跨节点缓存传输（RDMA、P2P 优化）
• 更丰富的存储后端（GPU Direct Storage、CXL 内存扩展）
• 与稀疏注意力、量化等推理优化技术的深度协同

如果你正在搭建大模型推理服务，尤其是面临多轮对话、Agent 工作流或长上下文等场景，值得了解一下 KV Cache 统一管理这个思路。有时候，性能优化的关键不在于算得更快，而在于少算。