llama.cpp长文档提速：分片+Host缓存让内存降三成速度翻倍

小糖元

121人浏览 · 2026-10-08 10:55:58

小糖元 · 2026-10-08 10:55:58 发布

llama.cpp跑长文档，最烦的不是模型加载慢，而是上下文一大，内存跟着爆炸，生成速度掉到没法看。试过硬塞整篇文档进去，结果要么OOM要么每蹦一个字都像挤牙膏。后来把思路换成分片处理加Host内存缓存，同样一台机器，处理速度直接翻倍，内存占用还降下来了。这篇就把我自己调优的过程、参数计算方式和踩过的坑完整写出来，给正在折腾本地长文档的朋友一个直接能抄的作业。

注意：以下涉及的具体数值均来自我在某台普通配置机器上的实测，不同机器、不同模型会有所偏差，但优化方向和参数选取逻辑是通用的。

1. 为什么长文档在本地跑不动：先搞清楚瓶颈在哪

1.1 长上下文带来的三重压力

本地跑大模型处理长文档，本质上是在跟三个东西较劲：上下文窗口大小、KV cache占用的内存、以及每一步生成时对KV cache的重复读取。

先说上下文窗口。llama.cpp加载模型时会根据 -c 参数分配上下文缓冲区，这个缓冲区的大小直接决定你能喂进去多少文本。但窗口开得越大，KV cache占用就越高。以一个7B量级的模型为例，上下文从4096拉到16384，KV cache的内存占用差不多是线性翻四倍，如果模型用的是f16精度的KV cache，这部分内存轻松超过显存容量。

再说KV cache本身。这是Transformer架构在推理时缓存历史token的中间状态，目的是避免每生成一个新token就重新计算一遍前面的内容。它的大小不取决于模型参数，而取决于上下文长度和层数。这意味着就算模型只有几GB，只要上下文拉长，KV cache照样能把内存吃干抹净。

最后是读取带宽。每生成一个token，都要把KV cache里所有历史token的键值对读一遍做注意力计算。上下文越长，单次读取的数据量越大，生成速度自然越慢。这个速度衰减不是线性的，上下文翻倍，速度衰减往往更严重。

1.2 “分片+缓存”组合拳的设计逻辑

明白了瓶颈之后，优化思路就很清晰了。

分片解决的是“上下文过长导致内存爆炸、速度劣化”的问题。把长文档切成多个小片段，每个片段独立喂给模型处理——总结、提取、问答都在片段内完成，最后再把结果拼起来。这样上下文窗口只需要覆盖单个片段的长度，KV cache的规模被牢牢控制住。

Host内存缓存解决的是“KV cache放不下显存、频繁换入换出导致速度暴跌”的问题。llama.cpp支持把KV cache分配到系统内存（Host RAM），显存放模型权重、内存放KV cache，两者分离。当上下文长度超过显存能承载的范围时，把KV cache放在Host内存里反而比硬塞显存加频繁换页要快得多。

这两个优化单独用效果都有限，合在一起才有效果：分片把单次推理的KV cache压到合理范围，Host缓存让KV cache在内存紧张时还能平稳运作，互不拖后腿。实测下来，同样是处理一个数万字的文档，优化前峰值内存翻倍、生成速度掉到个位数，优化后内存占用降了大概三成，生成速度提升了将近一倍。

2. 精准分片实操：如何把文档切成既不漏信息又不超窗口的块

2.1 分片大小计算：别拍脑袋定数字

分片大小是整个方案的基石。设小了，文档被切成太多块，每块之间的上下文断裂，很容易丢失前后文关联；设大了，又回到了长上下文的泥潭。

我的经验是用下面这个公式反推：

有效窗口 = 上下文总长度 - 保留给回答/总结的长度

假设模型上下文窗口设为8192，我希望每次生成的回答（比如总结或答案）不要太长，留2000个token给输出，那有效输入窗口就是6192个token。实际切分时还要留出安全边际，因为Tokenize之后的长度跟字符数不完全对应，中文一个字接近1个token，英文一个词大概1到1.3个token。

具体操作我通常把分片大小控制在有效窗口的一半到三分之二。比如有效窗口6000，那每片控制在3000到4000 token，换算成字符，中文大约3000字左右。这个体量既能保留一个相对完整的语义段落，又不会让单次推理的负担太重。

2.2 重叠窗口设计：防止信息在地缝里丢失

直接按固定大小硬切，最容易出的问题就是关键信息刚好被切成两半——一个概念的定义在前一片结尾，它的解释落在后一片开头，结果两边都答得支离破碎。

解决办法是引入重叠窗口（overlap）。每相邻两个分片之间，让尾部的一部分文本重复出现在下一片的开头。重叠量一般取分片大小的10%到20%。比如分片大小4000 token，重叠400到800 token左右。

这里有个节奏问题要注意：重叠不是为了凑字数，而是要让被切开的完整语义单元至少在一个分片里是完整的。所以重叠区域最好落在段落边界或句子边界，而不是硬生生从句子中间劈开。

2.3 token长度自适应切分：一份能直接用的方案

字符计数和token计数之间总有偏差，靠肉眼估算早晚翻车。稳妥的做法是写一个小脚本，先用分词器把整篇文档编号，再根据token序列切分，最后逆映射回文本。llama.cpp本身没有直接的可调用接口做这件事，我用的是模型配套的tokenizer工具脚本，或者用llama.cpp命令行自带的 --print-token-count 这类辅助参数配合处理。

下面是一个简化的Python切分脚本思路，在实际项目中我封装成了一个函数：

import tiktoken

# 这里用tiktoken做示例，实际llama.cpp场景使用对应模型的tokenizer
enc = tiktoken.get_encoding("cl100k_base")

def split_document(text, chunk_size=3500, overlap_size=500):
    tokens = enc.encode(text)
    chunks = []
    start = 0
    while start < len(tokens):
        end = min(start + chunk_size, len(tokens))
        chunk = tokens[start:end]
        chunks.append(enc.decode(chunk))
        if end >= len(tokens):
            break
        start = end - overlap_size
    return chunks

实际使用中，我在按token切分之后还会做一步后处理：把每个chunk的首尾调整到最近的段落边界或句号位置。如果没有合适边界，宁可少几十个token，也不从半句话中间截断。这一步对下游总结质量的影响远比想象中大。

2.4 语义边界优先：让切分贴合文章结构

纯按长度切分有一个顽固毛病：同一篇文章里不同章节的信息密度不一样。技术文档前面是名词解释，后面是操作步骤，固定长度会把操作步骤拦腰切断。

我后来做了一版改进：先按文章的自然层级——标题、章节、段落——做粗切分，再对超长的段落用token数量做细切。粗切分保证了章节完整性，细切分保证单块长度可控。两轮处理之后，每个分片内部逻辑是完整的，片与片之间靠重叠窗口衔接。

具体来说，我用的策略是：先按Markdown标题或空行把文档拆成“语义单元”，然后把相邻几个语义单元合并，直到达到目标token范围。如果某个语义单元本身就超长，再对它单独做token级切分并加重叠。这样处理的文档，后面的问答环节基本不会出现“答非所问”或者“信息缺胳膊少腿”的情况。

3. Host内存缓存原理与配置：什么时候开、怎么开、开完有什么效果

3.1 KV cache到底存在哪：显存与系统内存的博弈

先说一个容易混淆的概念。llama.cpp支持GPU推理时，默认会把模型权重、KV cache、中间激活都尽可能放进显存。显存够大当然没问题，但一旦总需求超过显存容量，程序就只能靠换页机制硬撑——把用不到的暂存数据挪到系统内存，用到再读回来。这个换页过程比正常读写慢一个数量级，实际表现就是生成速度忽快忽慢，鼠标都跟着卡。

Host内存缓存解决的问题就是让KV cache明确分配到系统内存，不参与“换页拉锯战”。代价是每次访问KV cache都要走PCIe总线从系统内存读取，单次访问延迟比显存高，但因为省去了换页的颠簸，整体吞吐反而是提升的。

这个取舍的本质是：当KV cache超过显存容量时，“全塞显存但反复换页”比“老老实实放内存”更慢。当KV cache小于显存容量时，直接放显存更快。所以Host内存缓存不是无脑开的，它的价值正好落在“KV cache超出显存但超出不多”这个甜点区间。

3.2 命令行参数与实操配置

llama.cpp各个版本的参数命名有点差异，我用的是较新版本，关键参数如下：

./llama-cli \
  -m /path/to/model.gguf \
  -c 8192 \
  -b 512 \
  -ub 512 \
  --host \
  -t 8 \
  -ngl 99

这里的 --host 就是启用Host内存分配的核心开关，部分版本里写作 --alloc-host 或者需要在编译时指定 LLAMA_ALLOC_HOST=ON 。如果你用的版本在命令行里看不到这个参数，可以先跑一句 ./llama-cli --help 确认。

配套使用的参数还有两个：

--no-kv-offload ：强制KV cache不加载到显存，配合 --host 使用效果更明确。
--cache-type-k 和 --cache-type-v ：设置KV cache的量化类型。支持f16、q8_0、q4_0等。用q8_0甚至q4_0可以把KV cache的占用降到f16的一半甚至四分之一，量化后的精度损失在多数文本处理场景下感知不强。

我的建议是优先用 q8_0 ，它能在占用和精度之间取得最好平衡。如果内存仍然吃紧，再尝试 q4_0 。注意KV cache量化跟模型权重量化是两回事，后者的精度影响比前者大得多。

3.3 显存内存协同分配：一个被忽略的细节

很多人以为开了Host内存缓存之后，KV cache就完全不走显存了。实际上llama.cpp会按层分配，模型权重可以全部放显存，KV cache按比例在显存和Host内存之间分配。如果你希望KV cache彻底放内存，需要同时确认没有开启KV cache的GPU offload相关参数。

实际操作中，我习惯这样分配：模型权重全量进显存（ -ngl 99 ），KV cache全部走Host内存（ --host + --no-kv-offload ）。这样显存只承担权重和激活值，内存承担KV cache，两者互不争抢。实测下来峰值内存反而比“所有东西都塞显存导致反复换页”更低，因为省掉了一堆临时缓冲区的开销。

另外别忘了配合 --mlock 参数把内存页锁住。这个参数的作用是防止操作系统把已分配的内存换到磁盘swap区，如果不用它，KV cache可能在推理中途被系统换出，速度瞬间崩盘。锁页之后内存占用会稳定很多，代价是系统可用内存瞬间减少，如果你的机器内存本来就只有16GB，最好算清楚再开。

4. 实测数据对比：优化前后到底差多少

4.1 测试环境说明

我在一台配置不算高、但也不算古董的机器上做的测试，8GB显存、32GB系统内存。模型是一个7B参数的量化版本，上下文窗口设8192。测试文档是一份约两万字的纯技术文档，要做的事情是分段总结加全文要点抽取。

所有测试都没有开流式输出，统一用相同的采样参数跑完整个任务。

4.2 四组策略的对照结果

策略组合	峰值内存	单token平均耗时	总耗时	处理结果
A：整篇塞入，全显存	崩溃/OOM	-	-	失败
B：整篇塞入，Host缓存	27.3GB	约95ms	超过15分钟	勉强跑完，速度极慢
C：分片处理，全显存	12.6GB	约48ms	6分40秒	正常
D：分片处理，Host缓存（8bit KV）	9.8GB	约25ms	3分15秒	正常，速度最优