Featured image of post Hermes 接入 New API 的提示词缓存排查:为什么 cached_tokens 总是 0

Hermes 接入 New API 的提示词缓存排查:为什么 cached_tokens 总是 0

Hermes Agent 通过 New API 调用 GPT、Grok、GLM、Claude 时提示词缓存不命中的排查指南:区分上游真没缓存和网关没记录两类问题,说明 named provider 与 transport 如何决定 prompt_cache_key,各模型应选的协议,New API 渠道亲和与流式 usage 的坑,以及逐层取证的验证方法。

-- 次浏览
-- 条评论

问题现象

这是 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_messagescache_control,必要时用 metadata.user_id 固定渠道
GPT精确前缀缓存,prompt_cache_key 辅助路由codex_responsesprompt_cache_key
Grok自动前缀缓存,Chat 和 Responses 用不同亲和字段codex_responsesResponses 用 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。

真正起作用的是这条因果链:

1
2
3
4
5
6
7
8
providers.<任意名称>.transport = codex_responses
  → Hermes 明确选择 Responses transport
  → 根据稳定的 instructions、tools 和会话 lineage 生成 prompt_cache_key
  → 放进 /v1/responses 请求体
  → New API 的 Responses 处理和 xAI adaptor 保留该字段
  → xAI Responses API 正好也支持 prompt_cache_key
  → xAI 把相关请求路由到同一台缓存服务器
  → 相同前缀的后续请求才更可能命中

生成 key 的代码见 agent/transports/codex.py,xAI 对该字段的说明见 官方文档。

Hermes 侧:普通 custom 会悄悄回退到 Chat

第二个坑是下面这种写法:

1
2
3
4
model:
  provider: custom
  base_url: https://newapi.example.com/v1
  api_mode: codex_responses

看起来已经指定了 Responses,但 Hermes 会把普通 custom 端点当作未知的兼容服务。为了避免把只支持 /chat/completions 的服务错误地请求成 /responses,域名不是已知的 OpenAI 或 xAI 地址时,它会忽略这个 api_mode 并回退到 chat_completions,日志里只有一行 info:

1
Ignoring persisted custom api_mode=codex_responses for non-OpenAI endpoint

回退之后就没有 prompt_cache_key 了。这个行为在 v0.23.0 中仍然存在(hermes_cli/runtime_provider.py)。

正确做法是按协议拆成 named provider,在 provider 上声明 transport:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
providers:
  newapi-gpt:
    api: https://newapi.example.com/v1
    key_env: NEWAPI_API_KEY
    transport: codex_responses
    discover_models: false
    models:
      gpt-5.6: {}

  newapi-grok:
    api: https://newapi.example.com/v1
    key_env: NEWAPI_API_KEY
    transport: codex_responses
    discover_models: false
    models:
      grok-4.7: {}

  newapi-glm:
    api: https://newapi.example.com/v1
    key_env: NEWAPI_API_KEY
    transport: chat_completions
    discover_models: false
    models:
      glm-5.3: {}

model:
  provider: custom:newapi-grok
  default: grok-4.7

会话中切换模型时,也用具体的 named provider:

1
2
/model custom:newapi-gpt:gpt-5.6
/model custom:newapi-glm:glm-5.3

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:

1
2
3
4
5
6
7
providers:
  newapi-gpt-chat:
    api: https://newapi.example.com/v1
    key_env: NEWAPI_API_KEY
    transport: chat_completions
    extra_body:
      prompt_cache_key: hermes-gpt-workflow-v1

这个 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 的默认亲和规则只覆盖了这一种情况(源码):

1
2
3
model: ^gpt-.*$
path: /v1/responses
key: prompt_cache_key

也就是说,GPT Responses 默认能按 Hermes 的 key 固定渠道,但 Grok Responses、GLM Chat,以及 openai/gpt-* 这类带前缀的模型名都不在范围内。可以增加一条自定义规则:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "name": "hermes non-claude cache affinity",
  "model_regex": ["^gpt-.*$", "^grok-.*$", "^glm-.*$"],
  "path_regex": ["^/v1/(responses|chat/completions)$"],
  "key_sources": [
    { "type": "gjson", "path": "prompt_cache_key" },
    { "type": "context_int", "key": "id" }
  ],
  "ttl_seconds": 3600,
  "skip_retry_on_failure": false,
  "include_using_group": true,
  "include_model_name": true,
  "include_rule_name": true
}

含义:

  • 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 内完成,验证期间只启用一个渠道。然后检查:

1
2
GPT / Grok Responses:usage.input_tokens_details.cached_tokens
GPT / GLM Chat:      usage.prompt_tokens_details.cached_tokens

如果直接请求都命中不了,问题和 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 聚合丢了字段。

判定标准

最终只认这一条:

1
同一真实上游 + 同一稳定前缀 + 后续请求的 cached_tokens > 0

并且 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:

New API:

总结

最终推荐的拓扑(中间都经过 New API,连线上标的是 New API 的入口路径):

这套拆分的重点不是"给每个模型都打开缓存”,而是让每个模型使用它真实上游认可的缓存协议,并让同一个稳定前缀尽量落到同一个缓存命名空间。排查时从 Hermes 请求、New API 转发、上游原始 usage、New API 日志四层逐层取证,不要凭一个 0 下结论。