在智能体应用和多轮对话应用中,始终将新的操作和指令追加到模型的上下文末尾,就能在多次 API 请求之间保留推理,让模型发挥最佳性能。保持前缀不变一直是使用提示词缓存的最佳实践。缓存从请求的开头逐项匹配,因此一旦前缀发生变化,从变化处开始的内容就可能无法复用缓存。将变更追加到末尾,可以让更多对话内容复用缓存,从而显著降低输入成本并加快响应速度。
从较新的前沿模型开始,作为一项防护措施,API 会丢弃前缀变更位置之后的推理项。推理项被丢弃后,模型可能需要重新进行部分推理,从而增加 Token 用量、成本和延迟。如果模型无法恢复丢失的推理,输出质量也可能下降。
为了让模型发挥最佳性能,建议保持前缀不变,并尽可能采用只追加内容的集成方式。
什么是前缀变更?
推理项的前缀是该推理项之前的对话历史。修改这段历史就会改变前缀,例如缩短某项工具结果、重写开发者消息,或用摘要替换较早的对话轮次。
| 原始对话 | 下一次请求及 API 处理方式 |
|---|---|
| 用户消息核对账本总额。 | 同一条消息 |
| 调用工具前的推理 | 可复用 |
工具调用lookup_ledger() | 同一次调用 |
工具结果[{"amount": 40}, {"amount": 50}] | 相同的数据行 |
| 收到工具结果后的推理 | 可复用 |
如何调整集成以避免更改前缀
更新 Responses API 的 tools 或 text.format 等参数、在使用 GPT-6.2 之前的模型时更改 instructions,或编辑较早的 input 项,都可能无意中改变前缀。请检查您的集成是否有这些操作。
下表列出了集成中更改前缀的常见原因,以及如何在可行时通过向上下文末尾追加内容来实现相同的目标。
| 更改前缀的常见原因 | 如何避免更改前缀 |
|---|---|
| 调整推理强度 | 保留 Responses API 的 reasoning.effort 参数原值,并向输入项列表末尾追加一个包含新推理强度的 configuration_update 项。原有的请求级设置保持不变。 |
| 更改结构化输出的模式 | 保留 Responses API 的 text.format 参数原值,并向输入项列表末尾追加一个包含新模式的 configuration_update 项。原有的请求级设置保持不变。 |
| 更改智能体可用的工具 | 保留 Responses API 的 tools 参数原值。使用 additional_tools 项添加工具,或结合使用 tool_choice 和 allowed_tools 来限制模型在某一轮中可以调用的工具。保持现有工具定义的顺序。追加 additional_tools 时,使用 developer 角色并提供一个 tools 数组。在后续请求中重新传入该项时,保留它在列表中的原位置。 |
| 更新开发者指令 | 将可复用的指令写入第一条 developer 消息,并将该消息放在 input 中。需要更新这些指令时,保留最初的开发者消息,在模型上下文末尾追加一条 新的 developer 消息。使用 GPT-6.2 或更新的模型时,请通过顶层 instructions 传入仅适用于当前轮次的开发者消息。API 会将这些消息追加到 input 之后,并按未缓存输入的费率对这些消息的 Token 计费。 |
| 压缩 | 压缩会改变前缀,因此这类情况下很难避免缓存未命中。 OpenAI 压缩:如果您使用 OpenAI 压缩,无论是通过 /responses/compact 还是 context_management,即使前缀发生变化,我们的系统也会保留后续的推理项。OpenAI 压缩项可以出现在上下文中的任意位置。调用 /responses/compact 时,请省略 instructions,并将返回的上下文窗口按原顺序传入下一次请求。context_management 会保留配置更新和开发者添加的工具。如果使用显式压缩,请在下一次请求中恢复这些配置更新和工具。自定义压缩:如果您使用其他压缩策略或自行实现了压缩,请将压缩后的项放在模型上下文末尾,避免将其放在最近几轮对话之前。您也可以接受这一取舍,让 API 丢弃原对话历史中位于该项之后的推理项。 |
| 缩短先前的工具输出或减小先前文件或图像的大小 | 有些集成会直接截短先前的工具输出、文件或图像等内容,以此代替压缩。这些修改会改变前缀。强烈建议使用压缩,或在首次将这些内容发送给模型之前,就缩短较长的工具输出并减小图像或文件的大小。 |
检查集成中的前缀变更
使用提示词缓存诊断查看何时发生缓存未命中,并排查前缀变更。要将当前请求与较早的响应进行比较,请将 prompt_cache_options.comparison_response_id 设为该响应的 ID,然后查看诊断给出的原因和缓存的 Token 数量。利用这些信息减少集成中的前缀变更。诊断会尽力报告发现的第一处差异,但无法验证模型是否复用了推理。
查看 Responses API 响应中的 input_transformations,了解 API 从输入中移除了哪些推理项,以及移除的原因。若要排查因 prefix_mismatch 被移除的推理项,可以用 id 在较早响应的 output 中找到对应的推理项。如果您的集成修改了较早的输入,可以按照上文的建议调整集成,以保留推理。