# Claude 提示缓存：cache_control、1 小时缓存与命中确认

Source: https://ofox.ai/zh/docs/develop/models/claude/caching

本页说明如何为 Claude 开启提示缓存并确认命中。模型 ID 与接口地址见 [Claude 系列概览](https://ofox.ai/zh/docs/develop/models/claude)。

**要点**:Claude 的缓存需要显式标记 cache_control，两种接口都不会自动缓存。

将长且固定的内容（系统提示词、文档、工具定义）放在请求开头，并在最后一个固定内容块上标记 `cache_control`。后续请求的前缀与之完全一致时，即可命中缓存。

**Anthropic 原生接口**

```python filename="claude_cache.py"
import os
import anthropic

client = anthropic.Anthropic(base_url="https://api.ofox.ai/anthropic", api_key=os.environ["OFOX_API_KEY"])
LONG_DOC = open("manual.txt", encoding="utf-8").read()  # 一份较长的固定文档

for question in ["第 3 章讲了什么？", "总结全文要点。"]:
    message = client.messages.create(
        model="anthropic/claude-sonnet-4.6",
        max_tokens=1024,
        system=[
            {"type": "text", "text": "根据下面的文档回答问题。"},
            {"type": "text", "text": LONG_DOC, "cache_control": {"type": "ephemeral"}},
        ],
        messages=[{"role": "user", "content": question}],
    )
    u = message.usage
    print("写入:", u.cache_creation_input_tokens, "读取:", u.cache_read_input_tokens)
```

**OpenAI 兼容接口**

```python filename="claude_cache_openai.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])
LONG_DOC = open("manual.txt", encoding="utf-8").read()

for question in ["第 3 章讲了什么？", "总结全文要点。"]:
    resp = client.chat.completions.create(
        model="anthropic/claude-sonnet-4.6",
        max_tokens=1024,
        messages=[
            {"role": "system", "content": [
                {"type": "text", "text": LONG_DOC, "cache_control": {"type": "ephemeral"}},
            ]},
            {"role": "user", "content": question},
        ],
    )
    details = resp.usage.prompt_tokens_details
    print("读取:", details.cached_tokens if details else 0)
```

| 项目 | 说明 |
|---|---|
| 有效期 | 默认 5 分钟，命中后重新计时；`"cache_control": {"type": "ephemeral", "ttl": "1h"}` 为 1 小时 |
| 确认命中（原生接口） | 首次请求 `usage.cache_creation_input_tokens` 大于 0；命中时 `usage.cache_read_input_tokens` 大于 0 |
| 确认命中（OpenAI 兼容接口） | 命中时 `usage.prompt_tokens_details.cached_tokens` 大于 0 |
| 最小长度 | 内容过短时不会缓存，两个字段均为 0。各模型的最小可缓存长度见 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching) |
| 计费 | 写入与读取分别按缓存写入、缓存读取单价计费，见[模型页](https://ofox.ai/zh/models/anthropic/claude-sonnet-4.6) |

缓存的通用说明见[提示缓存](https://ofox.ai/zh/docs/develop/advanced/prompt-caching)。

其他报错见[常见报错](https://ofox.ai/zh/docs/develop/models/claude#errors)。