1. 问题现场每轮对话都在重算 24K tokens如果你正在用 Claude Code 接本地 LLM 做日常开发某天突然发现每轮对话都要等将近一分钟那大概率撞上了 KV Cache 复用失效。这个问题的典型特征是Claude Code 明明只往 prompt 末尾追加了几十个 token但服务端却把整个 24K 上下文从头算了一遍prompt evaluation 耗时 55 秒而真正新增的 token 只有 30 到 50 个。我试过在 AMD AI MAX 395128GB 显存上跑 Qwen3-Coder-Next-Q4_K_M.gguf上下文窗口开到 262144后端分别用 LM Studio v0.4.12 和 llama.cpp 8853 验证。现象完全一致llama.cpp 日志里反复出现KV cache reuse failed. Forcing full prompt re-processing. n_past 21, n_checkpoint 8191, reason: no matching checkpoint found, common_prefix 0。注意common_prefix 0这个值它意味着前后两次请求的 prompt 前缀匹配度为零而理论上这两次请求的前缀重叠应该超过 99%。这篇文章适合两类人一是已经在用 Claude Code 接本地模型、被响应延迟折磨的开发者二是准备搭本地 LLM 编码环境、想提前避开这个坑的人。我会把排查路径、可复制的 config.toml 与 settings.json 骨架、CC Switch 配置片段以及逐项验证动作全部摊开让你能直接定位根因并确认修复效果。先说结论方向根因不在模型架构不在显存也不在 llama.cpp 的 checkpoint 机制而在 Claude Code 自己往 prompt 最前面注入的一段带时间戳的 header。它只改了几个 token却足以让整个前缀匹配归零。2. 前置准备TaoToken 与本地后端的分工在动手排查之前先把工具链的角色理清楚。Claude Code 是客户端负责组织对话、注入系统提示、发起请求本地 LLM 后端llama.cpp 或 LM Studio负责推理和 KV Cache 管理。两者之间通过 OpenAI 兼容接口通信。如果你同时需要云端模型做对照验证可以用 TaoToken 作为统一入口。它的 API 地址是 https://taotoken.net/api兼容 OpenAI 协议Claude Code 里配置 base_url 指向它即可。这样你可以在同一套 Claude Code 配置下快速切换本地后端和云端后端判断问题到底出在客户端还是服务端。具体操作上先在 TaoToken 控制台创建一个 API Key然后把它写进 Claude Code 的环境变量或 settings.json。这一步的意义是当你怀疑本地后端有问题时切到云端跑一轮如果云端也慢说明是 Claude Code 侧的 prompt 组织问题如果云端正常才回头查本地后端。需要提醒的是本地后端和云端后端在 KV Cache 行为上并不完全等价。云端服务通常有更成熟的 prefix caching 实现对 prompt 前缀变化更宽容本地 llama.cpp 的 LCP 匹配阈值默认是 0.1前缀相似度低于这个值就直接放弃复用。所以排查时要以本地日志为准。3. 可复制配置llama.cpp 启动参数与 Claude Code 环境变量3.1 llama.cpp 最简启动配置先给出一份经过验证的最简启动命令。注意这里刻意不加任何优化参数目的是先建立基线确认默认配置下 KV Cache 能否工作。./llama-server.exe \ -m Qwen3-Coder-Next-Q4_K_M.gguf \ --port 1234 --host 0.0.0.0 \ -c 262144 -ngl 99启动后观察日志应该能看到prompt cache is enabled和selected slot by LCP similarity这两行。如果没看到说明你的 llama.cpp 版本较旧建议升级到 8853 之后的版本。3.2 Claude Code 环境变量配置关键修复只有一个环境变量。在 macOS 的~/.zshrc或 Windows 的系统环境变量里加上export CLAUDE_CODE_ATTRIBUTION_HEADER0 export CLAUDE_CODE_ENABLE_TELEMETRY0 export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC1第一个是解决 KV Cache 失效的核心后两个是接非官方 API 时的常规清理项关闭计费头、使用统计和后台 ping。三个一起配能减少不必要的请求头变化。3.3 settings.json 骨架如果环境变量不生效或者你想把配置固化到项目里用.claude/settings.json{ env: { CLAUDE_CODE_ATTRIBUTION_HEADER: 0, CLAUDE_CODE_ENABLE_TELEMETRY: 0, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1 } }3.4 CC Switch 配置片段如果你用 CC Switch 管理多套 Claude Code 配置在对应的 profile 里加上同样的 env 块。CC Switch 的本质是切换不同的 settings.json所以配置内容和上面一致只是要确认切换后CLAUDE_CODE_ATTRIBUTION_HEADER确实被注入到了进程环境里。验证方法是启动 Claude Code 后在对话里让它执行echo $CLAUDE_CODE_ATTRIBUTION_HEADER看输出是否为 0。4. 验证请求从 55 秒到 786 毫秒的日志对比配置改完后必须用日志确认效果不能凭感觉。下面是我实测的日志对比。修复前的 llama.cpp 日志slot 0: KV cache reuse failed. Forcing full prompt re-processing. n_past 21, n_checkpoint 8191 reason: no matching checkpoint found. common_prefix 0 slot 0: evaluating [ 0, 8191) ... done. slot 0: evaluating [ 8191, 16383) ... done. slot 0: evaluating [ 16383, 24510) ... done. prompt eval time: 55.123s修复后的 llama.cpp 日志# 冷启动第一轮 prompt eval time 55531 ms / 24479 tokens # 第二轮起 slot 1: selected slot by LCP similarity, sim_best 0.999, f_keep 1.000 slot 1: n_tokens 24564, new_tokens 25 prompt eval time 278 ms / 25 tokens关键指标是sim_best和f_keep。sim_best是当前请求与候选 slot 的最长公共前缀相似度f_keep是可保留的缓存比例。修复后sim_best稳定在 0.997 到 0.999f_keep为 1.000说明缓存完整命中。修复前common_prefix 0sim低到 0.086远低于 0.1 的阈值所以直接放弃复用。LM Studio 侧的验证同样如此。切回 LM Studio开 4 个并行 slot只配CLAUDE_CODE_ATTRIBUTION_HEADER0日志显示sim_best 0.997, f_keep 1.000prompt eval 从 53 秒降到 786 毫秒处理 token 数从 23881 降到 124。这里有个容易误判的点LM Studio 日志里可能出现cache reuse is not supported - ignoring n_cache_reuse 256。这条日志指的是不支持 llama.cpp 的n_cache_reuse批量化复用优化不是说不支持 KV Cache 本身。只要sim_best和f_keep正常checkpoint-based 的 KV 状态恢复依然生效。判断标准永远是实际 prompt eval 耗时和这两个指标不是单看某条日志。5. 常见错排查参数名过时、并行 slot、SWA 层5.1 参数名过时导致启动失败社区文章里流传的--checkpoint-every-nb 3参数名已经过时直接跑会报error: invalid argument: --checkpoint-every-nb。正确参数名是--checkpoint-every-n-tokens。查参数永远以llama-server.exe --help | findstr checkpoint的输出为准不要照抄博客。5.2 --parallel 1 是否必要不必要。llama.cpp 新版本内置了 LCP 相似度 slot 选择能自动把请求路由到缓存命中的 slot。我实测开 4 个并行 slot缓存照样命中。--parallel 1是旧版本为了强制单 slot 复用的权宜之计现在反而限制了并发能力。5.3 --checkpoint-every-n-tokens 3 是否必要不必要。默认 8192 的 checkpoint 间隔配合 LCP 匹配已经足够f_keep能到 1.000。把间隔调到 3 只会增加 checkpoint 开销对缓存命中率没有实质帮助。5.4 --swa-full 与 --no-context-shift--swa-full影响的是 SWA滑动窗口注意力层使用完整上下文还是窗口上下文属于模型质量参数不影响缓存机制。--no-context-shift在 25K/262K 的上下文占用下根本用不到因为远未触达上下文上限。这两个参数加不加对 KV Cache 复用没有影响。5.5 排查顺序建议遇到缓存失效按这个顺序查先看 llama.cpp 日志里的common_prefix和sim_best如果common_prefix 0直接怀疑 prompt 前缀被污染然后检查CLAUDE_CODE_ATTRIBUTION_HEADER是否为 0最后才考虑后端参数。不要一上来就改模型、改显存、改并发那些大概率是无用功。6. 语义一致收尾把配置固化下来排查完成后最重要的一步是做减法验证。我当时的做法是把之前加的所有参数全部删掉只留CLAUDE_CODE_ATTRIBUTION_HEADER0重新跑一轮。如果缓存依然命中说明其他参数都是多余的。实测下来llama.cpp 和 LM Studio 都只需要这一个环境变量。如果你还需要云端模型做对照或者想把本地和云端统一管理可以在 TaoToken 的 API Keys 页面生成一个 Key配置到 Claude Code 的 base_url 里。这样切换后端时不用改代码只改配置。接入文档里有完整的 OpenAI 兼容配置示例照着填就行。最后留一个实用技巧每次改完配置不要只看 Claude Code 的响应速度一定要去后端日志里确认sim_best和f_keep。响应快可能是模型小、可能是缓存部分命中只有这两个指标都接近 1.0才说明 KV Cache 真正复用了。这个习惯能帮你省下大量以为修好了其实没修好的时间。
