问题现象
这是 Hermes Agent 架构系列的番外排查篇,背景见 模型篇。
Agent 每轮请求都会带上很长的固定前缀:系统提示词、技能列表、工具定义、记忆。理论上这正是提示词缓存(Prompt Cache)最擅长的场景,命中后输入费用能降一大截。
我在把 Hermes 接入自建的 New API 网关时,专门排查过一次提示词缓存:New API 消费日志里的 cache_tokens 显示为 0,看不出缓存到底有没有生效。
排查下来的结论是:不同厂商的提示词缓存根本不是同一种协议,Hermes 侧选什么 transport、New API 怎么路由渠道、网关如何统计 usage,每一层都可能让缓存失效或"看起来失效"。
环境与前提
- Hermes Agent 通过自定义 provider 接入 New API,调用 GPT、Grok、GLM,Claude 作为补充说明。
- 文中 Hermes 的关键行为已在
v0.23.0上核对;源码链接基于排查时的main@f751a8c(对应正式版v0.20.5前后)。 - New API 的结论基于
v1.0.0-rc.25(main@2d8e50b)。New API 更新较快,涉及 New API 的缺口请以你实际运行的版本为准。 - 示例域名统一使用
newapi.example.com。
先给结论
| 模型家族 | 上游缓存机制 | Hermes 推荐 transport | 缓存亲和字段 |
|---|---|---|---|
| Claude | 显式 cache_control 断点 | anthropic_messages | cache_control,必要时用 metadata.user_id 固定渠道 |
| GPT | 精确前缀缓存,prompt_cache_key 辅助路由 | codex_responses | prompt_cache_key |
| Grok | 自动前缀缓存,Chat 和 Responses 用不同亲和字段 | codex_responses | Responses 用 prompt_cache_key,Chat 用 x-grok-conv-id |
| GLM | 自动隐式上下文缓存 | chat_completions | 无专用字段,保证前缀稳定并固定渠道 |
对应的做法:
- Claude 走 New API 原生的
/v1/messages,不要经过 OpenAI Chat 到 Claude Messages 的转换。 - GPT 和 Grok 优先走
/v1/responses,让 Hermes 自动生成稳定的prompt_cache_key。 - GLM 保持
/v1/chat/completions,依赖上游自动缓存。 - 非 Claude 模型不要开 Hermes 的
prompt_caching,它只用于 Anthropic 风格的cache_control。 - New API 有多个候选渠道时,一定要配置渠道亲和。
cache_tokens = 0不一定是上游没缓存,也可能是 New API 统计时丢了字段。
排查过程
先分清是哪一类问题
“缓存是 0"其实有两种完全不同的情况:
第一类:上游真的没命中。 Hermes 请求的前缀变了、缺少亲和字段、或者被分散到不同渠道,上游响应里的 cached_tokens 本身就是 0,New API 按普通输入计费。常见原因:
- 系统提示词、工具定义、消息顺序或模型名发生变化;
- 输入没达到模型的最低可缓存长度;
- 请求落到了不同的上游 API Key、组织、区域或模型实例;
- 两次请求间隔超过了缓存 TTL;
- 协议选错,或者缺少
prompt_cache_key、x-grok-conv-id,高并发时被路由到没有缓存的机器; - 渠道其实不是官方上游,模型名一样,但缓存能力和计费规则不同。
第二类:上游命中了,但 New API 没记下来。 上游响应里 cached_tokens > 0,New API 在协议转换或流式聚合时丢了这部分 usage,日志里显示 0,本地计费和上游真实成本对不上。
判断属于哪一类,要同时对比三样东西:New API 发往上游的请求、上游原始响应里的 usage、New API 最终消费日志里的 cache_tokens 和 cache_creation_tokens。只看前端那一列 0,下不了结论。
Hermes 侧:provider 名字不会启用缓存
第一个误区是以为把 provider 命名为 newapi-grok,Hermes 就会按 Grok 处理。实际上这个名字只是 providers 下的一个引用键,改成 my-router 效果完全一样,Hermes 不会因为名字里有 grok 就把它识别成 xAI。
真正起作用的是这条因果链:
| |
生成 key 的代码见 agent/transports/codex.py,xAI 对该字段的说明见 官方文档。
Hermes 侧:普通 custom 会悄悄回退到 Chat
第二个坑是下面这种写法:
| |
看起来已经指定了 Responses,但 Hermes 会把普通 custom 端点当作未知的兼容服务。为了避免把只支持 /chat/completions 的服务错误地请求成 /responses,域名不是已知的 OpenAI 或 xAI 地址时,它会忽略这个 api_mode 并回退到 chat_completions,日志里只有一行 info:
| |
回退之后就没有 prompt_cache_key 了。这个行为在 v0.23.0 中仍然存在(hermes_cli/runtime_provider.py)。
正确做法是按协议拆成 named provider,在 provider 上声明 transport:
| |
会话中切换模型时,也用具体的 named provider:
| |
Hermes 侧:能拿到 cache key,不等于完整的 xAI 支持
custom:newapi-grok 在 Hermes 内部仍然是 custom provider。只有 provider 是 xai / xai-oauth,或者主机名是 api.x.ai 时,Hermes 才会启用 xAI 专用行为(判断代码,v0.23.0 中逻辑未变)。
| 能力 | custom:newapi-grok + codex_responses |
|---|---|
请求 New API 的 /v1/responses | 可以 |
生成通用的 prompt_cache_key | 可以 |
| New API 把 key 转发给 xAI | 可以,前提是渠道走 Responses 且没有被参数覆盖删掉 |
| xAI 根据 key 做缓存路由 | 可以 |
| Hermes 把它完整识别为 xAI | 不可以 |
自动发送 Chat 专用的 x-grok-conv-id | 不可以 |
| 自动套用全部 Grok reasoning 参数规则 | 不可以 |
自动过滤 xAI 不支持的 include、service_tier 等字段 | 不保证 |
所以会出现"缓存能命中,但某些 Grok 型号报 reasoning.effort、include 或 service_tier 不支持"的情况。这是 xAI transport 兼容性问题,不是缓存问题。
各模型的具体情况
GPT
OpenAI 的提示词缓存要求渲染后的完整前缀匹配;GPT-5.6 及以后最低可缓存长度为 1024 tokens,更早的模型通常需要 2048。model、tools、系统指令、历史消息都会影响前缀。prompt_cache_key 是路由提示,不保证命中,但高并发时能减少请求被分到没有缓存的机器(官方文档)。
推荐链路:Hermes codex_responses → New API /v1/responses → OpenAI Responses。New API 的 Responses 处理在流式和非流式下都会记录 usage.input_tokens_details.cached_tokens。
如果某个 GPT 上游只支持 Chat Completions,Hermes 不会给自定义域名自动加 prompt_cache_key。确认上游接受该字段后,可以给 provider 配一个固定的 key:
| |
这个 key 按系统提示词和工具版本划分,不要带时间戳,也不要每轮随机生成。
Grok
xAI 的缓存规则:相邻请求开头完全相同时自动复用;Chat Completions 用 x-grok-conv-id 请求头把同一会话路由到同一台服务器,Responses API 用请求体里的 prompt_cache_key 达到同样效果。缓存存在具体服务器上,所以粘性路由对命中率非常关键(官方文档)。
走 Chat 很容易丢缓存,原因有两层:
- Hermes 不知道 custom provider 背后是 xAI,不会自动发
x-grok-conv-id;New API 默认也不透传任意请求头,需要显式配置pass_headers。 - New API
rc.25的xAIStreamHandler在流式聚合 usage 时只复制了PromptTokens、TotalTokens、CompletionTokens,丢了PromptTokensDetails.CachedTokens(源码)。结果是 xAI 实际命中了缓存,New API 日志和本地计费却显示 0。非流式处理返回完整 usage,可以用stream: false做对照。
所以 Grok 优先走 Responses:Hermes 生成 key,New API 保留字段并正确记录 cached_tokens,同时绕开了 Chat 流式统计的缺口。
如果必须继续用 Chat,需要同时满足三点:Hermes 发出稳定的 x-grok-conv-id、New API 渠道允许透传这个请求头、New API 修复流式 usage 聚合。
GLM
智谱 GLM 使用自动上下文缓存,不需要手动加任何缓存字段,重复的系统提示词和多轮历史会被自动识别,命中情况在 usage.prompt_tokens_details.cached_tokens 中(官方文档)。注意小的格式变化也会降低命中。
所以 GLM 保持 transport: chat_completions,不要开 prompt_caching。New API 的智谱适配器会重建请求,但保留消息、工具和顺序;它不保留 prompt_cache_key,不过 GLM 本来也不依赖这个字段。New API 读取智谱 usage 时会依次尝试 prompt_tokens_details.cached_tokens、input_tokens_details.cached_tokens、cached_tokens、prompt_cache_hit_tokens 几种格式。
另外,New API rc.25 的智谱适配器还没有实现 Responses 转换,所以 GLM 不能和 GPT、Grok 一起统一切到 Responses。
Claude
Claude 要走原生链路:Hermes anthropic_messages → New API /v1/messages → Claude Messages 上游。
不要让它经过 New API 的 OpenAI Chat → Claude Messages 转换。rc.25 在这个转换里重建 system 和文本块时没有复制 CacheControl(system、文本块),缓存断点在半路就丢了。原生 Claude 渠道直接透传原请求,没有这个问题。
New API 侧:渠道亲和
New API 一个模型配了多个渠道时,同一会话的请求可能在不同账号、区域或实例之间轮换,每换一次都是一次冷启动。渠道亲和就是让相关请求尽量落到同一个渠道。
rc.25 的默认亲和规则只覆盖了这一种情况(源码):
| |
也就是说,GPT Responses 默认能按 Hermes 的 key 固定渠道,但 Grok Responses、GLM Chat,以及 openai/gpt-* 这类带前缀的模型名都不在范围内。可以增加一条自定义规则:
| |
含义:
- GPT、Grok 的 Responses 请求优先按请求体里的
prompt_cache_key固定渠道; - GLM Chat 没有这个字段,退回按 New API 的用户 ID 固定;
skip_retry_on_failure: false偏向可用性,固定的渠道失败后允许换,但换过去的第一次请求会冷启动;改成true亲和更强,但渠道故障时不会自动换路。
几个注意点:规则按顺序匹配,先命中的生效;model_regex 匹配的是进入 New API 时的模型名,不是映射后的上游模型名;如果每个模型本来就只有一个渠道,亲和规则就不是必需的。
验证方法
先不用 Hermes,直接测 New API
直接向 New API 连续发两三次请求:模型、系统提示词、工具及其顺序、长历史前缀都相同,只改最后一条用户消息,在缓存 TTL 内完成,验证期间只启用一个渠道。然后检查:
| |
如果直接请求都命中不了,问题和 Hermes 无关,去查上游、模型支持、前缀和渠道路由。
再验证 Hermes
逐项确认:
- GPT、Grok 的 provider 确实是
transport: codex_responses,GLM 是chat_completions; - 没有给非 Claude 模型开
prompt_caching; - Responses 请求体里有
prompt_cache_key,并且跨轮稳定; - 连续几轮被 New API 分到了同一个渠道;
- 系统提示词、工具和早期消息逐字稳定。
Grok 流式与非流式对照
对同一个 Grok Chat 渠道,用相同的长前缀和亲和 ID 分别发 stream: false 和 stream: true 的请求。如果非流式 cache_tokens > 0、流式等于 0,基本可以确定是 New API 流式 usage 聚合丢了字段。
判定标准
最终只认这一条:
| |
并且 New API 日志记录了相同的缓存量。只看到配置名、key 存在或渠道固定,都只能说明链路可能生效,不能证明命中。
不要这样做
- 只调 New API 的缓存倍率。 如果上游真实
cached_tokens = 0,调低cache_ratio只是本地少扣费,上游照常收钱,真实成本一分没降。 - 给所有模型开
prompt_caching。 这会把 Anthropic 风格的cache_control注入 GPT、Grok、GLM 请求,轻则被忽略,重则改变消息结构或被严格的上游拒绝。 - 每轮生成不同的 cache key。 时间戳、随机 UUID 都会把本可复用的请求打散。key 应该对应稳定的提示词和工具版本,或者稳定的会话。
- 只看第一次请求。 第一次通常是冷请求或写入缓存,要看后续相同前缀的请求。
- 把代码推断当成实测结果。 读代码只能说明字段可能被发送、丢失或解析,最终要用真实请求验证。
相关 issue 与 PR
Hermes Agent:
- LiteLLM OpenAI wire 0 缓存问题 #84506,修复 #87517
- Anthropic 自定义模型别名缓存 #85554
- custom OpenAI Chat provider 的逐模型缓存声明 #93321
- GPT-5.6 显式 cache breakpoint 讨论 #70382
New API:
- OpenAI 格式请求 Claude 渠道的缓存计费问题 #1601
- Chat/Claude 转 Responses 丢失 prompt cache key #6538
- Claude Messages 转 OpenAI 残留
cache_control#5982 - Claude 转 OpenAI 的 cache control 和 prompt key 相关 PR #6691
总结
最终推荐的拓扑(中间都经过 New API,连线上标的是 New API 的入口路径):
这套拆分的重点不是"给每个模型都打开缓存”,而是让每个模型使用它真实上游认可的缓存协议,并让同一个稳定前缀尽量落到同一个缓存命名空间。排查时从 Hermes 请求、New API 转发、上游原始 usage、New API 日志四层逐层取证,不要凭一个 0 下结论。
