<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>GLM on 记录点滴 - 分享</title><link>https://www.iminling.com/tags/glm/</link><description>Recent content in GLM on 记录点滴 - 分享</description><generator>Hugo -- gohugo.io</generator><language>zh-cn</language><copyright>iminling.com</copyright><lastBuildDate>Thu, 19 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://www.iminling.com/tags/glm/index.xml" rel="self" type="application/rss+xml"/><item><title>Hermes 接入 New API 的提示词缓存排查：为什么 cached_tokens 总是 0</title><link>https://www.iminling.com/ai/hermes/hermes-agent-newapi-prompt-cache/</link><pubDate>Thu, 19 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.iminling.com/ai/hermes/hermes-agent-newapi-prompt-cache/</guid><description>&lt;img src="https://images.iminling.com/i/2026/11/19/e78b7dc1f3976415b6b20150e7e36433.webp" alt="Featured image of post Hermes 接入 New API 的提示词缓存排查：为什么 cached_tokens 总是 0" /&gt;&lt;h2 id="问题现象"&gt;问题现象&#10;&lt;/h2&gt;&lt;p&gt;这是 Hermes Agent 架构系列的番外排查篇，背景见 &lt;a class="link" href="https://www.iminling.com/ai/hermes/hermes-agent-model-config/" &gt;模型篇&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;Agent 每轮请求都会带上很长的固定前缀：系统提示词、技能列表、工具定义、记忆。理论上这正是提示词缓存（Prompt Cache）最擅长的场景，命中后输入费用能降一大截。&lt;/p&gt;&#10;&lt;p&gt;我在把 Hermes 接入自建的 New API 网关时，专门排查过一次提示词缓存：New API 消费日志里的 &lt;code&gt;cache_tokens&lt;/code&gt; 显示为 &lt;code&gt;0&lt;/code&gt;，看不出缓存到底有没有生效。&lt;/p&gt;&#10;&lt;p&gt;排查下来的结论是：&lt;strong&gt;不同厂商的提示词缓存根本不是同一种协议&lt;/strong&gt;，Hermes 侧选什么 &lt;code&gt;transport&lt;/code&gt;、New API 怎么路由渠道、网关如何统计 usage，每一层都可能让缓存失效或&amp;quot;看起来失效&amp;quot;。&lt;/p&gt;&#10;&lt;h2 id="环境与前提"&gt;环境与前提&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;Hermes Agent 通过自定义 provider 接入 New API，调用 GPT、Grok、GLM，Claude 作为补充说明。&lt;/li&gt;&#10;&lt;li&gt;文中 Hermes 的关键行为已在 &lt;code&gt;v0.23.0&lt;/code&gt; 上核对；源码链接基于排查时的 &lt;code&gt;main@f751a8c&lt;/code&gt;（对应正式版 &lt;code&gt;v0.20.5&lt;/code&gt; 前后）。&lt;/li&gt;&#10;&lt;li&gt;New API 的结论基于 &lt;code&gt;v1.0.0-rc.25&lt;/code&gt;（&lt;code&gt;main@2d8e50b&lt;/code&gt;）。New API 更新较快，&lt;strong&gt;涉及 New API 的缺口请以你实际运行的版本为准&lt;/strong&gt;。&lt;/li&gt;&#10;&lt;li&gt;示例域名统一使用 &lt;code&gt;newapi.example.com&lt;/code&gt;。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="先给结论"&gt;先给结论&#10;&lt;/h2&gt;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;模型家族&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;上游缓存机制&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;Hermes 推荐 &lt;code&gt;transport&lt;/code&gt;&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;缓存亲和字段&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Claude&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;显式 &lt;code&gt;cache_control&lt;/code&gt; 断点&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;anthropic_messages&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;cache_control&lt;/code&gt;，必要时用 &lt;code&gt;metadata.user_id&lt;/code&gt; 固定渠道&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;GPT&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;精确前缀缓存，&lt;code&gt;prompt_cache_key&lt;/code&gt; 辅助路由&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;codex_responses&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;prompt_cache_key&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Grok&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动前缀缓存，Chat 和 Responses 用不同亲和字段&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;codex_responses&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Responses 用 &lt;code&gt;prompt_cache_key&lt;/code&gt;，Chat 用 &lt;code&gt;x-grok-conv-id&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;GLM&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动隐式上下文缓存&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;chat_completions&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;无专用字段，保证前缀稳定并固定渠道&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;对应的做法：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;Claude 走 New API 原生的 &lt;code&gt;/v1/messages&lt;/code&gt;，不要经过 OpenAI Chat 到 Claude Messages 的转换。&lt;/li&gt;&#10;&lt;li&gt;GPT 和 Grok 优先走 &lt;code&gt;/v1/responses&lt;/code&gt;，让 Hermes 自动生成稳定的 &lt;code&gt;prompt_cache_key&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;GLM 保持 &lt;code&gt;/v1/chat/completions&lt;/code&gt;，依赖上游自动缓存。&lt;/li&gt;&#10;&lt;li&gt;非 Claude 模型不要开 Hermes 的 &lt;code&gt;prompt_caching&lt;/code&gt;，它只用于 Anthropic 风格的 &lt;code&gt;cache_control&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;New API 有多个候选渠道时，一定要配置渠道亲和。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;cache_tokens = 0&lt;/code&gt; 不一定是上游没缓存，也可能是 New API 统计时丢了字段。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="排查过程"&gt;排查过程&#10;&lt;/h2&gt;&lt;h3 id="先分清是哪一类问题"&gt;先分清是哪一类问题&#10;&lt;/h3&gt;&lt;p&gt;&amp;ldquo;缓存是 0&amp;quot;其实有两种完全不同的情况：&lt;/p&gt;&#10;&lt;p&gt;&lt;strong&gt;第一类：上游真的没命中。&lt;/strong&gt; Hermes 请求的前缀变了、缺少亲和字段、或者被分散到不同渠道，上游响应里的 &lt;code&gt;cached_tokens&lt;/code&gt; 本身就是 0，New API 按普通输入计费。常见原因：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;系统提示词、工具定义、消息顺序或模型名发生变化；&lt;/li&gt;&#10;&lt;li&gt;输入没达到模型的最低可缓存长度；&lt;/li&gt;&#10;&lt;li&gt;请求落到了不同的上游 API Key、组织、区域或模型实例；&lt;/li&gt;&#10;&lt;li&gt;两次请求间隔超过了缓存 TTL；&lt;/li&gt;&#10;&lt;li&gt;协议选错，或者缺少 &lt;code&gt;prompt_cache_key&lt;/code&gt;、&lt;code&gt;x-grok-conv-id&lt;/code&gt;，高并发时被路由到没有缓存的机器；&lt;/li&gt;&#10;&lt;li&gt;渠道其实不是官方上游，模型名一样，但缓存能力和计费规则不同。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;&lt;strong&gt;第二类：上游命中了，但 New API 没记下来。&lt;/strong&gt; 上游响应里 &lt;code&gt;cached_tokens &amp;gt; 0&lt;/code&gt;，New API 在协议转换或流式聚合时丢了这部分 usage，日志里显示 0，本地计费和上游真实成本对不上。&lt;/p&gt;&#10;&lt;p&gt;判断属于哪一类，要同时对比三样东西：New API 发往上游的请求、上游原始响应里的 usage、New API 最终消费日志里的 &lt;code&gt;cache_tokens&lt;/code&gt; 和 &lt;code&gt;cache_creation_tokens&lt;/code&gt;。&lt;strong&gt;只看前端那一列 0，下不了结论。&lt;/strong&gt;&lt;/p&gt;&#10;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart TB&#10; Start[cache_tokens = 0] --&gt; Q1{Hermes 请求里&lt;br/&gt;有所需的亲和字段吗}&#10; Q1 --&gt;|没有| R1[Hermes provider / transport 配置问题]&#10; Q1 --&gt;|有| Q2{New API 发往上游时&lt;br/&gt;字段还在吗}&#10; Q2 --&gt;|丢了| R2[New API adaptor 或参数覆盖问题]&#10; Q2 --&gt;|在| Q3{上游原始 usage&lt;br/&gt;cached_tokens &gt; 0 ?}&#10; Q3 --&gt;|等于 0| R3[前缀、长度、TTL、模型支持或渠道轮换问题]&#10; Q3 --&gt;|大于 0| R4[New API usage 解析或流式聚合问题]&lt;/pre&gt;&lt;h3 id="hermes-侧provider-名字不会启用缓存"&gt;Hermes 侧：provider 名字不会启用缓存&#10;&lt;/h3&gt;&lt;p&gt;第一个误区是以为把 provider 命名为 &lt;code&gt;newapi-grok&lt;/code&gt;，Hermes 就会按 Grok 处理。实际上这个名字只是 &lt;code&gt;providers&lt;/code&gt; 下的一个引用键，改成 &lt;code&gt;my-router&lt;/code&gt; 效果完全一样，Hermes 不会因为名字里有 &lt;code&gt;grok&lt;/code&gt; 就把它识别成 xAI。&lt;/p&gt;&#10;&lt;p&gt;真正起作用的是这条因果链：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;span class="lnt"&gt;8&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;providers.&amp;lt;任意名称&amp;gt;.transport = codex_responses&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → Hermes 明确选择 Responses transport&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → 根据稳定的 instructions、tools 和会话 lineage 生成 prompt_cache_key&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → 放进 /v1/responses 请求体&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → New API 的 Responses 处理和 xAI adaptor 保留该字段&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → xAI Responses API 正好也支持 prompt_cache_key&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → xAI 把相关请求路由到同一台缓存服务器&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; → 相同前缀的后续请求才更可能命中&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;生成 key 的代码见 &lt;a class="link" href="https://github.com/NousResearch/hermes-agent/blob/f751a8c5467c41500e505d90cb0eb8b70929080f/agent/transports/codex.py#L600-L623" target="_blank" rel="noopener"&#10; &gt;agent/transports/codex.py&lt;/a&gt;，xAI 对该字段的说明见 &lt;a class="link" href="https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits" target="_blank" rel="noopener"&#10; &gt;官方文档&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h3 id="hermes-侧普通-custom-会悄悄回退到-chat"&gt;Hermes 侧：普通 custom 会悄悄回退到 Chat&#10;&lt;/h3&gt;&lt;p&gt;第二个坑是下面这种写法：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;base_url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api_mode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;codex_responses&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;看起来已经指定了 Responses，但 Hermes 会把普通 custom 端点当作未知的兼容服务。为了避免把只支持 &lt;code&gt;/chat/completions&lt;/code&gt; 的服务错误地请求成 &lt;code&gt;/responses&lt;/code&gt;，域名不是已知的 OpenAI 或 xAI 地址时，它会&lt;strong&gt;忽略这个 &lt;code&gt;api_mode&lt;/code&gt; 并回退到 &lt;code&gt;chat_completions&lt;/code&gt;&lt;/strong&gt;，日志里只有一行 info：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;Ignoring persisted custom api_mode=codex_responses for non-OpenAI endpoint&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;回退之后就没有 &lt;code&gt;prompt_cache_key&lt;/code&gt; 了。这个行为在 &lt;code&gt;v0.23.0&lt;/code&gt; 中仍然存在（&lt;code&gt;hermes_cli/runtime_provider.py&lt;/code&gt;）。&lt;/p&gt;&#10;&lt;p&gt;正确做法是按协议拆成 named provider，在 provider 上声明 &lt;code&gt;transport&lt;/code&gt;：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;span class="lnt"&gt;15&#10;&lt;/span&gt;&lt;span class="lnt"&gt;16&#10;&lt;/span&gt;&lt;span class="lnt"&gt;17&#10;&lt;/span&gt;&lt;span class="lnt"&gt;18&#10;&lt;/span&gt;&lt;span class="lnt"&gt;19&#10;&lt;/span&gt;&lt;span class="lnt"&gt;20&#10;&lt;/span&gt;&lt;span class="lnt"&gt;21&#10;&lt;/span&gt;&lt;span class="lnt"&gt;22&#10;&lt;/span&gt;&lt;span class="lnt"&gt;23&#10;&lt;/span&gt;&lt;span class="lnt"&gt;24&#10;&lt;/span&gt;&lt;span class="lnt"&gt;25&#10;&lt;/span&gt;&lt;span class="lnt"&gt;26&#10;&lt;/span&gt;&lt;span class="lnt"&gt;27&#10;&lt;/span&gt;&lt;span class="lnt"&gt;28&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-gpt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;NEWAPI_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;codex_responses&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;discover_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;gpt-5.6&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;{}&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-grok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;NEWAPI_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;codex_responses&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;discover_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;grok-4.7&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;{}&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-glm&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;NEWAPI_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;chat_completions&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;discover_models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;models&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;glm-5.3&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;{}&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;model&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;provider&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;custom:newapi-grok&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;grok-4.7&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;会话中切换模型时，也用具体的 named provider：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;/model custom:newapi-gpt:gpt-5.6&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;/model custom:newapi-glm:glm-5.3&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;h3 id="hermes-侧能拿到-cache-key不等于完整的-xai-支持"&gt;Hermes 侧：能拿到 cache key，不等于完整的 xAI 支持&#10;&lt;/h3&gt;&lt;p&gt;&lt;code&gt;custom:newapi-grok&lt;/code&gt; 在 Hermes 内部仍然是 custom provider。只有 provider 是 &lt;code&gt;xai&lt;/code&gt; / &lt;code&gt;xai-oauth&lt;/code&gt;，或者主机名是 &lt;code&gt;api.x.ai&lt;/code&gt; 时，Hermes 才会启用 xAI 专用行为（&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/blob/f751a8c5467c41500e505d90cb0eb8b70929080f/agent/chat_completion_helpers.py#L1884-L1903" target="_blank" rel="noopener"&#10; &gt;判断代码&lt;/a&gt;，&lt;code&gt;v0.23.0&lt;/code&gt; 中逻辑未变）。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;能力&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;&lt;code&gt;custom:newapi-grok&lt;/code&gt; + &lt;code&gt;codex_responses&lt;/code&gt;&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;请求 New API 的 &lt;code&gt;/v1/responses&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;生成通用的 &lt;code&gt;prompt_cache_key&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;New API 把 key 转发给 xAI&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;可以，前提是渠道走 Responses 且没有被参数覆盖删掉&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;xAI 根据 key 做缓存路由&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Hermes 把它完整识别为 xAI&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;不可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动发送 Chat 专用的 &lt;code&gt;x-grok-conv-id&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;不可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动套用全部 Grok reasoning 参数规则&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;不可以&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;自动过滤 xAI 不支持的 &lt;code&gt;include&lt;/code&gt;、&lt;code&gt;service_tier&lt;/code&gt; 等字段&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;不保证&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;所以会出现&amp;quot;缓存能命中，但某些 Grok 型号报 &lt;code&gt;reasoning.effort&lt;/code&gt;、&lt;code&gt;include&lt;/code&gt; 或 &lt;code&gt;service_tier&lt;/code&gt; 不支持&amp;quot;的情况。这是 xAI transport 兼容性问题，不是缓存问题。&lt;/p&gt;&#10;&lt;h2 id="各模型的具体情况"&gt;各模型的具体情况&#10;&lt;/h2&gt;&lt;h3 id="gpt"&gt;GPT&#10;&lt;/h3&gt;&lt;p&gt;OpenAI 的提示词缓存要求渲染后的完整前缀匹配；GPT-5.6 及以后最低可缓存长度为 1024 tokens，更早的模型通常需要 2048。model、tools、系统指令、历史消息都会影响前缀。&lt;code&gt;prompt_cache_key&lt;/code&gt; 是路由提示，不保证命中，但高并发时能减少请求被分到没有缓存的机器（&lt;a class="link" href="https://developers.openai.com/api/docs/guides/prompt-caching/" target="_blank" rel="noopener"&#10; &gt;官方文档&lt;/a&gt;）。&lt;/p&gt;&#10;&lt;p&gt;推荐链路：Hermes &lt;code&gt;codex_responses&lt;/code&gt; → New API &lt;code&gt;/v1/responses&lt;/code&gt; → OpenAI Responses。New API 的 Responses 处理在流式和非流式下都会记录 &lt;code&gt;usage.input_tokens_details.cached_tokens&lt;/code&gt;。&lt;/p&gt;&#10;&lt;p&gt;如果某个 GPT 上游只支持 Chat Completions，Hermes 不会给自定义域名自动加 &lt;code&gt;prompt_cache_key&lt;/code&gt;。确认上游接受该字段后，可以给 provider 配一个固定的 key：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;span class="lnt"&gt;4&#10;&lt;/span&gt;&lt;span class="lnt"&gt;5&#10;&lt;/span&gt;&lt;span class="lnt"&gt;6&#10;&lt;/span&gt;&lt;span class="lnt"&gt;7&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-yaml" data-lang="yaml"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="nt"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;newapi-gpt-chat&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;api&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;https://newapi.example.com/v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;key_env&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;NEWAPI_API_KEY&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;transport&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;chat_completions&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;extra_body&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;prompt_cache_key&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="l"&gt;hermes-gpt-workflow-v1&lt;/span&gt;&lt;span class="w"&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;这个 key 按系统提示词和工具版本划分，不要带时间戳，也不要每轮随机生成。&lt;/p&gt;&#10;&lt;h3 id="grok"&gt;Grok&#10;&lt;/h3&gt;&lt;p&gt;xAI 的缓存规则：相邻请求开头完全相同时自动复用；Chat Completions 用 &lt;code&gt;x-grok-conv-id&lt;/code&gt; 请求头把同一会话路由到同一台服务器，Responses API 用请求体里的 &lt;code&gt;prompt_cache_key&lt;/code&gt; 达到同样效果。缓存存在具体服务器上，所以&lt;strong&gt;粘性路由对命中率非常关键&lt;/strong&gt;（&lt;a class="link" href="https://docs.x.ai/developers/advanced-api-usage/prompt-caching" target="_blank" rel="noopener"&#10; &gt;官方文档&lt;/a&gt;）。&lt;/p&gt;&#10;&lt;p&gt;走 Chat 很容易丢缓存，原因有两层：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;Hermes 不知道 custom provider 背后是 xAI，不会自动发 &lt;code&gt;x-grok-conv-id&lt;/code&gt;；New API 默认也不透传任意请求头，需要显式配置 &lt;code&gt;pass_headers&lt;/code&gt;。&lt;/li&gt;&#10;&lt;li&gt;New API &lt;code&gt;rc.25&lt;/code&gt; 的 &lt;code&gt;xAIStreamHandler&lt;/code&gt; 在流式聚合 usage 时只复制了 &lt;code&gt;PromptTokens&lt;/code&gt;、&lt;code&gt;TotalTokens&lt;/code&gt;、&lt;code&gt;CompletionTokens&lt;/code&gt;，丢了 &lt;code&gt;PromptTokensDetails.CachedTokens&lt;/code&gt;（&lt;a class="link" href="https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relay/channel/xai/text.go#L38-L60" target="_blank" rel="noopener"&#10; &gt;源码&lt;/a&gt;）。结果是 xAI 实际命中了缓存，New API 日志和本地计费却显示 0。非流式处理返回完整 usage，可以用 &lt;code&gt;stream: false&lt;/code&gt; 做对照。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;所以 Grok 优先走 Responses：Hermes 生成 key，New API 保留字段并正确记录 &lt;code&gt;cached_tokens&lt;/code&gt;，同时绕开了 Chat 流式统计的缺口。&lt;/p&gt;&#10;&lt;p&gt;如果必须继续用 Chat，需要同时满足三点：Hermes 发出稳定的 &lt;code&gt;x-grok-conv-id&lt;/code&gt;、New API 渠道允许透传这个请求头、New API 修复流式 usage 聚合。&lt;/p&gt;&#10;&lt;h3 id="glm"&gt;GLM&#10;&lt;/h3&gt;&lt;p&gt;智谱 GLM 使用自动上下文缓存，不需要手动加任何缓存字段，重复的系统提示词和多轮历史会被自动识别，命中情况在 &lt;code&gt;usage.prompt_tokens_details.cached_tokens&lt;/code&gt; 中（&lt;a class="link" href="https://docs.z.ai/guides/capabilities/cache.md" target="_blank" rel="noopener"&#10; &gt;官方文档&lt;/a&gt;）。注意小的格式变化也会降低命中。&lt;/p&gt;&#10;&lt;p&gt;所以 GLM 保持 &lt;code&gt;transport: chat_completions&lt;/code&gt;，不要开 &lt;code&gt;prompt_caching&lt;/code&gt;。New API 的智谱适配器会重建请求，但保留消息、工具和顺序；它不保留 &lt;code&gt;prompt_cache_key&lt;/code&gt;，不过 GLM 本来也不依赖这个字段。New API 读取智谱 usage 时会依次尝试 &lt;code&gt;prompt_tokens_details.cached_tokens&lt;/code&gt;、&lt;code&gt;input_tokens_details.cached_tokens&lt;/code&gt;、&lt;code&gt;cached_tokens&lt;/code&gt;、&lt;code&gt;prompt_cache_hit_tokens&lt;/code&gt; 几种格式。&lt;/p&gt;&#10;&lt;p&gt;另外，New API &lt;code&gt;rc.25&lt;/code&gt; 的智谱适配器还没有实现 Responses 转换，所以 GLM 不能和 GPT、Grok 一起统一切到 Responses。&lt;/p&gt;&#10;&lt;h3 id="claude"&gt;Claude&#10;&lt;/h3&gt;&lt;p&gt;Claude 要走原生链路：Hermes &lt;code&gt;anthropic_messages&lt;/code&gt; → New API &lt;code&gt;/v1/messages&lt;/code&gt; → Claude Messages 上游。&lt;/p&gt;&#10;&lt;p&gt;不要让它经过 New API 的 OpenAI Chat → Claude Messages 转换。&lt;code&gt;rc.25&lt;/code&gt; 在这个转换里重建 system 和文本块时没有复制 &lt;code&gt;CacheControl&lt;/code&gt;（&lt;a class="link" href="https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relaykit/relayconvert/internal/oai_chat/to_claude_messages_req.go#L255-L269" target="_blank" rel="noopener"&#10; &gt;system&lt;/a&gt;、&lt;a class="link" href="https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/relaykit/relayconvert/internal/oai_chat/to_claude_messages_req.go#L331-L338" target="_blank" rel="noopener"&#10; &gt;文本块&lt;/a&gt;），缓存断点在半路就丢了。原生 Claude 渠道直接透传原请求，没有这个问题。&lt;/p&gt;&#10;&lt;h2 id="new-api-侧渠道亲和"&gt;New API 侧：渠道亲和&#10;&lt;/h2&gt;&lt;p&gt;New API 一个模型配了多个渠道时，同一会话的请求可能在不同账号、区域或实例之间轮换，每换一次都是一次冷启动。渠道亲和就是让相关请求尽量落到同一个渠道。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;rc.25&lt;/code&gt; 的默认亲和规则只覆盖了这一种情况（&lt;a class="link" href="https://github.com/QuantumNous/new-api/blob/f116414284162ad15d8925f7bca494c109b83e93/setting/operation_setting/channel_affinity_setting.go#L113-L150" target="_blank" rel="noopener"&#10; &gt;源码&lt;/a&gt;）：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;span class="lnt"&gt;3&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;model: ^gpt-.*$&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;path: /v1/responses&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;key: prompt_cache_key&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;也就是说，GPT Responses 默认能按 Hermes 的 key 固定渠道，但 Grok Responses、GLM Chat，以及 &lt;code&gt;openai/gpt-*&lt;/code&gt; 这类带前缀的模型名都不在范围内。可以增加一条自定义规则：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt; 1&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 2&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 3&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 4&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 5&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 6&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 7&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 8&#10;&lt;/span&gt;&lt;span class="lnt"&gt; 9&#10;&lt;/span&gt;&lt;span class="lnt"&gt;10&#10;&lt;/span&gt;&lt;span class="lnt"&gt;11&#10;&lt;/span&gt;&lt;span class="lnt"&gt;12&#10;&lt;/span&gt;&lt;span class="lnt"&gt;13&#10;&lt;/span&gt;&lt;span class="lnt"&gt;14&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-json" data-lang="json"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;{&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;name&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;hermes non-claude cache affinity&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;model_regex&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;^gpt-.*$&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;^grok-.*$&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;^glm-.*$&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;path_regex&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;&amp;#34;^/v1/(responses|chat/completions)$&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;key_sources&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;type&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;gjson&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;path&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;prompt_cache_key&amp;#34;&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;type&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;context_int&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nt"&gt;&amp;#34;key&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;&amp;#34;id&amp;#34;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="p"&gt;],&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;ttl_seconds&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;3600&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;skip_retry_on_failure&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;include_using_group&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;include_model_name&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt; &lt;span class="nt"&gt;&amp;#34;include_rule_name&amp;#34;&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;&lt;span class="p"&gt;}&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;含义：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;GPT、Grok 的 Responses 请求优先按请求体里的 &lt;code&gt;prompt_cache_key&lt;/code&gt; 固定渠道；&lt;/li&gt;&#10;&lt;li&gt;GLM Chat 没有这个字段，退回按 New API 的用户 ID 固定；&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;skip_retry_on_failure: false&lt;/code&gt; 偏向可用性，固定的渠道失败后允许换，但换过去的第一次请求会冷启动；改成 &lt;code&gt;true&lt;/code&gt; 亲和更强，但渠道故障时不会自动换路。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;几个注意点：规则按顺序匹配，先命中的生效；&lt;code&gt;model_regex&lt;/code&gt; 匹配的是进入 New API 时的模型名，不是映射后的上游模型名；如果每个模型本来就只有一个渠道，亲和规则就不是必需的。&lt;/p&gt;&#10;&lt;h2 id="验证方法"&gt;验证方法&#10;&lt;/h2&gt;&lt;h3 id="先不用-hermes直接测-new-api"&gt;先不用 Hermes，直接测 New API&#10;&lt;/h3&gt;&lt;p&gt;直接向 New API 连续发两三次请求：模型、系统提示词、工具及其顺序、长历史前缀都相同，只改最后一条用户消息，在缓存 TTL 内完成，验证期间只启用一个渠道。然后检查：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;span class="lnt"&gt;2&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;GPT / Grok Responses：usage.input_tokens_details.cached_tokens&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;GPT / GLM Chat： usage.prompt_tokens_details.cached_tokens&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;如果直接请求都命中不了，问题和 Hermes 无关，去查上游、模型支持、前缀和渠道路由。&lt;/p&gt;&#10;&lt;h3 id="再验证-hermes"&gt;再验证 Hermes&#10;&lt;/h3&gt;&lt;p&gt;逐项确认：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;GPT、Grok 的 provider 确实是 &lt;code&gt;transport: codex_responses&lt;/code&gt;，GLM 是 &lt;code&gt;chat_completions&lt;/code&gt;；&lt;/li&gt;&#10;&lt;li&gt;没有给非 Claude 模型开 &lt;code&gt;prompt_caching&lt;/code&gt;；&lt;/li&gt;&#10;&lt;li&gt;Responses 请求体里有 &lt;code&gt;prompt_cache_key&lt;/code&gt;，并且跨轮稳定；&lt;/li&gt;&#10;&lt;li&gt;连续几轮被 New API 分到了同一个渠道；&lt;/li&gt;&#10;&lt;li&gt;系统提示词、工具和早期消息逐字稳定。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h3 id="grok-流式与非流式对照"&gt;Grok 流式与非流式对照&#10;&lt;/h3&gt;&lt;p&gt;对同一个 Grok Chat 渠道，用相同的长前缀和亲和 ID 分别发 &lt;code&gt;stream: false&lt;/code&gt; 和 &lt;code&gt;stream: true&lt;/code&gt; 的请求。如果非流式 &lt;code&gt;cache_tokens &amp;gt; 0&lt;/code&gt;、流式等于 0，基本可以确定是 New API 流式 usage 聚合丢了字段。&lt;/p&gt;&#10;&lt;h3 id="判定标准"&gt;判定标准&#10;&lt;/h3&gt;&lt;p&gt;最终只认这一条：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;div class="chroma"&gt;&#10;&lt;table class="lntable"&gt;&lt;tr&gt;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code&gt;&lt;span class="lnt"&gt;1&#10;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&#10;&lt;td class="lntd"&gt;&#10;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;同一真实上游 + 同一稳定前缀 + 后续请求的 cached_tokens &amp;gt; 0&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;&#10;&lt;/div&gt;&#10;&lt;/div&gt;&lt;p&gt;并且 New API 日志记录了相同的缓存量。只看到配置名、key 存在或渠道固定，都只能说明链路&lt;strong&gt;可能&lt;/strong&gt;生效，不能证明命中。&lt;/p&gt;&#10;&lt;h2 id="不要这样做"&gt;不要这样做&#10;&lt;/h2&gt;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;只调 New API 的缓存倍率。&lt;/strong&gt; 如果上游真实 &lt;code&gt;cached_tokens = 0&lt;/code&gt;，调低 &lt;code&gt;cache_ratio&lt;/code&gt; 只是本地少扣费，上游照常收钱，真实成本一分没降。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;给所有模型开 &lt;code&gt;prompt_caching&lt;/code&gt;。&lt;/strong&gt; 这会把 Anthropic 风格的 &lt;code&gt;cache_control&lt;/code&gt; 注入 GPT、Grok、GLM 请求，轻则被忽略，重则改变消息结构或被严格的上游拒绝。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;每轮生成不同的 cache key。&lt;/strong&gt; 时间戳、随机 UUID 都会把本可复用的请求打散。key 应该对应稳定的提示词和工具版本，或者稳定的会话。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;只看第一次请求。&lt;/strong&gt; 第一次通常是冷请求或写入缓存，要看后续相同前缀的请求。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;把代码推断当成实测结果。&lt;/strong&gt; 读代码只能说明字段可能被发送、丢失或解析，最终要用真实请求验证。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="相关-issue-与-pr"&gt;相关 issue 与 PR&#10;&lt;/h2&gt;&lt;p&gt;Hermes Agent：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/issues/84506" target="_blank" rel="noopener"&#10; &gt;LiteLLM OpenAI wire 0 缓存问题 #84506&lt;/a&gt;，修复 &lt;a class="link" href="https://github.com/NousResearch/hermes-agent/pull/87517" target="_blank" rel="noopener"&#10; &gt;#87517&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/pull/85554" target="_blank" rel="noopener"&#10; &gt;Anthropic 自定义模型别名缓存 #85554&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/pull/93321" target="_blank" rel="noopener"&#10; &gt;custom OpenAI Chat provider 的逐模型缓存声明 #93321&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/NousResearch/hermes-agent/issues/70382" target="_blank" rel="noopener"&#10; &gt;GPT-5.6 显式 cache breakpoint 讨论 #70382&lt;/a&gt;&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;New API：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/QuantumNous/new-api/issues/1601" target="_blank" rel="noopener"&#10; &gt;OpenAI 格式请求 Claude 渠道的缓存计费问题 #1601&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/QuantumNous/new-api/issues/6538" target="_blank" rel="noopener"&#10; &gt;Chat/Claude 转 Responses 丢失 prompt cache key #6538&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/QuantumNous/new-api/issues/5982" target="_blank" rel="noopener"&#10; &gt;Claude Messages 转 OpenAI 残留 &lt;code&gt;cache_control&lt;/code&gt; #5982&lt;/a&gt;&lt;/li&gt;&#10;&lt;li&gt;&lt;a class="link" href="https://github.com/QuantumNous/new-api/pull/6691" target="_blank" rel="noopener"&#10; &gt;Claude 转 OpenAI 的 cache control 和 prompt key 相关 PR #6691&lt;/a&gt;&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;h2 id="总结"&gt;总结&#10;&lt;/h2&gt;&lt;p&gt;最终推荐的拓扑（中间都经过 New API，连线上标的是 New API 的入口路径）：&lt;/p&gt;&#10;&lt;pre class="mermaid" style="visibility:hidden"&gt;flowchart LR&#10; H1[newapi-gpt&lt;br/&gt;codex_responses] --&gt;|/v1/responses| U1[GPT 上游&lt;br/&gt;prompt_cache_key + 渠道亲和]&#10; H2[newapi-grok&lt;br/&gt;codex_responses] --&gt;|/v1/responses| U2[xAI 上游&lt;br/&gt;prompt_cache_key + 渠道亲和]&#10; H3[newapi-glm&lt;br/&gt;chat_completions] --&gt;|/v1/chat/completions| U3[Z.AI 上游&lt;br/&gt;自动缓存 + 渠道亲和]&#10; H4[newapi-claude&lt;br/&gt;anthropic_messages] --&gt;|/v1/messages| U4[Claude 上游&lt;br/&gt;原生 cache_control]&lt;/pre&gt;&lt;p&gt;这套拆分的重点不是&amp;quot;给每个模型都打开缓存&amp;rdquo;，而是让每个模型使用它真实上游认可的缓存协议，并让同一个稳定前缀尽量落到同一个缓存命名空间。排查时从 Hermes 请求、New API 转发、上游原始 usage、New API 日志四层逐层取证，不要凭一个 0 下结论。&lt;/p&gt;&#10;</description></item></channel></rss>