Prompt Caching(提示词缓存)

Prompt caching 让重复的前缀按远低于正常输入价的费率计费。网关后面每个厂商的做法略有不同——有的需要你标记前缀,有的自动缓存——折扣按厂商费率透传。

两种启用方式

显式厂商只缓存你标记的前缀。在本网关上,cache_control 会在 Anthropic 兼容路径上转发;其他厂商的显式缓存通过它们自己的 API 暴露,而不是通过这个端点。自动厂商会缓存任何超过最低长度的前缀,无需改代码。适用哪一种取决于你调用的模型。

显式标记前缀

把稳定的部分放在前面,并标记它的最后一个 block。标记之前的全部内容构成缓存前缀,所以两次调用之间这部分必须逐字节一致:

curl https://synthorai.io/v1/chat/completions \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "system", "content": [
        {"type": "text", "text": "<your long, stable system prompt>",
         "cache_control": {"type": "ephemeral"}}
      ]},
      {"role": "user", "content": "The part that changes every call."}
    ]
  }'

逐厂商行为

各厂商的最低前缀、缓存存活时间与写入附加费:

转录自各厂商自己的官方文档;语义未经其文档核实的厂商不在此表内,而不是凭猜测填写。此处的最低值是厂商默认值——具体模型各有自己的门槛,有高有低(多个 Claude 模型要求 4,096 token,有一个只需 512)。以模型自己页面上的数字为准。模式写着显式的,用 cache_control 标记前缀在 Anthropic 兼容路径上有效;其他厂商的显式缓存要通过它们自己的 API。

账单上怎么体现

缓存读取按单独的、更低的输入费率计费——每次请求的用量里可见,每个模型的价格页也有。对写入缓存收费的厂商,首次调用高于普通输入价,所以缓存从第二次相同前缀开始回本。没有单独写入费率的模型,写入按普通输入价计费。

让缓存在一整段会话里保持有效

缓存条目属于厂商侧的某一把 API key。当一条渠道配了多把 key 时,连续调用可能落到不同的 key 上,于是又付一次写入费用。给同一段会话的每次调用带上同一个 X-Session-Id,网关就会把它们固定到同一条渠道、同一把 key。在 /v1/chat/completions 与 /v1/responses 上,请求体里的 prompt_cache_key 能达到同样效果,无需加头。

完整行为、限制与排障: 请求头

常见错误

• 把可变内容放在最前面。缓存匹配的是前缀。prompt 顶部的时间戳或用户 ID 会让它后面的一切失效。
• 前缀低于最低长度。低于门槛时既不缓存也不报告——看起来就像缓存悄无声息地失败了。请查模型页而不是这张表:有几个模型的门槛高于其厂商默认值。
• 两次调用间隔超过存活时间。空闲间隔长于 TTL,下次调用就要重新付写入成本。

完整请求体参考: Chat Completions