OpenAI API/OpenAI 扩展推理与会话状态

OpenAI 各代际模型推理强度、GPT-6 推理配置、加密内容回放自愈、服务端会话状态与提示词缓存。

OpenAI 扩展推理与会话状态

本文档详细说明通过 UniGateway 调用 OpenAI 规范端点时的推理控制参数(reasoning 与 reasoning_effort)、GPT-6 原生推理配置、加密推理状态回放与破损自愈、服务端会话状态管理(store 与 previous_response_id)及提示词缓存(Prompt Cache)策略。


章节导引

本篇为 OpenAI API 参考文档的第 3 章节:

  1. Responses 概述与快速开始
  2. 请求参数与输入格式
  3. 扩展推理与会话状态(当前章节)
  4. 结构化输出与采样参数
  5. 工具调用与内置工具
  6. 响应、流式与错误处理

推理控制与代际档位规范

OpenAI 推理模型通过隐藏的思维链(Reasoning Tokens)进行深度思考。在 Responses API 中通过 reasoning 对象控制,在 Chat Completions API 中通过 reasoning_effort 字符串控制。

1. reasoning 与 reasoning_effort 三维对照表

参数 / 场景OpenAI 官方规范与 Migration GuideUniGateway 处理规则
gpt-6.1-sol 与 gpt-6.1-terra 推理档位显式校验gpt-6.1-sol 支持 low / medium / high / xhigh / ultra / max(不支持 none 与 minimal);gpt-6.1-terra 支持 none / low / medium / high / xhigh / ultra / max(不支持 minimal)。前置拦截非法档位:当向 gpt-6.1-sol 显式传入 none 或 minimal(含 thinking.type: "disabled"、output_config.effort 及模型后缀 -none / -minimal),或向 gpt-6.1-terra 显式传入 minimal 时,网关直接返回 400 invalid_request_error 并列出合法档位。
各代模型 reasoning.effort / reasoning_effort 范围与钳制各代模型支持的档位不同:o1/o3/o4-mini 支持 lowhigh;GPT-5 支持 minimalhigh(pro 仅 high);GPT-5.1 支持 nonehigh;GPT-5.2 与 GPT-5.3-codex 支持 nonexhigh;GPT-5.4/5.5 支持 nonexhigh;GPT-5.6、GPT-6 Sol/Luna 支持 nonemax;GPT-6 Astra 支持 low~max;GPT-6.1 系列支持至 ultra 与 max。规范校验与就近钳制协同:对于超出模型能力表范围的档位,网关遵循官方规范校验返回 400 invalid_request_error;在跨协议转换与渠道适配中,网关执行就近钳制(将不支持的 none / minimal 向上钳制为 low,将超出模型上限的 max / xhigh 向下钳制为 xhigh 或 high),并支持分组级最大推理强度上限策略。
多形态推理开关兼容转换不同客户端与生态使用 reasoning_effort、reasoning、thinking 或 enable_thinking 控制思考模式。渠道原生格式归一:在特定通道(如原生 thinking 对象或顶层 enable_thinking 布尔值)上,网关自动将 reasoning_effort、reasoning、thinking 与 enable_thinking 统一转换为目标通道的原生格式。
reasoning.mode(GPT-6 专属字段迁移)GPT-6 (gpt-6 / gpt-6-astra) 原生支持 reasoning.mode 与 reasoning.effort 独立配置;而在非 GPT-6 模型上,reasoning.mode 不受支持。代际降级转换:在 gpt-6 / gpt-6-astra 上完整保留 reasoning.mode;在非 GPT-6 模型上,若客户端传入 reasoning.mode: "pro",网关自动将其等效迁移为 reasoning.effort: "max"(若未显式设置 effort,随后按目标模型上限参与档位钳制)并移除 reasoning.mode 字段。
reasoning.summary(思维链摘要)/v1/responses 字段,可选值为 "auto"、"concise"、"detailed",控制是否在输出中返回可读的思维过程摘要(summary_text)。跨协议自动桥接:当客户端通过 /v1/chat/completions 调用推理模型并设置 reasoning_effort 时,若底层经由 /v1/responses 转发,网关自动注入 reasoning.summary: "auto",并将上游返回的推理摘要映射为 Chat Completions 响应中的 message.reasoning_content(及流式 delta.reasoning_content)。

加密推理状态回放与破损自愈

在无状态模式(store: false)或跨轮次多工具调用交互中,OpenAI 官方规范要求客户端在后续轮次中将上一轮返回的 reasoning 内容项放回 input[] 中,以便模型恢复先前的思考上下文。

1. reasoning.encrypted_content 交互机制

  • 获取加密推理项:客户端在请求体中设置 "include": ["reasoning.encrypted_content"]。
  • 回放机制:模型在响应的 output 数组中返回 {"type": "reasoning", "id": "rs_...", "encrypted_content": "gAAAAAB..."}。客户端在发起下一轮调用时,需将该项原样保存在 input[] 中传递。

2. 破损加密推理内容自动自愈重试

场景上游行为UniGateway 自愈处理规则
跨组织密钥轮换或签名失效若 encrypted_content 跨不同组织调用、遭截断或上游密钥轮换,上游返回 400 encrypted content ... could not be verified 或 missing required reasoning item。破损加密推理内容自动剥离重试:当上游因 encrypted_content 校验失败或关联的未持久化推理项缺失返回 400 时,网关自动触发自适应修复:从 input[] 中剥离失效的 encrypted_content 及孤立的 rs_ / msg_ / fc_ ID,保留明文对话与工具输出上下文后自动重发请求,使长会话无需中断。在响应头中输出 x-gateway-rectified: corrupted_encrypted_content。

服务端会话状态管理

Responses API 原生支持通过服务端持久化会话状态,极大降低多轮对话中的网络带宽传输开销。

参数 / 场景OpenAI 官方规范与 Migration GuideUniGateway 处理规则
store(有状态存储开关)与无状态清洗控制 OpenAI 是否在服务端保存本次响应(/v1/responses 默认为 true)。当显式设置 "store": false 时,服务端不持久化响应项 ID(如 rs_...、msg_...)。若后续轮次在 store: false 下仍向 input[] 回传未持久化的 rs_* ID 或无 encrypted_content 的推理项,上游会报错 Item 'rs_...' of type 'reasoning' was provided without its required following item。store: false 深度兼容清洗:当请求设置 store: false 时,网关主动剥离 input[] 中 rs_ 前缀的推理项 id、移除不包含 encrypted_content 的纯摘要 reasoning 项,并剔除指向 rs_* 的 item_reference 引用项;在无状态通道上,网关自动将 store 固定为 false 并执行上述无状态清洗。
previous_response_id(有状态多轮续写)/v1/responses 特性,传入上一轮响应的 id(resp_...)即可在服务端自动拼接历史上下文,无需客户端重传全部 input。有状态能力路由与降级:当请求携带 previous_response_id 或显式要求 store: true 时,调度器优先选择支持服务端状态存储的官方 API Key 账号;在不支持服务端存储的无状态通道上,网关自动剥离未持久化的 previous_response_id,避免上游返回 400/404。
truncation(上下文截断策略)/v1/responses 字段,可选 "auto"(上下文超出窗口时自动丢弃对话中段历史)或 "disabled"(默认,超长时返回 400)。通道兼容处理:在标准 OpenAI 通道原样透传;若部分上游不支持 truncation 字段并返回 400 Unsupported parameter: truncation,网关自动剥离该字段并重试。
include(附加响应内容)/v1/responses 数组字段,如 ["reasoning.encrypted_content", "file_search_call.results"]。自动注入与过滤:在无状态转换路径中,网关自动在 include 中确保包含 "reasoning.encrypted_content" 以保障多轮推理上下文完整;同时在激活推理时自动剔除不兼容的 "message.output_text.logprobs"。

提示词缓存 Prompt Cache

UniGateway 完整支持 OpenAI 原生提示词缓存机制,通过会话粘性调度与参数规范化提升缓存命中率,大幅降低长上下文请求的延迟与计费:

参数 / 场景OpenAI 官方规范与 Migration GuideUniGateway 处理规则
prompt_cache_keyOpenAI 官方用于辅助提示缓存路由的字符串标识(相同前缀 + 相同 prompt_cache_key 的请求更容易路由至同一缓存实例)。多租户缓存隔离与粘性路由:网关利用 prompt_cache_key(或自动从会话特征派生的稳定哈希种子)进行上游账号粘性会话调度以最大化缓存命中率,并在跨协议转换(Chat Completions ⇄ Responses)时自动保留并传递客户端显式指定的 prompt_cache_key。
prompt_cache_retention控制提示缓存的保留时长策略,官方支持 "in_memory" 与 "24h"(扩展保留)。通道兼容剥离:在支持扩展缓存保留的官方 API Key 通道原样透传;在不支持该字段的通道上,网关自动在转发前剥离 prompt_cache_retention,防止上游返回 Unsupported parameter。
prompt_cache_optionsGPT-5.6、GPT-6 及 GPT-6.1 系列支持的原生提示缓存选项对象(如 {"ttl": "30m"})。代际白名单与 TTL 归一化:网关仅在支持该特性的模型(gpt-5.6-*、gpt-6-*、gpt-6.1-*)上保留 prompt_cache_options,并将其 ttl 字段统一规范化为 "30m";若在其他模型或不支持该特性的上游通道中出现,网关自动剥离(含上游 400 触发的回退剥离)。