12 月前要处理的 Gemini 模型迁移
Gemini 2.5 Pro、Flash 和 Omni 1.1 的自动路由即将变化，Embedding 2 Preview 则已切换。按日期区分替换模型与同空间更名，安排协议和业务验证。
如果应用还在使用 Gemini 2.5 Pro、2.5 Flash 或 Omni 1.1 Flash，11 月值得安排一次迁移检查。Google 已公告，12 月起旧模型名将陆续自动路由到后继型号。请求名字还能发出去，不代表参数、工具行为和任务结果会保持原样。
与此同时，Embedding 2 Preview 到正式版的切换已经在 11 月 6 日生效，官方明确说明使用相同的向量空间。这是另一类迁移，不能与聊天模型替换混为一谈。
以下时间与范围于 2026 年 11 月 11 日核对 Gemini 更新记录和弃用页面。它们描述 Google 官方 Gemini API；第三方服务是否采用相同日期与映射，需要另外确认。本文没有运行带认证的迁移请求，也没有验证任意聚合平台会自动采用同一策略。
先把已经发生和即将发生的变化分开
| 模型名 | 官方公告的后续路径 | 生效日期 | 写作当天的状态 |
|---|---|---|---|
gemini-embedding-2-preview | 路由至 gemini-embedding-2 | 2026-11-06 | 已生效，建议更新模型字符串 |
gemini-2.5-pro | 自动路由至 gemini-3.8-flash | 2026-12-01 | 未来变化，应提前验证 |
gemini-2.5-flash | 自动路由至 gemini-3.5-flash-lite | 2026-12-01 | 未来变化，应提前验证 |
gemini-omni-1.1-flash | 自动路由至 gemini-omni-1.2-flash | 2026-12-03 | 未来变化，应提前验证 |
弃用页还限定 2.5 Pro 与 Flash 的当前 API 访问面向过去活跃使用过它们的现有用户，且它们已不能在 Google AI Studio 中选择。不要把未来路由日期理解为新账号仍可自由接入旧型号，也不要把这里的四个名称套到所有 preview、日期版或第三方别名上。
客户端显示名、请求中的模型名和服务端映射可能是三层配置。先读模型 ID、别名和能力的区别，再找到应用真正使用的那一层。
2.5 的接替型号，参数要跟着检查
Pro 路由到 Flash，Flash 路由到 Flash-Lite，这次公告没有沿用“同系列同档位”的直觉。目标名称以原公告为准，不要自行猜一个看起来更对应的后继型号。
官方 3.8 Flash 迁移指南与 3.5 Flash-Lite 迁移章节列出了需要处理的差异：
- 思考设置。 用目标模型支持的
thinking_level取代旧thinking_budget，不能把一个数字直接当作新枚举。3.8 Flash 不支持minimal，3.5 Flash-Lite 的默认设置和任务建议也不同。 - 旧参数与预填消息。 按指南移除弃用的
temperature、top_p、top_k，以及不支持的candidate_count和预填 model turn。3.6 指南说明部分采样字段当前被忽略，未来型号可能报错；不能笼统声称它们今天一律返回 400。 - 工具往返。 核对 SDK、函数调用结构和
thought_signature的保留。只测第一条文字回复，无法覆盖工具结果回传后的验证。
这些是官方原生接口的迁移项。应用若经 OpenAI 兼容层或其他 SDK 适配，字段可能在中间被转换；应该检查实际发送的请求，而不是给所有协议盲加同一字段。三种 API 格式的说明可以作为前置阅读。
一个可用的验收至少包括：普通文字回复、完整工具往返、应用需要的结构化输出，以及一段依赖前文的对话。图片或文件输入也要用自己的公开样本覆盖。每项记录成功条件与实际结果，别只写“连接成功”。
这一次 Embedding 为什么不用重建索引
11 月 6 日条目明确写出，gemini-embedding-2 与对应 preview 使用相同 API schema、价格和 embedding space，因此这次不需要额外代码修改或向量重建。建议更新的模型字符串仍然要处理。
这个结论的依据是厂商对这两个具体模型版本的兼容声明，不是“名字差不多”，也不是“维度相同”。换到其他向量模型时，即使长度一样，也不能默认旧文档向量与新查询向量可直接比较。
迁移前保留模型身份、维度、查询和文档侧配置，以及少量公开问题的已知检索结果。更新字符串后复查这些记录；若实际请求绕到了另一模型、配置改变或结果不符，就不能继续套用官方的同空间结论。
遇到维度报错或旧资料召回异常，可按Dify 的模型、缓存与旧索引检查缩小范围；通用接入字段见 Embeddings API。不要因为这次官方迁移无需重建，就删除自己对其他模型更换的验证流程。
用 11 月完成一次小范围切换
先在项目里找出引用位置。下面命令只列匹配文件名，避免直接把可能含配置细节的整行打印出来；它不发网络请求，也不修改文件：
rg -l --hidden \
-g '!node_modules/**' -g '!.git/**' -g '!*.lock' -g '!.env*' \
'gemini-2[.]5-(pro|flash)|gemini-omni-1[.]1-flash|gemini-embedding-2-preview|thinking_budget' .
再查部署环境、后台摘要任务、工作流节点、备用模型和服务端映射；它们未必出现在代码搜索里。密钥管理系统只核对相关配置，不把凭据复制到迁移清单中。
在测试环境显式使用目标型号，逐项验证后再逐步切换。保留可用的替代配置，但不要把即将被自动路由的旧名称当成长期回退方案。Omni 用户还要分别验证生成、编辑和延长，具体差异见对话式视频创作说明。
通过 Nbility 使用时，从模型与 ID 文档确认当前目录，再核对服务映射；Google 公告不能替本站作上线承诺。完成这份清单后，12 月的变化才会从被动等待变成可以检查的迁移。
