CacheBlend 缓存知识融合:在 UCM 中为 RAG 场景加速首 Token 生成
CacheBlend 缓存知识融合:在 UCM 中为 RAG 场景加速首 Token 生成
本篇技术指南围绕 Unified Cache Manager(UCM)中集成的 CacheBlend 稀疏注意力方案展开:它面向检索增强生成(RAG)中"多个知识段落拼接后输入 LLM"的典型形态,通过选择性重计算少量 token 的 KV Cache 来融合多个已缓存的文本块缓存,显著降低首 Token 延迟(TTFT)并提升吞吐。读完本文你将掌握 CacheBlend 的核心原理、UCM 中的工程实现链路(chunk hash 编码、Delta-Rope 后处理、compute mask 构建),以及基于 offline_inference_blend.py 的完整配置与运行方法。
一、什么是 CacheBlend:为 RAG 拼接输入设计的缓存融合系统
CacheBlend 是一套"缓存融合"(cached fusion)系统:当多个预先计算好的 KV Cache 所对应的文本被拼接进 LLM 输入时,CacheBlend 并不会机械地把整段输入当作全新的 prefix 重新计算,而是选择性重计算一小部分 token 的 KV Cache 值,从而复用各文本块的历史缓存。
该方案发表于 EuroSys 2025(论文题为 CacheBlend: Fast large language model serving for RAG with cached knowledge fusion),其动机非常贴合 RAG 的在线服务形态:
- RAG 请求通常由"系统提示(system prompt)+多个检索知识段落(passages)+用户问题"拼接而成;
- 知识段落本身是相对稳定、可被反复检索与命中的文本块;
- 若每次请求都完整重算所有段落的 KV Cache,会造成大量重复计算,TTFT 与吞吐都难以满足在线要求。
CacheBlend 的思路是:把这些文本块对应的 KV Cache 以 chunk 粒度提前缓存起来,新请求到来时按需加载并融合,融合代价仅为对少量"高偏差"token 的重计算。
1.1 三大核心组件
原文档将 CacheBlend 拆解为三个关键组件:
- Loading Controller(加载控制器):编排"加载哪些 KV Cache、从哪里加载、需要多少重计算"。它决定每个请求的缓存命中面,是整个融合过程的调度大脑。
- KV Cache Store(KV Cache 存储):以文本块标识(text-chunk identity)为键,管理预计算 KV Cache 的持久化存储、查找与淘汰(eviction)。
- Cache Fusor(缓存融合器):将多个 chunk 级缓存合并成一个连贯的、cross-attention 语义正确的 KV Cache,且仅引入最小化的重计算。
1.2 论文报告的关键结果
- 长序列场景下 TTFT 加速 2.2~3.3 倍,吞吐提升 2.8~5 倍;
- 相比完整 KV 重计算,质量损失控制在 1%~3% 以内(negligible quality drop)。
注:以上数字来自原文档与 EuroSys 2025 论文的声明,作为方案效果的参考基线;实际收益与模型、场景、存储后端配置相关。
二、UCM 中的工程实现:原生 Block 级 Chunk KV Cache 全链路
UCM 将 CacheBlend 落地为"原生 block 级 chunk KV Cache 的 dump / load / postprocess / recompute"完整链路,共五个核心环节。下面结合仓库源码逐一展开。
2.1 Chunk Hash 编码:与 prefix hash 共享同一 hash 空间
CacheBlend 的块级哈希采用与原生 prefix cache 相同的"三字段"哈希模式。在 request_hasher.py 中,RequestHasher 以 (parent_hash, token_ids_block, extra_keys) 三元组递推生成每个 block 的哈希(make_request_block_hasher,见 request_hasher.py);而 Blend 连接器在 blend_connector.py 中用同一个 _generate_chunk_hashes 对 chunk 内的 token 序列逐 block 生成哈希。
def _generate_chunk_hashes(self, token_ids: List[int]) -> list[bytes]:
"""Hash a plain-text chunk with the common three-field schema."""
parent = self._seed
hashes = []
for start in range(0, len(token_ids), self.block_size):
end = start + self.block_size
if end > len(token_ids):
break
parent = self.request_hasher((parent, tuple(token_ids[start:end]), None))
hashes.append(parent)
return hashes
这一点由单元测试 test_ucm_blend_hash.py 直接验证:test_chunk_build_and_lookup_use_the_same_plain_text_hash_schema 断言同一段文本经 request_block_hasher(request) 与 _generate_chunk_hashes(...) 得到的哈希完全一致(test_ucm_blend_hash.py)。这正是 chunk cache 与 prefix cache 能共存于同一存储的关键前提。
此外,Blend 只支持纯文本请求:_validate_supported_request 会对多模态特征(mm_features)、LoRA、cache salt、prompt embeds 等无法安全哈希的请求语义抛出 RequestHashError(blend_connector.py),对应测试 test_cacheblend_rejects_request_semantics_it_cannot_hash(test_ucm_blend_hash.py)。
2.2 共享存储:Prefix Cache 与 Chunk Cache 的查找顺序
由于 chunk cache 与原生 prefix cache 共享同一 hash 空间,它们可以存放在同一个存储后端中。查找时采用两段式策略(见 _get_req_chunk_hit,blend_connector.py):
- 先对整段输入的 prefix block 哈希做 prefix cache 查找,命中部分完全复用(
pc_hit_blocks); - 再对剩余 chunk block 哈希做 chunk cache 精确查找,得到候选融合块(
chunk_hit_blocks),并逐个把命中结果写回chunk_meta.store_hits。
代码中还体现了两个工程细节:
- 部分前缀命中的截断:若首 chunk 的头部块恰好命中 prefix cache,
update_meta_partial_pc会把这些块从 chunk 元数据中裁剪掉,使融合只作用于剩余部分(blend_connector.py); - 融合阈值:
min_blend_threshold = 16——当 chunk cache 命中块数少于 16 块时,收益不足以覆盖融合开销,直接退化为普通 prefix cache 构建(blend_connector.py 与 blend_connector.py)。
_generate_blend_dispatch_meta 中的注释清晰刻画了三种 stage 的 block 布局(blend_connector.py):
Stage: Cache Blend
| prefix cache at first chunk | other chunk cache hit | other chunk cache miss | suffix part(question) |
| LOAD | LOAD | NO NEED TO DUMP | NO NEED TO DUMP |
| REUSE | REUSE & RECOMPUTE | RECOMPUTE | RECOMPUTE |
即:前缀命中块直接复用;chunk 命中块"复用+按需重计算";chunk 未命中块与问题后缀部分照常重计算。UCM 通过 BlendStage 枚举(BUILD_CHUNK_CACHE / BUILD_PREFIX_CACHE / CACHE_BLEND)区分请求处于"构建 chunk 缓存"还是"缓存融合"阶段(blend_connector.py)。
2.3 Delta-Rope 后处理:按新请求中的位置矫正缓存
Chunk 缓存保存时记录的是原请求中的位置,融合进新请求后,其绝对位置发生变化,而旋转位置编码(RoPE)对绝对位置敏感,直接复用会导致注意力语义错误。UCM 的解法是 Delta-Rope:在加载后按 position_offset(新位置与缓存位置的差值)对 K Cache 做块级旋转矫正。
ChunkMetaData.position_offset 定义为 start_token_dix - cached_start_position(blend_connector.py);加载完成后,wait_for_layer_load 调用 _post_process_chunk_cache,通过 Triton 编写的 block_wise_rope_forward 对命中块的 K 向量统一施加位置偏移旋转(blend_connector.py、blockwise_rope.py)。该 kernel 以 (batch_idx, seq_idx, head_idx) 为程序网格,逐块读取 cos_sin_cache 完成旋转;文件末尾还内置了与朴素 PyTorch 实现的精度对比(MAE 期望 1e-3 量级)与带宽基准(blockwise_rope.py)。
2.4 Compute Mask 构建:HKVD 重计算+缓存未命中+后缀
融合的核心是"算得越少越好,但必须保证正确"。Blend 稀疏模块在 blend.py 中维护一个全局 compute_mask 布尔张量,标识哪些 token 位置必须参与计算,构造规则见 update_req_compute_mask(blend.py):
- chunk 缓存未命中块:
masked_fill_(~chunk_hit_mask.unsqueeze(1), True),直接标记为需要重计算; - chunk 缓存命中块中的 HKVD token:HKVD 即 Highest KV Deviation——对加载的 K 与当前请求新计算的 K 逐 token 求绝对差(
diff_k = torch.sum((his_k - golden_k).abs(), dim=<a href="https://link.gitcode.com/i/a0ee6e8b4810e2735bcf00ca278c8fd8" target="_blank">1])),再取torch.topk选出偏差最大的ratio比例 token 强制重计算([blend.py)。ratio即来自配置中compute_meta[层名]["ratio"],示例取 0.2,即只重算命中块中偏差最大的 20% token; - 问题后缀部分:默认全部重计算。
构建 compute mask 的同时,update_query_lens 会同步缩减各请求的 query 长度,使后续所有 kernel 都只处理"必须算"的 token(blend.py)。
2.5 全流水线 Hook:不止压缩 Attention,而是压缩所有算子
UCM 的 Blend 稀疏模块基于 UcmSparseBase 提供的统一稀疏接口(base.py),通过一组 hook 让整个 LLM 前向流水线都感知 token 缩减,而不仅仅是 attention kernel:
attention_begin:对配置层(compute_meta中列出的层)重建 compute mask,并按 mask 索引 Q/K/V,同时更新attn_metadata(slot_mapping、query_start_loc、max_query_len、num_actual_tokens),日志会打印reduce attn tokens from ... to ...(blend.py);ffn_begin/layer_begin:对 FFN 输入与整层输入做同样的索引缩减(blend.py);execute_finished:融合后 query 序列被压缩,logits 索引需按新的query_start_loc重映射(blend.py)。
在 attention_begin 的 _update_attn_metadata 中还可看到两个设计取舍:HBM 前缀缓存当前不支持(blended cache 是全局视角的融合结果,无法安全复用于其他请求),而 UCM Store 前缀缓存则支持被首 chunk 完全复用(blend.py)。
Blend 方法通过工厂注册表挂接进 UCM 稀疏框架:UcmSparseFactory.register_sparse_method("Blend", "ucm.sparse.blend.blend", "Blend")(factory.py),与 ESA、GSAOnDevice、KVStarMultiStep 等稀疏方案平级。
三、快速开始:环境、配置与运行
3.1 安装与环境准备
Blend 属于 UCM 的 Sparse Attention 模块。安装 UCM 时需显式开启 sparse 构建,例如 CUDA 构建脚本 build_cuda.sh 中默认 export ENABLE_SPARSE=${ENABLE_SPARSE:-TRUE}(build_cuda.sh),Ascend 构建脚本同理(build_ascend.sh)。运行示例脚本时也需设置:
export ENABLE_SPARSE=TRUE
export DATA_DIR=/home/data/kv_cache
export MODEL_PATH=/home/models/mistralai/Mistral-7B-Instruct-v0.2
export BLEND_DATASET_PATH=/home/datasets/LongBench/data/2wikimqa.jsonl
python <ucm-repo>/examples/offline_inference_blend.py
平台限制:当前 Blend 仅支持 CUDA GPU——原文档明确说明其他后端起缺少对应 kernel 实现(例如 Delta-Rope 的 Triton kernel 依赖 CUDA 执行环境)。
3.2 配置示例详解
Blend 的接入方式与 UCM 的 offline_inference_esa.py 等示例一致:通过 vLLM 的 KVTransferConfig 指定连接器,并在 ucm_sparse_config 中选择 Blend 方法。核心配置如下(完整可运行示例见 offline_inference_blend.py):
ktc = KVTransferConfig(
kv_connector=name, # "UCMBlendConnector"
kv_connector_module_path=module_path, # "ucm.integration.vllm.blend_connector"
kv_role="kv_both",
kv_connector_extra_config={
"ucm_connectors": [
{
"ucm_connector_name": "UcmNfsStore",
"ucm_connector_config": {
"storage_backends": data_dir,
"use_direct": False,
},
}
],
"ucm_sparse_config": {
"Blend": {
"chunk_end_token_id": chunk_end_token_id,
"compute_meta": {
"model.layers.1.self_attn.attn": {
"ratio": 0.2,
},
},
}
},
},
)
各字段说明:
- kv_connector / kv_connector_module_path:示例使用
"UCMBlendConnector"与模块路径"ucm.integration.vllm.blend_connector"(offline_inference_blend.py)。UCMBlendConnector负责 chunk 哈希处理、prefix cache 匹配、加载/卸载调度(blend_connector.py); - kv_role="kv_both":同一进程同时承担 KV 的加载与卸载;
- ucm_connectors:配置底层持久化存储。示例使用
UcmNfsStore(NFS 后端)。storage_backends可配置多个路径、以:分隔(见 nfsstore_connector.py);use_direct控制是否使用直通 IO(默认 False)。NFS Store 还支持io_size、stream_number(默认 32)、buffer_number(默认 512)、storage_capacity、recycle_enable等参数(nfsstore_connector.py); - chunk_end_token_id:文本块边界标记 token id。示例脚本中按模型自动推导:Qwen 系使用
pad_token_id,Llama 系使用▁对应的 token(unk_token)作为 padding/结束标记(offline_inference_blend.py)。该值用于_process_req中按"每 block 最后一个 token 是否为 end token"切分 chunk(blend_connector.py); - compute_meta:声明需要执行融合重计算的层(键为 vLLM 层名),
ratio为该层命中块内按 HKVD 重计算的 token 比例。示例对model.layers.1.self_attn.attn取 0.2。可以同时配置多个层,每层独立取ratio。
配套的 EngineArgs 关键项(offline_inference_blend.py):enforce_eager=True、max_model_len=16384*2、max_num_batched_tokens=16384*2、gpu_memory_utilization=0.8、block_size=64、enable_prefix_caching=False(融合缓存暂不依赖 vLLM 原生 prefix cache 机制)、tensor_parallel_size=1、trust_remote_code=True。
提示:
ucm_connectors也可改用 ucm_config_example.yaml 形式的独立配置文件(通过UCM_CONFIG_FILE指定),支持 PipelineStore、Posix 等更多存储组合;Blend 示例选择 UcmNfsStore 作为最直接的起步后端。
3.3 支持的模型
原文档声明:当前支持 Llama 系与 Qwen 系模型(基于其注意力的 RoPE 结构与 tokenizer 特性实现)。示例默认路径为 Mistral-7B-Instruct-v0.2,脚本注释同时说明 Qwen 使用 pad_token_id 作为 chunk 边界(offline_inference_blend.py)。
四、深入示例:offline_inference_blend.py 的完整工作流
offline_inference_blend.py 不仅是配置样例,更完整演示了 CacheBlend 在 RAG 场景的标准使用流程。
4.1 Token 预处理:块对齐 padding 与 chunk 边界标记
RAG 文本块的长度往往不是 block_size 的整数倍。脚本用 pad_rag_chunks 将每个 chunk 补齐到整块,并以 end_id 收尾(offline_inference_blend.py):
def pad_rag_chunks(token_ids, block_size, pad_id, end_id):
remainder = len(token_ids) % block_size
if remainder == 0 and token_ids[-1] in [pad_id, end_id]:
# no need to pad
token_ids[-1] = end_id
return token_ids
pad_len = block_size - remainder - 1
padded = token_ids + [pad_id] * pad_len + [end_id]
return padded
其作用是:保证每个 chunk 的 token 总数是 block_size 的整数倍,且块边界 token 恒为 end_id——这正是 _process_req 识别 chunk 边界所依赖的模式("current we use a fix pattern (end with a fix token id) to recognize the text token chunk",blend_connector.py)。
4.2 六阶段执行流程
main() 依次执行六个阶段,直观对比四种路径的耗时与输出(offline_inference_blend.py):
- System prompt 预热(warm up):将 padding 后的系统提示作为请求发出,使其 KV Cache 写入存储;
- Baseline(无缓存融合):直接请求"原始 unpadded 全量 prompt",作为无任何缓存加速的基准;
- 缓存 RAG chunks:将每个 padding 后的 chunk 作为独立请求发出,把各 chunk 的 KV Cache dump 进存储(对应
BUILD_CHUNK_CACHE阶段); - Blend 代码预热(warm up blend code):将系统提示+所有 chunks+问题拼接成"融合形态"请求再跑一次,触发 CUDA graph 等运行时路径的首次编译/捕获;
- Cache Blend 正式请求:发送"padding 后的拼接 prompt"(系统提示+padding chunks+问题),此时连接器执行 chunk hash 查找、prefix cache 匹配、chunk 加载、Delta-Rope 后处理与 HKVD 重计算,即完整的
CACHE_BLEND阶段; - Prefix Cache 对照:再次发送"原始 unpadded 全量 prompt",度量纯 prefix cache 路径的耗时。
脚本最后打印四组结果:Baseline generated text / cost time、Prefix Cache generated text / cost time、Blend generated text / cost time,以及数据集中的问题与 golden answer(offline_inference_blend.py),便于直接验证融合路径相对 baseline 的 TTFT 收益与输出质量一致性。
4.3 运行注意事项
- 数据格式:示例读取 LongBench v1 的
2wikimqa.jsonl,并用正则把context拆分为多个Passage N:文本块(offline_inference_blend.py); - 采样参数:prefill 阶段
max_tokens=1,正式生成max_tokens=128、temperature=0、top_p=0.95,保证对比的确定性; - 脚本对缺失的
MODEL_PATH/DATA_DIR/BLEND_DATASET_PATH会交互式询问,也可直接通过环境变量注入。
五、源码地图:深入阅读的入口
| 关注点 | 文件 |
|---|---|
| Blend 连接器(chunk 切分、哈希、加载/卸载调度) | blend_connector.py |
| Blend 稀疏模块(compute mask、HKVD topk、流水线 hook) | blend.py |
| Delta-Rope Triton kernel 与精度/带宽基准 | blockwise_rope.py |
| 统一稀疏接口(UcmSparseBase)与工厂注册 | base.py、factory.py |
| 三字段哈希模式与请求语义校验 | request_hasher.py |
| 哈希一致性/非法请求拒绝的单元测试 | test_ucm_blend_hash.py |
| 完整可运行示例 | offline_inference_blend.py |
| NFS 存储后端配置 | nfsstore_connector.py |
六、引用
若在论文或报告中引用 CacheBlend,可使用仓库文档给出的 BibTeX 条目:
@inproceedings{yao2025cacheblend,
title={CacheBlend: Fast large language model serving for RAG with cached knowledge fusion},
author={Yao, Jiayi and Li, Hanchen and Liu, Yuhan and Ray, Siddhant and Cheng, Yihua and Zhang, Qizheng and Du, Kuntai and Lu, Shan and Jiang, Junchen},
booktitle={Proceedings of the Twentieth European Conference on Computer Systems},
pages={94--109},
year={2025}
}
小结
CacheBlend 是 UCM 稀疏注意力矩阵中面向 RAG 长输入场景的关键成员:它以块级哈希复用为前提,将"prefix cache 完全复用+chunk cache 选择性重计算+后缀重计算"三类计算有机融合,配合 Delta-Rope 位置矫正与全流水线 token 缩减,在几乎不损失质量的前提下显著降低 TTFT、提升吞吐。如果你正在基于 vLLM 构建 RAG 在线服务,且使用 Llama/Qwen 系模型与 CUDA 环境,可参照 offline_inference_blend.py 快速验证 CacheBlend 在本场景下的收益。
