提示缓存

通过缓存复用的前缀内容（如系统 Prompt、长上下文文档），大幅降低重复调用的 Token 成本。缓存由后端提供商自动管理，开发者只需标记可缓存部分。

工作原理

提示缓存通过将消息标记为 cache_prefix: true，告知后端该消息内容可作为缓存前缀。后续请求中，相同的前缀内容直接从缓存读取，无需重新计算。

💡 核心概念：缓存是基于消息内容前缀的。只有连续的前缀消息才能被缓存，中间的消息变化会导致缓存失效。

使用方法

在消息对象中添加 cache_prefix 字段即可：

使用 cache_prefixPython

from openai import OpenAI

client = OpenAI(
    base_url="https://www.ulovegpt.com/v1",
    api_key="<你的 API_KEY>"
)

# 使用 cache_prefix 标记可缓存的前缀消息
# 第一次调用：缓存系统 prompt
response1 = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {
            "role": "system",
            "content": "你是一个专业的代码审查助手。请根据以下规范审查代码：\n\n1. 命名规范：使用 snake_case\n2. 代码结构：每个函数不超过 50 行\n3. 注释要求：每个公开方法必须有 docstring\n4. 错误处理：必须使用 try/except\n...",
            "cache_prefix": True
        },
        {"role": "user", "content": "请审查这段代码：def hello(): print('world')"}
    ]
)

# 第二次调用：复用缓存的系统 prompt（成本大幅降低）
response2 = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {
            "role": "system",
            "content": "你是一个专业的代码审查助手。请根据以下规范审查代码：\n\n1. 命名规范：使用 snake_case\n2. 代码结构：每个函数不超过 50 行\n3. 注释要求：每个公开方法必须有 docstring\n4. 错误处理：必须使用 try/except\n...",
            "cache_prefix": True
        },
        {"role": "user", "content": "请审查这段代码：def add(a, b): return a + b"}
    ]
)

成本节省示例

缓存 vs 非缓存成本对比Text

# 没有缓存：每次都需要重新处理整个 prompt
# 第 1 次请求： 处理 500 tokens → 500 tokens 计费
# 第 2 次请求： 处理 500 tokens → 500 tokens 计费
# 第 3 次请求： 处理 500 tokens → 500 tokens 计费
# 总计：1500 tokens 计费

# 有缓存：前缀只处理一次
# 第 1 次请求： 处理 500 tokens → 500 tokens 计费（缓存建立）
# 第 2 次请求： 缓存命中 480 tokens → 20 tokens 计费
# 第 3 次请求： 缓存命中 480 tokens → 20 tokens 计费
# 总计：540 tokens 计费（节省 64%）

缓存定价

操作	定价	说明
缓存写入	与 input token 相同	首次建立缓存的费用
缓存读取	通常为 input 的 10-20%	复用缓存大幅降低成本
缓存过期	无需付费	缓存由后端自动管理

最佳实践

系统 Prompt 缓存：长的系统 Prompt 是最佳缓存候选
文档/知识库缓存：RAG 场景中的参考文档可以缓存
前缀连续性：确保缓存消息在所有请求中保持一致的位置和内容
最小缓存粒度：不同提供商有最小缓存单位（如 Anthropic 为 1024 tokens）
不是所有模型都支持：使用前确认模型支持提示缓存