开始/Advanced

提示词缓存 & 会话亲和

对支持提示词缓存的模型，将大篇幅的静态上下文（如系统提示词、知识库、历史消息）进行缓存，可缩短响应延迟并削减高达 90% 的输入成本。网关独创的「会话亲和」机制确保了缓存的高命中率。

#1. 工作原理

传统的 API 网关会对每次请求的完整输入重新计费。而启用提示词缓存的模型在遇到相同请求前缀时，会读取上游服务商缓存好的数据，只对缓存读取（Read）按极低单价计费。
- 缓存写入 (Cache Write)： 第一次请求（或缓存过期后）将整段上下文传给模型，触发上游建立缓存，此阶段按缓存写入价格收费（通常等于或略高于普通输入价）。
- 缓存读取 (Cache Read)： 后续相同前缀的请求，会自动读取该缓存，收费大降（低至普通输入的 1/10 价格）。

#2. 会话亲和 (Session Affinity)

由于 API 网关通常会绑定多个服务通道与多组不同的 API key 进行负载均衡，若每次请求都被随机分发到不同通道，缓存将永远无法命中。
为了解决这个问题，Sozdai 引入了 **会话亲和 (Session Affinity) 路由**：
系统提取您发送的第一条消息的哈希值作为亲和 Key（Affinity Key）。只要模型名和首条消息相同，网关将**锁定并持续路由到完全相同的上游渠道与 Key**，确保缓存始终在同一上游账号和通道中保持温热，极大提升缓存命中率。

#3. 触发与声明方式

您可以通过以下两种方式让网关识别并启用缓存路由：

显式请求头： 在请求中携带 `x-corry-cache: true` 请求头。
标准 Anthropic Caching Block 声明： 像平时调用 Anthropic 接口一样，在消息内容块中塞入 { "type": "ephemeral" } 标记。

json

{
  "model": "claude-3-5-sonnet",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "...(very long developer guidelines or database schemas)...",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    { "role": "user", "content": "Query statistics for May." }
  ]
}

#4. 响应与命中反馈

当成功命中了缓存，返回的 JSON 响应中会包含 `usage` 统计细节，如 `cached_tokens`：

json

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "model": "claude-3-5-sonnet",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here is the summary of the database schema..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5120,
    "completion_tokens": 150,
    "total_tokens": 5270,
    "prompt_tokens_details": {
      "cached_tokens": 4096
    }
  }
}