OpenRouter.help
返回首页

prompt-caching

阅读约 18 分钟

原文链接：Prompt Caching

Prompt Caching

缓存 prompt 消息

为了节省推理成本，您可以在支持的提供商和模型上启用 prompt 缓存。

大多数提供商自动启用 prompt 缓存，但请注意，有些（见下面的 Alibaba 和 Anthropic）需要您逐条启用。

使用缓存时（无论是自动缓存的模型还是通过 cache_control 属性），OpenRouter 使用提供商粘性路由来最大化缓存命中率 — 有关详细信息，请参阅下面的 Provider Sticky Routing。

Provider Sticky Routing

为了最大化缓存命中率，OpenRouter 使用 提供商粘性路由 将您的后续请求路由到缓存请求后的同一提供商端点。这对隐式缓存（如 OpenAI、DeepSeek、Gemini 2.5）和显式缓存（如 Anthropic cache_control 断点）都自动工作。

工作原理：

  • 在使用 prompt 缓存的请求之后，OpenRouter 记住为您的请求提供服务的提供商。

  • 同一模型的后续请求被路由到同一提供商，保持缓存热状态。

  • 仅当提供商的缓存读取价格低于常规 prompt 价格时，才激活粘性路由，确保您始终受益于成本节省。

  • 如果粘性提供商变得不可用，OpenRouter 自动回退到下一个最佳提供商。

  • 当您通过 provider.order 指定手动提供商顺序时，不使用粘性路由 — 在这种情况下，您的显式排序优先。

粘性路由粒度：

粘性路由在账户级别、按模型和按对话进行追踪。OpenRouter 通过哈希处理每个请求中的第一个系统（或 developer）消息和第一个非系统消息来识别对话，因此共享相同开场消息的请求被路由到同一提供商。这意味着不同的对话自然地粘到不同的提供商，在改善负载均衡和吞吐量的同时，保持每个对话内的缓存热状态。

检查缓存使用情况

要查看每个生成节省了多少缓存，您可以：

  1. 在 Activity 页面点击详情按钮

  2. 使用 /api/v1/generation API，文档在此

  3. 检查每个 API 响应中包含的 usage 响应中的 prompt_tokens_details 对象

响应体中的 cache_discount 字段将告诉您响应在缓存使用上节省了多少。一些提供商（如 Anthropic）的缓存写入会有负折扣，但缓存读取会有正折扣（降低总成本）。

Usage 对象字段

API 响应中的 usage 对象在 prompt_tokens_details 字段中包含详细的缓存指标：

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

关键字段是：

  • cached_tokens：从缓存读取的 token 数（缓存命中）。当这大于零时，您正在受益于缓存内容。

  • cache_write_tokens：写入缓存的 token 数。这在建立新缓存条目时首次请求上出现。

OpenAI

缓存价格变化：

  • 缓存写入：免费

  • 缓存读取：（取决于模型）按原始输入价格的 0.25 倍或 0.50 倍收费

点击此处查看每个模型的 OpenAI 缓存定价。

OpenAI 的 prompt 缓存是自动的，不需要任何额外配置。最小 prompt 大小为 1024 token。

点击此处阅读更多关于 OpenAI prompt 缓存及其限制的信息。

Grok

缓存价格变化：

  • 缓存写入：免费

  • 缓存读取：按原始输入价格的 0.25 倍收费

点击此处查看每个模型的 Grok 缓存定价。

Grok 的 prompt 缓存是自动的，不需要任何额外配置。

Moonshot AI

缓存价格变化：

  • 缓存写入：免费

  • 缓存读取：按原始输入价格的 0.25 倍收费

Moonshot AI 的 prompt 缓存是自动的，不需要任何额外配置。

Groq

缓存价格变化：

  • 缓存写入：免费

  • 缓存读取：按原始输入价格的 0.5 倍收费

Groq 的 prompt 缓存是自动的，不需要任何额外配置。目前在 Kimi K2 模型上可用。

点击此处查看 Groq 的文档。

Alibaba Qwen

显式缓存的缓存价格变化：

  • 缓存写入：按原始输入价格的 1.25 倍收费

  • 缓存读取：按原始输入价格的 0.1 倍收费

Alibaba prompt 缓存需要显式缓存断点。使用与 Anthropic 显式缓存相同的语法，在您想要缓存的内容块上添加 cache_control: { "type": "ephemeral" }。缓存写入使用 5 分钟 TTL。

Alibaba 显式缓存在 deepseek/deepseek-v3.2、qwen/qwen3-max、qwen/qwen-plus、qwen/qwen3.6-plus、qwen/qwen3-coder-plus 和 qwen/qwen3-coder-flash 上可用。快照端点，包括 qwen/qwen3.5-plus-02-15 和 qwen/qwen3.5-flash-02-23，不支持显式缓存。

示例

{
  "model": "qwen/qwen3-coder-plus",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Use the reference below when answering."
        },
        {
          "type": "text",
          "text": "HUGE TEXT BODY",
          "cache_control": {
            "type": "ephemeral"
          }
        },
        {
          "type": "text",
          "text": "Summarize the main implementation details."
        }
      ]
    }
  ]
}

Anthropic Claude

缓存价格变化：

  • 缓存写入（5 分钟 TTL）：按原始输入价格的 1.25 倍收费

  • 缓存写入（1 小时 TTL）：按原始输入价格的 2 倍收费

  • 缓存读取：按原始输入价格的 0.1 倍收费

启用 Anthropic prompt 缓存有两种方式：

  • 自动缓存 ：在请求顶层添加单个 cache_control 字段。系统自动将缓存断点应用到最后一个可缓存块，并随着对话增长向前推进。最适合多轮对话。

  • 显式缓存断点 ：直接在各个内容块上放置 cache_control，以精细控制确切缓存的内容。显式断点限制为四个。建议将缓存断点保留给大型文本主体，如角色卡片、CSV 数据、RAG 数据、书籍章节等。

自动缓存（顶层 cache_control）仅在请求被直接路由到 Anthropic 提供商时支持。Amazon Bedrock 和 Google Vertex AI 目前不支持顶层 cache_control — 当存在时，OpenRouter 将仅路由到 Anthropic 提供商并排除 Bedrock 和 Vertex 端点。显式每块 cache_control 断点可在所有 Anthropic 兼容提供商上工作，包括 Bedrock 和 Vertex。

Responses API 支持： Responses API 仅支持通过顶层 cache_control 的 自动缓存。input 项目内的显式每块缓存断点 不通过 Responses API 暴露 — 如果您需要精细断点，请使用 Chat Completions 或 Anthropic Messages API。

默认情况下，缓存在 5 分钟后过期，但您可以通过在 cache_control 对象中指定 "ttl": "1h" 将其延长至 1 小时。

点击此处阅读更多关于 Anthropic prompt 缓存及其限制的信息。

支持的模型

以下 Claude 模型支持 prompt 缓存（自动和显式）：

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

最低 token 要求

每个模型都有最小可缓存 prompt 长度：

  • 4096 token ：Claude Opus 4.7、Claude Opus 4.6、Claude Opus 4.5、Claude Haiku 4.5

  • 2048 token ：Claude Sonnet 4.6、Claude Haiku 3.5

  • 1024 token ：Claude Sonnet 4.5、Claude Opus 4.1、Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7

短于这些最小值的 prompt 不会被缓存。

缓存 TTL 选项

OpenRouter 支持 Anthropic 的两个缓存 TTL 值：

  • 5 分钟（默认）："cache_control": { "type": "ephemeral" }

  • 1 小时："cache_control": { "type": "ephemeral", "ttl": "1h" }

1 小时 TTL 对于您希望跨多个请求维护缓存内容的较长会话很有用，避免重复缓存写入成本。1 小时 TTL 的缓存写入成本更高（2 倍基础输入价格 vs 5 分钟 TTL 的 1.25 倍），但通过避免重复缓存写入可以在扩展会话中节省资金。显式缓存断点的 1 小时 TTL 在所有 Claude 模型提供商（Anthropic、Amazon Bedrock 和 Google Vertex AI）上支持。

示例

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

使用自动缓存，在请求顶层添加 cache_control。系统自动缓存到最后一个可缓存块的所有内容：

{
  "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?"
    }
  ]
}

随着对话增长，缓存断点自动前进以覆盖增长的消息历史。

使用 1 小时 TTL 的自动缓存：

{
  "model": "anthropic/claude-sonnet-4.6",
  "cache_control": { "type": "ephemeral", "ttl": "1h" },
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is the meaning of life?"
    }
  ]
}

显式缓存断点（精细控制）

系统消息缓存示例（默认 5 分钟 TTL）：

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

使用 1 小时 TTL 的用户消息缓存示例：

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Given the book below:"
        },
        {
          "type": "text",
          "text": "HUGE TEXT BODY",
          "cache_control": {
            "type": "ephemeral",
            "ttl": "1h"
          }
        },
        {
          "type": "text",
          "text": "Name all the characters in the above book"
        }
      ]
    }
  ]
}

DeepSeek

缓存价格变化：

  • 缓存写入：按原始输入价格收费

  • 缓存读取：按原始输入价格的 0.1 倍收费

DeepSeek 的 prompt 缓存是自动的，不需要任何额外配置。

Google Gemini

隐式缓存

Gemini 2.5 Pro 和 2.5 Flash 模型现在支持 隐式缓存，提供类似于 OpenAI 自动缓存的自动缓存功能。隐式缓存无缝工作 — 无需手动设置或额外的 cache_control 断点。

价格变化：

  • 无缓存写入或存储费用。

  • 缓存 token 按原始输入 token 成本的 0.25 倍收费。

请注意，TTL 平均为 3-5 分钟，但会有所不同。Gemini 2.5 Flash 最小 1024 token，Gemini 2.5 Pro 最小 4096 token，才有资格进行缓存。

Google 官方公告

要最大化隐式缓存命中率，请在请求之间保持消息数组的初始部分一致。将变体（如用户问题或动态上下文元素）推向 prompt/请求的末尾。

缓存请求的价格变化：

  • 缓存写入： 按输入 token 价格加上 5 分钟缓存存储收费，计算如下：
 缓存写入成本 = 输入 token 价格 +（缓存存储价格 × (5 分钟 / 60 分钟)）
  • 缓存读取： 按原始输入 token 成本的 0.25 倍收费。

支持的模型和限制：

只有某些 Gemini 模型支持缓存。请参阅 Google 的 Gemini API 定价文档获取最新详情。

缓存写入的生存时间（TTL）为 5 分钟，不更新。5 分钟后，缓存过期，必须写入新缓存。

Gemini 模型通常有 4096 token 的最小值才能进行缓存写入。缓存 token 计入模型的最大 token 使用量。Gemini 2.5 Pro 最小 4096 token，Gemini 2.5 Flash 最小 1024 token。

Gemini Prompt Caching 在 OpenRouter 上如何工作

OpenRouter 简化了 Gemini 缓存管理，抽象了复杂性：

  • 您 不需要 手动创建、更新或删除缓存。

  • 您 不需要 明确管理缓存名称或 TTL。

如何启用 Gemini Prompt Caching

OpenRouter 中的 Gemini 缓存需要在消息内容中明确插入 cache_control 断点。

© 2026 OpenRouter.help
查看官方英文原件