Prompt 缓存

Prompt 缓存允许供应商重用之前处理过的提示内容。当您的提示开头与之前缓存的前缀匹配时，供应商会跳过重新处理这些 Token——显著降低成本和延迟。

查看缓存使用情况

缓存使用情况反映在每个响应的 usage 对象中：

{
  "usage": {
    "prompt_tokens": 1500,
    "completion_tokens": 100,
    "total_tokens": 1600,
    "prompt_tokens_details": {
      "cached_tokens": 1024,
      "cache_write_tokens": 476
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

字段	说明
`prompt_tokens_details.cached_tokens`	从缓存读取的 Token（缓存命中——更便宜）
`prompt_tokens_details.cache_write_tokens`	本次请求写入缓存的 Token（一次性写入费用）

OpenAI 自动缓存

OpenAI 自动缓存提示前缀，无需特殊请求配置。 工作原理：

缓存在 OpenAI 服务端发生，当提示足够长时自动触发
最小提示长度：1,024 Token
缓存条目在闲置约 1 小时后过期
缓存 Token 按折扣价计费（通常享受 50% 折扣）

from openai import OpenAI

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# 重复调用时，长系统提示会自动被缓存
response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[
        {
            "role": "system",
            "content": "You are an expert assistant. " + "<long context>" * 100,
        },
        {"role": "user", "content": "Summarize the above."},
    ],
)

print(response.usage.prompt_tokens_details)
# PromptTokensDetails(cached_tokens=1024, audio_tokens=0)

Anthropic Claude Prompt 缓存

Anthropic 支持两种缓存模式：

自动缓存（默认）：Claude 自动缓存系统提示。最少 1,024 Token。
显式缓存（cache_control）：使用 "cache_control": {"type": "ephemeral"} 标记特定内容块，精确控制缓存内容。

缓存 TTL

缓存类型	TTL
自动	5 分钟
显式（`ephemeral`）	1 小时（Claude 3.5+）或 5 分钟（Claude 3）

支持的模型

模型	最少 Token（文本）	最少 Token（图像）
`anthropic/claude-sonnet-4.6`	1,024	1,024
`anthropic/claude-opus-4.5`	1,024	1,024
`anthropic/claude-haiku-3.5`	2,048	2,048
`anthropic/claude-3-5-sonnet`	1,024	1,024

显式缓存示例

使用 cache_control 在内容块级别控制缓存：

{
  "model": "claude-sonnet-4.6",
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant with access to the following reference document:\n\n<document>...</document>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "What does the document say about pricing?" }
  ],
  "max_tokens": 1024
}

通过 OpenAI 兼容端点时，使用 extra_body 传递：

Python (OpenAI)
Node.js (OpenAI)
Anthropic SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

long_document = "<document content here>" * 50  # 确保 > 1024 Token

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": f"Reference document:\n\n{long_document}",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {"role": "user", "content": "Summarize the key points."},
    ],
)

print(response.usage)
# Usage(prompt_tokens=1500, completion_tokens=80, total_tokens=1580,
#   prompt_tokens_details=PromptTokensDetails(cached_tokens=1024, cache_write_tokens=476))

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.arouter.ai/v1",
  apiKey: "lr_live_xxxx",
});

const longDocument = "<document content here>".repeat(50);

const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.6",
  messages: [
    {
      role: "system",
      content: [
        {
          type: "text",
          text: `Reference document:\n\n${longDocument}`,
          // @ts-ignore — cache_control 是 Anthropic 特有的
          cache_control: { type: "ephemeral" },
        },
      ],
    },
    { role: "user", content: "Summarize the key points." },
  ],
});

console.log(response.usage?.prompt_tokens_details);
// { cached_tokens: 1024, cache_write_tokens: 476 }

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.arouter.ai",
    api_key="lr_live_xxxx",
)

long_document = "<document content here>" * 50

response = client.messages.create(
    model="claude-sonnet-4.6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": f"Reference document:\n\n{long_document}",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {"role": "user", "content": "Summarize the key points."}
    ],
)

print(response.usage)
# Usage(input_tokens=1500, output_tokens=80,
#   cache_creation_input_tokens=1024, cache_read_input_tokens=0)

# 第二次调用——从缓存读取而非写入
response2 = client.messages.create(
    model="claude-sonnet-4.6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": f"Reference document:\n\n{long_document}",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {"role": "user", "content": "What's the main topic?"}
    ],
)

print(response2.usage)
# Usage(input_tokens=476, output_tokens=40,
#   cache_creation_input_tokens=0, cache_read_input_tokens=1024)

DeepSeek 自动缓存

DeepSeek 与 OpenAI 类似，自动缓存提示前缀，无需配置。

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# DeepSeek 在重复调用相同前缀时自动缓存
response = client.chat.completions.create(
    model="deepseek/deepseek-v3.2",
    messages=[
        {"role": "system", "content": "<long context>" * 100},
        {"role": "user", "content": "Analyze the above."},
    ],
)

# 在 usage 中检查缓存命中
print(response.usage.prompt_tokens_details.cached_tokens)

xAI（Grok）自动缓存

Grok 模型在跨请求重用相同前缀时自动缓存提示前缀，无需特殊配置。

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# Grok 在重复调用相同前缀时自动缓存
response = client.chat.completions.create(
    model="x-ai/grok-4.20",
    messages=[
        {"role": "system", "content": "<long system prompt>" * 100},
        {"role": "user", "content": "Answer the question."},
    ],
)

# usage 中反映缓存命中
print(response.usage.prompt_tokens_details)

Groq 自动缓存

Groq 的推理基础设施为支持的模型自动缓存提示前缀。缓存命中降低延迟，并反映在响应 usage 对象中。

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# Groq 在重复调用时自动缓存
response = client.chat.completions.create(
    model="groq/meta-llama/llama-4-maverick",
    messages=[
        {"role": "system", "content": "<long context>" * 100},
        {"role": "user", "content": "Analyze the above."},
    ],
)

print(response.usage.prompt_tokens_details.cached_tokens)

Google Gemini Prompt 缓存

Gemini 支持隐式（自动）和显式缓存。

隐式缓存

Gemini 2.5 Flash 和 Pro 自动缓存大型上下文，无需额外费用。缓存命中在响应 usage 中可见。

通过 Gemini 原生 API 进行显式缓存

如需精细控制，可使用 Gemini 原生 cachedContents API。您创建缓存对象并在后续请求中引用它：

{
  "model": "models/gemini-2.5-flash",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "What are the key points in this document?"
        }
      ]
    }
  ],
  "cachedContent": "cachedContents/abc123"
}

通过 ARouter 的提供商代理使用 Gemini 原生端点处理缓存内容：

# 创建缓存内容
curl https://api.arouter.ai/google/v1beta/cachedContents \
  -X POST \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-2.5-flash",
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "<large document content>"}]
      }
    ],
    "ttl": "3600s"
  }'

响应包含 name 字段（如 cachedContents/abc123），在后续请求中引用：

curl https://api.arouter.ai/google/v1beta/models/gemini-2.5-flash:generateContent \
  -X POST \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Summarize"}]}],
    "cachedContent": "cachedContents/abc123"
  }'

缓存使用情况出现在响应中：

{
  "usageMetadata": {
    "promptTokenCount": 200,
    "cachedContentTokenCount": 1500,
    "candidatesTokenCount": 50,
    "totalTokenCount": 250
  }
}

提供商粘性路由

为最大化缓存命中率，您的重复请求应到达同一提供商实例。ARouter 支持粘性路由，确保需要的提供商获得此保证。当您的请求中包含 Anthropic cache_control 块时，ARouter 自动将具有相同前缀的后续请求路由到同一提供商端点，保持缓存有效性。

粘性路由工作原理

带有 cache_control 块的首次请求在提供商处处理并缓存
ARouter 记录处理该请求的提供商实例
具有相同缓存前缀的后续请求被路由到同一实例
缓存命中降低您的费用（读取比写入便宜）并减少延迟

验证缓存命中

检查 usage 对象以确认跨请求的缓存命中：

# 首次请求——缓存未命中，写入内容
response1 = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {"role": "system", "content": [{"type": "text", "text": long_doc, "cache_control": {"type": "ephemeral"}}]},
        {"role": "user", "content": "Question 1"},
    ],
)
# prompt_tokens_details.cache_write_tokens > 0
print(response1.usage.prompt_tokens_details)

# 第二次请求——缓存命中
response2 = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {"role": "system", "content": [{"type": "text", "text": long_doc, "cache_control": {"type": "ephemeral"}}]},
        {"role": "user", "content": "Question 2"},
    ],
)
# prompt_tokens_details.cached_tokens > 0（缓存命中！）
print(response2.usage.prompt_tokens_details)

提供商缓存支持汇总

提供商	缓存类型	最少 Token	TTL	配置
OpenAI	自动	1,024	约 1 小时	无需配置
Anthropic	自动 + 显式	1,024	5 分钟（自动），1 小时（显式）	`cache_control` 块
DeepSeek	自动	1,024	供应商定义	无需配置
Google Gemini	自动 + 显式	32,768	默认 1 小时	`cachedContents` API
xAI（Grok）	自动	供应商定义	供应商定义	无需配置
Groq	自动	供应商定义	供应商定义	无需配置

快速开始

核心概念

路由

功能特性

使用指南

隐私

管理

最佳实践

框架与集成

供应商接入

帮助

查看缓存使用情况

OpenAI 自动缓存

Anthropic Claude Prompt 缓存

缓存 TTL

支持的模型

显式缓存示例

DeepSeek 自动缓存

xAI（Grok）自动缓存

Groq 自动缓存

Google Gemini Prompt 缓存

隐式缓存

通过 Gemini 原生 API 进行显式缓存

提供商粘性路由

粘性路由工作原理

验证缓存命中

提供商缓存支持汇总

​查看缓存使用情况

​OpenAI 自动缓存

​Anthropic Claude Prompt 缓存

​缓存 TTL

​支持的模型

​显式缓存示例

​DeepSeek 自动缓存

​xAI（Grok）自动缓存

​Groq 自动缓存

​Google Gemini Prompt 缓存

​隐式缓存

​通过 Gemini 原生 API 进行显式缓存

​提供商粘性路由

​粘性路由工作原理

​验证缓存命中

​提供商缓存支持汇总

查看缓存使用情况

OpenAI 自动缓存

Anthropic Claude Prompt 缓存

缓存 TTL

支持的模型

显式缓存示例

DeepSeek 自动缓存

xAI（Grok）自动缓存

Groq 自动缓存

Google Gemini Prompt 缓存

隐式缓存

通过 Gemini 原生 API 进行显式缓存

提供商粘性路由

粘性路由工作原理

验证缓存命中

提供商缓存支持汇总