1. 多轮对话越聊越慢问题出在 Prefix Cache 没命中Hermes Agent 跑多轮对话时如果你发现第 1 轮响应很快到第 5 轮、第 10 轮开始明显变慢账单上的输入 token 也一路飙升大概率不是模型变笨了而是 Prefix Cache 没命中。Prefix Cache 是 LLM 推理侧对「相同前缀」的 KV cache 复用机制前缀只要一个 token 变了后面整段缓存全部作废。Hermes Agent 的冻结快照Frozen Snapshot就是为这件事设计的会话开始时把 MEMORY.md 和 USER.md 注入系统提示整个会话期间系统提示保持不变让 LLM 的 Prefix Cache 能持续命中跳过系统提示的重复计算。但实际跑起来很多人会遇到「明明用了冻结快照cache 命中率还是低」的情况。原因通常不在快照机制本身而在接入层Key 不统一、请求头不一致、系统提示被动态拼接、多轮消息顺序抖动任何一个环节让前缀发生字节级变化Prefix Cache 就失效。这篇是系列第五篇聚焦 Hermes Agent 多轮对话场景下 Prefix Cache 命中率低的排查与优化从冻结快照机制切入说明 KV cache 复用与 Prefix Cache 的配合逻辑并交付可复制的 config.toml 与 settings.json 骨架、TaoToken 统一 Key 接入步骤以及用日志验证 cache 命中与快照冻结是否生效的具体动作。适合已经在跑 Hermes Agent、想压 token 成本和首 token 延迟的开发者。2. 冻结快照、KV cache、Prefix Cache 三者的配合逻辑2.1 冻结快照到底冻结了什么冻结快照是 Hermes 在会话开始时捕获的一份不可变的系统提示状态。核心原则一句话会话开始时固定会话期间永不改变。它把 MEMORY.md 和 USER.md 的内容注入系统提示词后续轮次不再重新加载系统提示。没有冻结快照时每轮都重新读取记忆第 1 轮系统提示 1000 tokens 对话 第 2 轮系统提示 1000 tokens 对话 ← 重复计算 第 3 轮系统提示 1000 tokens 对话 ← 又重复 总计3000 tokens仅记忆部分有冻结快照时第 1 轮系统提示 1000 tokens 对话 第 2 轮系统提示 0 tokensKV Cache 命中 对话 第 3 轮系统提示 0 tokensKV Cache 命中 对话 总计1000 tokens仅记忆部分注意一个容易踩的细节MEMORY.md 和 USER.md 文件在每轮对话时仍会读取以保证工具返回最新状态但系统提示的 token 计算被缓存了。也就是说磁盘上的记忆可以更新但当前会话的快照不变新记忆要等下一个会话才生效。2.2 KV cache 是「用空间换时间」LLM 生成回复时每个 token 都要算出 K特征标识向量和 V语义内容向量。以简化四维为例k1[-0.1, 0.5, 0.3, 0.8]v1[0.2, -0.3, 0.5, 0.6]实际维度是 512 或 4096。没有 KV cache每轮都要把系统提示的 1000 个 token 重新算一遍 K、V有了 KV cache第 2 轮直接复用只算新增对话的 10 个 token。无 KV cache3 轮 第 1 轮 1010 次计算 第 2 轮 1010 次计算 ← 系统提示重复算 第 3 轮 1010 次计算 ← 又重复 总计 3030 次浪费 2000 次66% 有 KV cache3 轮 第 1 轮 1010 次计算 缓存 K,V 第 2 轮 10 次计算复用系统提示 第 3 轮 10 次计算复用系统提示 总计 1030 次节省 2000 次66%代价是内存。以 Qwen3.5 为例模型维度约 5000每 token 缓存约 20KB1000 tokens 系统提示约 20MB128k 上下文约 2.5GB。计算量每次都要花 GPU 时间也就是钱内存是一次性占用相对便宜所以这笔交易划算。2.3 Prefix Cache 命中要求前缀字节级一致KV cache 和冻结快照的关系可以概括成系统提示不变KV Cache 才能复用。有冻结快照 第 1 轮 系统提示 快照 v1不变→ KV Cache 复用 第 2 轮 系统提示 快照 v1不变→ KV Cache 复用 第 3 轮 系统提示 快照 v1不变→ KV Cache 复用 节省 66% 计算量 没有冻结快照 第 1 轮 系统提示 MEMORY.md v1 → 计算 K,V 第 2 轮 系统提示 MEMORY.md v2变了→ KV Cache 失效 第 3 轮 系统提示 MEMORY.md v3又变了→ KV Cache 失效 节省 0%Prefix Cache 是推理服务侧对「相同前缀」的复用它比 KV cache 更严格前缀必须逐字节一致。系统提示里多一个空格、时间戳、随机 ID、动态拼接的工具列表都会让前缀变化命中率直接掉到 0。所以排查命中率低第一步永远是确认「发出去的请求前缀是否真的稳定」。3. TaoToken 前置统一 Key 让前缀稳定可复现3.1 为什么接入层会导致 cache 失效Hermes Agent 默认可能从多个来源取 Key环境变量、本地配置文件、不同 provider 的 endpoint。多来源混用时请求头、base_url、模型名、甚至 JSON 字段顺序都可能不一致。Prefix Cache 的命中判定发生在推理服务侧它看到的是最终拼好的请求体。只要请求体前缀有任何抖动缓存就废了。TaoToken 在这里的作用是提供一个统一的 API 入口和统一的 Key让 Hermes Agent 的所有请求走同一条路径、同一套鉴权、同一个 base_url。前缀稳定了Prefix Cache 才有命中的前提。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 不加 UTM。3.2 拿 Key 与确认模型登录后进入控制台在 API Keys 页面创建 Key。建议给 Hermes Agent 单独建一个 Key方便按项目统计用量和排查问题。创建后复制保存页面只显示一次。控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite拿不准模型名和参数时可以先用模型对话页面验证一次请求格式确认返回正常再写进配置模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite3.3 环境变量统一注入最稳的做法是把 Key 和 base_url 都放进环境变量Hermes Agent 和任何子进程都读同一份避免多来源覆盖。# ~/.hermes/env.sh export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export HERMES_MODEL你的模型名chmod x ~/.hermes/env.sh source ~/.hermes/env.sh # 验证 echo $TAOTOKEN_BASE_URL注意不要把 Key 写进会提交到 git 的 config.toml用环境变量引用。config.toml 里只写${TAOTOKEN_API_KEY}这种占位。4. 可复制配置config.toml 与 settings.json 骨架4.1 config.toml 骨架下面这份 config.toml 的关键点是provider 只有一个、base_url 固定、系统提示从快照读取而不是动态拼接、关闭会引入时间戳的字段。# ~/.hermes/config.toml [provider] name taotoken base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model ${HERMES_MODEL} timeout 120 [snapshot] # 冻结快照会话开始时注入会话期间不变 enabled true memory_file MEMORY.md user_file USER.md # 关键不要在系统提示里插入时间戳/随机ID否则前缀抖动 inject_timestamp false inject_session_id false [prefix_cache] # 让请求前缀稳定最大化命中 stable_system_prompt true sort_tools true strip_whitespace true [logging] level debug log_cache_stats true log_file ~/.hermes/logs/hermes.log4.2 settings.json 骨架settings.json 管的是运行时行为重点是消息顺序稳定、工具列表排序、不动态改系统提示。{ agent: { name: hermes, max_turns: 50, system_prompt_mode: frozen_snapshot, reload_memory_each_turn: true, apply_memory_to_snapshot: false }, request: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, model_env: HERMES_MODEL, stable_prefix: true, sort_tools: true, dedupe_messages: true }, cache: { enable_prefix_cache: true, log_hit_miss: true, warn_on_prefix_change: true } }两个配置里最容易被忽略的是inject_timestamp和inject_session_id。很多模板默认往系统提示里塞当前时间或会话 ID看起来方便调试实际上每轮前缀都不同Prefix Cache 永远命中不了。排查命中率低时先把这两个关掉。4.3 启动与加载source ~/.hermes/env.sh hermes --config ~/.hermes/config.toml --settings ~/.hermes/settings.json启动后确认日志里 provider 只有一个、base_url 是 https://taotoken.net/api 没有 fallback 到其他 endpoint。5. 验证请求用日志确认 cache 命中与快照冻结5.1 发一轮最小请求先用 curl 确认 TaoToken 侧请求格式正确再让 Hermes 跑多轮。curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $HERMES_MODEL, messages: [ {role: system, content: 你是一个编程助手。}, {role: user, content: 用 Go 写个 API} ] } | head -c 500返回正常后再跑 Hermes 多轮对话观察日志。5.2 看日志里的 cache 命中字段tail -f ~/.hermes/logs/hermes.log | grep -E cache|snapshot|prefix期望看到类似输出[snapshot] frozen at turn1, system_tokens1000 [turn 1] prefix_cachemiss, computed_tokens1010 [turn 2] prefix_cachehit, computed_tokens10 [turn 3] prefix_cachehit, computed_tokens10 [turn 4] prefix_cachehit, computed_tokens12如果第 2 轮开始还是miss说明前缀在变回到第 4 节检查inject_timestamp、inject_session_id、工具列表排序。5.3 对比命中与未命中的 token 消耗grep computed_tokens ~/.hermes/logs/hermes.log | awk -F {sum$2} END {print total computed:, sum}跑 10 轮对话命中正常时总计算量应该在 1100 左右首轮 1010 后续每轮约 10而不是 10100。这个数字对不上就说明 Prefix Cache 没生效。5.4 验证快照冻结是否生效在会话中途改 MEMORY.md然后继续对话观察日志echo 项目改用 PostgreSQL MEMORY.md # 继续第 5 轮对话 tail -n 20 ~/.hermes/logs/hermes.log | grep snapshot期望看到快照没有重建frozen at turn1保持不变说明当前会话快照冻结生效新记忆要等下一个会话。如果日志里出现snapshot rebuilt说明apply_memory_to_snapshot被打开了改回 false。6. 本篇常见错排查6.1 命中率一直是 0先查系统提示是否含动态内容。时间戳、会话 ID、随机数、动态工具列表都会让前缀变化。把inject_timestamp和inject_session_id设为 falsesort_tools设为 true再跑一轮看日志。6.2 第 1 轮命中第 2 轮开始 miss多半是消息顺序抖动或工具返回内容被塞进了系统提示。检查dedupe_messages是否开启工具返回是否被错误地拼进 system role。工具结果应该走 tool role不要混进 system。6.3 多来源 Key 导致请求头不一致如果环境里同时存在其他 provider 的 KeyHermes 可能 fallback。确认 config.toml 里 provider 只有一个且没有其他 base_url 配置。用env | grep -i key检查是否有冲突变量。6.4 快照没冻结每轮都重建检查 settings.json 里system_prompt_mode是否为frozen_snapshotapply_memory_to_snapshot是否为 false。如果用了自定义插件在每轮改系统提示也会导致快照重建需要把插件改成写磁盘而不是改快照。6.5 长会话里记忆过时这是冻结快照的已知代价会话内记忆更新不生效要等下一个会话。如果确实需要会话内即时生效可以手动结束当前会话开新的或者对特定场景关闭快照。但关闭后 Prefix Cache 命中率会掉需要权衡。6.6 内存占用过高KV cache 用空间换时间128k 上下文约 2.5GB 缓存。如果显存吃紧可以缩短系统提示、减少工具数量或者降低 max_turns。不要为了省内存关掉 Prefix Cache那样计算成本会翻几倍。6.7 日志里看不到 cache 字段确认 config.toml 里log_cache_stats truelogging level 为 debug。有些版本字段名是prefix_cache_hit而不是prefix_cache用grep -i cache宽匹配。排查顺序建议固定成先确认 provider 唯一和 base_url 正确再确认系统提示无动态内容再看日志 cache 字段最后验证快照冻结。按这个顺序走绝大多数命中率问题都能定位。长期跑编码任务或 Agent 工作流建议用 Coding Plan 把额度和模型统一管理避免多 Key 混用导致前缀抖动Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteClaude Code 场景的接入参考ClaudeCodeAnthropichttps://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite接入和排障遇到问题直接查接入文档最快接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite我自己的习惯是每次改完 config.toml 先跑 3 轮最小对话确认日志里第 2 轮开始是 hit 再上真实任务。这一步花两分钟能省掉后面几小时的排查。