Modelink

Claude Prompt Caching

信息

Modelink 缓存完全支持 Anthropic 官方命中逻辑，请先仔细阅读官方介绍：Claude Prompt Caching 官方文档

本文档介绍如何在调用 Claude 系列模型时使用缓存功能，以降低 API 调用成本并提高响应速度。

缓存功能简介

Claude 的 Prompt Caching 功能允许您缓存常用的上下文内容（如系统提示词、长文档、代码库等），在后续的请求中复用这些缓存内容，从而：

  • 降低成本：缓存命中的 tokens 按更低的价格计费（约为标准价格的 10%）
  • 提高速度：缓存内容无需重新处理，可显著减少首 token 响应时间
  • 提升效率：适合需要反复使用相同上下文的场景

缓存机制

  • 缓存有效期：默认 5 分钟（300 秒）
  • 最小缓存大小：缓存内容至少需要 1024 个 tokens
  • 缓存位置：可以在 system 消息和 user/assistant 消息的最后一个内容块上设置缓存点
  • 计费说明：
    • 缓存写入（Cache Creation）：按标准价格的 125% 计费
    • 缓存读取（Cache Hit）：按标准价格的 10% 计费

信息

注意：AWS 在 2026 年部分模型已经支持 1h 缓存，1h 缓存写入价格为标准价格的 200%，Modelink 即将支持。Amazon Bedrock now supports 1-hour duration for prompt caching

支持的协议

Modelink 在兼容 OpenAI 和 Anthropic 协议的基础上，扩展支持 cache_control 参数，您可以使用任一协议调用 Claude 模型并启用缓存功能。

OpenAI 协议调用方式

cache_control 参数说明

字段类型必填说明
typestring是缓存类型，固定值 "ephemeral"（临时缓存）
ttlstring否缓存过期时间（仅支持 5m，即将支持 1h）

完整示例

curl -X POST https://api.qnaigc.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "claude-3.5-sonnet",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "你是一个 Python 专家，精通算法和数据结构。"
          },
          {
            "type": "text",
            "text": "# Python 标准库文档\n\n这里是 Python 标准库的详细文档内容...(超过 1024 tokens 的长文本)",
            "cache_control": {
              "type": "ephemeral"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": "如何使用 collections.defaultdict？"
      }
    ],
    "max_tokens": 1024,
    "stream": false
  }'

Anthropic 协议调用方式

请求格式

Anthropic 原生协议同样支持在内容块中添加 cache_control 字段。

完整示例

curl -X POST https://api.qnaigc.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3.5-sonnet",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是一个技术支持专家。"
      },
      {
        "type": "text",
        "text": "# 产品技术文档\n\n这里是完整的技术文档内容...(超过 1024 tokens)",
        "cache_control": {
          "type": "ephemeral"
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "如何配置系统参数？"
      }
    ]
  }'

最佳实践

1. 合理选择缓存位置

将稳定且重复使用的内容放在需要缓存的位置，例如：

✅ 推荐缓存的内容：

  • 系统提示词（system prompt）
  • 长文档和代码库
  • 示例数据集
  • 产品知识库

❌ 不推荐缓存的内容：

  • 用户的具体问题（每次都不同）
  • 临时生成的内容
  • 频繁变化的数据

2. 确保缓存内容足够大

缓存只对超过 1024 tokens 的内容有效，否则不会产生缓存效果。

// ❌ 内容太短，无法缓存
{
  "type": "text",
  "text": "你是一个助手。",
  "cache_control": { "type": "ephemeral" }
}
// ✅ 内容足够长，可以缓存
{
  "type": "text",
  "text": "[超过 1024 tokens 的长文本内容...]",
  "cache_control": { "type": "ephemeral" }
}

3. 缓存放在最后

在多内容块场景中，将 cache_control 标记放在最后一个内容块上，这样可以缓存前面所有内容的上下文。（最多 20 个块）

// ✅ 推荐方式：缓存所有系统消息
{
  "role": "system",
  "content": [
    {
      "type": "text",
      "text": "你是一个专家。"
    },
    {
      "type": "text",
      "text": "这是背景知识..."
    },
    {
      "type": "text",
      "text": "这是详细文档...",
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

4. 利用缓存有效期

缓存有效期为 5 分钟，在此期间发起的后续请求都可以命中缓存。适合：

  • 多轮对话场景
  • 批量处理相同上下文的任务
  • 用户在短时间内的连续提问

5. 监控缓存使用情况

在响应中查看缓存使用情况，评估缓存效果。

OpenAI 协议响应示例（cache_creation_tokens 为 Modelink 扩展字段）：

{
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 150,
    "total_tokens": 250,
    "prompt_tokens_details": {
      "cache_creation_tokens": 2000,
      "cached_tokens": 2000
    }
  }
}

Anthropic 协议响应示例：

{
  "usage": {
    "input_tokens": 100,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 2000,
    "output_tokens": 150
  }
}

常见问题

其他非 Claude 模型可能不支持此功能，添加 cache_control 参数不会报错，但也不会生效。

Q: 如何判断缓存是否生效？

A: 在 OpenAI 协议响应的 usage 字段中，检查 prompt_tokens_details 的值：cache_creation_tokens 表示创建缓存；cached_tokens 表示命中缓存。

在 Anthropic 协议响应的 usage 字段中，检查 cache_creation_input_tokens 表示创建缓存，cache_read_input_tokens 表示命中缓存。

Q: 为什么字段名称不同？

A: 这是因为 OpenAI 原生协议没有缓存创建的概念，而 Anthropic 协议原生支持缓存功能。为了保持协议兼容性：

  • Anthropic 协议：遵循 Anthropic 官方规范，使用 cache_creation_input_tokens 和 cache_read_input_tokens
  • OpenAI 协议：在保持 OpenAI 协议兼容性的基础上，Modelink 添加了扩展字段：
    • 使用 cache_creation_tokens 表示缓存创建（与 Anthropic 的命名逻辑一致）
    • 使用 cached_tokens 表示缓存命中（符合 OpenAI 协议的命名习惯）

信息

常见疑问：有客户反馈在使用 OpenAI 协议时，为什么看不到 cache_creation_input_tokens 字段？这是因为 OpenAI 协议使用的是 cache_creation_tokens 字段（而非 cache_creation_input_tokens），这是为了与 OpenAI 协议的字段命名风格保持一致。

Q: 缓存功能会增加成本吗？

A: 首次创建缓存时，缓存写入按标准价格的 125% 计费，但后续命中缓存的请求按标准价格的 10% 计费。如果在 5 分钟内有 2 次以上的缓存命中，总体成本会降低。

示例：

  • 标准价格：$0.01/1K tokens
  • 缓存写入：$0.0125/1K tokens（首次）
  • 缓存读取：$0.001/1K tokens（后续）

如果相同内容使用 3 次：

  • 不使用缓存：$0.01 × 3 = $0.03
  • 使用缓存：$0.0125 + $0.001 × 2 = $0.0145（节省 51.7%）

信息

注意，即将支持的 1h 缓存，缓存写入价格是标准价格的 200%。

Q: 缓存过期后会怎样？

A: 缓存过期后，下次请求会重新创建缓存。缓存过期不会影响 API 的正常使用，只是无法享受缓存带来的成本和速度优势。

Q: 可以手动清除缓存吗？

A: 不支持手动清除缓存，缓存会在 5 分钟后自动失效。如果需要更新缓存内容，只需发送新的请求即可创建新的缓存。

Q: 缓存内容有大小限制吗？

A: 缓存内容的最小大小为 1024 tokens，最大大小受模型的 context window 限制（例如 Claude 4.5 Sonnet 支持 200K tokens）。

API 接入点

协议接入点认证方式
OpenAI 兼容https://api.qnaigc.com/v1/chat/completionsAuthorization: Bearer YOUR_API_KEY
Anthropic 原生https://api.qnaigc.com/v1/messagesx-api-key: YOUR_API_KEY

海外部署可使用 https://api.modelink.ai 作为接入点，路径与认证方式相同。详见服务接入点。

Last updated

© 2026 Modelink. All rights reserved.

构建来自Clarify