Prompt Caching FAQ：命中率、计价、何时关闭

## Prompt Caching FAQ：命中率、计价、何时关闭

OpenAI 的 Prompt Caching 功能专为需要重复处理长提示（prompt）的开发者设计。它允许模型复用已处理的固定前缀（prefix），大幅降低输入令牌成本并缩短响应延迟。适用于构建代理、多轮对话或批量处理应用的团队。

谁适用：如果你在 OpenAI API 项目中多次发送包含相同系统提示、工具定义或历史记录的请求，就值得开启 Prompt Caching。怎么决策：查看你的提示长度是否超过模型最低缓存阈值（GPT-5.6 及以后模型通常 1024 个令牌），并通过 OpenAI 仪表盘或响应中的 cached_tokens 字段测试命中率。如果命中率能稳定在 50% 以上且缓存写成本可回收，就值得保留；否则可关闭以避免多余开销。

核心概念与术语

• Prompt Caching（提示缓存）：OpenAI 自动缓存模型处理过的提示前缀（key-value 状态），后续请求只要前缀完全匹配即可复用，大幅节省算力。
• 命中率（Cache Hit Rate）：复用缓存的输入令牌比例。官方典型示例可达 90%+。
• 计价（Pricing）：缓存输入按大幅折扣计费（最高 90% 省）。首次写入缓存（cache write）按 1.25 倍标准输入价，之后读取按 0.1 倍标准输入价。
• Cache Write / Cache Read：写入缓存（首次或新前缀）和读取缓存（后续复用）的计费区分。
• Cache Key：可选的 prompt_cache_key 参数，用于按用户/组织分组缓存，方便多用户场景隔离。
• TTL / Retention：缓存有效期，默认 30 分钟（GPT-5.6 及以后模型），可通过 prompt_cache_options.ttl 调整。

决策表：Prompt Caching 适用场景对照

使用场景	是否推荐开启	主要原因	关闭建议场景
多轮对话或 Agent（稳定系统提示+工具）	强烈推荐	命中率高，成本可降 80-90%	提示频繁变长或缓存过期
批量处理相同文档/代码	推荐	固定前缀重用率高	每次提示差异极大
短期测试或单次调用	不推荐	写入成本高于节省	缓存命中率 <30%
用户级隔离（多个 Org）	推荐	用 Cache Key 分组	提示结构完全不同
缓存命中率低（<50%）	可关闭	实际节省微薄	提示长度 <1024 令牌

实操清单：分步可核对你的 Prompt Caching 设置

1. 检查模型支持：确保使用 GPT-5.6 / GPT-6 及以上模型（Responses API 或 Chat Completions API）。早期模型仅隐式缓存。

2. 设置缓存选项（隐式或显示模式）：

   "prompt_cache_options": {

     "mode": "implicit",  // 或 "explicit"

     "ttl": "30m"

   }

隐式模式无需改代码即可自动在用户/工具块末尾添加断点。

3. 添加 Cache Key（可选，多用户场景用）：

   "prompt_cache_key": "your-app-v1"

4. 测试命中率：调用 API 后查看响应 usage.input_tokens_details.cached_tokens 和 cache_write_tokens。

5. 监控与诊断：使用 Prompt Caching Dashboard 查看整体命中率，或在单个请求中传入 comparison_response_id 诊断缓存未命中的原因（如 tools_changed、model_changed）。

6. 验证成本：对比不开启缓存和开启缓存的同等请求账单，确认缓存写成本在第 2-3 次调用后回收。

7. 关闭或调整：若缓存 TTL 已过或提示频繁变更，移除 prompt_cache_options 或切换模式。

常见坑与风险边界

• 命中率低：缓存写入成本（1.25 倍）超过读取节省时，长期使用反而贵。建议监控仪表盘命中率 <50% 就关闭。
• 缓存失效：提示内容或设置稍有变动（如工具名称、reasoning.effort）即无法复用。固定系统提示和工具定义是关键。
• 与 ChatGPT Plus 计划不直接相关：Prompt Caching 仅限 OpenAI API 付费调用。ChatGPT Plus 主要用于对话界面，无 API 缓存功能。
• 零数据保留兼容：启用 Zero Data Retention 后缓存仍可用，但诊断记录过期更快。
• 缓存位置：缓存仅在服务器端 GPU，本地或第三方工具无法直接访问。
• 长期风险：关闭后重新写入每次都按全价计费，累计成本可能高于缓存模式。

免责声明：以上基于 OpenAI 官方 API 挂牌价格（2026 年 9 月数据）。实际费用可能随模型更新、地区定价或组织策略调整。请以 OpenAI 平台实时数据为准。

站内路径：相关工具与页面

• 官方 API 计费对照与模型详情：官方 API 价格页
• 快速了解 Prompt Caching 原理与代码示例：官方 API 指南
• API 计费对账与成本核算工具：计费对账工具
• 真实 API 调用与 Token 成本估算示例：使用示例
• 详细开发与迁移指南：API 过渡指南

延伸阅读

• OpenAI 官方 Prompt Caching 文档：查看完整计价表与设置指南
• 监控缓存命中率的 Dashboard 教程
• 常见设置变更导致缓存未命中的诊断方法

---