OpenAI 升级到 GPT-5.6 Sol

本指南用于把现有 OpenAI API 集成、仓库、提示词系统、智能体、模型路由器或选择器迁移到 GPT-5.6 Sol 或 GPT-5.6 家族。

明确的默认目标为 gpt-5.6-sol；gpt-5.6 别名路由到 Sol，仅在仓库有意使用家族别名时采用。GPT-5.6 家族具有不同的成本、延迟、上下文和质量层级，不能把所有旧模型一律替换成 Sol。

迁移前读取当前GPT-5.6 指南，修改提示词时读取其提示实践部分。模型 ID、参数、限额、价格和功能以当前官方资料为准，本页说明查找位置、保留事项、兼容风险和验证方法。

核心原则

先保持各使用点的行为、延迟等级、成本等级、推理力度、端点合同、工具语义、缓存行为和输出合同，再做最小迁移。新能力只在解决测得的问题或明确需要时引入。

单纯模型升级不自动意味着增加推理字段、改变请求 Schema 或重写测试。只有已知旧的实际行为，且在新模型上省略设置会改变行为时，才需要显式补充。

主要风险包括：用 Sol 覆盖原本 mini／nano 的低成本分工；把原有效 none 变为新默认 medium；Chat Completions 函数工具没有显式 none；动态后缀破坏缓存命中；图像或 PDF 的 auto 细节增加词元；向不支持的路由发送新字段；只换字符串而漏掉注册表、白名单、价格、能力标记、测试和选择器。

迁移分类

修改前盘点

除模型 ID 外，还要查找：别名、环境变量、CLI 参数、配置与部署默认值；Responses、Chat Completions、Batch 和提供商适配器；推理、词元预算、采样、超时；函数与托管工具、结构化输出、解析器、重放逻辑；system／developer／user／工具描述提示词；路由、回退、白名单、枚举、正则、验证 Schema 与能力表；选择器文字、上下文和价格元数据；缓存键、保留选项、稳定前缀与指标；图像、PDF、OCR、文件与计算机输入；测试、样本、快照、评测、分析标签、账单表和文档。

更改默认模型时，应同时检查运行配置、环境文件、安装说明、测试、CLI 默认值与部署示例，避免不同入口使用不同默认值。

为每个调用记录原模型及用途、端点与客户端、提示词位置、实际推理力度（含默认值）、成本／延迟／上下文／质量角色、工具与缓存、状态重放、多模态输入、下游解析合同、迁移类别和验证计划。

按角色选择目标

原指南给出的检查起点：Sol、Terra 约1.05M上下文、最大128K输出；Luna为400K上下文、最大128K输出。Sol／Terra超过272K输入词元可能改变整个请求的价格。注册表或UI的数据必须再从对应模型资料核实，不能猜测。

选择器默认保留现有项，新增家族选项；只有明确要求时才移除旧项。使用别名时，在验证中记录实际 response.model，不要假设它在控制台、限额、分析或账单中与显式 Sol 名称完全等同。

先保持实际推理力度

GPT-5.6 支持 none、low、medium、high、xhigh、max，省略时默认 medium。GPT-5.5 通常也是 medium，而 GPT-5.4、mini、nano 的相关旧调用可能实际为 none，所以同样省略字段也可能改变速度、费用及函数工具兼容性。

显式值先保留；省略值且知道旧默认时，只在新默认会改变行为的情况下显式补充；旧行为不明时标为待核，不猜测。基线通过后，用相同力度与低一档力度比较。xhigh、max 仅用于评测证明有收益的困难任务，不能全局推荐最高档。

先检查失败是否来自成功条件缺失、依赖不清、工具路由、状态重放或验证循环，再决定是否增加力度。两个端点使用不同字段：

Responses请求中的推理配置；字段层级保持来源格式

{
  "model": "gpt-5.6-sol",
  "reasoning": { "effort": "none" }
}

Chat Completions请求中的推理配置；与Responses格式不同

{
  "model": "gpt-5.6-sol",
  "reasoning_effort": "none"
}

Chat Completions 与函数工具

GPT-5.6 在 Chat Completions 中仅当实际推理为 none 时兼容函数工具；推理加工具应使用 Responses。默认是 medium，因此下面省略力度的组合存在兼容风险，不能作为可直接运行的正确示例：

不安全组合示意：函数工具存在，但未显式保持none

{
  "model": "gpt-5.6-luna",
  "tools": [{ "type": "function", "function": { "...": "..." } }]
}

必须保留低延迟 Chat Completions 函数工具时，显式设置：

保留函数工具时显式指定none推理力度

{
  "model": "gpt-5.6-luna",
  "reasoning_effort": "none",
  "tools": [{ "type": "function", "function": { "...": "..." } }]
}

同时需要推理和工具，则在获准改实现的范围内迁移到 Responses；否则报告兼容阻塞。不要靠删除工具、取消必要推理或偷偷改变业务行为掩盖问题。若当前 API 拒绝预期的 none 路径，应记录原请求与错误，而非编造绕过方案。

Responses 与会话状态

推理、工具、多轮智能体和5.6新能力优先考虑 Responses。普通多轮调用先保持现有状态策略，不因为支持持久化推理就自动引入。

有意启用时，仅在目标和假设稳定时使用 reasoning.context: "all_turns"。服务端可承载状态时优先 previous_response_id；手动重放必须保留每次用户输入和全部相关输出项，而非只保留文字。store: false 或 ZDR 场景还需保存并回传返回的推理项，包括 encrypted_content。旧推理可能过时或误导时使用当前轮次行为。

重放应完整保留项类型、ID、调用ID、caller元数据、assistant的phase值；缺失可能静默降低质量或破坏工具续接。

提示词缓存

不能假设换模型后仍有相同命中率。5.6隐式缓存会在最新用户／工具消息附近管理断点，不再依赖128词元取整；稳定长前缀后附动态后缀，也可能失去命中。

检查可重用system／developer提示、动态后缀、变化的时间戳／请求ID／用户值／工具列表，以及缓存键、保留设置、监控和只统计读取而忽略写入的费用逻辑。

保持可重用前缀稳定，避免无故改动大提示词。对比新旧 cached_tokens、cache_write_tokens、延迟和费用。只有实际稳定边界被隐式缓存漏掉且有测量证据时才增加显式断点，不要全局转换。混合模型请求构造器应隔离5.6专属字段，不能发送到旧路由。

新的顶层prompt_cache_options配置；JSON中不添加注释

{
  "prompt_cache_options": {
    "mode": "explicit",
    "ttl": "30m"
  }
}

显式断点通过 prompt_cache_breakpoint 放在实际渲染后的稳定边界。已有 prompt_cache_key 则保留。旧 prompt_cache_retention 结构已弃用，重写前核对当前资料。缓存写入比普通未缓存输入更贵，命中率降低可能同时增加延迟和费用。

图像、PDF、文件与长上下文

即使提示词不变，5.6也可能改变输入用量：图像省略detail或为auto时可能保留原尺寸；Responses文件／PDF省略input_file.detail或为auto时可能采用较高页面图像细节；Chat Completions文件输入不提供相同控制；Sol／Terra长输入可能跨定价阈值；Luna较小上下文可能放不下原任务。

迁移前后测量输入词元和延迟。成本敏感时显式设置detail；无需空间精度的任务可缩图或用低细节；密集图表、坐标、OCR、定位和视觉检查可保留原始／高细节。测试最坏上下文长度，不只测常规样本。元数据缺少某标记不足以断言能力被移除，应结合当前文档与代表性请求核实。

结构化输出、解析器与工具合同

保留JSON Schema、必填字段、枚举、拒绝处理、解析预期、工具名、参数Schema、call ID与重试。下游依赖的引用、证据字段与原生交付物也应保留。最终回答本身必须符合合同，工具调用成功不等于最终回答正确。

没有产品变更要求时，不能通过放宽Schema、删除必需行为、路由或工具、改业务逻辑来让迁移“通过”。

可选：Pro 模式

基线迁移不默认开启Pro，除非旧用途本来类似Pro或明确要求。5.6 Pro使用基础模型加模式：

Pro模式的JSON请求配置；模式与力度分别设置

{
  "model": "gpt-5.6-sol",
  "reasoning": {
    "mode": "pro",
    "effort": "medium"
  }
}

使用Responses；不寻找或编造gpt-5.6-pro独立模型名。Pro支持的力度从medium开始，模式与力度分别决策。比较质量、总延迟和实际计费词元；旧Pro模型迁移时应单独评测模式变化。

可选：程序化工具调用

仅当代码能在大型结构化中间结果返回模型前有效压缩数据时采用。适合有界、只读的筛选、关联、排序、排名、去重、聚合、同类记录批处理、确定性验证和返回紧凑结构的map-reduce检索。

单次直接调用、每次结果都改变下一决策的自适应流程、写入或审批、有副作用的操作、重引用与原生交付物，以及需要模型直接判断的语义任务通常不适合。

程序化工具调用的请求结构；programmatic_tool_calling不嵌入另一tools属性

{
  "tools": [
    { "type": "programmatic_tool_calling" },
    {
      "type": "function",
      "name": "lookup_records",
      "allowed_callers": ["programmatic"]
    }
  ]
}

宿主需处理program、程序发出的function_call、function_call_output、program_output；回传结果保留原call_id与caller。限定阶段、只读工具范围、输出Schema、重试次数与回到直接判断的交接点。程序结果正确仍须验证最终回答。

可选：多智能体 Beta

基线迁移不自动启用多智能体。应用已有明确可并行流程且用户需要时，再检查以下要求：OpenAI-Beta: responses_multi_agent=v1请求头；multi_agent: { "enabled": true, "max_concurrent_subagents": 3 }；处理multi_agent_call、multi_agent_call_output、agent_message；执行任意智能体的普通开发者函数并返回全部结果；保留新项以便重放与追踪；核对压缩、推理摘要、工具调用限制的兼容性。

限制并发，避免无限委派、重复工作或缺少最终综合。

提示词迁移判断

模型与API基线运行后，先看代表性轨迹，只针对测得的失败修改提示词。优先简洁、结果导向的提示，明确成功条件、依赖、停止和完成边界；保留用户值；为隐含选择给出决策标准；明确自主与许可边界、工具路由、资源链接、路径线索、长任务阶段计划及交接；完成声明前做真实验证。

避免泛泛的“简短”“全面”“逐步思考”、可能导致无意切换语言的全局语言要求、反复“先问”阻塞安全本地工作、难以定位退化原因的大规模改写，以及在需要证据时机械压缩工具循环。

原提示词的中文译文，保留任务条件与限制

保留已有功能、路由、输出及用户可见行为。
不要只为让构建通过，就删除或禁用必需行为。
结束前运行相关构建、测试、类型检查、渲染或冒烟检查，并报告证据。

长任务还应明确当前层次是研究、设计、实现、审查还是外部协调，避免未经说明就跨层执行。

升级工作流

先读取实时5.6文档和提示实践，盘点每个调用及邻近配置／注册表／解析器／测试；按角色与迁移类别选择Sol、Terra、Luna，保持旧实际推理力度。检查端点与SDK、Chat工具、缓存、上下文与长输入费用、图像／PDF细节、结构化输出、重放与工具续接、混合模型字段。

然后执行最小模型、配置、注册表和提示词修改。不要默认加入Pro、持久化推理、PTC、显式缓存、多智能体。运行已有测试与代表性评测，分别汇报修改、保留、阻塞、待确认的位置。

验证矩阵

以控制变量方式比较：旧模型／旧提示／旧设置；新目标／相同提示／保留力度；新目标／相同提示／低一档力度；针对实测失败的最小修复；最后单独测可选新功能。

记录任务成功与可见质量，结构合法性与解析成功，工具选择／参数／重试／循环／完成率，首个可见词元时间（TTFT）、总延迟、超时与并发，输入／输出／推理／缓存读取／缓存写入词元，每次成功任务成本，长上下文／压缩／重放，图像PDF词元及OCR准确度，完整性、引用和验证证据。

路由器和选择器至少为每个角色测一个代表任务，确认没有把最低成本层误用于关键质量任务，也没有把Sol误用于所有任务。

最终报告

报告应包含当前调用清单、端点与角色、提示词位置及原实际力度；目标映射与理由；字符串、推理、提示词、注册表、元数据、测试和API结构变化；全部兼容检查；每项提示词修改对应的失败；实际命令、评测、轨迹、前后测量及缺口；保留的历史／固定／含糊用途；具体阻塞、原因与最小下一步。

不能仅因为模型名已替换就宣称迁移完成。只有受影响行为和合同经过验证，或剩余缺口已明确记录，才能准确说明迁移结果。