Gemini 3 Pro Preview 找不到：下线错误快速修复指南（2026）

如果你看到 gemini-3-pro-preview not found、model not found 或 404 NOT_FOUND，最核心的答案其实很直接：Google 已在 2026 年 3 月 9 日下线 Gemini 3 Pro Preview，所以旧模型 ID 现在已经不是可继续使用的默认目标。官方给出的直接替代是 gemini-3.1-pro-preview。如果你已经把模型名改掉，但在 Vertex AI 上依然报错，下一步最该检查的不是 API Key，而是区域配置，因为 Google 目前把 gemini-3.1-pro-preview 标记为 仅支持 global 端点。

这篇文章会把三个最容易混在一起的问题拆开讲清楚：旧模型已经退役、替代模型该怎么选，以及为什么你改完模型名之后仍然可能继续失败。如果你时间很紧，先看下面的快速修复表和迁移清单，通常就够了。

要点速览：快速修复表

这里最重要的一点是：这已经首先是一个模型生命周期问题，不是一个等待几分钟就会恢复的临时故障。继续重试旧模型不会让它重新可用。

为什么现在会出现 gemini-3-pro-preview 找不到

Google 的官方信息是明确的，只是分散在 models 页面、deprecations 页面、release notes 和论坛公告里，所以很多读者仍会把它误判为权限问题或平台故障。按实际迁移顺序看，事情是这样的：

当前的 models 页面已经直接显示警告：Gemini 3 Pro Preview 已于 2026 年 3 月 9 日下线，并要求迁移到 Gemini 3.1 Pro Preview。所以如果你的代码、模板或提示词里仍然出现旧字符串，报错本身就是符合预期的行为。

另一个很容易让人误解的点是：这并不代表你的项目、API Key 或 AI Studio 历史被删除了。Google 在官方论坛回复里明确说过，项目、密钥和保存的提示词都会保留，真正会报错的是仍然指向旧模型的引用。所以很多人感受到的是“环境坏了”，实际上问题是“引用没迁完”。

正确替代方案：gemini-3.1-pro-preview 还是 gemini-2.5-pro

很多页面只会告诉你“把模型名改成 3.1”。这对一部分人是对的，但对所有人并不都对。这个关键词背后的真实决策是：你到底是想继续走 Gemini 3 的最新 Pro 路线，还是想尽快恢复一个更稳定的 Pro 级工作流。

所以大多数读者真正需要的是下面这个判断：

• 如果你当初选择 Gemini 3 Pro Preview，就是为了最前沿的 Gemini 3 推理与 Agent 路线，那就迁到 gemini-3.1-pro-preview。
• 如果你的主要目标只是“尽快恢复一个还能稳定跑的 Pro 模型”，那 gemini-2.5-pro 反而更保守、更省心。

如果你想看更完整的差异分析，可以继续读我们的 Gemini 3.1 Pro vs Gemini 2.5 Pro 对比。但对当前这个“找不到模型”的问题来说，重点不是理论对比，而是先做出正确迁移选择。

不要把这些相似模型名称搞混

Gemini 的模型命名现在已经足够复杂，很多迁移失败并不是因为代码不会写，而是因为开发者改到了“看起来很像，但其实不是同一路线”的模型名称。

最常见的误改就是从 gemini-3-pro-preview 直接跳到 gemini-3-pro-image-preview，因为名字看起来接近。但如果你的工作流是聊天、编程、分析或推理，这个改法就是错的。

第二类常见问题来自封装层里的“latest”“pro 默认模型”这类抽象名称。它们平时方便，但到了迁移期就容易让你看不清底层实际落到哪个模型 ID。排障阶段请尽量改成显式模型名，不要继续依赖模糊别名。

按使用场景修复：API、AI Studio、Vertex AI 与封装层

真正的修复方式，要看旧模型字符串现在藏在哪一层。

Gemini API / SDK 代码

最直接的情况就是代码里写死了旧模型名。把它替换掉即可：

python

model = "gemini-3-pro-preview"

# 官方直接替代
model = "gemini-3.1-pro-preview"

# 更稳妥的回退
model = "gemini-2.5-pro"

Google AI Studio

如果旧提示词在 2026 年 3 月之后突然跑不动，第一反应不应该是“项目没了”。更常见的情况是：这个提示词仍然绑定 gemini-3-pro-preview。打开提示词，检查模型选择器并改成 gemini-3.1-pro-preview。论坛里 Google 的官方回复也明确说过，保存的项目和提示词不会消失，真正出问题的是模型引用。

如果你的团队多人共用 AI Studio，还要顺手更新内部说明文档、截图和 onboarding 页面。很多迁移问题不是技术没修，而是新成员继续照着旧截图操作，把旧错误重新带回来。

Vertex AI

这是迁移后的第二大坑。很多人已经把模型名改成 gemini-3.1-pro-preview，但请求仍然失败，于是误以为“新模型也坏了”。Google 当前的 Vertex AI Gemini 3 指南写得很清楚：gemini-3.1-pro-preview 只支持 global endpoint。

你的环境变量至少要像这样：

bash
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_USE_VERTEXAI=True

如果 location 仍是区域端点，即使模型名已经改对，也可能继续失败。

第三方封装、模板与隐藏默认值

最麻烦的一层通常不是主代码，而是散落在其他地方的默认配置：

• .env 文件
• SDK 封装层默认模型
• CI/CD 密钥与环境变量
• Prompt 模板
• 测试夹具
• 管理后台数据库配置
• Agent 框架内置默认模型

先做一次全局搜索再说：

bash
rg "gemini-3-pro-preview"

只要还能搜到，就说明还有可能在某条路径里继续调用旧模型。

现有代码库迁移清单

如果你处理的是一个真实项目而不是单文件 Demo，建议按这个顺序做迁移，能减少很多来回试错：

“最小请求验证”这一步非常重要。不要一上来就用最复杂的旧生产请求去测试迁移。先发一个最小化 prompt，如果它能返回结果，就说明模型已经可达，之后再排查参数、上下文、超时或封装层问题会更清楚。

可直接复制的迁移示例

下面这些示例尽量保持“只改必要部分”。做模型迁移时，最容易犯的错误就是顺手把别的逻辑也一起重构，结果你根本分不清到底是哪一步把问题修好了。

Python — Gemini API

python
from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="用简单的话解释一下 TLS 握手。"
)

print(response.text)

如果你决定走更稳妥的回退路线：

python
from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="用简单的话解释一下 TLS 握手。"
)

print(response.text)

Node.js — Gemini API

javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-3.1-pro-preview",
  contents: "用简单的话解释一下 TLS 握手。"
});

console.log(response.text);

Vertex AI — Gemini 3.1 Pro Preview

python
from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="总结一下这段设计评审。"
)

print(response.text)

这段代码的前提是你的 Vertex AI 环境已经设置为 GOOGLE_CLOUD_LOCATION=global。

curl — 直接替换模型名

bash
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "用简单的话解释一下 TLS 握手。" }
        ]
      }
    ]
  }'

迁移规则其实很朴素：先改模型名，再复测。只有在改完模型名之后仍然失败，才应该继续检查端点、API 版本或封装层行为。

Troubleshooting：改完模型名后仍报错，应该怎么排查

如果你已经把模型名改掉，请不要再把所有后续错误都当成“模型不存在”的同一种问题。到这一步时，你大概率已经进入了新的排障分支。

1. 端点或 location 仍然不对

对于 Vertex AI，这仍然是最高概率问题。Google 当前文档明确要求 gemini-3.1-pro-preview 走 global 端点。如果你还保留区域 location，请先修这一点。

2. 某个旧提示词、模板或隐藏配置仍在引用退役模型

这在多层配置系统里非常常见。主代码改了，但后台配置、任务队列、Agent 默认模型或测试夹具没改，结果旧字符串仍然会从某条路径冒出来。

3. 你换到了错误的模型家族

如果你把文本推理工作流改成了 gemini-3-pro-image-preview，那不是“替代成功”，而是模型家族换错了。对聊天、编程和分析任务来说，这是错误方向。

4. 你现在其实在排查另一种错误

一旦模型名正确，之后出现的报错可能已经完全不是“退役模型”问题了：

• 404 NOT_FOUND 也可能来自错误请求面或错误资源路径
• 400 INVALID_ARGUMENT 常常意味着参数或请求体有问题
• 503 UNAVAILABLE 则是暂时性服务负载问题，不是生命周期问题

如果你改名之后，错误类型发生了变化，这往往反而是好事，说明你已经跨过“旧模型不存在”这一层了。之后的广义 API 故障排查可以继续看我们的 Gemini API 错误排查完全指南。

另一个很实用的原则是：一旦发生模型生命周期变更，不要再拿“我之前那套旧请求明明能跑”为唯一参照。此时真正应该对齐的是当前官方文档。对于这个问题来说，models 页面、deprecations 页面和 Vertex AI 指南，都是比旧教程更可靠的基准。

是否应该直接升级到 3.1 Pro Preview

如果你当初之所以用 Gemini 3 Pro Preview，就是因为你要追 Gemini 3 这条最新 Pro 推理路线，那么迁到 gemini-3.1-pro-preview 就是对的。Google 的 deprecations 页面和论坛公告在这一点上非常一致。

但这并不意味着所有团队都必须把 3.1 当成唯一答案。如果你的真实目标是“尽快恢复一个可靠的 Pro 级工作流”，那 gemini-2.5-pro 会是更保守的选择。它不是官方意义上的直接继任者，但却是更容易接受的稳定回退。

所以实际决策可以简单理解成：

• 要走官方最新 Pro 继任路径：选 gemini-3.1-pro-preview
• 要更稳妥的活跃 Pro 回退路线：选 gemini-2.5-pro
• 要图像生成能力：明确选择图像模型，不要靠名字相似误改

如果你迁到 3.1 之后遇到慢响应或超时问题，可以继续看我们的 Gemini 3.1 Pro 超时修复指南。

常见问题

Gemini 3 Pro Preview 是被彻底移除了吗？
是的。Google 官方 deprecations 页面明确写明 gemini-3-pro-preview 已于 2026 年 3 月 9 日关闭。

gemini-3.1-pro-preview 是官方指定替代吗？
是的。无论是 deprecations 表还是 release notes，都把它标成旧 Pro Preview 的替代模型。

AI Studio 会不会把我的项目或提示词删掉？
不会。Google 在官方论坛回复中说明，项目、API Key 和保存的提示词会保留，真正会报错的是仍然引用旧模型的提示词。

为什么我已经改成 3.1 了，Vertex AI 还是报错？
最常见的原因是 location 没改成 global。Google 当前文档就是这样要求的。

我能不能直接改成 gemini-3-pro-image-preview？
不能，除非你本来就在做图像生成。它不是文本 Pro 模型的替代。

如果我不想继续依赖 preview 模型怎么办？
那就用 gemini-2.5-pro。它不是“直接继任”，但通常是更稳妥的当前回退路径。

结论

gemini-3-pro-preview not found 现在已经不是一个模糊问题了。截至 2026 年 3 月 9 日，旧模型已经下线，所以最关键的修复是停止继续调用它。如果你要继续沿着 Gemini 3 Pro 的官方路径走，就改成 gemini-3.1-pro-preview；如果你更在意稳定性，就改用 gemini-2.5-pro。如果你在 Vertex AI 上改完模型名仍然失败，先检查 GOOGLE_CLOUD_LOCATION=global，再排查其他问题。