kv-cache | llama.cpp 学习笔记

KV Cache 缓存 Transformer 推理中已计算的 Key 和 Value 向量，避免重复计算，是自回归生成的核心优化。

为什么需要 kv-cache

Transformer 自回归生成时，每生成一个新 token 都需要对之前所有 token 做注意力计算。KV Cache 将已计算的 K/V 向量缓存起来，使得每步只需计算当前 token 的 Q/K/V，然后与缓存的 K/V 做注意力。

核心原理

Prefill 阶段：处理整个 prompt
  token[0..N] → 计算 K[0..N], V[0..N] → 存入 cache

Decode 阶段：逐个生成
  token[N+1] → 计算 Q, K, V → K,V 追加到 cache
            → Attention(Q, K_cache, V_cache) → 输出 logits

内存布局（每层）：

K_cache: [max_positions, kv_hidden_dim]
V_cache: [max_positions, kv_hidden_dim]

关键优化：

GQA — Grouped Query Attention 减少 KV head 数
Prefix Caching — 复用已处理的 prompt 前缀
Rolling Cache — 淘汰旧位置以支持无限生成

注意事项：

使用 LLAMA_STATE_SEQ_FLAGS_ON_DEVICE 时，每个序列只能保存一个设备端状态，保存新状态会使旧状态失效
MTP draft token 复用普通 KV Cache（-ctk 只是 --cache-type-k 的 CLI 简写，并非独立的 MTP cache 类型），推测解码中 draft 模型走同一套 cache 机制
SWA checkpoint 优化 — 保存 Sliding Window Attention 状态时仅写入未屏蔽的 cell
TP 量化 KV — Tensor Parallel 现支持量化 KV cache，正确处理跨设备部分缓冲区视图
DSA KV cache — DeepSeek V3.2 使用 llama_kv_cache_dsa，附带 lightning indexer 缓存和 Hadamard 旋转张量
dsv4 KV cache — DeepSeek V4（LLM_ARCH_DEEPSEEK4）使用全新专用类型 llama_kv_cache_dsv4（约 1800 行），内建 save-load 状态、Sinkhorn eps 纠正与 rope 处理，支持 pro 模型
MSA indexer — MiniMax-M3（MSA 稀疏注意力）的 indexer 缓存现由组合类 llama_kv_cache_msa 持有（内部为 K/V 与 indexer 两个 llama_kv_cache 实例）；DeepSeek DSA 的 llama_kv_cache_dsa 附加 lightning indexer；qwen4exp 的 QSA indexer 由 llama_memory_hybrid_idx 镜像实现
token id 追踪 — KV cell 扩展记录现含 llama_token tok（多模态输入为 LLAMA_TOKEN_NULL），get_prev_tokens() 供 n-gram 嵌入使用；cell_ext 纳入状态保存（状态版本 2→3）
循环态回滚 — ggml_ssm_scan 的 K 参数 + n_rs_seq 让循环模型在推测解码中可回滚状态快照（Kimi K3 / qwen4exp）
KV cache 家族 — 现为基类 llama_kv_cache + 专用 msa / dsv4 / dsa / dsa-iswa / iswa / hybrid-idx，统一经 llama_memory 暴露（不存在 *-unified.cpp，前缀早于 #15467 去除）
recurrent n_keep_tail — split_equal 拆批时为循环 / 混合记忆类型保留尾部 token
n_layer_all — 层数区分 n_layer（标准层）和 n_layer_all（含 SWA/MTP 等额外层）
共享 cells 零拷贝 — v_cells 重构为 std::shared_ptr<llama_kv_cells_vec> + 引用（[TAG_KV_CACHE_SHARE_CELLS]），多 cache 共享同一份 cell 元数据时不再逐 cell 拷贝；共享时沿用源 cache 的容量
main_gpu 校验放宽 — 无可用设备时跳过 main_gpu 校验（纯 CPU / 无 GPU 场景）
n_discard 修复 — context shifting 时非绑定 n_discard 值正确处理，避免丢弃数量错误

在源码中的实现

src/llama-memory.cpp — KV Cache 管理逻辑
src/llama-kv-cache.cpp — KV Cache 核心实现
src/llama-kv-cells.h — Cache 单元定义
src/llama-context.cpp — decode 时的 cache 更新

为什么需要 kv-cache ​

核心原理 ​

在源码中的实现 ​

相关概念 ​

为什么需要 kv-cache

核心原理

在源码中的实现

相关概念