1. 长文档智能体为什么会在KV缓存上翻车1.1 从一个真实场景说起前段时间我帮一个做法律文书分析的朋友搭本地AI Agent需求很明确把几百页的合同、判决书、招股书丢进去让Agent自己检索、比对、总结。硬件是一台双路工作站两张24G显存的卡跑的是llama.cpp量化后的MoE模型。单轮对话测试一切正常响应速度也漂亮。可一旦把文档长度拉到几万字以上问题就来了——要么直接OOM崩掉要么输出开始胡言乱语要么同一个问题问两遍答案完全不一样。我一开始怀疑是量化精度问题换了Q8、换了FP16没用。又怀疑是上下文窗口设置不对把n_ctx从8192拉到32768结果更糟。折腾了整整两天最后定位到根因KV缓存分片失效。这个词听起来很唬人但拆开看其实不复杂而且它是所有本地长文档Agent都绕不过去的一道坎。这篇复盘就是把我踩过的坑、验证过的方案、以及最后跑通的配置完整记录下来。如果你正在用llama.cpp、Ollama、或者自己基于llama.cpp封装Agent并且要处理长文档那这篇内容大概率能帮你省下至少一个周末。1.2 KV缓存到底是什么为什么它决定了长文档Agent的生死先把这个概念讲透。Transformer模型在生成每一个token的时候需要用到前面所有token的Key和Value向量做注意力计算。如果每生成一个token都把前面的全部重算一遍复杂度是O(n²)长文档直接算到天荒地老。所以工程上做了个优化把已经算过的K和V缓存起来下一个token直接复用这就是KV缓存。你可以把它理解成做菜时的备菜台。第一次切好的葱姜蒜放在台面上后面每炒一道菜直接抓一把用不用重新切。文档越长这个备菜台就越大。问题在于备菜台的大小是有限的——它占的是显存。这里有个容易忽略的点KV缓存的大小不是固定的它跟层数、注意力头数、头维度、序列长度、批大小、数据类型都相关。粗略公式是KV缓存字节数 2 × 层数 × 序列长度 × 隐藏维度 × 数据类型字节数注意那个2因为K和V各一份。以常见的7B模型为例32层、隐藏维度4096、FP16存储序列长度拉到327682 × 32 × 32768 × 4096 × 2 ≈ 17.2 GB光KV缓存就吃掉17个G。这还没算模型权重本身。所以长文档场景下KV缓存才是真正的显存杀手而不是模型参数。1.3 分片失效多卡并行时最隐蔽的坑单卡跑不动自然想到多卡。llama.cpp支持把模型切到多张卡上但这里有个关键细节KV缓存的分片策略必须和模型权重的分片策略对齐。我遇到的情况是这样的模型权重按层切分到两张卡但KV缓存因为某些参数没配对实际只在主卡上分配。结果就是主卡显存爆了副卡闲着一大半。更隐蔽的是有时候它不报错只是悄悄把超出部分换到内存里速度断崖式下跌你还以为是模型本身慢。还有一种失效是分片边界不对齐。比如模型有32层你切成两张卡各16层这没问题。但如果切分粒度是注意力头级别而KV缓存的分配又按层来就会出现某张卡上的缓存对不上号注意力计算拿到错误的K/V输出自然就崩了。这种错误不会抛异常只会让模型变傻排查起来极其痛苦。提示判断是否发生KV缓存分片失效最直接的方法是观察每张卡的显存占用。如果负载严重不均或者总显存占用远大于理论值基本可以确定分片出了问题。2. 我的实测环境与踩坑全过程2.1 硬件与软件配置清单先把环境交代清楚方便你对照自己的情况。项目配置CPU双路至强共48核内存256GB DDR4GPU两张24GB显存卡操作系统Linux推理框架llama.cpp自行编译模型MoE架构总参数较大激活参数较小量化Q4_K_M测试文档约8万字的合同合集选MoE是有原因的。MoE混合专家架构的特点是总参数量大但每次推理只激活一部分专家理论上能在有限显存下获得更好的效果。但它对KV缓存的管理更复杂因为不同专家可能分布在不同设备上缓存的对齐要求更高。2.2 第一次翻车单卡直接OOM最开始我图省事只用了一张卡n_ctx设成16384。前几千字没问题文档一长直接报显存不足。这时候我犯了个典型错误——以为是上下文不够把n_ctx往上调。结果当然是崩得更快。正确的思路应该是反过来先算清楚显存预算再决定n_ctx能开多大。我当时的账是这样的模型权重Q4量化后约占14GB单卡24GB剩10GB给KV缓存按前面的公式反推10GB大约能支撑19000左右的序列长度但实际能用的远不到这个数因为还有计算中间激活、CUDA上下文、碎片化等开销。实测下来单卡稳定跑长文档n_ctx开到8192就到头了。这显然不够用。2.3 第二次翻车多卡分片后输出错乱上了双卡用-ngl参数把层分到两张卡上。显存占用看起来正常了但输出开始出问题。具体表现是短问题回答正常一旦涉及文档深处的细节答案就开始编造而且同一个问题问两次结果不一样。我做了个对照实验同一段文档同一段prompttemperature设成0贪心解码跑十次。正常情况十次结果应该完全一致。实测有三次不同。这就说明不是采样随机性的问题而是计算过程本身不稳定典型的KV缓存错位症状。2.4 定位过程怎么确认是KV缓存分片的问题排查这种问题不能靠猜得有方法。我用了三步第一步关掉多卡退回单卡把n_ctx降到4096确认模型本身没问题。结果输出稳定说明模型和量化都没毛病。第二步多卡但不开长上下文n_ctx设2048跑短文本。结果也稳定。说明多卡分片的基本逻辑是对的。第三步多卡加长上下文问题复现。到这一步基本可以锁定问题出在长序列下的KV缓存分配上。然后我去看了llama.cpp的启动日志发现一个关键信息KV缓存的实际分配并没有完全按照我预期的分片走有一张卡的缓存分配量明显偏小。这就是分片失效的直接证据。3. 根因分析与解决方案3.1 为什么分片会失效三个层面的原因把原因拆开看分三个层面。参数层面llama.cpp里控制分片的参数不止一个-ngl管的是模型层放到GPU但KV缓存的分配还受--tensor-split、--split-mode等参数影响。如果只设了-ngl没设--tensor-split框架会按默认策略分配很可能和你的预期不一致。架构层面MoE模型的专家分布和注意力层的分布不一定一致。如果专家被切到不同卡上而KV缓存按注意力层切两者对不齐就会出现跨卡访问延迟飙升甚至数据错位。框架层面llama.cpp在长上下文下的缓存管理有一些已知的边界情况。特别是当序列长度超过某个阈值缓存的重新分配逻辑可能触发如果此时多卡状态没同步好就会失效。3.2 解决方案一显式指定分片比例最直接的修复是显式指定每张卡的分配比例不要让框架猜。启动参数大致是这样./llama-server \ -m model.gguf \ -ngl 99 \ --tensor-split 12,12 \ -c 16384 \ --split-mode layer \ -fa几个关键点--tensor-split 12,12明确告诉框架两张卡各分12份比例对齐。--split-mode layer按层切分这是长上下文下最稳的模式。另一种row模式在某些情况下会导致缓存不对齐。-fa开启Flash Attention。这个对长上下文几乎是必开的它能把注意力的显存占用降下来一大截而且计算更快。注意--tensor-split的数值是相对比例不是绝对显存。12,12表示均分。如果你的两张卡显存不一样比如24G和16G可以写成3,2这样的比例。3.3 解决方案二用Flash Attention压住缓存峰值Flash Attention值得单独说。它的核心思想是不把完整的注意力矩阵算出来再存而是分块计算、边算边丢大幅降低显存峰值。对长文档Agent来说这几乎是刚需。开启前后的对比我实测过指标关闭FA开启FA最大可用n_ctx819224576首token延迟较高明显降低长文档稳定性易崩稳定同样的硬件开启FA后能支撑的上下文长度翻了近三倍。这个提升对长文档场景是决定性的。3.4 解决方案三分层卸载与内存兜底如果显存实在不够还有一个办法把部分层留在内存里用CPU算。llama.cpp支持这种混合模式通过调整-ngl的值来控制放多少层到GPU。代价是速度会慢但胜在能跑起来。我的经验是把大部分层放GPU留几层在CPU配合大内存可以跑起单卡完全跑不动的长文档。对于不追求实时响应的批处理任务这个方案很实用。具体操作是把-ngl从99往下调比如调到28假设模型32层观察显存和速度的平衡点。每调一次跑一遍长文档测试找到那个刚好不崩的临界值。4. 长文档Agent的完整实操配置4.1 从零搭建的步骤拆解把上面的经验整合成一套可复现的流程。第一步编译llama.cpp。建议从源码编译因为发行版自带的版本可能没开FA等特性。编译时确认CUDA支持打开。cmake -B build -DGGML_CUDAON -DGGML_CUDA_FAON cmake --build build --config Release -j第二步准备模型。选MoE模型的话注意选GGUF格式且量化等级合适的版本。Q4_K_M是效果和体积的平衡点追求质量可以上Q5或Q6但显存要留够。第三步确定参数。这是最关键的一步参数不对前面全白搭。核心参数就几个-ngl、--tensor-split、-c、-fa、--split-mode。第四步压力测试。别拿短文本测直接上你最长的文档跑满上下文看稳定性。4.2 参数计算n_ctx到底能开多大这个必须会算不然就是瞎试。步骤是查模型信息层数、隐藏维度、注意力头数。算单token的KV缓存大小2 × 层数 × 隐藏维度 × 字节数。用可用显存除以单token大小得到理论上限。打个七折留出激活和碎片空间。举个例子32层、隐藏维度4096、FP16单token 2 × 32 × 4096 × 2 524288 字节 ≈ 0.5 MB可用显存假设10GB10 × 1024 / 0.5 ≈ 20480 token打七折约14000。所以n_ctx设成14336比较稳妥。这个算法不精确但能给你一个靠谱的起点避免盲目试错。4.3 Agent层的配合检索与上下文管理光把推理跑稳还不够Agent本身也要配合。长文档不可能全部塞进上下文必须做检索。我的做法是分块加向量检索把文档切成合适大小的块建向量索引Agent根据问题先检索出最相关的几块再拼进上下文。这样实际送进模型的长度可控KV缓存压力也小。这里有个坑块切得太大检索精度下降切得太小上下文碎片化模型理解困难。我实测下来每块500到800字比较合适块之间留一点重叠避免关键信息被切断。提示检索回来的块要按相关性排序最相关的放最前面。因为长上下文下模型对开头和结尾的信息注意力更强中间容易遗忘。5. 常见问题速查与避坑心得5.1 问题排查速查表现象可能原因排查方向直接OOMn_ctx过大或缓存未分片算显存预算检查tensor-split输出错乱、结果不稳定KV缓存分片失效关多卡对比看启动日志速度断崖下跌缓存被换到内存看显存占用调-ngl短文本正常长文本崩长序列缓存分配问题开FA降n_ctx多卡负载不均分片比例没设对显式指定tensor-split5.2 几条用血泪换来的经验别迷信参数越大越好。n_ctx不是越大越强超过模型训练时的上下文长度效果反而下降。而且显存压力是指数级增长的。MoE模型对分片更敏感。如果你的模型是MoE架构分片参数要比稠密模型更谨慎最好先在小上下文下验证分片正确性再逐步拉长。日志是你的朋友。llama.cpp启动时会打印缓存分配信息养成看日志的习惯很多问题在启动那一刻就有征兆。测试要用真实数据。拿几百字的demo测出来的稳定不代表几万字的文档稳定。一定要用你实际业务里最长的文档做压力测试。留足显存余量。别把显存算到刚好留20%到30%的余量应对碎片化和峰值。我见过太多理论够用实际崩的案例。5.3 关于长文档Agent的一点个人体会折腾这一圈下来我最大的感受是本地长文档Agent的瓶颈往往不在模型本身而在工程细节。KV缓存分片这种问题文档里不会重点讲但它实实在在决定了你的Agent能不能用。我现在搭这类系统的习惯是先把推理层的稳定性跑通用最长的文档压测到不崩再往上叠Agent逻辑。顺序反了后面排查问题会非常痛苦因为你分不清是推理的锅还是Agent的锅。另外MoE架构在本地长文档场景确实有优势激活参数少意味着计算量小但前提是分片配置对。配置对了它是利器配置错了它比稠密模型更难伺候。最后分享一个我常用的小技巧在正式跑业务前先跑一个一致性测试——同一段长文档同一个问题temperature设0跑十次看结果是否完全一致。一致说明缓存和分片都正常不一致别急着上业务先回去查分片。这个测试花不了几分钟但能帮你挡掉大部分隐蔽的坑。