跳转到主要内容

概览

GoModel 内置两层响应缓存,适用于以下端点上的流式和非流式请求:
  • /v1/chat/completions
  • /v1/responses
  • /v1/messages
  • /v1/embeddings
  • /v1/systemone(以及 Kev 的 /permute 和 /separate)
同一请求的流式和非流式版本会分别缓存:流式请求未命中时会存储原始 SSE 字节,流式请求命中时会以 text/event-stream 原样重放这些字节。超过 4 MiB 的流仍会完整发送给客户端,但不会被缓存。 精确匹配缓存返回逐字节相同的响应,并带有:
语义缓存使用嵌入(Embeddings)加向量检索,使语义相同的提示词可以复用已存储的响应:
/v1/embeddings 只参与精确缓存。嵌入必须表示所请求的确切文本,因此为仅仅相似的输入重放向量,会得到一个错误的答案,而不是一个等价的答案。嵌入请求也从不使用流式传输,因此只缓存 JSON 响应。System One 决策同理:相似的状态并不意味着相同的决策。

启用精确缓存

将响应缓存指向 Redis:
您也可以通过环境变量进行配置:
  • REDIS_URL
  • REDIS_KEY_RESPONSES
  • REDIS_TTL_RESPONSES

启用语义缓存

添加一个 semantic 配置块,并指定嵌入提供商和向量存储:
支持的向量存储:
  • qdrant
  • pgvector
  • pinecone
  • weaviate
两层缓存都在工作流和护栏修补之后运行,因此它们作用于最终发送到上游的请求。使用 Cache-Control: no-cache 或 Cache-Control: no-store 可以针对单个请求绕过缓存。插件也可以在其决策中使用 NoStore,使某个响应不进入两层缓存;将请求特定数据恢复到回复中的护栏就是这样做的,以确保恢复后的文本绝不会被重放给其他调用方。/v1/responses 上的 background: true 请求同样会绕过两层缓存:它的 queued 响应体携带一个只属于某个调用方响应的 id。 有关语义缓存的完整设计和存储选项,请参阅 ADR-0006。

精确缓存键的组成

精确缓存会对以下内容计算哈希:
  • 请求路径
  • 用于执行的已解析工作流上下文,具体为执行模式、提供商类型和解析后的模型
  • 请求解析到的护栏链,涵盖提示词、响应和流三个阶段
  • 最终的请求体
  • 有效 user_path,仅在启用 partition_by_user_path 时(见下文)
这意味着,当护栏和工作流改变了解析后的工作流或经过执行发送的最终请求体时,它们会影响缓存键。 缓存命中时会重放已存储的响应,而不会重新运行响应和流护栏链,因此一个缓存条目只会提供给护栏链与生成它时相同的请求。编辑、添加或删除某个护栏步骤,或者使用另一个护栏链不同的工作流,都会导致缓存未命中,而不是返回这些护栏从未检查过的回复。因此,更改护栏配置会使旧护栏链下存储的条目失效。 在计算哈希之前,JSON 对象成员的顺序和无意义的空白会被规范化。因此,仅格式不同的请求会共用同一个精确缓存条目。并发的相同未命中请求也会在进程内合并:只有一个请求到达提供商,其他等待的请求会重放它的响应。失败的或其他不可缓存的响应绝不会被分发给等待者。

语义缓存键的组成

语义缓存命中要求最后一条用户消息相似,并且其他所有内容完全一致:
  • 请求路径、解析后的提供商和模型、护栏链以及嵌入模型
  • 之前的对话轮次,以及最后一条用户消息中的所有非文本部分
  • 其他所有顶层请求字段,例如 temperature、seed、stop、n、tools、tool_choice、response_format、text、reasoning_effort、thinking 或 system,以及 GoModel 无法识别的任何字段
  • 请求是否为流式;仅当 stream 为 true 时才计入 stream_options
名称各不相同的 Chat Completions 函数工具,其顺序不影响匹配;其他任何工具列表的顺序都必须一致。 以下字段不计入,因为它们不会改变回答:user、metadata、safety_identifier、prompt_cache_key 和 prompt_cache_retention。在 /v1/responses 上它们会计入,因为响应会将它们返回给调用方。设置 exclude_system_prompt: true 时,系统消息和顶层 system 也不计入;Responses API 的 instructions 始终计入。

提供商提示词缓存规划

在路由解析出具体的提供商和模型之后,如果稳定前缀达到该提供商的最小长度,且客户端尚未提供缓存指令,GoModel 会添加一个缓存计划:
  • OpenAI 会收到一个稳定的 prompt_cache_key;支持显式缓存的模型还会收到一个断点和显式缓存模式。
  • Anthropic 会收到顶层的自动临时缓存(ephemeral caching)。
  • Amazon Bedrock Converse 会在稳定前缀之后收到一个缓存点。
  • 原生 Gemini AI Studio 会创建并复用一个五分钟有效的缓存内容对象,并按前缀和稳定凭据合并并发创建。
该计划在路由之后应用,因此仅属于特定提供商的字段不会在回退到其他后端时泄漏出去。缓存键包含具体的提供商实例和模型,并且调用方提供的缓存控制始终优先。 提供商提示词缓存规划默认启用。要禁用 GoModel 的自动规划,同时继续透传兼容的客户端缓存指令,请设置:
该标志接受 Go 布尔值。缺失、为空或无效的值会保持安全的默认值(true),无效值会在启动时输出警告。

user_path 行为

默认情况下,user_path 不属于任何一层缓存的缓存键。 这是有意为之。如果两个请求最终具有相同的路径、解析后的工作流和最终请求体,即使它们来自不同的 user_path 值,也可以共用同一个条目;在语义缓存中,相似的提示词同样如此。共用能带来最高的命中率,但也意味着一个租户可能收到为另一个租户缓存的响应。

按 user_path 对缓存分区

当调用方不得收到彼此缓存的响应时(例如绑定到 user_path 的 API 密钥属于不同租户),请启用分区:
也可以设置 RESPONSE_CACHE_PARTITION_BY_USER_PATH=true。 该设置覆盖上述各端点所使用的每一层缓存(嵌入和 System One 只使用精确缓存),无论是否为流式请求:
  • 有效 user_path 不同的请求绝不会共用条目。在精确缓存中,并发的相同未命中请求只会等待来自同一路径的请求。
  • 路径必须完全匹配。/team/alpha 不会复用 /team 或 /team/alpha/bob 的条目。
  • 没有 user_path 的请求自成一个分区,与 / 分开。
  • 每个路径都要为自己的首次请求付费,因此当租户发送相同提示词时命中率会下降。
隔离仅在绑定了 user_path 的 API 密钥之间成立。主密钥和未绑定路径的托管密钥可通过 user path 请求头自行选择路径,因此可以读取任意分区;关闭身份验证时,所有调用方同样如此。
更改该设置会使现有条目产生缓存未命中:它们绝不会跨模式提供,但也不会被删除。它们会按 TTL 过期;如果在此之前切换回去,它们会再次被提供。若要避免先前共用的条目重新出现,请在切换回去之前等待 TTL 结束或清空缓存。以 ttl: 0 存储的语义缓存条目永不过期,请将其清除。

其他限定缓存范围的方式

如果您只需要按作用域区分缓存行为,而不需要隔离:
  • 在带作用域的工作流中禁用缓存
  • 为不同的 user_path 值使用不同的带作用域工作流
  • 加入特定于作用域的上下文,使最终请求体有所不同

通过故障转移返回的响应不会被缓存

当请求由某个故障转移目标而不是路由最初选择的目标应答时,该响应不会被存储。精确缓存键是根据故障转移之前的解析结果计算的,因此如果存储备用目标的应答,在主目标恢复后,这个应答会以主目标的缓存键被返回。 实际影响是:如果某个虚拟模型的第一个目标长期不可用,在其不可用期间,该虚拟模型将不再积累缓存条目。每个未命中的请求都会故障转移并获得新的响应,而这些响应都不会被存储。故障之前写入的条目在 TTL 过期前会继续提供服务:缓存查找在分发之前进行,因此命中时直接返回,不会触及任何目标。如果某个目标将在一段时间内不可用,请调整链的顺序(或将虚拟模型指向健康的目标),使应答请求的响应重新可被缓存。 同一目标内的重试不受影响:只有在切换到其他目标之后产生的响应,才会被排除在两层缓存之外。

缓存分析

当启用了响应缓存和用量追踪时,Admin API 会在以下位置提供仅包含缓存数据的概览:
缓存命中也会记录为用量条目,并带有调用方的 user_path,以及值为 exact 或 semantic 的 cache_type。用量端点(/admin/usage/* 和 /v1/usage)默认不包含这些条目,使总量和成本反映的是提供商支出;传入 cache_mode=all 可包含它们,传入 cache_mode=cached 则只查看命中条目。/admin/usage/sessions 是例外:会话的请求数和 Token 总数始终包含缓存命中,而其成本字段仍只统计提供商支出。
参阅 Admin 端点和 Usage API。
最后修改于 2026年11月10日