上下文缓存（Context Cache）

对于重复的 system prompt、长文档上下文或多轮对话的固定前缀，启用上下文缓存可节省高达 90% 的输入费用。

工作原理

标记缓存

在 content block 上添加 cache_control 注解

首次请求

标记部分被缓存，按 1.25x 输入价计费

后续请求

命中缓存，按 0.1x 输入价计费（省 90%）

计费规则

Token 类型计费倍率响应字段说明

缓存创建1.25xcache_creation_input_tokens首次请求写入缓存，略高于正常输入

缓存命中0.1xcached_tokens后续请求命中，节省 90%

正常输入1xprompt_tokens - 缓存部分未被缓存标记的输入

输出1xcompletion_tokens正常输出计费，不受缓存影响

缓存条件

最小 Token 数：显式缓存需要标记内容 ≥ 1024 tokens（部分模型 256/512）
缓存 TTL：ephemeral 类型缓存有效期约 5 分钟，期间相同前缀的请求自动命中
最多标记数：每个请求最多 4 个 cache_control 标记点
隐式 vs 显式：隐式缓存（不加标记）由系统自动判断，无需配置；显式缓存通过标记精确控制缓存边界
互斥：同一请求中显式和隐式缓存互斥，有标记时以显式为准

使用方式：OpenAI 协议

在 /v1/chat/completions 请求中，将 content 改为数组格式，在需要缓存的文本块上添加 cache_control：

curl https://nexusflow.hk/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "enable_context_caching": true,
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "你是一个金融分析助手。以下是公司年报全文（约 50,000 字）...",
            "cache_control": {"type": "ephemeral"}
          }
        ]
      },
      {"role": "user", "content": "总结这份年报的核心风险"}
    ]
  }'

使用方式：Anthropic 协议

在 /v1/messages 请求中，同样在 system 或 messages 的 content block 上添加标记：

curl https://nexusflow.hk/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是一个代码审查专家。以下是完整代码库上下文...",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "找出这段代码的安全漏洞"}
    ]
  }'

Python SDK 示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-air-xxx",
    base_url="https://nexusflow.hk/v1"
)

# 长 system prompt 只在第一次请求时被缓存，后续请求自动命中
response = client.chat.completions.create(
    model="qwen3.5-plus",
    extra_body={"enable_context_caching": True},
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": long_document,  # 你的长文档
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        },
        {"role": "user", "content": "请总结要点"}
    ]
)

# 查看缓存命中情况
details = response.usage.prompt_tokens_details
print(f"缓存命中: {details.cached_tokens} tokens")
print(f"缓存创建: {details.cache_creation_input_tokens} tokens")

支持的模型

供应商模型最小缓存长度

通义千问Qwen3.7 Max, Qwen3.6 Max Preview, Qwen3.6 Plus/Flash, Qwen3.5 Plus/Flash, Qwen3 Max, Qwen Plus/Turbo, Qwen VL 系列, Qwen3 Coder 系列1024 (显式) / 256 (隐式)

DeepSeekDeepSeek V3.21024 (显式)

智谱 GLMGLM 5.1, GLM 5, GLM 4.7512

KimiKimi K2.5, K2.61024 (显式)

AnthropicClaude Opus 4.7, Sonnet 4.6, Haiku 4.51024

响应格式

缓存命中信息通过 usage 字段返回，不同协议格式略有不同：

OpenAI 协议响应

usage.prompt_tokens_details:
  cached_tokens: 1804
  cache_creation_input_tokens: 0

Anthropic 协议响应

usage:
  cache_read_input_tokens: 1804
  cache_creation_input_tokens: 0

最佳实践

将不变的长内容（system prompt、参考文档、代码上下文）放在 messages 最前面并标记缓存
用户消息放最后 — 缓存从 messages 数组开头到标记位置，变化的内容放后面不影响缓存命中
适合场景：RAG 文档注入、多轮对话固定 system prompt、Agent 的工具定义、代码仓库上下文
不适合场景：每次请求内容完全不同、prompt 长度低于最小阈值