Gemini 3 Pro Preview 停用迁移指南（含 -latest）
gemini-3-pro-preview 要下架这件事，已经不是“传闻”了。Google 在官方开发者论坛明确公告：2026-03-09 起，Gemini API 与 Google AI Studio（AIS）将停止 Gemini 3 Pro Preview；并建议迁移到 gemini-3.1-pro-preview。同时 2026-03-06 会把 -latest 别名切换到 3.1 预览版。
这篇文章尽量只讲工程动作：要改什么、要测什么、最容易踩哪里。
TL;DR（30 秒读完）
- 停用时间：
gemini-3-pro-preview在 2026-03-09 于 Gemini API + AIS 停用 - 别名变更：
-latest在 2026-03-06 指向gemini-3.1-pro-preview - 迁移目标：
gemini-3.1-pro-preview - 上线前必做：用真实样本做回归（成功率/延迟/成本/结构稳定性），别只跑两条 demo prompt
1. 先把时间线记牢（不然后面全是事故）
- 2026-03-06：
-latest别名将指向gemini-3.1-pro-preview（如果你线上用-latest，这天开始输出行为可能“静默变化”）。 - 2026-03-09：
gemini-3-pro-preview在 Gemini API + AIS 停用（继续调用基本等于等死）。
1.1 一图看懂：时间线表格
| 日期 | 变化 | 你应该做什么 |
|---|---|---|
| 2026-03-06 | -latest 别名切到 gemini-3.1-pro-preview |
生产环境别用 -latest，固定 model name |
| 2026-03-09 | gemini-3-pro-preview 停用 |
完成替换 + 回归 + 降级方案 |
2. 最小迁移：把 model name 换掉，但别把它当成“迁移完成”
最表面的迁移当然是把：
gemini-3-pro-preview
改成gemini-3.1-pro-preview
但真实世界里，迁移失败通常不是因为“字符串没改”，而是因为下面这些：
- 账号/项目 还没被灰度放开（尤其是 CLI/OAuth 等通道）
- 区域端点不对（global vs region）
- 工具链没同步更新模型列表，出现 “model not found / invalid”
- 429（限流）、503（高负载）导致链式任务崩溃
GitHub 上 gemini-cli 的高热 issue 基本把这些坑集齐了：有人能在 Vertex 通道用 3.1，但 API key 或 OAuth 不行；有人模型列表里根本找不到；有人直接报 “publisher model ... was not found or your project does not have access”。
2.1 最小改动示例（仅展示“换 model name”）
Python（伪代码）：
model = "gemini-3.1-pro-preview" # 原来是 gemini-3-pro-preview
resp = client.generate_content(model=model, contents=[{"role": "user", "parts": [{"text": prompt}]}])
JavaScript（伪代码）：
const model = "gemini-3.1-pro-preview"; // 原来是 gemini-3-pro-preview
const resp = await client.models.generateContent({ model, contents });
提示：上面只演示“字符串替换”。真正上线前，你还得确认自己是否用到了函数调用、结构化输出、PDF/媒体输入，以及你所在通道的权限与灰度情况。
3. 强烈建议：生产环境不要用 -latest
官方公告里专门提了 -latest 的切换日期，这很罕见，也很有信号意义。
如果你的生产环境用的是 -latest，等于：
- 你把版本升级权交给了供应方
- 回归测试变成“追着公告跑”
- 出现质量回退时，你很难解释“到底是谁改了系统”
建议做法很简单：生产只用明确的 model name，把 -latest 留给实验环境。
4. 回归测试怎么做才像样（而不是跑两条 prompt 就上线）
Google Cloud 的迁移文档讲得很现实：多数应用迁移代码改动不大，但 prompt 和输出分布可能变化，建议做充分测试。你可以用下面的“轻量但有效”的方案：
4.1 选一组真实样本（别用你最满意的那几个例子）
- 30～100 条线上真实输入
- 覆盖你最常见的失败模式（工具调用、JSON 输出、长文档、边界条件）
4.2 你至少要对这四个指标负责
- 成功率：有没有更多的 timeout / 429 / 503 / notFound
- 延迟：端到端耗时是否变长
- 成本：token 数、重试次数、工具调用次数
- 结构稳定性：JSON/函数调用格式是否更容易跑偏
4.3 给链式任务准备“降级路线”
现实一点：新模型的灰度/配额/负载波动都可能导致不可用。建议至少准备：
- 主模型：
gemini-3.1-pro-preview - 备选模型：你当前生产里最稳的 GA 型号（按业务权衡效果/成本）
5. 迁移时最容易被忽略的 breaking changes（Vertex 侧文档给了清单）
如果你在 Vertex AI 上跑，官方迁移文档列了一串“看起来很细、但会让你翻车”的点（我只挑最容易出事故的几类）：
- PDF 处理：Gemini 3 Pro 及之后，对扫描 PDF 默认不走 OCR（你以前靠 OCR 的流程可能直接废掉）
- 思考/推理参数：3 Pro 之后用
thinking_level，而不是旧的thinking_budget - usage metadata 口径：PDF token 统计归类变化（如果你做成本归因，会出现账对不上）
- 媒体分辨率与 token 化策略变化：图片/PDF/视频的默认分辨率与 token 成本不同（会影响预算与限流）
- 安全过滤默认值：如果你依赖默认安全策略，迁移后可能出现“同样输入，旧模型放行，新模型拦截/反之”
这类点不需要你现在就全改，但你至少要知道：迁移不只是换名字，有些行为是“会变的”。
6. 常见报错与处理思路（从社区真实案例里来）
6.1 “Model was not found / invalid”
常见于工具链模型列表未更新、或者还没灰度开通。GitHub 上有人用 CLI 指定 -m gemini-3.1-pro-preview，但 UI 列表没有；也有人直接报 invalid。
处理思路：
- 确认你调用通道（API key / OAuth / Vertex）是否具备权限
- 等灰度（官方明确说是 phased rollout）
- 工具升级到支持新模型的版本（或直接按 model name 调用，而不是依赖列表）
6.2 404 NOT_FOUND（旧模型也可能遇到）
早期也有人在 CLI 里选 gemini-3-pro-preview，结果提示没权限、再报 404，最后发现是本地状态缓存导致，清理后恢复。
处理思路：
- 清理本地旧缓存/旧配置，重新鉴权
- 检查项目与区域端点配置
6.3 429 / 503 / “high demand”
如果你是 agentic workflow（多轮工具调用），这类错误会放大：一次失败可能触发一串重试，成本和延迟一起炸。
处理思路：
- 明确重试上限 + 退避策略
- 超时兜底：失败就降级到更稳的 GA 型号
- 关键链路做熔断，不要无限重试
7. 你现在应该做的 checklist（写给要对线上负责的人）
- 代码层面：替换所有
gemini-3-pro-preview调用点 - 版本层面：生产环境去掉
-latest，只用明确型号 - 评测层面：做一轮离线回归（成功率/延迟/成本/结构稳定性）
- 运行层面：准备降级模型与熔断策略
- 治理层面：把“模型版本升级”当成发布事件，纳入变更流程
参考链接
- 官方公告：Gemini 3 Pro Preview 停用与迁移（含
-latest切换日期）https://discuss.ai.google.dev/t/migrate-from-gemini-3-pro-preview-to-gemini-3-1-pro-preview-before-march-9-2026/127062
- Google Cloud Blog：Gemini 3.1 Pro 上线与可用渠道说明
https://cloud.google.com/blog/products/ai-machine-learning/gemini-3-1-pro-on-gemini-cli-gemini-enterprise-and-vertex-ai
- Vertex AI 迁移文档：breaking changes 与迁移流程建议
https://docs.cloud.google.com/vertex-ai/generative-ai/docs/migrate
- GitHub Issue：gemini-cli 对
gemini-3.1-pro-preview的模型列表/权限/灰度讨论（👍 很多）https://github.com/google-gemini/gemini-cli/issues/19532
- GitHub Issue：CLI 使用
gemini-3-pro-preview的 404 / 权限误判案例https://github.com/google-gemini/gemini-cli/issues/15162
- GitHub Changelog：Gemini 3.1 Pro 在 Copilot 的公开预览（工具精度与 edit-then-test 叙述很典型）
https://github.blog/changelog/2026-02-19-gemini-3-1-pro-is-now-in-public-preview-in-github-copilot/