1. 两个日期，两条替换路径

2026 年 11 月 2 日的 Gemini API 更新记录宣布，Gemini 2.5 Pro 和 2.5 Flash 已弃用，不能再从 Google AI Studio 中选择。API 的变化定于 12 月 1 日生效：gemini-2.5-pro 的请求会自动路由到 gemini-3.8-flash；gemini-2.5-flash 会路由到 gemini-3.5-flash-lite，并按目标模型费率计费。

截至本文 11 月 4 日核对，旧模型的 API 访问限于过去实际使用过它们的用户。另一个名称相近的 gemini-2.5-flash-lite 不在这次弃用范围内。今天旧名称仍能返回结果，并不能证明截止日后行为不变；已读取的公告也没有给出准确切换时刻及其时区。

这些陈述针对 Gemini Developer API 与 AI Studio，不能直接套用到 Gemini 消费应用、订阅权益或所有 Vertex AI 部署。先在每张迁移工单上写清服务入口和项目负责人，再讨论替换模型，才能避免团队各自验证了不同产品。

Google：11 月 2 日 Gemini API 更新记录 · Google：弃用、访问资格与自动路由时间表

2. 先盘点应用契约，再修改模型字符串

检查应用配置、后台任务、笔记本、批处理和自建网关别名。环境变量写着 pro，不代表网关或任务执行器最终也使用同一模型。记录配置中的模型以及响应实际暴露的模型标识；HTTP 200 只能证明请求得到了响应，不能单独证明预期路由和业务行为都正确。

将模型迁移与接口迁移分开。Google 仍支持 GenerateContent，Interactions 是新项目推荐入口；不用为了升级模型而把端点、SDK、提示词和工具协议一次全部重写。先冻结可以复现的基线，再逐个改变变量，失败时才有办法说明是哪一层发生了变化。

  • 每个调用入口都记录端点、模型 ID、SDK 版本、提示词版本、工具 schema 摘要和默认请求参数。
  • 标明状态由谁维护：SDK 会话历史、应用保存的 content parts、服务端 Interactions，还是无状态 steps 回放。
  • 区分只读任务与发送消息、改记录、产生费用等写操作；回放阶段用模拟效果替代真实动作。
  • 为任务设置负责人、验收规则和获准使用的数据集；不要把客户凭据或未脱敏会话复制进迁移仓库。

Google：Interactions 状态、单回合设置与存储 · Google：API key、项目与凭据边界

3. 用兼容矩阵取代旧参数假设

当前迁移指南不仅要求替换模型名，也列出了请求层变化。部分采样参数在文档描述的模型中会被忽略，未来代际可能返回错误；这与“所有相关请求现在都报错”不同。应主动移除它们，再验证以前依赖这些设置的业务行为，而不是把没有报错当成设置仍然有效。

下表是建议的应用审查项目。请求合法只是第一道门槛，不能推出业务输出等价、推理投入相同或整体更省钱。每个移除的旧假设都应保留一个失败样例，防止共享封装将来又把它加回来。

建议在隔离测试项目执行的兼容检查，本文未报告测试结果
旧假设迁移动作验收证据
thinking_budget 的数字可以直接复用为目标模型选择支持的 thinking_level实际序列化请求与对应任务的通过结果
temperature / top_p / top_k 仍控制旧行为移除已弃用采样字段请求不再含这些字段，业务输出规则仍通过
candidate_count 仍被支持Gemini 3 及后续模型移除该参数应用不再假定一次返回多个候选
最后补一个 model 前缀即可强制格式改用系统指令或结构化输出没有末尾 model 预填充，解析与数值检查均通过
保存纯文本历史已经足够保留该协议要求的完整模型状态多回合工具回放完成且没有丢失上下文
切回旧模型别名就能回滚准备仍受支持的显式备用配置备用路由可以直接指定并独立通过验收

Google：Gemini 3.8 Flash 迁移清单 · Google：Gemini 3.6 与 3.5 Flash-Lite 参数变化

4. 显式设置推理投入，再比较效果

Gemini 3.8 Flash 支持 low、medium、high，默认是 medium，不支持 minimal。不要不加区分地搬用 Flash-Lite 的设置。路由器应该校验“模型与 thinking level”这对组合，而不是给所有模型拼接同一个配置。

以下是未执行的 Interactions REST 请求体示例，适用于合成只读样例，端点为 POST https://generativelanguage.googleapis.com/v1beta/interactions，凭据应由服务端提供。它只说明请求形状，不代表生产配置或性能结果。store=false 不能用于后台执行，也不能在后续用 previous_interaction_id 继续这次交互；它不是所有服务端保留行为都为零的通用承诺。

用相同验收样例比较 low 与 medium，再决定是否升级推理投入。输出上限、超时和工具调用预算应分别设置。把最大输出压得很短可能截断交付物，不能拿它替代 thinking level 控制；最终少输出几个字，也不等于少完成了内部工作。

{
  "model": "gemini-3.8-flash",
  "store": false,
  "input": "合成测试：列出 [7, 3, 7] 中重复的 ID，不调用任何外部工具。",
  "generation_config": {
    "thinking_level": "low"
  }
}

Google：Gemini 3.8 Flash 迁移清单 · Google：Interactions 状态、单回合设置与存储 · Google：11 月 3 日按任务成本路由的工程实验

5. 用真实工具回合验证签名保留

思考签名属于不透明协议状态，不是答案、需要执行的指令或可直接阅读的推理全文。在 GenerateContent 中，它可能附着于 content parts；Interactions 则通过 thought steps 和特定内置工具步骤承载相关状态。只用页面可见文本重建历史，会丢掉下一回合可能需要的信息。

有状态 Interactions 可以通过 previous_interaction_id 由服务端维护这部分上下文。无状态回放需要原样重发返回的 thought steps，以及相关内置工具签名。两种表示必须分别处理，不要虚构所有接口通用的签名字段，更不要翻译、压缩总结或自行重构不透明值。

  • 至少回放用户请求、模型工具调用、工具结果、最终答案的完整链条；一句问候无法验证状态连续性。
  • 流式和非流式分别测试，保留完整协议事件及签名增量；看到文字开始输出，不代表这个回合已经完整结束。
  • 加入丢失 thought step、签名截断、序列化器删除未知字段等反例，记录实际错误或错误续答，不预设所有端点都返回同一种 HTTP 状态。

Google：thinking、签名与流式状态

6. 配对工具结果，防止重复副作用

Interactions 的 function_result 使用 call_id 和函数名识别对应调用。应用适配器应为每个调用返回且只返回一个匹配结果，失败也应有明确结果。并行返回不能只按数组位置配对；两个调用可能函数名相同、参数不同，错配后模型仍可能生成看似合理的总结。

协议匹配正确，不等于业务操作具备幂等性。如果写入成功但网络确认丢失，重跑整个代理回合可能重复动作。需要独立业务操作键和效果账本，不能只把模型生成的 call ID 当作持久事务身份。迁移回放阶段可用桩函数记录计划动作，遇到重复操作立即拒绝。

Interactions 中，即使用 previous_interaction_id 保留历史，tools、system_instruction、generation_config 仍然只对当前交互生效。每回合要重新提供本次需要的策略与配置；历史还在，并不证明上一回合的工具权限或 thinking 设置自动继承。

Google：函数调用与工具结果匹配 · Google：Interactions 状态、单回合设置与存储

7. 检查输出契约和每一种模态

结构化输出约束形状，不保证数值真实。标识符、日期、算术、允许枚举和业务关系仍需要客户端校验。文档支持的是 JSON Schema 子集，不是所有约束都由解码器强制执行；不要把长度限制或去重要求完全交给模型端 schema。

两个目标模型的参考页都列出文本、图像、视频、音频和 PDF 输入，输出为文本。能读音频不等于能生成语音，能读图片也不等于能生成图片。Live、语音生成、图像生成端点应另做专门迁移审查，不能套用这次文本模型的替换路径。

  • 文档任务用已知页码和答案对照，同时要求结果值与证据位置，不能只看语言流畅。
  • 图表样例加入不清楚的坐标轴或单位，允许明确说明不确定，而不是逼模型猜数字。
  • JSON 提取覆盖缺失数据、重复 ID 和多余字段，分别校验序列化格式与领域规则。
  • 工具返回媒体时检查适配器是否保留正确内容类型与载荷，不能只剩文件名或一句文字描述。

Google：结构化输出及 schema 限制 · Google：Gemini 3.8 Flash 能力参考 · Google：Gemini 3.5 Flash-Lite 能力参考

8. 让回放测试能够否决漂亮答案

使用合成数据或经批准脱敏的样例，固定工具返回，再留出一组不参与调提示词的保留集。每个样例写清预期结果与业务意义。有证据的答案、正确拒绝、合规转人工要分开记录，不能把所有完成响应都算任务成功。

下表是原创测试设计，并非本文已经执行的结果。发布阈值应在看到候选结果前确定。按流程和严重程度分组汇报，防止大量简单提取题掩盖一次重复支付、标识符泄露或多步骤工具链失败。

建议的最小迁移验收集
样例检查项目阻断该流程的失败
简单字段提取已知 ID、必填字段和业务约束JSON 格式正确但值错误
两个独立只读工具ID、名称、结果数量与对应关系结果附到错误调用
顺序依赖工具第二步参数来自第一步已核实结果用猜测值代替工具证据
模拟写入后丢失确认业务效果账本最多记录一次重试重复写入
有状态与无状态会话完整工具回合中状态得到保留签名丢失或指令遗忘
流式连接中断识别未完成回合，恢复有次数上限将半截文字当最终结果
证据未知或文件缺失说明不确定或按批准流程交接编造引文或文件内容
超时、配额、非法请求有限重试与明确失败分类无限循环或非法请求重试风暴

Google：thinking、签名与流式状态 · Google：函数调用与工具结果匹配 · Google：结构化输出及 schema 限制

9. 将失败尝试算入通过验收的任务成本

Google 11 月 3 日的工程文章讨论按成功任务成本进行路由。它使用 50 道题、每种设置一次运行和有限自动评分，是厂商发表的个案，不是本站实测、独立通用榜单或生产收益保证。对团队更有价值的启发，是把完整任务而不是单个 token 价格作为比较单位。

评估时汇总窗口内实际计费的模型调用、路由器、重试、外部工具以及单独计费的基础设施，再除以独立规则验收通过的任务数。如果一个也没通过，应报告“没有通过任务”和已花费用，不能除以零或默默删除失败尝试。已包含在账单总额里的思考 token 不要再次计费。

输入、输出、思考、缓存 token 作为诊断指标，与对账后的费用并列保存。对比当前费率与已公布的未来费率期，不把限时价格当成永久价格。同时看延迟分布、重试次数、工具效果和转人工数量；平均费用低，也可能只是把修复工作转给了人。

每个通过任务的成本 = 对账后的全部任务费用 / 验收通过任务数

# 建议的评估记录：应用自定义，不是 Gemini API 字段
case_id, model, endpoint, sdk_version, prompt_digest
thinking_level, state_mode, tool_schema_digest
accepted, failure_category, latency_ms, retry_count
reconciled_cost, rate_date, cache_condition, intended_effects

Google：Gemini Developer API 计费 · Google：11 月 3 日按任务成本路由的工程实验

10. 路由器先和简单基线比较

先比较少量固定策略：让 Flash-Lite 处理全部适用任务，或统一用 3.8 Flash 的 low、medium。保持相同测试集和质量要求，再引入选择这些合法组合的路由器。否则一个复杂系统可能只是战胜了配置不合理的基线，看起来经济却没有证明额外维护值得。

路由器应判断可观察属性，例如是否需要顺序工具证据、是否涉及写入，而不是一句模糊的“简单还是复杂”。不确定或后果严重的任务走已经验证的配置或人工审查。不要只按提示词长度分流；短小状态模拟可能比很长的直接摘录更需要推理。

冷热上下文分别评估，保存足以解释模型切换的元数据。路由会改变上下文复用和会话状态条件，必须测试回合中途切换；一次全新请求成功，不能证明续接正确。后续模型还必须支持对话里已有输出的输入模态。

  • 路由规则纳入版本管理，只在开发集调优，保留集评估前冻结。
  • 路由器费用、升级重试、已经浪费的便宜路径工作，都计入同一个任务账本。
  • 升级链路有次数上限和最终交接，两个代理互相要求再试一次不算恢复方案。
  • 只有维持事先约定的验收水平，并改善真实运营指标，才采用路由器；本文不预设节省比例。

Google：Interactions 状态、单回合设置与存储 · Google：11 月 3 日按任务成本路由的工程实验

11. 准备能跨过 12 月 1 日的回退路径

先回放只读工作，再进行禁用副作用的影子比较。影子路径不能重复发邮件、改记录或扣费。只有对应流程的验收集通过，才把有限用户群切到新配置，并让实际路由与失败分类可观察。

自动重路由生效后，把配置改回 gemini-2.5-pro 或 gemini-2.5-flash，并不能恢复原模型。真正的回退是已经通过相同验收、目前仍受支持的显式配置，或获准的人工队列。保留旧适配器不等于保留供应商旧模型可用性。

  • 重复副作用、证据链接失效、持续非法请求、任务预算超限都应有停止条件。
  • 备用配置也要测试相同数据限制和工具权限，不能在救援时悄悄扩大访问范围。
  • 提前完成迁移，不赌公告没有写明的切换时区或延期。
  1. 盘点路由与数据边界
  2. 冻结基线和合成样例
  3. 验收请求、状态和工具契约
  4. 评估通过任务及全部成本
  5. 无副作用影子验证后有限上线
  6. 监控并切换已验证备用或人工
建议发布流程：每个关卡都产出可审阅工件

Google：11 月 2 日 Gemini API 更新记录 · Google：弃用、访问资格与自动路由时间表

12. 留下其他工程师能复现的迁移记录

迁移记录应包含来源核对日期、受影响路由、准确目标配置、样例摘要、评分规则、失败例子与回退负责人。把已经测到的结果和计划检查分开。本文资料核对日期为 2026 年 11 月 4 日，请求体、矩阵和发布流程都是未执行示例，没有验证读者账号资格、配额、延迟或节省金额。

下面的任务模板要求交付具体工件，并在真实副作用之前停止。除非组织批准另一条数据路线，应使用合成样例替代生产会话。实现当天还要再查官方参考，因为模型时间表和请求字段可能继续变化。

审查本应用的 Gemini 2.5 迁移，不调用付费 API，不修改生产。
1. 盘点模型 ID、端点、SDK 版本、提示词和工具适配器。
2. 将受影响路由映射到显式受支持目标与 thinking level。
3. 找出 model 预填充、移除参数和丢失的协议状态。
4. 为顺序/并行工具、半截流式响应及重复副作用设计合成样例。
5. 产出验收矩阵、费用账本和备用方案验证计划。
将每项标为代码已核实、带日期官方文档支持、工程推断或仍未知。

Google：11 月 2 日 Gemini API 更新记录 · Google：Gemini 3.8 Flash 迁移清单 · Google：Gemini 3.6 与 3.5 Flash-Lite 参数变化 · Google：API key、项目与凭据边界