UCM增强前缀缓存部署指南

UCM增强前缀缓存部署指南#

概述#

统一缓存管理（UCM）为vLLM/vLLM-Ascend中的前缀缓存场景提供了外部KV缓存存储层。与仅通过聚合设备内存扩展前缀缓存容量、因此仍受限于片上内存/DRAM大小且缺乏持久性的KV池化不同，UCM将计算与存储解耦，并采用分层设计。每个节点使用本地DRAM作为快速缓存，而共享后端（如3FS或企业级存储）则作为持久化KV存储。这种方法消除了设备内存带来的容量上限，实现了持久可靠的前缀缓存，并使缓存容量能够随存储系统而非计算资源扩展。

先决条件#

操作系统：Linux
配备昇腾NPU的硬件。通常是Atlas 800 A2系列。
vLLM：main分支
vLLM Ascend：main分支

UCM安装#

请参考昇腾NPU的官方UCM安装指南

为前缀缓存配置UCM#

修改UCM配置文件以指定使用哪个UCM连接器以及KV块应存储在何处。您可以直接编辑位于以下路径的示例文件：

unified-cache-management/examples/ucm_config_example.yaml

有关最新的配置选项，请参考前缀缓存的官方UCM文档

最小配置示例如下：

ucm_connectors:
  - ucm_connector_name: "UcmNfsStore"
    ucm_connector_config:
      storage_backends: "/mnt/test"
      use_direct: false

load_only_first_rank: false

说明：

ucm_connector_name: "UcmNfsStore"：指定UcmNfsStore作为UCM连接器。
storage_backends：指定用于存储KV块的目录。可以是本地目录或NFS挂载路径。UCM将在此处存储KV块。⚠️ 请确保将"/mnt/test"替换为您的实际存储目录。
use_direct：是否启用直接I/O（可选）。默认为false。
load_only_first_rank：控制是否仅rank 0加载KV缓存并将其广播到其他rank。此功能目前在昇腾上不受支持，因此必须设置为false（所有rank独立加载/转储）。

启动推理#

在本指南中，我们描述使用带有UCM连接器的vLLM进行在线推理，部署为OpenAI兼容的服务器。为获得UCM的最佳性能，建议将block_size设置为128。

要使用Qwen/Qwen2.5-14B-Instruct模型启动vLLM服务器，请运行：

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_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"替换为您的实际配置文件路径。

如果您看到以下日志：

INFO:     Started server process [1049932]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

恭喜，您已成功启动带有UCM连接器的vLLM服务器！

评估UCM前缀缓存性能#

在启用UCMConnector启动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):                           15323.87

检查vLLM服务器日志会发现类似条目：

INFO ucm_connector.py:228: request_id: xxx, total_blocks_num: 125, hit hbm: 0, hit external: 0

这表明对于第一个推理请求，UCM未命中任何缓存的KV块。因此，必须计算完整的16K令牌预填充，导致相对较大的TTFT。

第二次执行后#

再次运行相同的基准测试会产生：

---------------Time to First Token----------------
Mean TTFT (ms):                            1920.68

vLLM服务器日志现在包含类似条目：

INFO ucm_connector.py:228: request_id: xxx, total_blocks_num: 125, hit hbm: 0, hit external: 125

这表明在第二次请求期间，UCM成功从存储后端检索了全部125个缓存的KV块。利用完全缓存的前缀显著减少了模型观察到的初始延迟，与首次运行相比，TTFT实现了约8倍的提升。