前缀缓存与语义缓存：KV 复用与重复计算消除

典型重复来源：
□ 系统提示词（system prompt）：每次请求都带，常常数百到数千 token
□ few-shot 示例：固定示例集，每请求重复
□ RAG 公共上下文：同一知识库检索出的相似片段
□ 多轮对话历史：后续轮次重复前面的上下文
□ Agent 循环：同一任务的多步共享大量上下文

重复的代价：
□ prefill 是 O(N²)（注意力）→ 前缀越长越贵
□ 前缀 2000 token × 每请求 → 每天百万请求 = 20 亿 token 白算
□ 直接体现为 TTFT（首 token 延迟）与 GPU 成本

缓存能省多少：
□ 场景：2000 token 系统提示 + 200 token 用户输入
□ 无缓存：prefill 2200 token
□ 前缀命中：prefill 200 token（前缀 KV 直接复用）
→ prefill 计算量降约 90%，TTFT 大幅下降

核心机制：
□ 前缀相同 → 其 KV 完全相同（注意力是因果的）
□ 把前缀按块（block）切分，每块算一个哈希
□ 新请求逐块比对哈希 → 找到最长匹配前缀
□ 匹配部分的 KV 直接复用，只需算「不匹配的尾部」

为什么前缀相同 KV 就相同：
□ 因果注意力：第 i 个 token 的 KV 只依赖前 i 个 token
□ 前缀一致 → 每个位置的输入一致 → KV 一致
□ 这是前缀缓存成立的数学基础

块哈希示意：
prompt: [系统提示 512 token][RAG 256 token][用户问题 64 token]

按 16 token 一块切分：
block 0:  hash(a1b2...) ─┐
block 1:  hash(c3d4...)  ├─ 命中已有缓存
block 2:  hash(e5f6...) ─┘
block 3:  hash(...)      ← 未命中，需计算
→ 复用前 3 块 KV，只算 block 3 起的部分

前缀缓存的两种粒度：
□ 块级（block-level）：按固定大小分块哈希，粒度粗但快
□ token 级：逐 token 匹配，更精确但开销大
□ 主流实现用块级（与 PagedAttention 的块对齐）

RadixAttention 的数据结构：
□ 用基数树（Radix Tree）组织已缓存的 token 序列
□ 树的每条边是一段 token，节点指向对应的 KV 块
□ 新请求在树上做最长前缀匹配
□ 匹配到的节点 → 复用其 KV；未匹配 → 新分支

为什么用基数树：
□ 天然支持「共享前缀」（公共祖先即公共前缀）
□ 插入/查询高效（按 token 段跳跃）
□ LRU 淘汰只需标记叶子节点

RadixAttention 匹配示意：
root
 ├─ "You are a helpful assistant..." (系统提示 A)
 │    ├─ "Example 1: ..." (few-shot)
 │    │    └─ "Q: 用户问题 1"
 │    └─ "Example 2: ..."
 └─ "You are a coding expert..." (系统提示 B)
      └─ "Q: 用户问题 2"

新请求 "You are a helpful assistant... Example 1: ... Q: 新问题"
→ 沿树走到 "Example 1" 节点，复用其 KV
→ 从 "Q: 新问题" 处新开分支，只算这段

# 块哈希的简化实现思路
def block_hash(tokens, block_size, prefix_hash=None):
    h = prefix_hash or 0
    for i in range(0, len(tokens), block_size):
        blk = tuple(tokens[i:i + block_size])
        h = hash((h, blk))     # 链式哈希：包含所有前序块
    return h
# 链式哈希保证：哈希相同 → 前缀完全相同（含顺序）

调度要点：
□ 命中判定：请求到达即做前缀匹配（在调度前）
□ 缓存复用：命中块的 KV 引用计数 +1
□ 引用计数归零 → 可被淘汰
□ 淘汰：LRU（最近最少使用）为主，按块粒度

多租户下的隔离：
□ 跨租户共享前缀：公共系统提示可共享（省显存）
□ 但需注意信息泄露：A 租户的前缀不应被 B 看到
□ 做法：缓存键加入租户/模型标识 → 逻辑隔离
□ 或：仅在明确安全的公共前缀上跨租户共享

命中率的影响因素：
□ 前缀稳定性：系统提示是否常变（变了就全失效）
□ 请求模式：是否大量共享前缀（RAG、Agent 场景高）
□ 缓存容量：显存能存多少块
□ 淘汰策略：LRU 对局部性强的负载有效

缓存容量 vs 命中率：
□ 容量小 → 频繁淘汰 → 命中率低
□ 容量大 → 挤占 KV 空间 → 并发下降
□ 平衡点：把「缓存块」与「活跃 KV」统一分页管理

语义缓存的思路：
□ 把历史「请求 → 回答」存入缓存
□ 新请求先算 embedding
□ 在向量库中检索最相似的缓存项
□ 相似度超过阈值 → 直接返回缓存答案（跳过推理）
→ 命中时零推理成本（连 prefill 都省了）

# 语义缓存的最小流程
def semantic_cache_lookup(query, embed, vstore, threshold=0.95):
    q_vec = embed(query)
    hits = vstore.search(q_vec, top_k=1)
    if hits and hits[0].score >= threshold:
        return hits[0].answer          # 命中：零推理
    return None                        # 未命中：走正常推理

与前缀缓存的差异：
维度         前缀缓存              语义缓存
匹配依据     token 完全相同          embedding 相似
命中收益     省 prefill            省全部推理
正确性       100%（KV 等价）       有风险（相似≠等价）
适用场景     固定前缀、多轮、Agent  FAQ、客服、高频重复问题

典型组合：
□ 请求先查语义缓存（最省）
□ 未命中 → 查前缀缓存（省 prefill）
□ 都未命中 → 正常推理，结果回填两层缓存

正确性风险：
□ 相似问句答案不同：「今天天气如何」vs「明天天气如何」
□ 阈值太低 → 误命中 → 返回错误答案
□ 阈值太高 → 命中率低 → 收益消失
□ 数值/实体敏感：日期、金额、ID 差一点答案完全不同
□ 时效性：历史答案可能已过期

缓解手段：
□ 高阈值（如 0.95+）+ 人工标注验证
□ 实体校验：命中后比对关键实体（日期、数字、ID）是否一致
□ 时效标记：缓存项带 TTL，过期作废
□ 白名单场景：只在「答案稳定」的场景开语义缓存
□ 降级：命中后仍走一次轻量校验（如小模型判别）

不该用语义缓存的场景：
□ 强时效（实时数据、新闻）
□ 强个性化（用户私有数据，答案因人而异）
□ 数值敏感（计算、财务、代码生成）
□ 高风险决策（医疗、法律建议）

安全考量：
□ 跨用户缓存 → 隐私泄露（A 的问题被 B 命中）
□ 必须按用户/租户隔离缓存命名空间
□ 缓存键要含：用户 ID、模型版本、参数（temperature 等）

三层缓存架构：
□ L1（GPU 显存）：前缀 KV 块 → 最快，容量最小
□ L2（CPU 内存）：KV 块溢出存放 → 中等速度，容量大
□ L3（分布式/磁盘）：跨实例共享 → 最慢，容量最大

KV 缓存的层级迁移：
□ 命中 L1：直接复用（微秒级）
□ 命中 L2：H2D 拷贝回 GPU（毫秒级）
□ 命中 L3：网络传输 + H2D（数十毫秒）
□ 未命中：重算 prefill（最慢）

分布式前缀缓存：
□ 多实例共享公共前缀（如统一系统提示）
□ 一台实例算好 → 广播/共享给其他实例
□ 适合「所有请求共享同一超长系统提示」的场景
□ 挑战：一致性、失效同步、网络带宽

LMCache 类方案的思路：
□ 把 KV 块抽出来独立管理（不绑定单个推理实例）
□ 支持 CPU/磁盘/远端多级存储
□ 实例重启不丢缓存
□ 多实例共享同一缓存池

提升命中率的手段：
□ 固定系统提示：把可变内容（时间戳、用户 ID）移到后面
□ 提示词模板化：few-shot 示例顺序稳定
□ 前缀对齐：公共前缀尽量放最前面
□ 块大小调优：与分页块对齐，减少碎片
□ 容量规划：按请求模式估算所需缓存块数

关键反模式：
□ 系统提示里带时间戳/随机 ID → 每次都不同 → 永不命中
□ few-shot 示例随机打乱顺序 → 前缀变化 → 命中率崩
□ 把用户输入放在最前 → 公共部分在后面 → 无法复用
□ 缓存键不含模型版本 → 换模型后命中脏缓存

监控指标：
□ 前缀命中率（命中 token / 总 prefill token）
□ 语义缓存命中率与误命中率
□ TTFT 的 P50/P99（缓存生效的直接体现）
□ 缓存显存占用与淘汰频率
□ 缓存收益：省下的 prefill FLOPs 与成本

高频踩坑：
□ 前缀含时间戳/随机数 → 命中率恒为 0
□ 缓存未按模型版本隔离 → 换模型后命中错误 KV
□ 语义缓存阈值过低 → 返回错误答案
□ 缓存块未随会话结束释放 → 显存泄漏
□ 多租户共享缓存未隔离 → 信息泄露
□ 缓存容量过大挤占 KV → 并发下降
□ 前缀缓存与 chunked prefill 配合不当 → 命中却仍重算
□ 缓存键未含 temperature 等参数 → 采样配置不同却复用
□ 缓存失效未广播（分布式）→ 各实例结果不一致

排查清单：
□ 打日志：每个请求的「命中前缀长度 / 总长度」
□ 检查系统提示是否含动态内容
□ 检查缓存键构成（模型、租户、参数）
□ 语义缓存抽样人工核验（误命中率）
□ 显存曲线：缓存占用是否稳定（泄漏检测）
□ 对比「开/关缓存」的 TTFT 与成本