大模型人工智能缓存【免费下载链接】unified-cache-managementUnified Cache Manager推理记忆数据管理器是一款以KV Cache为中心的推理加速套件其融合了多类型缓存加速算法工具分级管理并持久化推理过程中产生的KV Cache记忆数据扩大推理上下文窗口以实现高吞吐、低时延的推理体验降低每Token推理成本。项目地址https://gitcode.com/ModelEngine/unified-cache-management点击查看免费下载NFS Store 是 Unified Cache ManagerUCM中基于已有文件系统路径保存 KV 块的前缀缓存 Connector路径既可以是本地磁盘也可以是 NFS 挂载。本文以 vLLM 的 V1 NFS Connector 配置为主线完整介绍存储路径选择、YAML 配置、服务启动与请求负载、持久化复用验证以及常见故障排查方法并结合仓库源码说明 Connector 的实际实现与参数底层影响。读完本文你将能够独立完成一套可跨主机共享、可复现的 NFS 前缀缓存部署。关联文档NFS Storeen对应 中文版更早期的用法示例与性能测试记录见 docs/source/user-guide/prefix-cache/nfs_store.md。NFS Connector 的定位直接文件系统 ConnectorNFS Store 的核心职责是把 KV 块通过已有的文件系统路径持久化下来。这个路径可以位于本地磁盘也可以是 NFS 挂载UCM 本身不负责挂载 NFS也不运行 NFS 服务端因此跨主机共享完全取决于你为每个服务进程提供的挂载与权限。也就是说UCM 只把 NFS 当作一个普通的可写目录来用远端可见性由 NFS 基础设施保证。从功能上看该 Connector 支持完整的前缀缓存操作集dump将 KV Cache 块从 GPU HBM 卸载offload到 SSD / 本地磁盘 / NFSload将 KV 块从存储介质加载回 HBMlookup按块哈希block hash在存储中查找 KV 块是否存在wait等待所有 dump / load 操作完成。在 docs/source/user-guide/prefix-cache/nfs_store.md 记录的早期性能测试中该能力被用于在关闭 HBM 缓存、仅从 SSD 检索匹配 KV 的场景下加速首 token 时延例如 QwQ-32B 与 DeepSeek-V3 模型在多并发下的多组测试数据。需要注意这些数据是历史测试记录不代表当前版本可复现的性能结果只能作为理解该 Connector 用途的背景。选择文件系统路径UcmNfsStore 还是 Cache|Posix当你要沿用这个直接文件系统 Connector 的已有配置时选择UcmNfsStore。而如果是新部署且需要主机缓存host cache、Posix 健康探针以及基于容量的 GC容量驱动垃圾回收则按 Pipeline Store 的说明选择Cache|Posix流水线。关键的一点是两种选择都可以使用 NFS 挂载挂载类型不会决定使用哪套 UCM 实现。NFS 只是一个文件系统视角而 UCM 的实现选择由 Connector 名决定。V1 包装器的张量大小约束V1 NFS 包装器要求tensor_size_list中的张量大小相等。若引擎适配层传入混合大小布局会直接报错PcStore does not support different tensor sizes.该列表由引擎适配层vLLM 集成侧提供修改 YAML 值来掩盖布局不匹配并不会让模型变得兼容。这一约束在源码中有明确对应在 pcstore_connector_v1.py 中UcmPcStoreV1会检查tensor_size_list一旦出现与首元素不同的值就抛出该RuntimeError并通过config[tensor_size] tensor_size_list[0]将统一后的张量大小传给原生 Store。安装与构建前提UcmNfsStore实际是 V1 工厂对UcmPcStoreV1的注册名。在 factory_v1.py 中可以看到映射关系UcmConnectorFactoryV1.register_connector( UcmNfsStore, ucm.store.pcstore.pcstore_connector_v1, UcmPcStoreV1 )ucmpcstore原生扩展由 ucm/store/pcstore/CMakeLists.txt 构建它链接storeintf、trans、infra_logger等库使用 UCM 自己的设备传输实现此 Connector 不需要任何 NFS 专用 Python 包。安装时请从 安装指南 获取匹配的 UCM 制品或在目标引擎/设备环境中按 从源码构建 自行构建。配置 UCM 前缀缓存准备目录为服务用户准备/mnt/ucm-nfs并授予读取、写入、目录遍历和删除权限。对 NFS 部署务必在实际运行推理的同一容器内确认挂载可见且可写再创建缓存文件——挂载是容器视角的脱离容器验证没有意义。最小配置ucm_connectors: - ucm_connector_name: UcmNfsStore ucm_connector_config: storage_backends: /mnt/ucm-nfs io_direct: false说明ucm_connector_name固定为UcmNfsStoreV1 工厂据此实例化UcmPcStoreV1。storage_backendsKV 块的存储目录可以是本地路径或 NFS 挂载路径。在 vLLM 的 YAML 里它是一个路径字符串由适配层转换为 Store 消费的列表源码中UcmNfsStore的旧实现按:分割V1 实现直接把字符串交给原生Config的storageBackends向量。后端设置必须放在ucm_connector_config内。初次验证建议使用一个专用目录确保写入者和读取者使用同一命名空间避免与其他实例的数据混淆。仓库根目录下的 examples/ucm_config_example.yaml 提供了完整的参考配置默认展示的是Cache|Posix流水线用法可作为理解配置结构的起点。可选参数参数V1 默认值作用io_directfalse在挂载和对齐支持时选择直接文件系统 I/O。stream_number8设备传输流数量。buffer_number4096中间传输缓冲数量。timeout_ms30000Store 传输的等待上限单位毫秒。shard_data_dirtrue将缓存文件分散到子目录。这些默认值在原生接口中有精确对应。在 pcstore.h 中PcStore::Config定义了原生默认值transferIoSize262144、transferIoDirectfalse、transferStreamNumber8、transferBufferNumber4096、transferTimeoutMs30000、shardDataDirtrue等Python 侧的 key 映射io_direct → transferIoDirect、stream_number → transferStreamNumber、timeout_ms → transferTimeoutMs、shard_data_dir → shardDataDir等在 pcstore_connector_v1.py 中完成。Setup阶段会将这些参数逐一落到原生传输管理器见 pcstore.cc 中对transMgr_.Setup的调用以及日志输出Set UC::StreamNumber to {}等确认信息。注意buffer_number不是 GiB 上限。内存占用还取决于张量传输大小transferIoSize× 块数调大缓冲数量可能带来远超预期的内存消耗。不属于本包装器的参数cache_buffer_capacity_gb、posix_capacity_gb、store_health用于配置 Pipeline 阶段见 Pipeline Store 文档此包装器不会将这些 key 映射到原生 PcStore 选项把它们写进UcmNfsStore配置不会生效。启动推理按 vLLM 快速开始 或 vLLM-Ascend 快速开始 启动保持引擎侧选择UCMConnector并将UCM_CONFIG_FILE指向这份 YAML。模型、并行配置tensor-parallel-size和块大小block_size都由引擎启动参数决定无需在 Store 配置中重复声明。UCM 场景下建议block_size取 128与 KV 块粒度和传输调度相匹配。启动后确认日志中选中了UcmNfsStore并初始化了ucmpcstore。这一点很关键HTTP 健康检查只能说明模型服务已就绪不能证明任何 KV 块已经写入 NFS。若出现Failed to initialize ucmpcstore说明原生扩展初始化失败详见下文排查表。原始服务启动与请求命令在匹配的引擎环境中将上面的 YAML 保存为/etc/ucm/ucm.yaml然后使用下面的 Qwen2.5-14B-Instruct 启动参数。其中--no-enable-prefix-caching是为原始存储测试保留的选项正常部署、需要同时使用原生前缀缓存时应移除此参数。export ENABLE_UCM_PATCH1 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: /etc/ucm/ucm.yaml} }要点拆解ENABLE_UCM_PATCH1启用 UCM 的 vLLM 集成补丁见 ucm/integration/vllm 下的 patch 目录。--kv-transfer-config以 JSON 方式指定 KV 传输配置kv_connector固定为UCMConnectorkv_role使用kv_both单进程同时承担 dump 与 loadkv_connector_module_path指向 ucm.integration.vllm.ucm_connectorUCM_CONFIG_FILE给出上文的 YAML 路径。--enforce-eager与--no-enable-prefix-caching来自原始存储测试的启动参数前者关闭 CUDA graph后者关闭 vLLM 原生前缀缓存便于隔离观察 UCM 的外部缓存行为。服务就绪后在另一终端运行请求负载以下为工作量输入命令不代表复现了原始性能结果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参数含义--dataset-name random生成随机输入--num-prompts 12共 12 条请求--random-input-len 16000/--random-output-len 2对应 16K 输入、2 token 输出的负载--request-rate inf表示不限速并发压入--percentile-metrics与--metric-percentiles指定采集 TTFT / TPOT / ITL / E2EL 的 90、99 分位--ignore-eos保证输出长度不被 EOS 提前截断。观察缓存命中日志中的关键证据在 vLLM 服务日志中UCM 会打印类似如下的命中统计来源为 ucm_connector.py 中total_blocks_num / hit hbm / hit external的日志拼接INFO ucm_connector.py:228: request_id: xxx, total_blocks_num: 125, hit hbm: 0, hit external: 0第一次推理hit external: 0说明外部存储中没有任何可复用的 KV 块16K token 的 prefill 必须全量计算TTFT 较大第二次运行相同负载hit external: 125全部 125 个 KV 块都命中外部存储TTFT 显著下降。这一对照实验正是早期文档 nfs_store.md 中记录的两轮vllm bench结果约 15.3s → 3.2s约 5× 的 TTFT 改善的验证方式——它只用于说明观测方法不代表当前版本可复现的性能结论。如需查看底层传输细节可将UC_LOGGER_LEVEL设为debug此时会看到原生传输任务完成日志[UC][D] Task(task_id,direction,task_count,size) finished, coststimes, bw{speed}GB/s该日志格式由 trans_task.h 中的Epilog方法生成各字段含义如下字段说明task_id传输任务的唯一标识direction传输方向PC::D2Sdump设备 → 存储或PC::S2Dload存储 → 设备task_count本次操作执行的子任务数量size传输的总数据量字节跨所有子任务time完整操作耗时秒speed设备与存储之间的任务传输带宽验证持久化复用跨主机共享验证的完整流程是使用空的专用目录执行 外部缓存检查对应流程也可参考 verify-cache.md。等待写入完成保留文件。重启服务进程重放完全相同的提示词与模型几何配置模型、tensor-parallel-size、block_size、dtype、tokenizer 版本均须一致。验证结果必须同时满足外部缓存命中external hits加载完成completed loads。若要验证跨主机共享在第二台主机上用相同模型与配置重复重放并确保两台主机能访问同一 NFS 挂载。故障排查对照表现象下一步检查Failed to initialize ucmpcstore原生扩展/设备依赖ucmpcstore是否按目标环境构建、路径权限、实际生效的配置。只有一台主机上出现文件实际容器挂载和后端 export 配置相同的路径字符串可能指向不同的文件系统例如容器内外路径映射不一致。PcStore does not support different tensor sizes.引擎的 KV 张量布局tensor_size_list与所选 Connector修改 YAML 掩盖不了布局不匹配。文件存在但没有外部命中Tokenize 后的前缀是否一致、模型修订版本、dtype、并行布局TP/CP 切分是否一致以及块是否完整写入写入中断的块不会被命中。传输超时在增大timeout_ms或并发stream_number/buffer_number之前先检查挂载可达性和存储时延——超时往往是存储本身慢而不是超时阈值小。性能评估的隔离要求评估性能时必须将冷外部读取首次从 NFS 读与操作系统页缓存、引擎内存缓存区分开报告 TTFT 的同时应一并报告NFS 流量与外部命中数仅凭重放时延无法确定数据来自哪一层缓存——第二次运行可能命中的是 vLLM 原生前缀缓存或页缓存而非 NFS。源码路径速览Connector 注册与工厂ucm/store/factory_v1.pyV1 Python 包装器与参数映射ucm/store/pcstore/pcstore_connector_v1.py原生配置默认值与接口ucm/store/pcstore/cc/api/pcstore.h原生构建目标ucm/store/pcstore/CMakeLists.txt底层传输任务与日志格式ucm/store/pcstore/cc/domain/trans/trans_task.h引擎侧命中统计与配置接线ucm/integration/vllm/ucm_connector.py扩展与后端入口说明extending-store.md历史用法与性能测试记录docs/source/user-guide/prefix-cache/nfs_store.md赞分享大模型人工智能缓存【免费下载链接】unified-cache-managementUnified Cache Manager推理记忆数据管理器是一款以KV Cache为中心的推理加速套件其融合了多类型缓存加速算法工具分级管理并持久化推理过程中产生的KV Cache记忆数据扩大推理上下文窗口以实现高吞吐、低时延的推理体验降低每Token推理成本。项目地址https://gitcode.com/ModelEngine/unified-cache-management点击查看免费下载相关推荐UCM Mooncake Store 实战指南基于 Mooncake 共享内存的 KV Cache 分层缓存配置与部署UCM Mooncake Store 实战指南基于 Mooncake 共享内存的 KV Cache 分层缓存配置与部署 Unified Cache Manag大模型人工智能缓存Ray Tune 持久化存储配置完全指南云存储 / NFS / 本地文件系统Ray Tune 持久化存储配置完全指南云存储 / NFS / 本地文件系统 本文围绕 Ray Tune 的持久化存储配置展开覆盖分布式集群下 Trial人工智能分布式训练强化学习任务调度模型推理服务后端PikiwiDBPika深度指南基于 RocksDB 的 Redis 兼容持久化 KV 存储系统PikiwiDBPika深度指南基于 RocksDB 的 Redis 兼容持久化 KV 存储系统 导读 PikiwiDB 是奇虎 360 基础设施团队开源数据库KV存储后端上一篇从零开始微调bge-large-en-v1.5-openmind定制专属文本嵌入模型的完整流程下一篇BrewUI 的 SelfUpgradeCoordinator 状态机设计让 macOS 应用自动升级又快又稳创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考