lama.cpp 已处理内容（KV/Prompt）缓存完整配置指南

AI

lama.cpp 已处理内容（KV/Prompt）缓存完整配置指南

by root 0 Comment

llama.cpp 里已处理文本缓存本质是 KV Cache：模型前置prompt、系统提示、长对话前缀计算后的Key/Value张量，缓存后重复请求无需重新全量预填充（prefill），速度提升数倍。分4种缓存方案，同时配套你之前写的Windows环境变量编辑器可一键配置。

一、4种缓存机制区分（按需选用）

1. 内存前缀自动复用缓存（默认开启，最常用）

作用：同模型多请求共享相同前缀（固定System提示词、通用模板），自动匹配复用KV，重启程序丢失缓存。

关键参数/环境变量（可在你的环境编辑器直接设置）

环境变量 对应启动参数 说明
LLAMA_ARG_CACHE_RAM --cache-ram N 内存缓存最大容量 MiB，默认8192；0关闭，-1无上限
LLAMA_ARG_CACHE_REUSE --cache-reuse N 可复用缓存块最小token长度，建议512/1024，开启前缀复用
LLAMA_ARG_KV_UNIFIED --kv-unified 统一KV缓冲区，多会话共享缓存，默认开启
LLAMA_ARG_CACHE_IDLE_SLOTS --cache-idle-slots 保留空闲会话缓存不立即释放

示例启动命令（main/llama-server通用）

# Windows cmd/PowerShell
set LLAMA_ARG_CACHE_RAM=16384
set LLAMA_ARG_CACHE_REUSE=512
llama-server -m qwen3-8b.gguf -c 8192 -ngl 35
​

2. 持久化Prompt缓存（单会话固定前缀，保存到磁盘文件）

作用：把固定系统提示词、超长前置文档一次性计算，保存.bin缓存文件，下次启动直接加载，跳过prefill。

参数

  • 启动参数：--prompt-cache cache_sys.bin
  • 无独立环境变量，只能命令行传入

流程

  1. 第一次运行带完整系统prompt，生成缓存文件
llama-cli -m model.gguf -c 8192 --prompt-cache sys_cache.bin -f system_prompt.txt
​
  1. 后续直接加载缓存，无需重复处理系统提示
llama-cli -m model.gguf -c 8192 --prompt-cache sys_cache.bin
​

3. Server多会话Slot持久化缓存（长对话断点续聊）

作用：llama-server HTTP服务每个对话独立slot，手动保存/加载单条对话完整KV缓存，重启服务仍可恢复聊天上下文。

核心参数/环境变量

环境变量 参数 功能
LLAMA_ARG_SLOT_SAVE_PATH --slot-save-path ./kv_slots 指定缓存存放目录，启用slot读写API

使用方式

  1. 启动服务开启slot持久化
$env:LLAMA_ARG_SLOT_SAVE_PATH="D:\llama_cache\slots"
llama-server -m model.gguf -c 16384 -ngl 40 --port 8080
​
  1. HTTP API 保存/恢复对话缓存
# 保存slot 1到文件chat1.bin
POST http://127.0.0.1:8080/slots/1?action=save
Content-Type: application/json
{"filename":"chat1.bin"}

# 重启服务后恢复对话
POST http://127.0.0.1:8080/slots/restore
{"slot_id":1,"filename":"chat1.bin"}
​

4. SSD磁盘KV Offload缓存（低显存/内存超长上下文）

作用：KV缓存放不下内存时，溢出到SSD磁盘，支持百万token超长上下文，需要编译时开启LLAMA_SSD=1。

环境变量/参数

LLAMA_SSD=1 # 编译时开启
LLAMA_ARG_SSD_CACHE=1
LLAMA_ARG_SSD_CACHE_PATH=D:\llama_cache\ssd_kv
​

启动示例：

$env:LLAMA_ARG_SSD_CACHE=1
$env:LLAMA_ARG_SSD_CACHE_PATH="D:\llama_cache\ssd_kv"
llama-server -m model.gguf -c 131072
​

二、KV缓存压缩（降低缓存内存占用，可配合所有缓存）

修改KV存储精度，大幅减少缓存体积，环境变量直接配置：

环境变量 参数 可选值 效果
LLAMA_ARG_CACHE_TYPE_K --cache-type-k f16/q8_0/q4_0 K向量量化压缩
LLAMA_ARG_CACHE_TYPE_V --cache-type-v f16/q8_0/q4_0 V向量量化压缩

推荐配置（平衡速度/显存）：

LLAMA_ARG_CACHE_TYPE_K=q8_0
LLAMA_ARG_CACHE_TYPE_V=q8_0
​

三、完整推荐生产缓存配置（环境变量一键设置）

通用桌面GPU（8G显存，多请求共享System提示）

# 基础推理
LLAMA_NUM_THREADS=12
LLAMA_ARG_CTX_SIZE=8192
LLAMA_ARG_N_GPU_LAYERS=35
# 缓存核心配置
LLAMA_ARG_CACHE_RAM=16384
LLAMA_ARG_CACHE_REUSE=512
LLAMA_ARG_KV_UNIFIED=1
LLAMA_ARG_CACHE_IDLE_SLOTS=1
# KV量化省显存
LLAMA_ARG_CACHE_TYPE_K=q8_0
LLAMA_ARG_CACHE_TYPE_V=q8_0
# 对话持久化保存目录
LLAMA_ARG_SLOT_SAVE_PATH=D:\AI\llama_kv_slots
​

低内存CPU机器（无独立显卡，SSD溢出缓存）

LLAMA_ARG_CTX_SIZE=32768
LLAMA_ARG_SSD_CACHE=1
LLAMA_ARG_SSD_CACHE_PATH=D:\AI\llama_ssd_cache
LLAMA_ARG_CACHE_RAM=4096
LLAMA_ARG_CACHE_TYPE_K=q4_0
LLAMA_ARG_CACHE_TYPE_V=q4_0
​

四、常见问题

  1. 缓存不生效，每次都完整prefill
    • 检查LLAMA_ARG_CACHE_REUSE大于0，必须开启统一KV缓冲区--kv-unified
    • 前缀token长度必须≥cache-reuse设定值才会复用
  2. slot保存API找不到
    • 必须配置LLAMA_ARG_SLOT_SAVE_PATH目录，服务启动才加载slot接口
  3. SSD缓存报错
    • 源码编译时加LLAMA_SSD=1，预编译二进制大多未开启SSD缓存
  4. 内存占用持续上涨
    • 调低LLAMA_ARG_CACHE_RAM限制最大缓存，或开启cache-idle-slots自动清理闲置slot

五、缓存生效验证

启动llama-server/llama-cli时，控制台输出prompt cache is enabled即代表自动前缀缓存正常工作；
复用缓存时prefill耗时会从几秒降到几十毫秒，日志可见cache hit命中标记。