GPT-6.2 Responses API:保持前缀不变,避免推理记录被丢弃
从 GPT-6.2 Astra 和 GPT-6.2 Sol 起,在 Responses API 中修改早期对话历史会丢弃其后的推理项,并可能从改动点起中断缓存复用。改用只追加的 input 历史,通过 configuration_update 与 additional_tools 在对话中途调整参数和工具,将可复用指令放在首条 developer 消息中,再用 input_transformations 与 Prompt Cache Diagnostics 验证排查。
本文内容

从 gpt-6.2-astra 和 gpt-6.2-sol 开始,在对话中途修改前缀、对模型降级,或发生组织变更或终端用户变更时,OpenAI Responses API 会丢弃其后的推理项(reasoning items)。如果你的代码或 Agent 框架会在轮次之间改写早期 developer 消息、裁剪过往工具结果,或调整 reasoning.effort、tools 等顶层参数,就会直接受到影响。请将集成改为只追加的 input 历史,使用 configuration_update 和 additional_tools 处理中途变更,并在每次响应中检查 input_transformations,确认没有推理项被移除。
为 GPT-6.2 Responses API 调用选择接入路线
GPT-6.2 Astra 和 Sol 支持通过 Chat Completions 处理纯文本,但工具调用必须使用 Responses API,且前缀保护控制项(configuration_update、additional_tools 与 input_transformations)均属于 Responses API 功能。请选择一条提供 POST /v1/responses 且符合你访问与计费条件的 API 路线。
| 路线 | 接入条件 | 计费单位 | Responses API 说明 | 适用场景 |
|---|---|---|---|---|
| BetterToken API 网关 | BetterToken 账号、控制台 API Key、按量付费余额(已购付费余额不会按月清零) | 按模型当前计费单位计费(输入、输出与缓存 token 的价格和规则可能不同);见当前价格 | https://www.bettertoken.ai/v1(POST /v1/responses)已上架 gpt-6.2-astra 和 gpt-6.2-sol;请先用自己的 Key 验证无状态 store: false 回放、configuration_update 及 input_transformations 透传 | 希望用同一个按量付费 API Key 调用所有可用模型,或无法使用 OpenAI 直连计费 |
| OpenAI API 直连 | 位于支持国家或地区的 OpenAI 账号及 API 计费方式 | 按每 1M 输入、缓存命中输入、缓存写入及输出 token 计费 | 官方文档明确原生支持 configuration_update、input_transformations、prompt_cache_diagnostics、previous_response_id、后台完成窗口及组织级零数据保留(ZDR) | 具备 OpenAI 直连条件,且依赖 OpenAI 托管状态、ZDR 或文档中的测试版功能 |
通过 BetterToken 验证只追加回放与前缀检测
BetterToken 在 https://www.bettertoken.ai/v1(POST /v1/responses)提供 OpenAI 兼容 API 路线,通过你在 BetterToken 控制台创建的 API Key 鉴权。截至 2026-11-21,gpt-6.2-sol 和 gpt-6.2-astra 均已上架该 Responses 端点。BetterToken 是多模型平台与 API 访问层,并非 OpenAI 官方产品。其 Responses API 参考文档并未验证无状态 store: false 加密推理回放、configuration_update、input_transformations 或 prompt_cache_diagnostics 的透传能力。正式部署前,请先用自己的 Key 运行下面这项受控的两轮无状态检查。
在 Bash 中无回显导出你的 BetterToken 密钥:
read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
第一轮请求传入 store: false,确认返回结果包含至少一个带 encrypted_content 的 reasoning 项,再将“只追加无状态回放”与“仅修改早期 developer 消息的对照请求”放在一起比对:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["BETTERTOKEN_API_KEY"],
base_url="https://www.bettertoken.ai/v1",
timeout=120.0,
max_retries=0,
)
model = "gpt-6.2-sol" # Or "gpt-6.2-astra"
history = [
{"role": "developer", "content": "You are a backend reviewer. Give concise engineering answers."},
{"role": "user", "content": "Draft a two-step plan to add a non-blocking index on PostgreSQL."},
]
first = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=history,
)
reasoning_items = [item for item in first.output if item.type == "reasoning"]
if not reasoning_items:
raise RuntimeError("Turn 1 returned no reasoning items; use a harder prompt or higher effort.")
if not all(getattr(item, "encrypted_content", None) for item in reasoning_items):
raise RuntimeError("Stateless replay unverified: Turn 1 reasoning items lack encrypted_content.")
reasoning_ids = [item.id for item in reasoning_items]
first_output = [item.to_dict() for item in first.output]
follow_up = {"role": "user", "content": "List the failure modes and rollback steps for step 2."}
append_only = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=[*history, *first_output, follow_up],
)
edited_history = [{**history[0], "content": history[0]["content"] + " Be brief."}, history[1]]
edited_control = client.responses.create(
model=model,
store=False,
reasoning={"effort": "low"},
input=[*edited_history, *first_output, follow_up],
)
print("reasoning_ids:", reasoning_ids)
print("append_only:", append_only.status, getattr(append_only, "input_transformations", None))
print("edited_control:", edited_control.status, getattr(edited_control, "input_transformations", None))
print("append_only_cached_tokens:", append_only.usage.input_tokens_details.cached_tokens)
上线前核对这四个信号:
status == "completed"只能说明请求已被接收并执行完毕,不能证明网关跨轮保留了推理项。- 确认第一轮带
store: false的请求返回了非空的reasoning_ids,且每个推理项都带有encrypted_content。如果网关省略了encrypted_content,请将无状态回放视为未验证,因为第二轮无法跨上游传递加密推理 token。 - 对比两次第二轮调用的
input_transformations。完成透传验证的结果应表现为:edited_control中出现匹配reasoning_ids中某个 ID 的prefix_mismatch记录,而append_only中没有。如果两次返回的input_transformations均为None或为空,说明网关可能没有转发该字段,测试结果无法下结论。 - 将
configuration_update透传测试与前缀检查分开执行。验证text.format更新时,可以单独发一次第二轮请求,把text.format切换为严格的 JSON schema,再确认输出符合该 schema。OpenAI 并未提供用于确认对话中途reasoning.effort生效的响应字段(响应里的reasoning.effort仍只报告请求级配置),因此通过 BetterToken 使用configuration_update调整reasoning.effort应视为未验证。
对于提示词缓存,OpenAI 在 GPT-5.6 及更新模型上设定的最低可缓存前缀条件为 1,024 个可见输入 token。当可复用前缀达到该阈值后,可通过 append_only.usage.input_tokens_details.cached_tokens 观察实际复用量。扩大调用规模前,先查阅当前价格确认最新模型费率与缓存规则。
如果你直接调用 OpenAI 官方接口,请省略 base_url,改用 OPENAI_API_KEY,并遵循 OpenAI 的保持前缀不变指南。
GPT-6.2 中哪些操作算作前缀变更
推理项的前缀是指排在它之前的整段对话历史。在 GPT-6.2 上,只要改动这段早期历史,API 就会丢弃位于修改点之后的推理项。
OpenAI 文档记录了两类前缀变更:
- 修改早期的
input项:例如缩短工具返回结果、重写developer消息、缩小历史图片或文件体积,或者用摘要替换旧对话轮次。 - 在轮次之间修改请求级参数:例如改动
tools(新增、删除、重排或编辑 schema 和描述)、更改text.format、调整顶层reasoning.effort,或在 GPT-6.2 之前的模型上修改instructions。
根据 OpenAI 的推理指南,在 GPT-6.2 及更新模型上,在推理项之前插入或修改内容会触发 prefix_mismatch。单纯删除整条旧项而不改动其余项,或在推理项之后追加新项,本身不会触发 prefix_mismatch。不过,删除旧轮次仍可能降低提示词缓存复用率;当这种改动阻止了缓存复用时,Prompt Cache Diagnostics 可能会报告 input_changed。
前缀修改只是 input_transformations 报告的五种移除原因之一:
移除 reason | API 移除该推理项的触发条件 |
|---|---|
prefix_mismatch | 在 GPT-6.2 及更新模型上,该推理项之前的内容被插入或修改 |
end_user_mismatch | 在 GPT-6.2 及更新模型上,创建该项与复用该项的请求中 safety_identifier 不一致,包括仅在其中一次请求中省略该字段 |
model_mismatch | 切换了模型系列,或在同一系列内降级(满足其他检查条件时,同系列内升级可保留兼容的推理项) |
organization_mismatch | 复用了来自其他组织,或不同用户所属工作空间的推理项 |
turn_boundary | 当模型仅使用当前轮次推理时,传入了更早轮次的推理项(在支持的模型上,reasoning.context 控制更早轮次的推理项是否可以复用) |
推理项被丢弃后会发生什么
即使推理项被扣留移除,Responses API 请求依然可以正常返回完成状态,因此如果不检查响应中的 input_transformations,推理丢失会在无报错的情况下静默发生。对话中途修改前缀会带来两笔独立的生产代价:
- 推理项被丢弃的影响:推理项移除后,模型可能需要重做此前的推理过程,进而推高 token 消耗、费用和响应延迟;如果模型无法恢复丢失的推理过程,输出质量也可能随之下降。
- 修改可缓存前缀的影响:提示词缓存从请求开头依次匹配,修改前缀可能从改动点起中断后续缓存复用,从而增加输入费用并拖慢响应速度。
OpenAI 截至 2026-11-21 公布的 Standard 费率(针对 272,000 个及以下输入 token)直观说明了缓存未命中为何会迅速推高账单:
- GPT-6.2 Astra(
gpt-6.2-astra):缓存命中输入 $0.40/1M,未缓存输入 $8/1M(30 分钟缓存写入 $10/1M,12 小时缓存写入 $20/1M),输出 $40/1M。 - GPT-6.2 Sol(
gpt-6.2-sol):缓存命中输入 $0.10/1M,未缓存输入 $2/1M(30 分钟缓存写入 $2.50/1M,12 小时缓存写入 $5/1M),输出 $10/1M。
输入 token 超过 272,000 时,OpenAI 会将整次请求的输入与缓存价格翻倍,输出按短上下文输出单价的 1.5x 计费。如果你想评估稳定前缀何时适合启用 12 小时缓存写入,可查阅我们的 OpenAI 12 小时提示词缓存指南。
在不破坏前缀的前提下更新参数和上下文
用只追加的条目替代原地改写,让推理记录和已缓存前缀能够跨轮保留。
使用 configuration_update 调整 reasoning.effort 和 text.format
修改顶层 reasoning.effort 可能会重写隐藏的系统指令。在支持该特性的 GPT-6 及更新模型的标准单 Agent 模式下,保持请求级 reasoning.effort 和 text.format 不变,在下一条用户消息之前向 input 追加一个 configuration_update 项:
{
"type": "configuration_update",
"reasoning": {
"effort": "high"
},
"text": {
"format": {
"type": "json_schema",
"name": "migration_checks",
"strict": true,
"schema": {
"type": "object",
"properties": {
"safe": { "type": "boolean" },
"rollback_sql": { "type": "string" }
},
"required": ["safe", "rollback_sql"],
"additionalProperties": false
}
}
}
}
使用 configuration_update 时遵守以下五条规则:
configuration_update会跨轮持续生效,直到被后续更新覆盖。只更新reasoning.effort会保留早前的text.format设置,反之亦然。- 响应对象里的
reasoning.effort仍只报告顶层请求级数值,不会反映中途更新后的设置。 - 使用
previous_response_id可自动延续更新;手动管理input时,必须在原始位置按序回放每一条configuration_update。 - 自动截断和独立的
/responses/compact端点都会拒绝包含configuration_update项的历史记录,请改用context_management或compaction_trigger(详见下文压缩说明)。 gpt-6.2-astra和gpt-6.2-sol均不接受reasoning.effort: "none"。OpenAI 的 Using GPT-6.2 指南建议先从medium起步,或用low替代原有的none与minimal。
在不修改 tools 的前提下新增或限制工具
在各轮请求间保持请求级 tools 数组、schema 定义和排列顺序完全不变,再通过三种不破坏前缀的方式控制可调用工具:
- 将
tool_choice设为"none",在当前轮次禁用工具,而无需删除tools。 - 通过带
allowed_tools的tool_choice在当前轮次限定可调用的工具范围:
{
"tool_choice": {
"type": "allowed_tools",
"mode": "auto",
"tools": [
{ "type": "function", "name": "get_weather" },
{ "type": "function", "name": "search_docs" }
]
}
}
- 在对话中途追加一条
developer角色的additional_tools项以新增工具,或启用带defer_loading: true的工具搜索,让按需发现的工具追加到上下文末尾。additional_tools里的工具只有在该项出现之后才可调用,因此回放时必须保留其原始位置:
{
"type": "additional_tools",
"role": "developer",
"tools": [
{
"type": "function",
"name": "get_customer",
"description": "Look up a customer by ID.",
"parameters": {
"type": "object",
"properties": {
"customer_id": { "type": "string" }
},
"required": ["customer_id"],
"additionalProperties": false
}
}
]
}
区分可复用 developer 消息与顶层 instructions
从 GPT-6.2 开始,OpenAI 会将顶层 instructions 追加到 input 之后,位于可缓存断点之外。即使内容毫无变化,OpenAI 仍会在每次请求中按未缓存输入费率对这部分 token 计费,且顶层 instructions 不会随 previous_response_id 传递到下一轮。
按作用域放置指令:
- 将可复用的系统提示词和公共规则放进
input的第一条developer消息中,使其能够匹配提示词缓存。 - 对话中途需要更新可复用指令时,在
input末尾追加新的developer消息,不要修改第一条。 - 仅将只针对当前这一次请求的说明放进顶层
instructions。
处理上下文压缩与超长工具输出
在首次发送给模型前,就先缩短超长的工具输出并压缩图片或文件尺寸,不要事后再回过头截断历史项。
上下文压缩会改变前缀,因此通常难以避免缓存未命中。针对长会话,OpenAI 的上下文压缩指南给出了两种方案:
- 自动压缩(配合
compact_threshold使用context_management):即使前缀因压缩发生改变,OpenAI 仍会保留其后的推理项。如果早期轮次含configuration_update项,API 会在compaction项之后紧接着生成一条新的configuration_update,并将additional_tools声明存放在加密压缩项中。按原顺序回放返回的输出项即可。 - 显式压缩或自定义压缩:独立的
/responses/compact端点会拒绝包含configuration_update项的历史;调用/responses/compact时,请省略instructions并按原顺序将返回的窗口传给下次请求。如果历史中用到了configuration_update,请改为在/responses中加入compaction_trigger项,随后在下一条用户消息之前追加新的configuration_update,重新声明所有变更过的字段。如果使用自定义压缩,应将压缩摘要放到上下文末尾,而不是原地替换旧轮次,否则就只能接受后续推理项被丢弃。
使用 input_transformations 和 Prompt Cache Diagnostics 验证前缀保留效果
结合两项响应检查:一项报告被扣留移除的推理项,另一项指出打断提示词缓存复用的具体原因。
1. 在每次响应中检查 input_transformations
在 Responses API create 参考文档中,input_transformations 是一个可选数组,按输入顺序返回 {id, action, reason, type} 对象,记录被扣留的推理项(action 为 "removed",type 为 "reasoning")。当 reason 为 "prefix_mismatch" 时,先用 id 在更早一次响应的 output 中找到被移除的推理项,再对比两次请求中排在该项之前的输入,定位实际改动。
2. 使用 comparison_response_id 运行 Prompt Cache Diagnostics
如果 usage.input_tokens_details.cached_tokens 低于预期,选取同一组织内近期完成、且当前请求预期复用其前缀的响应(例如同一会话的上一轮响应),把它的 id 传入 prompt_cache_options.comparison_response_id,再检查返回的 prompt_cache_diagnostics:
{
"prompt_cache_diagnostics": {
"type": "cache_miss",
"reason": "tools_changed",
"comparison_reusable_tokens": 5629,
"cache_missed_tokens": 5629
}
}
OpenAI 的 Prompt Cache Diagnostics 指南中,prompt_cache_diagnostics.type 会返回 cache_hit、cache_miss、comparison_response_not_found 或 unavailable。出现 cache_miss 时,结果会包含 reason 和 cache_missed_tokens(估算未复用的 token 数),并可能包含 comparison_reusable_tokens(基线响应可复用前缀的原始 token 数)。未命中的 reason 分为以下几类:
input_changed:早期输入发生变更,例如在developer消息中加入了时间戳或请求 ID,或对旧轮次进行了编辑、重排或删除。tools_changed:工具被新增、删除、重排或编辑。reasoning_effort_changed或text_format_changed:直接修改了顶层reasoning.effort或text.format,而未使用configuration_update。model_changed、service_tier_changed、verbosity_changed、prompt_cache_key_changed或context_compacted:模型选择、服务层级、输出详略程度、缓存键或压缩状态发生变化。
使用诊断功能需留意五项限制:诊断要求使用 GPT-5.6 及更新模型,且可复用前缀不少于 1,024 个 token;诊断按尽力而为方式仅报告首个归类原因;不产生额外费用且支持零数据保留(Zero Data Retention);开启 stream=True 时,需从 response.completed 事件的 event.response 中读取 prompt_cache_diagnostics;诊断结果无法用来证实模型是否复用了推理记录。
自定义 API 与网关接入时的四个注意事项
通过自定义 API Base URL 或多上游网关路由 GPT-6.2 的团队,应核对以下四项细节:
- 调用
POST /v1/responses,而非 Chat Completions:GPT-6.2 Astra 和 Sol 虽支持用 Chat Completions 处理纯文本,但工具调用、configuration_update、additional_tools和input_transformations必须走 Responses API。基础迁移检查项见我们的 GPT-6 Astra Responses API 迁移指南。 - 回放完整的只追加
input数组,不要只依赖previous_response_id:BetterToken 的智能路由会把请求发往当前可用的上游通道,配置了多个上游的模型在遇到不可用、适用错误或超时时可以执行故障转移(并非每个模型都配有多个上游,并非每类错误都会触发故障转移,也不保证请求必然成功)。无状态回放能避免服务端状态绑定在单一上游。在 OpenAI API 上,零数据保留(ZDR)是面向已获批组织、在符合条件的端点和功能上启用的组织级配置,与单次请求设置store为false并不相同。在这两种无状态模式下(store: false,或启用 ZDR 的组织;此时 OpenAI 会将store视作false),output中的推理项默认包含encrypted_content。OpenAI 为兼容性仍接受旧版include: ["reasoning.encrypted_content"],但不强制传入。请按顺序回放全部返回的output项,在各轮间保持safety_identifier完全一致(或每轮都不传)以避免end_user_mismatch,并监控input_transformations中是否出现organization_mismatch。 - 省略不支持的采样参数:向
gpt-6.2-astra和gpt-6.2-sol发送 Responses 请求时,省略顶层temperature、top_p和top_logprobs参数,并仅从include中移除message.output_text.logprobs。 - 将后台完成窗口限定于 OpenAI 直连调用:在 OpenAI 的 Responses API 中,GPT-6.2 Astra 和 Sol 不支持
service_tier: "flex"。直接调用 OpenAI API 执行长耗时任务时,可使用后台模式的 2 小时或 8 小时完成窗口(公测版),详情见我们的 Responses API completion_window 指南。BetterToken 的公开 Responses API 文档尚未验证后台完成窗口,若业务依赖该功能,请自行测试验证或直接路由至 OpenAI 官方接口。