Hermes-Agent 缓存命中率突然暴跌？排查思路与解决方案

最近折腾 AI 代理的时候，真的遇到个让人头秃的问题。

一直跑得好好的 hermes-agent，昨天开始突然“摆烂”。我现在的组合拳是用 NewAPI 接入了商汤、魔搭、官方等多个上游，主要用来玩 GPT-4 之类的模型。按理说这种配置，缓存命中率应该很稳才对，结果后台一看，数据惨不忍睹——大部分时候全是 0 命中。

NewAPI后台数据显示缓存命中率极低

NewAPI后台配置截图查看细节

这就直接导致了一个很直接的后果：首字生成慢，整体延迟拉高，用户体验极差。排查了一圈，发现很玄学：

• Cron 定时任务： 命中率完全正常，说明缓存机制本身没烂。
• 其他调用方式（如 opencode）： 也是正常的。
• 唯独主 Agent： 命中率雪崩。

针对这种情况，我整理了一些排查思路，如果你也遇到了类似的问题，可以从这几个角度下手检查，别急着重装。

1. 检查 Prompt 和参数的一致性

缓存命中的核心前提是“请求完全一致”。哪怕只是多了一个空格、参数精度（比如 temperature 从 0.7 变成 0.7000001）的微小差异，或者系统偷偷加上了默认参数，都会导致缓存失效。

• 排查点： 检查最近是不是调整了 System Prompt 或者前端默认参数？有些集成环境会在请求头里加 metadata，导致 Key 变化。

2. NewAPI 的上游轮询策略

既然用了 NewAPI 接入多上游，要确认是不是负载均衡策略变了。

• 排查点： 即使请求内容一样，如果 NewAPI 在多次请求中随机切换了不同的上游渠道，而 hermes-agent 是基于渠道 ID 或者响应头来计算缓存 Key 的，那命中率自然就上不去。建议暂时固定只走一个上游测试，看看命中率是否回升。

3. Redis 或缓存存储层的 Key 冲突

如果 Cron 任务和主 Agent 走的是不同的缓存前缀或者逻辑，可能会导致互相覆盖或无法读取。

• 排查点： 确认一下 hermes-agent 的配置文件，是否有区分不同调用入口的缓存命名空间。如果 Cron 一直在热车，但主 Agent 读不到，可能是配置里的 Path 路由规则写串了。

4. 网络“中间人”搞鬼

有时候看起来是缓存问题，其实是网络层的问题。

• 排查点： 检查一下有没有开启 SSL MitM（中间人代理）。如果代理层对请求体进行了重写（比如格式变化），虽然发出去的内容一样，但对缓存中间件来说，这就变成了两个不同的 Request。

解决方案建议

既然其他入口正常，主 Agent 异常，大概率是请求特征发生了微小变化。

1. 开启 Debug 日志： 临时把 hermes-agent 的日志级别调到 Debug，对比一下“命中高”的 Cron 请求和“0 命中”的主 Agent 请求，看看到底哪个字段不一样（通常是 model name 或额外的 query param）。
2. 重置缓存池： 极端情况下，可能是缓存索引坏了（虽然少见）。尝试清空一下 Redis 对应的 DB，重启 Agent 让它重新建立缓存索引。
3. 标准化请求参数： 在发给 Agent 之前，先在网关层把请求参数“清洗”一遍，强制对齐 Temperature、Max_Tokens 等精度，剔除多余字段。

折腾了一圈，如果还没解决，大概率是上游接口返回了某些新字段导致匹配失败。先别慌，按上边这几点查，大概率能揪出那个捣乱的参数。