MaoMaoToken 文档

缓存创建

Claude 提示词缓存可以把频繁复用的大段上下文缓存起来,减少重复输入的成本,并在一定程度上提升响应速度。适合大型系统提示词、长参考文档、固定示例数据等场景。

概述

Prompt Caching 通过 cache_control 标记需要缓存的内容。缓存内容通常需要达到一定长度才会创建成功,建议用于 2048 tokens 以上的稳定上下文。

功能特性

  • 支持缓存大型系统提示词。
  • 降低重复调用时的输入 Token 成本。
  • 适合长文档、多轮分析、固定上下文复用。
  • 临时缓存通常有有效期,过期后需要重新创建。

请求地址

https://api.maomaotoken.com/v1/messages

Python 示例代码

下面示例演示如何在 system 中设置 cache_control: {"type": "ephemeral"},并通过响应里的 usage 字段检查缓存是否创建成功。

import json
import os
import requests


# ==================== 配置参数 ====================

API_KEY = os.getenv("MAOMAO_API_KEY", "sk-************************************")
API_URL = "https://api.maomaotoken.com/v1/messages"


headers = {
    "content-type": "application/json",
    "x-api-key": API_KEY,
    "anthropic-version": "2023-06-01",
}


LONG_CONTEXT = """
You are an AI assistant tasked with analyzing literary works.
Your goal is to provide insightful commentary on themes, characters, and writing style.

Below is a long reference document for analysis.

Pride and Prejudice - Chapter 1 to 5 (Excerpt)

It is a truth universally acknowledged, that a single man in possession of a good fortune,
must be in want of a wife.

...这里放入足够长、会被多次复用的系统提示词、参考资料或示例文本...

Additional chapters and content would continue here to ensure the cache threshold is clearly exceeded.
"""


payload = {
    "model": "claude-sonnet-4-6",
    "system": [
        {
            "type": "text",
            "text": LONG_CONTEXT,
            "cache_control": {
                "type": "ephemeral"
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Analyze the major themes in Pride and Prejudice."
        }
    ]
}


def main():
    print("[START] 开始调用 Claude API,测试缓存创建")
    print(f"[INFO] API 端点: {API_URL}")
    print(f"[INFO] 使用模型: {payload['model']}")
    print("-" * 60)

    try:
        response = requests.post(
            API_URL,
            headers=headers,
            json=payload,
            timeout=30
        )

        if response.status_code != 200:
            print(f"[ERROR] 请求失败,状态码: {response.status_code}")
            print(response.text)
            return

        result = response.json()
        usage = result.get("usage", {})

        print("[SUCCESS] 请求成功")
        print("\n[USAGE] Token 使用统计:")
        print(f"  - 输入 tokens: {usage.get('input_tokens', 0)}")
        print(f"  - 输出 tokens: {usage.get('output_tokens', 0)}")
        print(f"  - 缓存创建 tokens: {usage.get('cache_creation_input_tokens', 0)}")
        print(f"  - 缓存读取 tokens: {usage.get('cache_read_input_tokens', 0)}")

        cache_created = usage.get("cache_creation_input_tokens", 0)
        if cache_created > 0:
            print(f"\n[CACHE] 缓存创建成功,已缓存 {cache_created} tokens")
        else:
            print("\n[WARNING] 缓存未创建")
            print("可能原因:内容长度不足、未正确设置 cache_control,或接口配置不符合要求。")

        content = result.get("content", [])
        if content:
            text = content[0].get("text", "")
            print("\n[RESPONSE] Claude 回复预览:")
            print(text[:300] + "..." if len(text) > 300 else text)

    except requests.exceptions.Timeout:
        print("[ERROR] 请求超时")
    except requests.exceptions.ConnectionError:
        print("[ERROR] 连接错误")
    except requests.exceptions.RequestException as e:
        print(f"[ERROR] 请求异常: {e}")
    except json.JSONDecodeError:
        print("[ERROR] JSON 解析错误")


if __name__ == "__main__":
    main()

代码说明

步骤说明
配置缓存控制system 内容块中添加 cache_control: {"type": "ephemeral"}
准备足够内容缓存内容建议超过 2048 tokens。
检查缓存状态通过 usage.cache_creation_input_tokens 判断是否创建成功。

响应示例

[START] 开始调用 Claude API,测试缓存创建
[INFO] API 端点: https://api.maomaotoken.com/v1/messages
[INFO] 使用模型: claude-sonnet-4-6
------------------------------------------------------------
[SUCCESS] 请求成功

[USAGE] Token 使用统计:
  - 输入 tokens: 17
  - 输出 tokens: 1043
  - 缓存创建 tokens: 2073
  - 缓存读取 tokens: 0

[CACHE] 缓存创建成功,已缓存 2073 tokens

[RESPONSE] Claude 回复预览:
# Major Themes in Pride and Prejudice

Based on the opening chapters provided, here is an analysis of the major themes...

Usage 字段说明

字段说明
input_tokens本次请求的新输入 Token。
output_tokens模型输出 Token。
cache_creation_input_tokens本次创建缓存的 Token 数。大于 0 通常表示创建成功。
cache_read_input_tokens本次命中并读取缓存的 Token 数。

使用建议

01适合缓存大型系统提示词、长参考文档、固定示例数据。

02不适合缓存一次性请求、频繁变化的上下文、短提示词。

03成本优化只有同一段上下文会被多次复用时,缓存才更有意义。

注意事项

  • 请将示例中的 API Key 替换为你的真实 MaomaoToken API Key。
  • 缓存内容通常需要至少 1024 tokens,建议 2048+ tokens。
  • 临时缓存有有效期,过期后需要重新创建。
  • 缓存命中受内容、时间窗口和请求一致性影响。
  • 不要把真实 API Key 写入公开仓库,建议使用环境变量管理。

On this page