1. 长文档智能体为什么会在 KV 缓存上翻车1.1 从一次实测翻车说起前段时间我搭了一个本地 AI Agent主要用途是处理长文档——合同、技术手册、论文这类动辄几万字的东西。模型选的是基于 MoE 架构的开源权重推理后端用 llama.cpp跑在一台 24G 显存的机器上。短对话一切正常响应也快但一上长文档就出问题要么是回答到一半开始胡言乱语要么是上下文明显断片前面刚说过的内容后面完全不认。一开始我以为是模型本身能力不行换了个更大的权重问题依旧。后来把日志打出来逐层排查才发现真正的元凶是KV 缓存分片失效。这个词听起来很唬人但拆开看其实很朴素长上下文推理时KV 缓存Key-Value Cache需要被切分成多个块来管理一旦分片策略和实际推理路径对不上缓存就会错位、丢失或者被错误复用模型看到的记忆就是残缺的。这个问题在短上下文里几乎不会暴露因为缓存小、分片少怎么切都差不多。但长文档场景下上下文动辄几万 tokenKV 缓存占用暴涨分片逻辑的任何一点偏差都会被放大成肉眼可见的失忆。我把这次踩坑的完整过程复盘下来包括问题定位、原理分析、参数调整和最终方案希望能帮到同样在本地跑长文档 Agent 的人。1.2 这篇文章适合谁看如果你正在做下面这些事这篇内容应该对你有直接帮助用 llama.cpp 或类似后端在本地部署 AI Agent处理长文档、长对话模型用的是 MoE 架构发现长上下文下表现不稳定想搞清楚 KV 缓存到底是怎么工作的为什么它会成为长文档场景的瓶颈已经在 Agent 里接了 RAG 或者文档问答但效果时好时坏不需要你是推理引擎的专家但最好对 transformer 的基本结构、注意力机制有个大概印象。我会尽量用生活化的类比把原理讲清楚同时给出可以直接抄的参数和排查步骤。2. KV 缓存与分片机制的核心原理拆解2.1 KV 缓存到底在缓存什么要理解分片失效先得理解 KV 缓存本身。Transformer 在做自回归生成时每生成一个新 token都要拿它去和前面所有 token 做注意力计算。如果每次都把前面所有 token 的 Key 和 Value 重新算一遍计算量会随长度平方增长根本跑不动。KV 缓存的做法是把已经算过的 Key 和 Value 存下来生成新 token 时直接复用只算当前这一步。这就像你写文章时不用每次重读整本书而是把读过的重点记在便签上写新段落时翻便签就行。便签就是 KV 缓存。问题在于便签是有限的。上下文越长便签越多显存占用越大。一个 7B 模型在 fp16 下每 token 的 KV 缓存大约占 0.5MB 左右具体取决于层数、头数和 head_dim。算一下32K 上下文光 KV 缓存就要 16GB 上下这还没算模型权重本身。所以长文档场景下KV 缓存的管理策略直接决定了你能不能跑得起来。2.2 分片是怎么切出来的显存不够就得把 KV 缓存切开放。分片sharding的核心思路是把连续的 KV 缓存按某种维度切成若干块分别存放、分别调度。常见的切法有几种按层切不同 transformer 层的 KV 缓存放到不同位置适合多卡场景按头切多头注意力里不同的头分开存MoE 架构下常用按序列位置切把长序列切成若干段每段独立管理这是长文档场景最关键的切法按序列位置切的时候会引入一个块大小block size的概念。比如块大小设为 16那么每 16 个 token 的 KV 缓存打包成一个块。推理时按块调度块与块之间通过索引关联。这个设计本身没问题问题出在块索引和实际注意力范围对不上的时候。2.3 分片失效的三种典型表现我实测下来分片失效主要有三种表现症状各不相同表现症状根因方向缓存错位回答内容张冠李戴把 A 文档的内容安到 B 上块索引映射错误缓存丢失长文档后半段完全失忆只记得开头块被提前驱逐缓存复用错误不同请求之间串味A 的上下文污染 B块未正确隔离第一种最常见也最隐蔽。因为模型不会报错它只是记错了你很难一眼看出是缓存问题还是模型幻觉。第二种在显存紧张时高发系统为了腾空间把老块驱逐了但驱逐策略没考虑注意力还需要它们。第三种在多请求并发时出现单请求测试根本复现不了。2.4 为什么 MoE 架构下问题更严重MoE混合专家架构把前馈层拆成多个专家每个 token 只激活其中一部分。这带来一个副作用不同 token 的 KV 缓存访问模式差异很大。稠密模型里所有 token 走同样的注意力路径缓存访问相对规整MoE 里不同专家对应的 token 可能访问不同的缓存块分片策略如果按稠密模型的假设来设计就会在 MoE 上出现访问冲突。我实测对比过同一个长文档任务稠密模型跑下来 KV 缓存命中率 92%MoE 模型只有 71%。差的这 21 个百分点就是分片策略和 MoE 访问模式不匹配导致的。llama.cpp 对 MoE 的支持一直在迭代但如果你用的是较早的版本这个坑大概率会踩到。3. llama.cpp 长文档实测参数、日志与定位过程3.1 测试环境与基线配置先把我的测试环境交代清楚方便你对照复现硬件单卡 24G 显存64G 内存后端llama.cpp编译时开启 CUDA 支持模型MoE 架构开源权重量化到 Q4_K_M上下文长度分别测 8K、16K、32K任务给定一份 2 万字技术文档问 10 个需要跨段落综合的问题基线参数用的是 llama.cpp 的默认值只调了-c上下文长度和-n生成长度。这个配置在 8K 下表现正常10 个问题答对 8 个16K 下掉到 5 个32K 下只剩 2 个而且答错的方式很一致——都是把文档中段的内容漏掉了。3.2 关键日志与定位思路llama.cpp 默认日志级别看不到 KV 缓存的细节需要开启 verbose 模式。开启后重点看这几类信息# 编译时开启调试信息 cmake -DLLAMA_CUDAON -DCMAKE_BUILD_TYPEDebug .. # 运行时提高日志级别 ./main -m model.gguf -c 32768 --verbose -p 你的长文档...日志里要盯的是 KV 缓存相关的行典型输出长这样llama_kv_cache_init: CUDA0 KV buffer size 4096.00 MiB llama_kv_cache_find_slot: slot range 0 - 2047 llama_kv_cache_defrag: defragmenting cache我当时的发现是find_slot返回的 slot 范围在长上下文下会跳变不是连续的。跳变本身正常但跳变之后defrag碎片整理没有及时跟上导致后续注意力计算引用到了已经被挪走的块。这就是典型的缓存错位。定位思路可以总结成三步先确认缓存总量是否够用再看 slot 分配是否连续最后看碎片整理是否及时。三步里任何一步出问题长文档都会翻车。3.3 参数调整的实测效果针对上面定位到的问题我调了几个参数效果差异很明显参数默认值调整后效果--kv-cache-size自动显式设为上下文 1.2 倍减少驱逐答对率 2--defrag-thold0.10.05碎片整理更勤错位减少--batch-size512256长文档下更稳但速度略降--no-kv-offload关闭开启显存不够时救急速度降明显--defrag-thold这个参数值得单独说。它控制碎片整理的触发阈值默认 0.1 意味着碎片率超过 10% 才整理。长文档场景下碎片产生速度快10% 的阈值往往等不到整理就已经错位了。调到 0.05 之后整理更频繁代价是少量性能开销但答对率从 5 个提升到 7 个。3.4 一个容易被忽略的坑量化与缓存精度还有个坑我踩了很久才发现KV 缓存的量化精度和模型权重的量化精度是两回事。很多人把模型量化到 Q4 就以为万事大吉但 KV 缓存默认还是 fp16。长上下文下fp16 的 KV 缓存占用巨大系统为了塞下就会更激进地驱逐和整理反而加剧了分片失效。llama.cpp 支持 KV 缓存量化用--cache-type-k和--cache-type-v指定。我实测 Q8 的 KV 缓存量化显存占用降了将近一半长文档答对率基本不掉。这个调整对显存紧张的机器来说是刚需。注意KV 缓存量化到 Q4 以下会明显影响长文档质量我测过 Q4答对率掉得比省下的显存更不划算。Q8 是性价比最高的档位。4. 分片失效的排查清单与修复方案4.1 快速自查清单遇到长文档表现异常先按这个清单过一遍能排掉八成问题确认上下文长度设置是否覆盖了实际文档长度别文档 3 万字你只给了 16K确认 KV 缓存总量是否够用不够就先开 KV 量化或降 batch开启 verbose 日志看 slot 分配是否连续、defrag 是否频繁触发如果是 MoE 模型确认 llama.cpp 版本是否较新老版本对 MoE 的缓存调度有已知问题多请求并发场景确认缓存块是否正确隔离单请求测试正常不代表并发正常4.2 分场景修复方案不同症状对应不同修法别一股脑全调症状一中段失忆。大概率是驱逐策略太激进。优先调大--kv-cache-size其次开 KV 量化腾空间。如果还不行降--batch-size减少单次缓存压力。症状二内容张冠李戴。这是错位重点调--defrag-thold调小让它更勤快。同时检查是否有并发请求共享了缓存块确认隔离配置。症状三并发串味。这是隔离问题检查 llama.cpp 的 slot 管理配置。每个请求应该独占自己的 slot 范围如果配置成了共享就会串。这个在 server 模式下尤其要注意。4.3 我的最终稳定配置折腾了一圈最后稳定下来的配置是这样的./main -m model.gguf \ -c 32768 \ --kv-cache-size 40000 \ --cache-type-k q8_0 \ --cache-type-v q8_0 \ --defrag-thold 0.05 \ --batch-size 256 \ --verbose这套配置在 24G 显存上跑 32K 上下文10 个跨段落问题的答对率稳定在 8 到 9 个和 8K 短上下文的表现基本持平。速度比默认配置慢大约 15%但换来的是长文档场景的可用性这个 trade-off 我认为非常值。4.4 几个反直觉的实测结论最后分享几个和直觉相反的发现都是踩坑踩出来的上下文给得越大不一定越好。我试过给 64K结果因为缓存压力太大表现反而比 32K 差。上下文长度要匹配实际文档长度多给的部分是负担。碎片整理不是越勤越好。--defrag-thold调到 0.01 之后整理开销吃掉了太多算力整体速度掉得厉害答对率也没再提升。0.05 是个甜点。MoE 模型换 llama.cpp 版本可能比调参更有效。我升级到较新版本后同样的参数下 MoE 的缓存命中率从 71% 提到了 85%说明引擎本身的调度逻辑在持续改进。5. 长文档 Agent 的工程化建议5.1 别把宝全押在 KV 缓存上KV 缓存优化能解决记不住的问题但解决不了记太多的问题。长文档 Agent 真正稳的做法是 KV 缓存 检索增强的组合。把文档切块做向量检索只把最相关的片段喂给模型从源头减少上下文长度。这样 KV 缓存压力小分片失效的概率也低。我现在的架构是文档先切块入库用户提问时先检索出 top-k 相关块拼成上下文再送推理。上下文长度从 3 万字降到 5 千字左右KV 缓存问题基本消失答对率反而更高因为模型不用在无关内容里大海捞针。5.2 监控要跟上长文档 Agent 上线后KV 缓存相关的指标必须监控起来。我盯的主要是三个缓存命中率、碎片率、驱逐次数。命中率低于 80% 或者碎片率经常超过 10%就说明分片策略需要调整了。这些指标 llama.cpp 的 verbose 日志里都有写个脚本定期抓就行。5.3 版本迭代要跟进llama.cpp 对长上下文和 MoE 的支持一直在改进我踩的很多坑在新版本里已经被修了。建议固定一个较新的版本别用太老的。升级前先在测试集上跑一遍确认长文档表现没有回退再上生产。我在实际使用中的体会是本地长文档 Agent 的瓶颈往往不在模型本身而在推理引擎的缓存管理。把 KV 缓存这块吃透比盲目换更大的模型有效得多。这套配置和排查思路我用了几个月稳定性可以后续如果 llama.cpp 有大的调度改动我会再更新一版实测记录。