OpenRouter Prompt Caching：多 Provider 缓存配置与最优成本实践

OpenRouter 支持多家 Provider 的 prompt caching，大多数 Provider（OpenAI、DeepSeek、Gemini 2.5）已默认自动缓存，无需任何额外配置。Anthropic 需要在请求中加入 cache_control 字段启用，支持自动模式（顶层）和精细模式（单独 content block）两种。OpenRouter 通过 Provider Sticky Routing 机制将后续请求路由到同一 Provider，保持缓存热度。缓存命中可节省高达 90% 的 prompt token 费用（Anthropic/DeepSeek 缓存读取仅收取 0.1x 费用）。

Prompt caching 是降低 AI 推理成本最直接有效的手段——对话中重复出现的长系统 prompt、RAG 文档、角色卡等内容，只需首次写入缓存，后续请求直接读取，大幅减少计费 token 量。

Provider Sticky Routing

OpenRouter 使用 Provider Sticky Routing 机制自动最大化缓存命中率：

发出一次使用了缓存的请求后，OpenRouter 记录为该请求服务的 Provider
后续针对同一模型的请求会优先路由到同一 Provider，保持缓存"热态"
仅在该 Provider 的缓存读取价格低于正常 prompt 价格时才激活 Sticky Routing
若该 Provider 不可用，OpenRouter 自动切换到下一可用 Provider
若你通过 provider.order 手动指定了 Provider 顺序，Sticky Routing 不生效，你的配置优先

Sticky Routing 粒度：按账号 + 模型 + 会话三维追踪。OpenRouter 通过对首条 system/developer 消息和首条非 system 消息哈希来识别会话，同一开头的请求路由到同一 Provider。

查看缓存节省

以下方式可检查每次请求的缓存情况：

在活动面板点击详情按钮
调用 /api/v1/generation?id={id} API 查询
检查响应中 usage.prompt_tokens_details 对象的字段值

响应体中的 cache_discount 字段表示本次请求通过缓存节省的费用。Anthropic 写入缓存时有负折扣（额外收费），读取命中时为正折扣（减少费用）。

usage 对象中的缓存字段

json

{
  "usage": {
    "prompt_tokens": 10339,
    "completion_tokens": 60,
    "total_tokens": 10399,
    "prompt_tokens_details": {
      "cached_tokens": 10318,
      "cache_write_tokens": 0
    }
  }
}

cached_tokens：从缓存读取的 token 数（命中时 > 0，说明在节省费用）
cache_write_tokens：写入缓存的 token 数（首次建立缓存条目时出现）

OpenAI

操作	费用
缓存写入	免费
缓存读取	原始 input 价格的 0.25x 或 0.50x（因模型而异）

全自动，无需任何配置。最小缓存 prompt 长度：1024 tokens。

Grok

操作	费用
缓存写入	免费
缓存读取	原始 input 价格的 0.25x

全自动，无需任何配置。

Moonshot AI

操作	费用
缓存写入	免费
缓存读取	原始 input 价格的 0.25x

全自动，无需任何配置。

Groq

操作	费用
缓存写入	免费
缓存读取	原始 input 价格的 0.5x

全自动，无需任何配置。目前仅 Kimi K2 模型可用。

Anthropic Claude

操作	费用
缓存写入（5 分钟 TTL）	原始 input 价格的 1.25x
缓存写入（1 小时 TTL）	原始 input 价格的 2x
缓存读取	原始 input 价格的 0.1x（节省 90%！）

Anthropic 的 prompt caching 需要在请求中显式声明，有两种模式：

自动缓存（推荐用于多轮对话）

在请求顶层添加 cache_control，系统自动将缓存断点推进到最后一个可缓存块：

json

{
  "model": "anthropic/claude-sonnet-4.6",
  "cache_control": { "type": "ephemeral" },
  "messages": [
    {
      "role": "system",
      "content": "You are a historian studying the fall of the Roman Empire. You know the following book very well: HUGE TEXT BODY"
    },
    {
      "role": "user",
      "content": "What triggered the collapse?"
    }
  ]
}

随着对话进行，缓存断点自动向前推移，覆盖逐渐增长的消息历史。

注意：自动缓存（顶层 cache_control）仅支持直连 Anthropic Provider，不适用于 Amazon Bedrock 和 Google Vertex AI。

1 小时 TTL 版本："cache_control": { "type": "ephemeral", "ttl": "1h" }

精细缓存断点（手动控制）

将 cache_control 放置在单个 content block 上，精确控制哪些内容被缓存，最多 4 个断点：

json

{
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "You are a historian studying the fall of the Roman Empire."
        },
        {
          "type": "text",
          "text": "HUGE TEXT BODY",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "user",
      "content": "What triggered the collapse?"
    }
  ]
}

建议将缓存断点用于大型静态文本块（角色卡、CSV 数据、RAG 文档、书籍章节等），而非动态变化的内容。精细断点适用于所有 Anthropic 兼容 Provider（含 Bedrock 和 Vertex）。

Cache TTL 选项

TTL	写法	写入成本	适用场景
5 分钟（默认）	`{ "type": "ephemeral" }`	1.25x	短会话
1 小时	`{ "type": "ephemeral", "ttl": "1h" }`	2x	长会话，多次命中更划算

支持的模型

Claude Opus 4.7、4.6、4.5、4.1、4
Claude Sonnet 4.6、4.5、4、3.7（已弃用）
Claude Haiku 4.5、3.5

最小 token 要求

最小 token	型号
4096	Claude Opus 4.7、4.6、4.5、Haiku 4.5
2048	Claude Sonnet 4.6、Haiku 3.5
1024	Claude Sonnet 4.5、Opus 4.1、4、Sonnet 4、3.7

prompt 不足最小长度时不会被缓存。

DeepSeek

操作	费用
缓存写入	与正常 input 价格相同
缓存读取	原始 input 价格的 0.1x（节省 90%！）

全自动，无需任何配置。

Google Gemini

隐式缓存（Implicit Caching）

Gemini 2.5 Pro 和 2.5 Flash 支持隐式缓存，类似 OpenAI 的自动缓存，无需任何配置：

无缓存写入或存储费用
缓存 token 收取原始 input 价格的 0.25x
TTL 平均 3-5 分钟（有波动）
最小 token：Gemini 2.5 Flash ≥ 1028，Gemini 2.5 Pro ≥ 2048

要最大化隐式缓存命中，保持请求消息数组的前段内容稳定，将动态变化的内容（用户提问、实时数据）放到消息末尾。

显式缓存（通过 cache_control）

对于需要缓存特定大块内容的场景，在 content block 中插入 cache_control 断点（同 Anthropic 格式）：

json

{
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "You are a historian. Below is an extensive reference book:"
        },
        {
          "type": "text",
          "text": "HUGE TEXT BODY HERE",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    {
      "role": "user",
      "content": "What triggered the collapse?"
    }
  ]
}

OpenRouter 会自动管理 Gemini 缓存，你无需手动创建、更新或删除缓存对象，也无需管理缓存名称或 TTL。

注意：cache_control 断点数量不限，但 OpenRouter 只使用最后一个断点来做 Gemini 缓存。

常见问题

Q: 如何判断某次请求是否命中了缓存？

A: 查看响应 usage.prompt_tokens_details.cached_tokens 字段，大于 0 即表示有 token 从缓存中读取。同时可在活动面板中直接查看 cache_discount 字段。

Q: Anthropic 自动缓存和精细断点缓存如何选择？

A: 多轮对话场景优先选择自动缓存（顶层 cache_control），系统会自动推进缓存边界，覆盖不断增长的历史消息；若你的 prompt 中有多段大型静态文本（如多份 RAG 文档），且需要控制具体哪些内容进入缓存，则用精细断点模式。

Q: 同时兼容 Anthropic 和 Bedrock/Vertex 时，如何使用缓存？

A: 只使用精细断点（在 content block 上加 cache_control），不要使用顶层 cache_control。精细断点兼容所有 Anthropic 系 Provider，而自动缓存（顶层）只支持直连 Anthropic。

Provider Sticky Routing ​

查看缓存节省 ​

usage 对象中的缓存字段 ​

OpenAI ​

Grok ​

Moonshot AI ​

Groq ​

Anthropic Claude ​

自动缓存（推荐用于多轮对话） ​

精细缓存断点（手动控制） ​

Cache TTL 选项 ​

支持的模型 ​

最小 token 要求 ​

DeepSeek ​

Google Gemini ​

隐式缓存（Implicit Caching） ​

显式缓存（通过 cache_control） ​

常见问题 ​

Provider Sticky Routing

查看缓存节省

usage 对象中的缓存字段

OpenAI

Grok

Moonshot AI

Groq

Anthropic Claude

自动缓存（推荐用于多轮对话）

精细缓存断点（手动控制）

Cache TTL 选项

支持的模型

最小 token 要求

DeepSeek

Google Gemini

隐式缓存（Implicit Caching）

显式缓存（通过 cache_control）

常见问题