提示词缓存 (Prompt Caching)

通过复用请求间的公共前缀(system / 工具定义 / 历史消息),缓存能显著降低延迟并节省费用。一个模型在哪几个协议(v1/chat/completions / v1/messages / v1/responses)下能用缓存,见下方矩阵。

按触发方式分两种机制:

隐式缓存(implicit) —— 平台自动识别请求间的公共前缀,客户端不需要任何参数;命中后按折扣价计费,没有写入开销。OpenAI / DeepSeek / Gemini / Doubao / Qwen 等绝大多数模型走这条路。
显式缓存(explicit) —— 客户端在请求里通过 cache_control 字段主动标记前缀检查点,可选 5 分钟 / 1 小时 TTL,写入和读取分别计费。Anthropic Claude 全系是这条路线。

各模型实际支持的协议、缓存能力、单价以模型目录为准 —— 模型卡片的 API 行列出了支持的协议,价格表的「缓存读 / 缓存写」列给出单价。

协议 × 厂商缓存矩阵

下表汇总主流厂商在三个协议下的缓存行为。

厂商 / 模型范围	缓存机制	`v1/chat/completions`	`v1/messages`	`v1/responses`	客户端是否要配置
Anthropic Claude(4.x / 5.x)	显式 `cache_control`	✅ `tools` 字段最稳定;`system` / `messages` 取决于 SDK 是否按 OpenAI 标准 content block 格式包装,可能失真	✅ 原生完整支持(system / messages / tools 全字段)	❌ 上游不支持	需要
Azure OpenAI(GPT-4o / GPT-4.1 / GPT-5.x / o1·o3·o4)	隐式自动	✅ 自动	✅ 自动	✅ 自动(GPT-5.x / o3 / o4 / o1 等支持的型号)	不需要
DeepSeek V4(`deepseek-v4-pro` / `flash`)	隐式自动	✅ 自动	✅ 自动	❌ 上游不支持	不需要
Google Gemini(2.5 / 3.x Pro)	隐式自动	✅ 自动	❌ 不支持	❌ 上游不支持	不需要
Doubao 1.6+	隐式自动	✅ 自动	❌ 不支持	❌ 上游不支持	不需要
阿里 Qwen(qwen3.5-plus / qwen3.6-plus·flash·max)	隐式自动(上游 DashScope)	⚠ 上游响应含 `cached_tokens`,Turing 当前未差异化计费(按标准输入价计)	⚠ 同左	❌ 上游不支持	不需要

完整型号清单和当前协议支持以模型目录中每个模型卡片的 API 字段为准,本表只列代表性范围。v1/responses 是 OpenAI 推出的新协议(用于 GPT-5 系列的有状态 reasoning / MCP connector 等),目前仅 Azure OpenAI 系模型支持。

厂商上游缓存文档

Anthropic Claude —— Prompt Caching
Azure OpenAI —— OpenAI Prompt Caching / Azure OpenAI Prompt Caching
DeepSeek —— KV Cache 官方说明
Google Gemini —— Vertex AI Context Caching
Doubao 火山方舟 —— Context Cache
阿里 Qwen(百炼) —— Context Cache 说明

隐式缓存 (Implicit Cache)

工作机制

上游(Azure OpenAI / DashScope / Vertex AI / 火山方舟)在自己的推理集群内自动对最近请求的前缀做 KV 复用
命中条件是严格前缀匹配:从请求起始到某个 token 为止,内容必须与之前已缓存的请求完全一致(包括 system、历史 messages、tools)
TTL 由上游平台动态管理(通常几分钟到一小时,长时间不访问会被清理);Azure OpenAI 可通过 prompt_cache_retention 请求 in_memory 或 24h 保留策略(具体取决于模型支持)
命中部分按缓存读价计费,没有写入开销

协议支持

v1/chat/completions —— 所有支持隐式缓存的模型默认入口。
v1/responses —— 仅 Azure OpenAI 系模型(GPT-5.x / o1·o3·o4 等)可用;隐式缓存照常生效,响应里 cached_tokens 字段相同。
v1/messages —— Azure OpenAI、DeepSeek V4 可用 messages 协议调用并享受隐式缓存(Qwen 3.5/3.6 plus 系列也可走 messages,但 Turing 暂未差异化计费,见上方矩阵)。响应字段格式按 messages 协议返回(见下方「响应字段速查」)。

触发与命中检查

各厂商最小命中前缀长度差异较大:

厂商	最小匹配长度	上游官方文档
Azure OpenAI(GPT 系 / o 系)	~1,024 tokens	OpenAI Prompt Caching
DeepSeek V4	256 tokens	DeepSeek KV Cache
Gemini 2.5 / 3.x Pro	~1,024 tokens	Vertex AI 定价
Doubao 1.6+	见火山方舟文档	火山方舟 Context Cache
Qwen 3.5+ / 3.6 系列	见 DashScope 文档	百炼 Context Cache

具体型号、是否支持隐式缓存、缓存读价见模型目录 ——「缓存读」列有数值即代表该型号已开启隐式缓存。

Azure OpenAI 的缓存控制字段

Azure OpenAI 不提供单独的 "create cache" API,也不需要像 Claude 那样在内容块上标记 cache_control。第一次满足条件的请求会自动 warm cache,后续相同长前缀请求命中后,响应中的 usage.prompt_tokens_details.cached_tokens 会大于 0。

Azure 支持两个可选字段来提高命中稳定性或调整保留时间:

字段	作用	是否必填
`prompt_cache_key`	与前缀 hash 一起参与路由,让共享长前缀的请求更容易落到同一缓存位置	否
`prompt_cache_retention`	请求缓存保留策略,常见值为 `in_memory` / `24h`;可用值和默认值随模型变化	否

不传这两个字段时,Azure 仍会默认开启 prompt caching;只是命中率和保留时长完全由上游默认策略决定。Azure 要求请求至少约 1,024 tokens,且前 1,024 tokens 完全一致;之后每 128 个相同 token 继续计入缓存命中。

Chat Completions 示例:

{
  "model": "turing/gpt-5.5",
  "messages": [
    { "role": "system", "content": "稳定 system prompt,不要混入时间戳或随机 ID。" },
    { "role": "user", "content": "这里放超过 1,024 tokens 且后续完全不变的长前缀..." }
  ],
  "prompt_cache_key": "my-stable-prefix-v1",
  "prompt_cache_retention": "24h",
  "max_completion_tokens": 256
}

Responses 示例:

{
  "model": "turing/gpt-5.5",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        { "type": "input_text", "text": "这里放超过 1,024 tokens 且后续完全不变的长前缀..." }
      ]
    }
  ],
  "prompt_cache_key": "my-stable-prefix-v1",
  "prompt_cache_retention": "24h",
  "max_output_tokens": 256
}

实践建议:

把稳定的大段内容放在 messages / input 的最前面,动态问题放最后。
system、tools schema、assistant 历史都可以参与缓存,但前缀中任何字符、顺序、图片 detail、工具定义变化都会导致 miss。
对同一类长前缀使用稳定的 prompt_cache_key,不要每轮随机生成。
第一次请求通常是 warm,cached_tokens 可能为 0;第二次及之后才应观察命中。

最小示例(无需任何额外字段):

curl $TURING_BASE_URL/chat/completions \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      { "role": "system", "content": "[共享的大段 system prompt,>= 256 tokens]" },
      { "role": "user", "content": "今天的问题" }
    ]
  }'

后续请求只要 system 与历史 messages 完全一致,平台会自动命中。在响应里查看缓存命中量:

{
  "usage": {
    "prompt_tokens": 1280,
    "completion_tokens": 80,
    "total_tokens": 1360,
    "prompt_tokens_details": {
      "cached_tokens": 1024
    }
  }
}

显式缓存 (Explicit Cache, Anthropic Claude)

官方文档:Anthropic Prompt Caching
适用接口:v1/messages(原生)/ v1/chat/completions
适用模型:以模型目录 → Claude 中的缓存读 / 写单价与能力标记为准。

工作机制

客户端在需要缓存的内容对象上加 cache_control: { "type": "ephemeral" },标记一个前缀检查点——从请求起始到该检查点的所有内容会被缓存
TTL 可选 5 分钟(默认)或 1 小时(部分模型,见下表)
单请求最多 4 个检查点
严格前缀匹配:检查点之前任何 token 不同则不命中
写入(创建)和读取(命中)分别计费:写入价高于基础输入价,读取价远低于基础输入价

缓存配置(全系通用)

配置项	取值
最小词元数	1,024 tokens(`claude-opus-4.5` / `claude-haiku-4.5` 为 4,096)
单请求最大检查点数	4
TTL 选项	5 分钟(默认)/ 1 小时(Sonnet 4.5 起支持,更早期 4.x 仅 5 分钟)

具体型号清单与缓存读 / 写单价见模型目录 → Claude ——「缓存读」「缓存写 5m」「缓存写 1h」列即对应单价。

协议差异(Anthropic 专属)

Claude 模型同时暴露 v1/messages 和 v1/chat/completions 两个协议,两者都能用 cache_control,但生效范围有差别:

注意

v1/messages(Anthropic SDK):上游原生协议,cache_control 在 system / messages / tools 三个字段上均完整生效。
v1/chat/completions(OpenAI SDK):tools[*].cache_control 最稳定;system / messages 中的 cache_control 是否生效取决于 SDK 是否按 OpenAI 标准 content block 格式包装,可能失真。可通过响应里的 usage.cache_creation_input_tokens 是否非零判断。

在 v1/messages 中使用

下面这个例子同时演示了在 system 上打 1 小时 TTL 检查点、在 tools 末尾打 5 分钟 TTL 检查点。messages 中如需缓存历史上下文,在对应 content block 上按相同写法加 cache_control 即可。

cURL
Python

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是一名资深法律顾问...[数千 token 的固定背景知识]",
        "cache_control": { "type": "ephemeral", "ttl": "1h" }
      }
    ],
    "tools": [
      { "name": "search_orders", "description": "...", "input_schema": { "type": "object", "properties": {} } },
      { "name": "get_customer_info", "description": "...", "input_schema": { "type": "object", "properties": {} },
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [
      { "role": "user", "content": "帮我查 ORD-2024-001 的状态" }
    ]
  }'

from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_TURING_API_KEY",
    base_url="https://live-turing.cn.llm.tcljd.com/api",
)

response = client.messages.create(
    model="turing/claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "你是一名资深法律顾问...[数千 token 的固定背景知识]",
            "cache_control": {"type": "ephemeral", "ttl": "1h"},  # 1 小时 TTL
        }
    ],
    tools=[
        {"name": "search_orders", "description": "...", "input_schema": {"type": "object", "properties": {}}},
        {
            "name": "get_customer_info",
            "description": "...",
            "input_schema": {"type": "object", "properties": {}},
            "cache_control": {"type": "ephemeral"},  # 默认 5 分钟
        },
    ],
    messages=[{"role": "user", "content": "帮我查 ORD-2024-001 的状态"}],
)

在 v1/chat/completions 中使用

OpenAI 兼容协议下,在 tools[*] 上打 cache 检查点是稳定生效的用法。system / messages 上的 cache_control 行为见上方协议差异说明。

curl $TURING_BASE_URL/chat/completions \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "帮我查 ORD-2024-001 的状态" }
    ],
    "tools": [
      {
        "type": "function",
        "function": { "name": "search_orders", "description": "...", "parameters": {} }
      },
      {
        "type": "function",
        "function": { "name": "update_order_status", "description": "...", "parameters": {} },
        "cache_control": { "type": "ephemeral" }
      }
    ]
  }'

在 system / messages 上完整生效的 cache_control 写法见 v1/messages 协议,详见选择合适的接口。

响应字段速查

可在请求里加 turing_options.include_service_usages: true 获取细分明细(含 5m / 1h TTL 拆分、计费金额、耗时)。

v1/chat/completions 响应

{
  "usage": {
    "prompt_tokens": 5139,
    "completion_tokens": 377,
    "total_tokens": 5516,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_creation_tokens": 5136
    },
    "cache_creation_input_tokens": 5136,
    "cache_read_input_tokens": 0
  }
}

v1/messages 响应

{
  "usage": {
    "input_tokens": 5139,
    "output_tokens": 377,
    "cache_creation_input_tokens": 5136,
    "cache_read_input_tokens": 0
  }
}

后续命中时,cache_creation_input_tokens = 0、cache_read_input_tokens = 5136。

字段含义

字段	出现位置	说明
`usage.prompt_tokens_details.cached_tokens`	仅 `v1/chat/completions`	本次缓存命中的 token 数(含隐式与显式)
`usage.cache_creation_input_tokens`	两者均有	本次写入缓存的 token 数(仅显式缓存非零)
`usage.cache_read_input_tokens`	两者均有	本次从缓存读取的 token 数(显式缓存)
`service_usages[].usage_detail.prompt_tokens_details.cached_tokens`	需开启 `include_service_usages`	与上行一致,持久化对账
`service_usages[].usage_detail.prompt_tokens_details.cache_creation_token_details.ephemeral_5m_input_tokens`	同上	5 分钟 TTL 创建的 token 数
`service_usages[].usage_detail.prompt_tokens_details.cache_creation_token_details.ephemeral_1h_input_tokens`	同上	1 小时 TTL 创建的 token 数
`service_usages[].bill_amount` / `bill_currency`	同上	本次该服务实际计费金额与币种

注意事项

隐式缓存对前缀稳定性敏感:长 system prompt 不要混入时间戳、UUID、当前用户名等动态内容,会导致缓存全部失效。Azure OpenAI 可用稳定的 prompt_cache_key 提高同一长前缀的命中稳定性,但它不会放宽严格前缀匹配要求。
跨模型不复用:不同模型 ID(包括同系列的 pro / flash / mini)各自维护缓存,切模型即丢缓存。
严格前缀匹配(两种模式通用):被缓存内容之前的所有 token 必须与先前请求完全一致,否则不命中。
显式缓存的最小 token 阈值:Claude Opus 4.5 / Haiku 4.5 要求 ≥ 4,096 tokens,其余 Claude 模型为 1,024 tokens;不达标则缓存不会被创建。
显式缓存的检查点上限:每请求最多 4 个 cache_control 检查点,可分布在 system / tools / messages 中。
显式缓存的回本阈值:首次写入比标准输入贵,需该缓存被后续请求命中 ≥ 2 次才整体降本。请求重复率低的场景开启缓存可能不划算,具体单价对比见模型目录。

如需查看实际计费明细,详见用量与计费。

协议 × 厂商 缓存矩阵​

厂商上游缓存文档​

隐式缓存 (Implicit Cache)​

工作机制​

协议支持​

触发与命中检查​

Azure OpenAI 的缓存控制字段​

显式缓存 (Explicit Cache, Anthropic Claude)​

工作机制​

缓存配置(全系通用)​

协议差异(Anthropic 专属)​

在 v1/messages 中使用​

在 v1/chat/completions 中使用​

响应字段速查​

v1/chat/completions 响应​

v1/messages 响应​

字段含义​

注意事项​

协议 × 厂商缓存矩阵

厂商上游缓存文档

隐式缓存 (Implicit Cache)

工作机制

协议支持

触发与命中检查

Azure OpenAI 的缓存控制字段

显式缓存 (Explicit Cache, Anthropic Claude)

工作机制

缓存配置(全系通用)

协议差异(Anthropic 专属)

在 v1/messages 中使用

在 v1/chat/completions 中使用

响应字段速查

v1/chat/completions 响应

v1/messages 响应

字段含义

注意事项