Claude 模型缓存功能使用指南 (Cache Control)

// ❌ 内容太短，无法缓存
{
    "type": "text",
    "text": "你是一个助手。",  // 少于 1024 tokens
    "cache_control": {"type": "ephemeral"}
}

// ✅ 内容足够长，可以缓存
{
    "type": "text",
    "text": "[超过 1024 tokens 的长文本内容...]",
    "cache_control": {"type": "ephemeral"}
}

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

{
    "usage": {
        "prompt_tokens": 100,
        "completion_tokens": 150,
        "total_tokens": 250,
        "prompt_tokens_details": {
            "cache_creation_tokens": 2000,// 写入缓存的 token 数（七牛扩展字段）
            "cached_tokens": 2000 // 从缓存读取的 token 数（命中缓存时出现）
    }
        }
    }
}

{
  "usage": {
    "input_tokens": 100,
    "cache_creation_input_tokens": 2000,  // 写入缓存的 token 数
    "cache_read_input_tokens": 2000,      // 从缓存读取的 token 数
    "output_tokens": 150
  }
}