Prompt Caching

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5",
      max_tokens=1024,
      system=[
          {
              "type": "text",
              "text": "You are an AI assistant tasked with analyzing legal documents.",
          },
          {
              "type": "text",
              "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
              "cache_control": {"type": "ephemeral"},
          },
      ],
      messages=[
          {
              "role": "user",
              "content": "What are the key terms and conditions in this agreement?",
          }
      ],
  )
  print(response.usage.model_dump_json())
  ```

</CodeGroup>

本示例演示基本的 Prompt Caching 用法：将法律协议全文作为前缀缓存，同时保持用户指令不缓存。

对于第一次请求：

* `input_tokens`：仅用户消息中的 token 数
* `cache_creation_input_tokens`：整个 system message 中的 token 数，包括法律文档
* `cache_read_input_tokens`: 0（第一次请求没有缓存命中）

对于缓存生命周期内的后续请求：

* `input_tokens`：仅用户消息中的 token 数
* `cache_creation_input_tokens`: 0（没有新的缓存创建）
* `cache_read_input_tokens`：整个已缓存 system message 中的 token 数

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5",
      max_tokens=1024,
      system=[
          {
              "type": "text",
              "text": "...long system prompt",
              "cache_control": {"type": "ephemeral"},
          }
      ],
      messages=[
          # ...long conversation so far
          {
              "role": "user",
              "content": [
                  {
                      "type": "text",
                      "text": "Hello, can you tell me more about the solar system?",
                  }
              ],
          },
          {
              "role": "assistant",
              "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
          },
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "Good to know."},
                  {
                      "type": "text",
                      "text": "Tell me more about Mars.",
                      "cache_control": {"type": "ephemeral"},
                  },
              ],
          },
      ],
  )
  print(response.usage.model_dump_json())
  ```

</CodeGroup>

本示例演示如何在多轮对话中使用 Prompt Caching。

在每一轮中，最后一条消息的最后一个块会标上 `cache_control`，以便对话可以被增量缓存。系统会自动查找并使用先前已缓存的最长块序列来处理后续消息。也就是说，先前用 `cache_control` 标记过的块之后不再带此标记，但如果在 5 分钟内被命中，它们仍会被视为缓存命中（同时也是一次缓存刷新！）。

此外，请注意 `cache_control` 参数放在了 system message 上。这是为了确保如果它从缓存中被驱逐（超过 5 分钟未被使用之后），会在下一次请求时被重新加入缓存。

这种方法适用于在进行中的对话里维持上下文，而无需反复处理相同信息。

正确设置后，你应在每个请求的 usage 响应中看到以下内容：

* `input_tokens`：新用户消息中的 token 数（会很少）
* `cache_creation_input_tokens`：新的 assistant 和 user 轮中的 token 数
* `cache_read_input_tokens`：直到上一轮为止的对话中的 token 数

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5",
      max_tokens=1024,
      tools=[
          {
              "name": "search_documents",
              "description": "Search through the knowledge base",
              "input_schema": {
                  "type": "object",
                  "properties": {
                      "query": {"type": "string", "description": "Search query"}
                  },
                  "required": ["query"],
              },
          },
          {
              "name": "get_document",
              "description": "Retrieve a specific document by ID",
              "input_schema": {
                  "type": "object",
                  "properties": {
                      "doc_id": {"type": "string", "description": "Document ID"}
                  },
                  "required": ["doc_id"],
              },
              "cache_control": {"type": "ephemeral"},
          },
      ],
      system=[
          {
              "type": "text",
              "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
              "cache_control": {"type": "ephemeral"},
          },
          {
              "type": "text",
              "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
              "cache_control": {"type": "ephemeral"},
          },
      ],
      messages=[
          {
              "role": "user",
              "content": "Can you search for information about Mars rovers?",
          },
          {
              "role": "assistant",
              "content": [
                  {
                      "type": "tool_use",
                      "id": "tool_1",
                      "name": "search_documents",
                      "input": {"query": "Mars rovers"},
                  }
              ],
          },
          {
              "role": "user",
              "content": [
                  {
                      "type": "tool_result",
                      "tool_use_id": "tool_1",
                      "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                  }
              ],
          },
          {
              "role": "assistant",
              "content": [
                  {
                      "type": "text",
                      "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                  }
              ],
          },
          {
              "role": "user",
              "content": [
                  {
                      "type": "text",
                      "text": "Yes, please tell me about the Perseverance rover specifically.",
                      "cache_control": {"type": "ephemeral"},
                  }
              ],
          },
      ],
  )
  print(response.usage.model_dump_json())
  ```

</CodeGroup>

这个综合示例演示如何使用全部 4 个可用缓存断点来优化 prompt 的不同部分：

1. **工具缓存**（缓存断点 1）：最后一个工具定义上的 `cache_control` 参数会缓存所有工具定义。

2. **可复用指令缓存**（缓存断点 2）：system prompt 中的静态指令被单独缓存。这些指令在请求之间很少变化。

3. **RAG 上下文缓存**（缓存断点 3）：知识库文档被独立缓存，让你可以更新 RAG 文档而不使 tools 或 instructions 缓存失效。

4. **对话历史缓存**（缓存断点 4）：最后一条用户消息标有 `cache_control`，以便随对话推进进行增量缓存。

这种方法提供最大灵活性：

* 如果你向对话追加新一轮且不更改更早的内容，全部四个缓存区段都会被复用
* 如果你更新 RAG 文档但保持相同的 tools 和 instructions，前两个缓存区段会被复用
* 如果你更改对话但保持相同的 tools、instructions 和 documents，前三个区段会被复用
* 任何断点处的变更会使该区段及其之后的一切失效，而更早的已缓存区段仍然有效

对于第一次请求：

* `input_tokens`：很少（最后一个缓存断点之后的 token，本示例中接近 0）
* `cache_creation_input_tokens`：所有被缓存区段中的 token（tools + instructions + RAG documents + conversation history）
* `cache_read_input_tokens`: 0（没有缓存命中）

对于仅带有新用户消息的后续请求（并且第四个断点移到该新的最后一条消息上，如示例所示）：

* `input_tokens`：很少（最后一个缓存断点之后的 token，本示例中接近 0）
* `cache_creation_input_tokens`：新用户消息和上一轮 assistant 中的 token（正在被缓存的新对话区段）
* `cache_read_input_tokens`：所有先前已缓存的 token（tools + instructions + RAG documents + previous conversation）

这种模式尤其适用于：

* 带有大型文档上下文的 RAG 应用
* 使用多种工具的 Agent 系统
* 需要维持上下文的长时间运行对话
* 需要独立优化 prompt 不同部分的应用