Claude 提示词缓存

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "stream": true,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."
      },
      {
        "type": "text",
        "text": "Pride and Prejudice by Jane Austen... [此处放置完整文本内容]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 16000
    },
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    api_key="sk-***", # 换成你在 AiHubMix 生成的密钥
    base_url="https://aihubmix.com"
)

# 使用缓存的流式响应
with client.messages.stream(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    thinking={
        "type": "enabled",
        "budget_tokens": 16000
    },
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# 非流式响应
message = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=20000,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works."
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}
    ]
)
print(message.content)

import requests

url = "https://aihubmix.com/v1/messages"
headers = {
    "content-type": "application/json",
    "x-api-key": "sk-***", # 换成你在 AiHubMix 生成的密钥
    "anthropic-version": "2023-06-01"
}
data = {
    "stream": True,
    "model": "claude-opus-4-20250514",
    "max_tokens": 20000,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
        },
        {
            "type": "text",
            "text": "<the entire contents of 'Pride and Prejudice'>",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "thinking": {
        "type": "enabled",
        "budget_tokens": 16000
    },
    "messages": [{"role": "user", "content": "Analyze the major themes in 'Pride and Prejudice'."}]
}

response = requests.post(url, headers=headers, json=data, stream=True)

# 检查响应状态
if response.status_code == 200:
    # Process the streaming response
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))
else:
    print(f"Error: {response.status_code}, {response.text}")

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

​

提示词缓存的工作原理

1. 系统会检查是否已经缓存了最近查询中指定缓存断点之前的提示词前缀
2. 如果找到，就使用缓存版本，减少处理时间和成本
3. 否则，系统会处理完整提示词，并在开始响应时缓存前缀部分

• 包含大量示例的提示词
• 大量的上下文或背景信息
• 具有一致指令的重复任务
• 长时间的多轮对话

​

常见错误：写了缓存却”只写不读”

​

❌ 错误写法：把每轮会变的问题放在断点前面

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结这份资料的核心观点。" },                          // ← 每轮会变,却放在断点前
        { "type": "text", "text": "<大文档>", "cache_control": { "type": "ephemeral" } }   // 断点
      ]
    }
  ]
}

​

✅ 正确写法：大文档放最前 + 断点 + 问题放最后

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<固定不变的大文档/参考资料，≥4096 token>", "cache_control": { "type": "ephemeral" } },  // 断点;前缀恒定
        { "type": "text", "text": "请总结这份资料的核心观点。" }                                                          // ← 每轮变化的问题,放在断点之后
      ]
    }
  ]
}

​

实测对照（claude-opus-4-6，两次调用间隔数秒）

1. 固定不变的大块（参考文档、长上下文）放在 messages 用户消息的最前面，cache_control 打在它末尾，这段内容一个字都不能动；
2. 每轮变化的问题/指令放到断点之后（同一条 user 消息里大文档之后，或后续消息）；多轮对话只往后追加，不要回头修改历史消息；
3. 开启 thinking 时，历史助手轮里的思考块要原样回传，否则前缀同样会断（见下文「无法缓存的内容」）；
4. 若该块小于最小缓存门槛（不同模型 512–4,096 Token 不等，见下文「缓存限制」），即使显式设置 cache_control 也不会被缓存——这是预期行为。

​

缓存定价

• 5 分钟缓存写入 Token 价格为基础输入 Token 价格的 1.25 倍
• 1 小时缓存写入 Token 价格为基础输入 Token 价格的 2 倍
• 缓存读取 Token 价格为基础输入 Token 价格的 0.1 倍
• 常规输入和输出 Token 按平台标准费率计价

​

如何实现提示词缓存

​

支持的模型

​

自动缓存（顶层 cache_control）

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are an AI assistant tasked with analyzing literary works.",
  "messages": [
    {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
  ]
}

​

构建提示词结构

​

缓存限制

• “ephemeral”：默认 5 分钟生存期
• 1 小时缓存：在 cache_control 中设置 "ttl": "1h"，适用于需要更长缓存时间的场景

​

1 小时缓存持续时间

curl https://aihubmix.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: AIHUBMIX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "system": [
      {
        "type": "text",
        "text": "Long-term instructions...",
        "cache_control": {
          "type": "ephemeral",
          "ttl": "1h"
        }
      }
    ],
    "messages": [...]
  }'

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
  }
}

​

何时使用 1 小时缓存

• 批处理作业：处理大量具有共同前缀的请求
• 长时间会话：需要在较长时间内保持上下文的对话
• 大型文档分析：对同一文档进行多次不同类型的分析
• 代码库问答：在较长时间内对同一代码库进行多次查询

​

混合不同的 TTL

{
  "system": [
    {
      "type": "text", 
      "text": "Long-term instructions...",
      "cache_control": {
        "type": "ephemeral",
        "ttl": "1h"
      }
    },
    {
      "type": "text",
      "text": "Short-term context...", 
      "cache_control": {
        "type": "ephemeral",
        "ttl": "5m"
      }
    }
  ]
}

​

可以缓存的内容

• 工具：tools 数组中的工具定义
• 系统消息：system 数组中的内容块
• 消息：messages.content 数组中的内容块，包括用户和助手的对话轮次
• 图片和文档：用户对话轮次中 messages.content 数组的内容块
• 工具使用和工具结果：用户和助手对话轮次中 messages.content 数组的内容块

​

无法缓存的内容

• 思考块无法直接使用 cache_control 缓存。但是，当思考块出现在之前的助手回合中时，可以与其他内容一起缓存。以这种方式缓存时，从缓存读取时它们确实计为输入 Token。
• 子内容块（如引用）本身无法直接缓存。相反，缓存顶级块。
• 空文本块无法缓存。

​

跟踪缓存性能

• cache_creation_input_tokens: 创建新缓存条目时写入缓存的 Token 数
• cache_read_input_tokens: 从缓存中检索的 Token 数
• input_tokens: 未从缓存读取或用于创建缓存的输入 Token 数

​

有效缓存的最佳实践

• 缓存稳定的、可重用的内容，如系统指令、背景信息、大型上下文或常用工具定义
• 将缓存内容放在提示词开头以获得最佳性能
• 策略性地使用缓存断点来分隔不同的可缓存前缀部分
• 定期分析缓存命中率并根据需要调整策略
• 对于长期使用的内容，考虑使用 1 小时缓存以获得更好的成本效益

​

针对不同用例的优化

• 对话代理：减少长时间对话的成本和延迟，特别是那些有长指令或上传文档的对话
• 编程助手：通过在提示词中保留相关部分或代码库的摘要版本，改善自动完成和代码库问答
• 大文档处理：在提示词中包含完整的长篇材料 (包括图片)，而不增加响应延迟
• 详细指令集：共享广泛的指令、程序和示例列表来微调 Claude 的响应。开发者通常在提示词中包含一两个示例，但使用提示词缓存，你可以通过包含 20+ 个高质量答案的多样化示例获得更好的性能
• 代理工具使用：提升涉及多个工具调用和迭代代码更改的场景性能，每个步骤通常需要新的 API 调用
• 与书籍、论文、文档、播客记录和其他长篇内容对话：通过在提示词中嵌入整个文档，让用户能够提问

​

常见问题解决

• 确保缓存部分在不同调用之间完全相同，并在相同位置标记了 cache_control
• 检查调用是否在缓存生存期内（5 分钟或 1 小时）
• 验证 tool_choice 和图片使用在调用之间保持一致
• 确认你缓存的 Token 数至少达到最小要求
• 虽然系统会尝试使用缓存断点之前位置的已缓存内容，但你可以使用额外的 cache_control 参数来保证查找提示词前面部分的缓存，这对于包含很长内容块列表的查询可能很有用

​

缓存存储和共享

• 组织隔离： 缓存在组织之间是隔离的。不同组织永远不会共享缓存，即使它们使用相同的提示词。
• 精确匹配： 缓存命中需要 100% 相同的提示词段，包括标记有 cache control 的块之前及其本身的所有文本和图片。在缓存读取和创建期间必须用 cache_control 标记相同的块。
• 输出 Token 生成： 提示词缓存不会影响输出 Token 生成。你收到的响应将与不使用提示词缓存时完全相同。

​

在客户端 / 平台中启用 Claude 缓存

​

Dify（通过 Aihubmix 插件）

1. 用 <cache>…</cache> 包裹要缓存的提示词（固定不变的系统提示词 / 长上下文），插件会在该处自动转换成 cache_control 断点；
2. 在模型参数里把「大消息自动缓存阈值」设为一个正整数：内容达到该 Token 阈值才会真正写缓存（仍受下文「缓存限制」的最小缓存约束，Opus 4.5/4.6、Haiku 4.5 为 4096 Token），设 0 或留空则关闭。

​

Cherry Studio

1. 点击 Aihubmix 供应商名称右侧的齿轮，打开「API 设置」（API Settings）：

2. 配置以下三项，客户端会据此为 Claude 自动注入 cache_control：

• 缓存 Token 阈值（Cache Token Threshold）：内容超过该 Token 数才注入缓存断点（设正数开启，0 或留空关闭）；
• 缓存系统消息（Cache System Message）：开启后给 system 消息打缓存断点（适合缓存固定的长系统提示词）；
• 缓存最后 N 条消息（Cache Last N Messages）：给最近 N 条消息打缓存断点（适合多轮对话滚动缓存）。

​

常见问题（FAQ）

​

为什么写了缓存（cache_creation_input_tokens 很大）却一直读不到（cache_read_input_tokens 为 0）？

​

缓存最少需要多少 Token？

​

缓存有效期多久？能改成 1 小时吗？

​

在 Dify / Cherry Studio 里怎么开缓存？

​

不同模型的支持情况

• 是否支持 Prompt Caching 取决于模型本身。
• 如果模型本身支持，并且不需要显式声明相关的参数，则通过 opanai 兼容格式转发可以支持。
• OpenAI 默认支持 Prompt Caching，自动生效（前缀 ≥1024 Token）。GPT-5.6 之前的模型缓存写入不另计费，不活跃 5-10 分钟后自动清除；GPT-5.6 及之后缓存写入按 1.25 倍输入价计费、读取按 0.1 倍计费，缓存至少保留 30 分钟，并支持显式缓存断点。详见 GPT 提示词缓存。
• Claude 需要原生的 cache_control: { type: "ephemeral" } 声明，缓存费率为常规输入的 1.25 倍（5 分钟）或 2 倍（1 小时），缓存 Tokens 读取费用为 0.1 倍，生命周期 5 分钟或 1 小时。文档
• Deepseek V3 和 R1 原生支持，缓存费率为常规输入的 1 倍，缓存 Tokens 读取费用为 0.1 倍。文档
• Gemini 模型支持隐式缓存：
  • 隐式缓存：默认情况下为所有 Gemini 2.5 模型启用。如果你的请求命中缓存，会自动传递成本节省。此功能自 2025 年 5 月 8 日起生效。上下文缓存的最低输入 Token 数：Gemini 2.5 Flash 为 1,024，Gemini 2.5 Pro 为 2,048。
    • 提高隐式缓存命中率的技巧：
      • 将大块的常见内容放在提示的开头。
      • 尝试在短时间内发送前缀相似的请求。
    • 你可以在响应对象的 usage_metadata 字段中查看缓存命中的 Token 数量。
    • 成本节省是根据预填充缓存命中次数衡量的。只有预填充缓存和 YouTube 视频预处理缓存支持隐式缓存。