prompt_cache_options.ttl,即可选择 30 分钟或 12 小时的最短缓存保留时间。本文使用 gpt-6.1-terra 演示。
12 小时缓存仅支持
/v1/responses,不支持 /v1/chat/completions。TTL 表示最短缓存保留时间,不表示到期立即删除,也不保证每次请求都命中缓存。准备 API 密钥
示例中的长文本是占位内容。请替换为实际需要复用的内容,待缓存前缀至少需要 1,024 token。直接使用这段短占位文本不会触发缓存写入。
使用 30 分钟缓存
将prompt_cache_options.ttl 设置为 "30m"。省略 ttl 时也使用 30 分钟;省略 mode 时默认使用隐式缓存,由上游自动选择缓存断点。
使用 12 小时缓存
将同一字段改为"12h",其余请求结构保持一致:
固定前缀、不同问题:使用显式断点
如果每次请求都复用同一份长文档,只改变最后的问题,将mode 设置为 "explicit",并在固定内容末尾的 input_text 块上添加 prompt_cache_breakpoint。下面使用 12 小时缓存;改用 30 分钟时,将请求中的 ttl 改为 "30m"。
只设置
mode: "explicit" 而不添加断点,不会读取或写入缓存。下面的断点未单独设置 TTL,因此继承请求级 prompt_cache_options.ttl。查看缓存是否生效
检查响应中的usage.input_tokens_details:
cached_tokens: 本次从缓存读取的 token 数,大于 0 表示发生了缓存读取。cache_write_tokens: 本次写入缓存的 token 总数。cache_write_tokens_details.ttl_30m_tokens: 本次按 30 分钟 TTL 写入的 token 数。cache_write_tokens_details.ttl_12h_tokens: 本次按 12 小时 TTL 写入的 token 数。
cached_tokens。前缀过短、内容变化或缓存未命中时,读取量可能为 0。
缓存 usage 示例与统计口径
下面是支持 OpenAI 缓存的模型同时包含两档写入时的响应片段,仅展示usage;具体数值以实际返回为准。
input_tokens 中。两档写入量是 cache_write_tokens 的拆分,不要把总量与明细再次相加,也不要把读写缓存加到总输入量上。
本例普通输入为 12000 - 4000 - 7000 = 1000;写入量为 5000 + 2000 = 7000;总 token 数为 12000 + 1000 = 13000。
缓存行为参考 OpenAI 官方缓存指南。