GPT 提示词缓存

​

快速开始

curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "prompt_cache_key": "my-app-report-assistant-v1",
    "messages": [
      {
        "role": "system",
        "content": "You are a meticulous assistant for analyzing quarterly financial reports... [此处放置固定不变的长指令或参考资料，≥1024 Token]"
      },
      {
        "role": "user",
        "content": "Summarize the key figures in one sentence."
      }
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIHUBMIX_API_KEY"],  # 密钥从环境变量读取
    base_url="https://aihubmix.com/v1",
)

long_context = "You are a meticulous assistant for analyzing quarterly financial reports... [固定不变的长指令或参考资料，≥1024 Token]"

# 相同前缀连续请求两次，第二次命中缓存
for i in range(2):
    completion = client.chat.completions.create(
        model="gpt-5.6-sol",
        prompt_cache_key="my-app-report-assistant-v1",
        messages=[
            {"role": "system", "content": long_context},
            {"role": "user", "content": "Summarize the key figures in one sentence."},
        ],
    )
    print(completion.usage.prompt_tokens_details)

// 第 1 次调用：无命中
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 0}

// 第 2 次调用：前缀命中缓存
"prompt_tokens_details": {"audio_tokens": 0, "cached_tokens": 2816}

​

缓存计费

​

缓存如何自动生效

1. 前缀达到 1,024 Token 且找到一致的缓存前缀时，命中部分按缓存读取价计费，并降低首 Token 延迟；
2. 未找到时按常规输入处理，并把前缀写入缓存（GPT-5.6 及之后按 1.25x 计写入费）；
3. 命中要求前缀逐字节一致，前缀中任何一处变化都会使该位置之后的缓存全部失效。

• 固定的长系统指令或大量 few-shot 示例
• RAG 场景中重复引用的长参考资料
• 携带大量工具定义（tools）的 Agent 工作流
• 只往后追加消息的长多轮对话

​

GPT-5.6 缓存参数

1. 默认（implicit 模式）：不传任何缓存参数也会自动写缓存——系统在最新一条消息的位置自动设置断点。GPT-5.6 及之后，自动发生的缓存写入同样按 1.25x 计费。
2. implicit 模式 + 显式断点：在自动断点之外，可在内容块上设置 prompt_cache_breakpoint，把缓存边界固定在稳定内容的末尾；断点之后的内容变化不会破坏断点之前的前缀缓存。
3. explicit 模式：prompt_cache_options.mode 设为 "explicit" 后只使用手动断点；完全不设置断点时该请求不使用缓存、也不产生缓存写入费。官方原文：“If the conversation contains no explicit breakpoints, the request does not use prompt caching or incur cache-write charges.”

{
  "model": "gpt-5.6-sol",
  "prompt_cache_options": {"mode": "explicit"},
  "messages": [
    {"role": "user", "content": "[不会复用的一次性长内容]"}
  ]
}

{
  "model": "gpt-5.6-sol",
  "prompt_cache_key": "my-app-report-assistant-v1",
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "[固定不变的长指令或参考资料，≥1024 Token]",
          "prompt_cache_breakpoint": {"mode": "explicit"}
        }
      ]
    },
    {"role": "user", "content": "Summarize the key figures in one sentence."}
  ]
}

• 每个请求最多创建 4 个新的缓存写入；implicit 模式下自动断点占用其中 1 个；
• 断点之前的前缀仍需达到 1,024 Token 才会被缓存；
• 读取时在最近 50 个断点中取最长匹配前缀；
• 断点设置在不支持的内容块上会返回 400 invalid_request_error。Chat Completions 支持 text / image_url / input_audio / file / refusal 块，Responses API 支持 input_text / input_image / input_file 块。

​

为什么缓存没有命中

• 前缀不足 1,024 Token：低于最小缓存长度的请求按常规输入处理；
• 前缀中混入了变化内容：时间戳、会话 ID、用户变量等应放到固定内容之后，前缀中任何一处变化都会使之后的缓存失效；
• tools 定义或顺序变化：工具列表参与前缀计算，定义与排列顺序都必须完全一致；
• 图片 detail 参数不一致：detail 影响图片 Token 化结果，需保持相同；
• 结构化输出 schema 变化：response_format 的 JSON Schema 作为系统消息前缀参与缓存，schema 变化即前缀变化；
• reasoning_effort 变化：官方将其列为缓存命中率降低的常见原因之一（“Changes to reasoning effort”）；
• 超过缓存保留期：GPT-5.6 之前不活跃 5–10 分钟后清除，GPT-5.6 及之后至少保留 30 分钟；
• 未设置 prompt_cache_key（GPT-5.6）：不设置时仍可能自动命中，但不使用更可靠的匹配机制。

​

最佳实践

• 固定内容（系统指令、示例、参考资料、工具定义）放在请求最前面，每轮变化的内容放在最后；
• 为共享同一前缀的流量设置同一个稳定的 prompt_cache_key，单个 key 的总流量控制在约 15 次/分钟内，超出时按业务拆分更多 key；
• 多轮对话只向后追加消息，避免修改历史消息；
• 保持相同前缀的请求有持续流量，减少缓存被清除；
• 前缀不会复用的一次性长请求，用 explicit 模式避免缓存写入费（GPT-5.6 及之后）；
• 通过 usage.prompt_tokens_details.cached_tokens 持续监控命中情况。

​

常见问题

​

GPT 的提示缓存需要手动开启吗？

​

GPT-5.6 的缓存写入费如何计算？如何避免不必要的写入费？

​

缓存能保留多久？

​

GPT-5.6 的显式断点和 Claude 的 cache_control 有什么区别？

​

缓存会影响输出内容吗？

​

官方参考

• GPT-5.6 发布公告：缓存写入 1.25x / 读取 90% 折扣的计费规则
• 提示缓存指南：机制、参数、usage 字段与限制
• OpenAI Pricing：各模型官方标价
• GPT-5.6 模型文档：上下文窗口、长上下文计费阈值