缓存创建
Claude 提示词缓存可以把频繁复用的大段上下文缓存起来,减少重复输入的成本,并在一定程度上提升响应速度。适合大型系统提示词、长参考文档、固定示例数据等场景。
概述
Prompt Caching 通过 cache_control 标记需要缓存的内容。缓存内容通常需要达到一定长度才会创建成功,建议用于 2048 tokens 以上的稳定上下文。
功能特性
- 支持缓存大型系统提示词。
- 降低重复调用时的输入 Token 成本。
- 适合长文档、多轮分析、固定上下文复用。
- 临时缓存通常有有效期,过期后需要重新创建。
请求地址
https://api.maomaotoken.com/v1/messagesPython 示例代码
下面示例演示如何在 system 中设置 cache_control: {"type": "ephemeral"},并通过响应里的 usage 字段检查缓存是否创建成功。
import json
import os
import requests
# ==================== 配置参数 ====================
API_KEY = os.getenv("MAOMAO_API_KEY", "sk-************************************")
API_URL = "https://api.maomaotoken.com/v1/messages"
headers = {
"content-type": "application/json",
"x-api-key": API_KEY,
"anthropic-version": "2023-06-01",
}
LONG_CONTEXT = """
You are an AI assistant tasked with analyzing literary works.
Your goal is to provide insightful commentary on themes, characters, and writing style.
Below is a long reference document for analysis.
Pride and Prejudice - Chapter 1 to 5 (Excerpt)
It is a truth universally acknowledged, that a single man in possession of a good fortune,
must be in want of a wife.
...这里放入足够长、会被多次复用的系统提示词、参考资料或示例文本...
Additional chapters and content would continue here to ensure the cache threshold is clearly exceeded.
"""
payload = {
"model": "claude-sonnet-4-6",
"system": [
{
"type": "text",
"text": LONG_CONTEXT,
"cache_control": {
"type": "ephemeral"
}
}
],
"messages": [
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice."
}
]
}
def main():
print("[START] 开始调用 Claude API,测试缓存创建")
print(f"[INFO] API 端点: {API_URL}")
print(f"[INFO] 使用模型: {payload['model']}")
print("-" * 60)
try:
response = requests.post(
API_URL,
headers=headers,
json=payload,
timeout=30
)
if response.status_code != 200:
print(f"[ERROR] 请求失败,状态码: {response.status_code}")
print(response.text)
return
result = response.json()
usage = result.get("usage", {})
print("[SUCCESS] 请求成功")
print("\n[USAGE] Token 使用统计:")
print(f" - 输入 tokens: {usage.get('input_tokens', 0)}")
print(f" - 输出 tokens: {usage.get('output_tokens', 0)}")
print(f" - 缓存创建 tokens: {usage.get('cache_creation_input_tokens', 0)}")
print(f" - 缓存读取 tokens: {usage.get('cache_read_input_tokens', 0)}")
cache_created = usage.get("cache_creation_input_tokens", 0)
if cache_created > 0:
print(f"\n[CACHE] 缓存创建成功,已缓存 {cache_created} tokens")
else:
print("\n[WARNING] 缓存未创建")
print("可能原因:内容长度不足、未正确设置 cache_control,或接口配置不符合要求。")
content = result.get("content", [])
if content:
text = content[0].get("text", "")
print("\n[RESPONSE] Claude 回复预览:")
print(text[:300] + "..." if len(text) > 300 else text)
except requests.exceptions.Timeout:
print("[ERROR] 请求超时")
except requests.exceptions.ConnectionError:
print("[ERROR] 连接错误")
except requests.exceptions.RequestException as e:
print(f"[ERROR] 请求异常: {e}")
except json.JSONDecodeError:
print("[ERROR] JSON 解析错误")
if __name__ == "__main__":
main()代码说明
| 步骤 | 说明 |
|---|---|
| 配置缓存控制 | 在 system 内容块中添加 cache_control: {"type": "ephemeral"}。 |
| 准备足够内容 | 缓存内容建议超过 2048 tokens。 |
| 检查缓存状态 | 通过 usage.cache_creation_input_tokens 判断是否创建成功。 |
响应示例
[START] 开始调用 Claude API,测试缓存创建
[INFO] API 端点: https://api.maomaotoken.com/v1/messages
[INFO] 使用模型: claude-sonnet-4-6
------------------------------------------------------------
[SUCCESS] 请求成功
[USAGE] Token 使用统计:
- 输入 tokens: 17
- 输出 tokens: 1043
- 缓存创建 tokens: 2073
- 缓存读取 tokens: 0
[CACHE] 缓存创建成功,已缓存 2073 tokens
[RESPONSE] Claude 回复预览:
# Major Themes in Pride and Prejudice
Based on the opening chapters provided, here is an analysis of the major themes...Usage 字段说明
| 字段 | 说明 |
|---|---|
input_tokens | 本次请求的新输入 Token。 |
output_tokens | 模型输出 Token。 |
cache_creation_input_tokens | 本次创建缓存的 Token 数。大于 0 通常表示创建成功。 |
cache_read_input_tokens | 本次命中并读取缓存的 Token 数。 |
使用建议
01适合缓存大型系统提示词、长参考文档、固定示例数据。
02不适合缓存一次性请求、频繁变化的上下文、短提示词。
03成本优化只有同一段上下文会被多次复用时,缓存才更有意义。
注意事项
- 请将示例中的 API Key 替换为你的真实 MaomaoToken API Key。
- 缓存内容通常需要至少 1024 tokens,建议 2048+ tokens。
- 临时缓存有有效期,过期后需要重新创建。
- 缓存命中受内容、时间窗口和请求一致性影响。
- 不要把真实 API Key 写入公开仓库,建议使用环境变量管理。