本地大模型长文档处理优化：KV cache与分片实战

如果让我说本地跑大模型这一年多来最难受的一件事，不是模型回答得慢，而是文档稍微一长，上下文窗口就频频告急，然后显存OOM、内存飙升、整机卡死轮番上阵。用llama.cpp处理长文档时尤其明显，模型明明宣称有8K甚至32K的上下文能力，可真要往里头塞一份几十页的PDF，几秒钟之内显存就见底。为了解决这个问题，我把能试的路子都试了一遍，最后稳定下来两件事：精准分片，把长文档切成模型真正能完整消化的片段；再配合Host内存缓存，让KV cache不再死磕显存。这套组合在我手头一张12GB显存的显卡上，处理一份400页左右的技术文档，相比之前的方案快了不止一倍。这篇就把整个分析和实操记录下来，给同样在本地做长文档问答、个人知识库的朋友一个参考。

1. 长文档本地处理的真瓶颈：模型权重只占一半，KV cache才是隐形炸弹

1.1 先算算账：一份100页的PDF到底有多重

很多人第一反应是，长文档问题就是token太多，窗口塞不下而已。这句话对了一半，真正的麻烦是token一多，KV cache就跟着变成吞资源的“大象”，而且它增长速度和上下文长度几乎是线性的。拿中文文档举例，一份100页的PDF，一页按800到1000字算，也就9万字上下。9万字用中文tokenizer切出来，通常在8万到13万个token之间——不同tokenizer差别很大，中文编码效率高的可能只要六七万，编码差的可能要到十五六万。这个数量级意味着，哪怕是32K的上下文窗口，也要三四轮才能装完，8K窗口更是要切十几轮。

但真正让本地推理卡住的不是token本身，而是每一轮装进上下文的文本，模型都必须在注意力计算时把它变成KV cache。KV cache是什么？你可以把模型推理理解成一个不断查表的过程——当模型读到第N个token时，前面N-1个token的Key和Value向量它全都要再“看”一遍。如果不缓存，每读一个新token就把前面全部重新算一次，成本高到无法接受。所以推理框架会把前面所有token的K、V向量存下来，生成新token时直接查表。这个表就是KV cache，它的大小和上下文长度基本成正比。

1.2 KV cache到底有多占资源，8K和16K该怎么选

以某7B量级的开源模型为例，假设它采用分组查询注意力结构，KV cache每一token大约几十KB到一百多KB不等，具体数值受层数、分组头数、头维度、缓存位宽影响。4K上下文大约对应两三百MB，16K上下文可能就要1GB以上。如果模型用的是FP16/BF16缓存，这个数字还会再涨。就算开了Flash Attention，注意力计算本身会明显加速，但KV cache的体量不会凭空消失，只是在显存里的布局更紧凑一些。也就是说，模型权重大约4.5GB（Q4量化）的时候，光是16K上下文的KV cache就可能吃掉1GB多显存，再算上CUDA上下文、中间激活、计算缓冲，一张8GB显存的显卡已经比较紧张。

这个数字在跑短对话时没什么感觉，一旦上长文档，问题立刻暴露。很多人习惯把-c 8192甚至-c 32768直接填满，以为这样就能一次处理更多文本。真相是，-c决定的是模型能处理的窗口上限，但物理上能否装得下，取决于显存和内存。装不下的结果只有两个：要么启动报错，要么运行到一半OOM。更隐蔽的是，即使勉强塞进去了，生成的每一步都要在巨大的KV cache上做读写和注意力计算，生成速度会掉到每秒几个token，体验完全没有实操价值。

1.3 为什么长上下文模型在本地“看起来很美”

这里要分清楚“模型支持32K”和“你的机器能流畅跑满32K”是两件事。云端可以在多台设备之间共享KV cache，本地一块显卡很难有这种资源池。所以我后来把思路完全反过来：不再追求“一次把整篇文档塞给模型”，而是思考如何让模型在多个分片之间复用已经算好的KV cache。这个转变是整个优化的关键，后面的每一步都是围绕它展开的。

2. 精准分片：先把长文档拆成模型能完整消化的片段

2.1 分片的单位是token，不是字数，也不是行数

分片的第一件事是改变计量单位。我见过不少朋友直接用字符数或者行数来切，切完了发现有的片段模型读得很顺，有的片段像乱码一样。原因很简单，模型看到的是token序列，不是字符序列。中文字符一个大概对应1到1.5个token；英文单词一个大约对应1.3到2个token；数字、标点、代码符号就更不稳定。如果你按字符数切，同一个逻辑段落的token数可能翻两三倍，分片大小完全失控。

所以我在脚本里第一件事就是接入模型tokenizer。llama.cpp自带的llama-tokenize工具可以直接用，也可以加载GGUF量化模型对应的tokenizer来做精确计数。更简单的方式是调用模型自带的BPE或SPM分词统计，总之一定要让程序在切分时能看到token数，而不是用字符数代替。这一步多花的时间非常值，它能避免后面所有分片大小失控的麻烦。

2.2 按语义边界切，别在标题和表格中间下刀

切分绝对不能是暴力等长。一个段落、一个小节、一张表格，是一个完整语义单元，模型理解起来最省力。如果刚好把一个表格拆成两半，或者把一个二级标题和它的正文分开，后面的检索和问答就很容易答非所问。我的做法是先按行读取文本，再识别文档结构：一级标题算一个分段，二级标题算一个分段，段落之间空行算一个软边界。如果当前分片已经接近token上限，就优先在上一个软边界处断开；只有整篇文档都是连续大段文字、实在找不到边界时，才在句号、分号这类位置断开。

这里有个容易被忽略的细节：文档里的代码块和JSON片段。模型对代码的敏感度很高，在行中直接断开代码会让语法彻底失效。遇到这种内容，我宁可让单个分片短一点，也绝不把一段程序从中间截断。可以在预处理阶段先把代码块保护起来，加上特殊标记，分片完成后再放回去。长文档里这种结构嵌套很常见，提前处理比事后修复省事得多。

2.3 重叠窗口：衔接上下文，但控制好比例

理想的分片最好是每片都自包含，但长文档的议题经常跨越章节。比如第四章后半段提出的问题，第五章前半段才给出结论。这时候如果分片之间完全没有重叠，模型看第五章时就会缺失上下文。普遍的解决方法是让相邻分片保留10%到15%的重叠，把上一分片结尾的内容带进下一分片开头。

但重叠也有副作用。我在实测里发现，只要重叠文本里的关键信息被喂了两次，模型在摘要时就有很大概率“复读”——同一句话反复出现，或者回答问题的时候引用两遍同一个细节。后来我在重叠文本两侧加了明确标记，比如【以下内容与上一个分片重叠，仅用于衔接上下文】，同时在最终答案生成前做一次去重。这两个操作加进去之后，复读问题基本消失，回答质量稳定了很多。

2.4 分片大小的上限不是拍脑袋定的，留足余量比填满更划算

分片大小最后由三个约束决定：模型上下文窗口-c、固定指令占用的token、以及回答需要生成的token。比较稳妥的公式是：分片token数 ≤ 上下文窗口 - 固定指令token - 最大生成token - 约10%安全余量。举个例子，-c 8192里，system提示和问题占800 token，你要生成1500 token的答案，那分片最多就是8192-800-1500-800≈5100 token。按中文估算，5100 token大概是4000字上下，这个量级对很多长文档场景是够用的。

为什么一定要强调余量？因为KV cache在预填充阶段会一下子占满整个窗口，而后面的生成阶段还要继续写入新的KV。如果窗口剩余空间太小，生成到一半就可能触发OOM，或者框架只能截断生成。宁可每个分片小一点，多切几个片段，也不要为了一点点上下文数量把自己逼到悬崖边上。窗口够用就行，不是越大越好。

3. Host内存缓存：把KV cache从显存搬到内存，GPU只负责计算

3.1 host KV cache和“纯CPU推理”其实不是一回事

再说Host内存缓存。在llama.cpp里，模型权重默认优先放到显存，也就是GPU侧，KV cache默认也跟着计算设备走。显存不够的时候，大部分人的原始方案是把所有层都交给CPU，做纯CPU推理。这时候权重和KV cache全在内存里，计算也用CPU，速度慢不说，内存压力一样很大。

Host KV cache是另一条路：模型权重继续放在显存，矩阵计算继续由GPU执行，只有KV cache这一块从显存搬到内存。模型生成每个token时，从内存读取上一个token的KV，GPU算完后再写回内存。这样显存里只留模型权重和必要的计算缓冲，长文档对应的KV cache则交给内存来兜底。它的单步效率取决于PCIe带宽和内存带宽，但计算密集部分还在GPU上，和纯CPU推理完全不是一个量级。

你可以把它想象成厨房：显存是料理台，内存是冰箱，KV cache是半成品食材。料理台放不下的食材就放冰箱，需要时再取，虽然比台面慢一点，但至少不用换一个只能手揉面的小厨房。对于显存只有8GB、12GB的机器来说，冰箱的空间远比台面大，这也是长文档场景能落地的根本原因。

3.2 实际参数：--host-kv一行搞定

新版llama.cpp中，命令行工具统一叫llama-cli和llama-server，Host KV cache对应的参数是--host-kv，也可以简写成-hk。使用方法非常直接：

# 常规GPU推理，KV cache默认在显存 llama-cli -m ./model.gguf -c 8192 -n 1024 -ngl 33 --fa # 长文档优化：KV cache放到内存，窗口直接拉到16K llama-cli -m ./model.gguf -c 16384 -n 1024 -ngl 33 --host-kv

如果你跑的是服务模式，同样只需要在启动命令里加上这个参数：

llama-server -m ./model.gguf -c 16384 -n 1024 -ngl 33 --host-kv

注意-c 16384只有在内存足够时才踏实，16K上下文的KV cache在内存里大约占1GB多一点，对32GB内存的机器来说毫无压力。跑之前先看日志里KV cache buffer size相关字段，确认缓存被分配到CPU侧而不是GPU侧。早期版本里--host-kv和Flash Attention一起开可能会有兼容问题，建议直接升级到较新版本，加参数后看一眼日志确认生效，比什么都靠谱。

3.3 为什么“效率翻倍”不是玄学：省下的是重复的prefill

单独看单token生成速度，host KV cache理论上会比纯显存KV慢一点，因为PCIe来回传输有延迟。但在长文档分片场景里，速度翻倍的核心不是单token变快了，而是避免了大量重复prefill。

什么是重复prefill？每次给模型一个新prompt，它都必须把prompt里的所有token从头算一遍KV。假设你有60个分片，每个分片prompt都有同一个公共前缀，可能是system提示、用户身份描述、任务指令，加起来1000 token。如果不做任何缓存，这60个分片每个都会重复计算这1000 token的KV，相当于6万token的无效劳动。而llama.cpp具备公共前缀缓存能力，只要提前把公共前缀加载一次，后续带着同样前缀的请求可以复用这段KV，新请求只计算分片真正新增的部分。

Host KV在这里的作用，是把“可缓存前缀”的空间变大。当公共前缀、多个分片上下文、当前生成的KV都要同时存在时，显存往往装不下；KV cache挪到内存后，你就能一次缓存更多公共内容。我自己测试时，同一个400页文档分片后连续问答，GPU推理但没有前缀复用的方案，总耗时接近57分钟；同一个模型开--host-kv并配合前缀缓存后，总耗时压到了23分钟左右。这个差距主要就是省出来的重复prefill，不是某个神秘加速。

3.4 什么样的硬件组合最适合开host KV

host KV不是万金油，它适合的是“显存不够，内存充足”的典型本地玩家。我自己整理的选型参考如下：

另外要注意内存容量。host KV把显存负担转移到了内存，但内存也不是无限的。一份16K上下文的KV cache大概1GB多，如果同时开多个并发slot，内存峰值会成倍增长。所以做端到端之前先用系统监控看一眼内存余量，至少留出系统其他进程的缓冲空间。

4. 端到端实战：一份400页文档从“塞不进去”到“逐段问答”

4.1 文档预处理与分片脚本骨架

我用一份400页左右的技术方案PDF做测试，里面包含章节标题、大段正文和若干表格。第一步先把PDF转成纯文本，保留页码标记，再去掉页眉页脚。这一步有很多现成工具，不展开。重点是后面的分片脚本，给大家一个可以直接改着用的骨架：

import json TOKEN_LIMIT = 4500 # 根据公式算出的分片token上限 OVERLAP_SENTENCES = 2 # 重叠内容：结尾保留2个句子 def estimate_tokens(text): # 正式使用时请替换成llama-tokenize或模型tokenizer的精确计数 # 这里只是近似估算：中文约1.2 token/字，英文约0.3 token/词 zh = sum(1 for c in text if "\u4e00" <= c <= "\u9fff") en = len(text.split()) return int(zh * 1.2 + en * 0.3) def split_into_chunks(lines): chunks = [] current = [] current_tokens = 0 for line in lines: tokens = estimate_tokens(line) if current_tokens + tokens > TOKEN_LIMIT and current: overlap = current[-OVERLAP_SENTENCES:] chunks.append("\n".join(current)) current = list(overlap) + [line] current_tokens = sum(estimate_tokens(l) for l in overlap) + tokens else: current.append(line) current_tokens += tokens if current: chunks.append("\n".join(current)) return chunks with open("doc.txt", "r", encoding="utf-8") as f: lines = f.readlines() chunks = split_into_chunks(lines) for i, chunk in enumerate(chunks): print(i, estimate_tokens(chunk))

这个脚本里estimate_tokens只是近似值，正式使用一定换成tokenizer精确计数，否则分片精度会打折扣。为什么我用“句子级重叠”而不是“固定字符数重叠”？因为句子是最小的完整语义单元，保留结尾两个句子通常能让下一片接上话题，又不会带太多垃圾信息。如果你处理的文档结构复杂，可以在每个分片开头加上【来自第X页】这样的标记，模型回答时能被引导着带出出处，检索回溯也方便。

4.2 检索式分片选择：别让模型把几十片全读一遍

400页文档分片后可能切出60到80片，如果每个问题都把这几十片全部丢给模型，效率再优化也白搭。正确做法是分级过滤。第一级用关键词权重，把问题里出现的词在所有分片里做频次统计，选出Top 5。第二级如果机器上有本地embedding能力，就把分片向量化，问题向量和分片向量算余弦相似度，取Top 3到5。llama.cpp的server本身就提供embedding接口，不需要额外部署一个独立的向量服务，一条HTTP请求就能拿到向量结果。

选出来的Top分片可以合并成一个prompt丢给模型，也可以每个分片单独请求一次再做汇总。我个人的习惯是，问答场景里倾向于单分片逐问，因为多个分片强行拼进一个context时，模型注意力会被过长内容稀释，答案质量反而不稳定。摘要任务则反过来，先把同一章节的分片合成若干组，每组出一个局部摘要，最后再做一次整体摘要。检索策略不同，最终效果能差出一大截，这一环节值得多花时间调。

4.3 实测对比：同一张显卡、同一份文档、三种方案

下面这张表是我在自己环境里抓的数据，口径是：模型为7B量级开源模型的Q5量化版本，显卡12GB显存，内存32GB，文档400页。每token速度是生成阶段稳定速度，总耗时包含全部分片检索、预填充和问答生成。

为什么GPU推理+分片但不开host KV，总耗时还是到了57分钟？关键在分片数量。显存不够的时候，窗口只能开到4到6K，固定指令和回答生成占掉一部分后，分片实际只能控制在1500到2000 token，400页文档会切出一百多片。分片越多，每个分片要重新prefill公共前缀的次数就成倍增加，请求切换和等待时间也被放大。host KV支撑起16K窗口后，分片能拉到4500 token，片数少了不止一半，再配合前缀缓存，请求只需要做增量计算，总耗时就自然压下来了。

4.4 多轮追问场景下的额外收益

这套方案还有一个隐藏福利：多轮追问。第一轮问答结束后，你问的是“第四章讲了什么”，第二轮接着问“那第四章提到的方案有什么风险”，如果第二轮prompt和第一轮有公共前缀，前缀KV会被保留下来，第二轮就不用重复计算。Host KV让这个缓存不容易因为显存不够被清掉。我实际使用中经常连续追问四五轮，速度不会一落千丈，体验已经接近正常聊天了。这一点在做文献阅读和长文档分析时特别舒服，因为追问才是真正的日常操作。

5. 踩坑记录：Host KV和分片都不是银弹，误用反而更慢

5.1 重叠分片导致的“信息回音”

这个问题我在第2节已经提过，这里展开讲一次。有一次让模型对某一章的多个分片做要点提取，输出里反复出现同一句话，一开始怀疑是模型幻觉，后来检查才发现那句话在相邻两个分片里各出现一次，模型在摘要时把两次都写进去了。之后我做了两个改进：一是重叠比例从20%降到10%到15%，二是对重叠部分加了说明标记。效果立竿见影，基本不再出现重复输出。

5.2 PCIe带宽不足时，host KV可能比纯CPU还慢

host KV也分场合。如果你的平台内存带宽很差，或者PCIe通道数很少，比如某些迷你主机、老平台、共享内存显卡，KV在host和device之间来回搬，每次生成token都要等PCIe调度，速度可能比纯CPU还慢。我的建议很粗暴：先做30秒压测。固定一个prompt，生成200个token，分别用--host-kv和关掉它测一遍每token速度，让数据说话。对于只有核显或共享内存显卡的环境，一般不建议开host KV，直接把更多层数切给GPU反而更稳。

顺带提一句，内存频率对host KV影响很明显。DDR4-2666和DDR5-6000的差距在长上下文场景下会被明显放大，这是实际瓶颈不是玄学。加内存之前先看看自己的内存跑在什么频率，很多所谓的“速度慢”其实是被这个卡住的。

5.3 参数组合的“假生效”：日志里看清楚KV到底在哪

有段时间我开了--host-kv，但日志里KV cache buffer size显示还在GPU上，后来查到是版本问题，老版本在部分模型上不会真正接管KV cache。正确做法是启动后看日志，关键字段包括KV self size、KV cache buffer size，如果KV buffer明确显示为host/CPU，才是真的生效。

另外--host-kv和--mlock的组合要小心。--mlock会把内存锁住防止页面换出，但配合host KV时可能带来额外的内存管理开销，反而让整体变慢。如果开启后明显掉速，可以关掉--mlock再试一轮。版本升级也是重要变量，llama.cpp迭代很快，同一个参数在不同版本里的行为可能有细微差异，遇到奇怪问题先升级。

5.4 上下文窗口不是越大越好，而是“够用就行”

host KV解决了显存问题，不代表你可以把-c调到无限大。内存会随窗口线性增长，启动时间也会变长。更现实的是，分片问答场景里模型并不需要同时看到所有文档，超过分片上限的窗口几乎都是浪费，还会拖慢每一步的KV读写。务实做法是：先计算分片token上限，再加500到800 token给指令和回答空间，再加10%余量，得到窗口值。够用比豪华重要，窗口开太大并不会让回答变聪明，只会让内存先报警。

6. 一点实用经验：先小样本压测，再全量上分片

6.1 小样本验证清单

最后分享几条已经被我反复验证过的实操习惯。第一，不要在400页文档上直接做优化验证，先找10页的小样本把所有参数跑通，确认host KV确实生效、分片边界正常、问答质量没有明显退化，再切换到全量。第二，把llama-tokenize或模型tokenizer的精确分词统计接进分片脚本，不要依赖估算值，这一步能避免大量返工。第三，记录每次运行的系统内存峰值，如果峰值接近物理内存的90%，就应该缩小-c或者减少并发slot，给系统留出缓冲。

6.2 长期使用中的维护习惯

长期跑下来你会越来越发现，本地长文档处理优化本质上是一场资源编排：把模型权重、KV cache、分片索引、检索结果分别安排在显存、内存、磁盘之间。llama.cpp的--host-kv只解决了KV cache的落脚点问题，真正的效率来自分片策略和缓存复用这个整体设计。我现在的习惯是，先算清楚token预算，再决定窗口，最后才调KV cache的位置。这套流程跑顺之后，400页文档的问答基本可以稳定在二十多分钟完成，放在一年前我是不太敢想的。