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

> 遇到 gemini-3-pro-preview 找不到或 404 NOT_FOUND？Gemini 3 Pro Preview 已于 2026 年 3 月 9 日下线。本文给出替代模型、Vertex AI 修复方法和可直接复制的迁移代码。

- Source: https://www.aifreeapi.com/zh/posts/gemini-3-pro-preview-not-found
- Language: zh
- Published: 2026-03-19
- Updated: 2026-03-19
- Publisher: AI Free API (https://www.aifreeapi.com)

如果你看到 `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` 找不到 | 你仍在调用已经退役的旧模型 ID | 改成 `gemini-3.1-pro-preview` |
| AI Studio 里旧提示词突然失效 | 保存的提示词仍绑定旧模型 | 打开提示词并改为 `gemini-3.1-pro-preview` |
| Vertex AI 改了模型名还是失败 | 你只改了模型名，没有改 location | 设置 `GOOGLE_CLOUD_LOCATION=global` |
| SDK 或封装层仍然报旧错误 | 某个隐藏配置还在引用旧模型 | 全局搜索 `gemini-3-pro-preview` |
| 你不想再押注新的 preview 模型 | 你需要一个更稳的 Pro 级回退方案 | 改用 `gemini-2.5-pro` |
| 你准备改成 `gemini-3-pro-image-preview` | 这是图像模型，不是文本 Pro 的替代 | 除非你本来就在做图像生成，否则不要这么改 |

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

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

![展示 2026 年 2 月到 3 月 Gemini 3 Pro Preview 下线过程的时间线图](https://www.aifreeapi.com/posts/zh/gemini-3-pro-preview-not-found/img/shutdown-migration-timeline.png)

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

| 日期 | 发生了什么 | 为什么重要 |
|---|---|---|
| 2026 年 2 月 19 日 | Google 发布 [`gemini-3.1-pro-preview`](https://ai.google.dev/gemini-api/docs/changelog) | 新替代模型先上线 |
| 2026 年 2 月 26 日 | Google 宣布 [`gemini-3-pro-preview` 将于 3 月 9 日下线](https://ai.google.dev/gemini-api/docs/changelog) | 正式迁移通知出现 |
| 2026 年 3 月 6 日 | Google 在[官方论坛公告](https://discuss.ai.google.dev/t/migrate-from-gemini-3-pro-preview-to-gemini-3-1-pro-preview-before-march-9-2026/127062)中提醒 `-latest` 别名用户将切到 3.1 | 一些封装工具在正式下线前就开始变化 |
| 2026 年 3 月 9 日 | Google 在 [deprecations 页面](https://ai.google.dev/gemini-api/docs/deprecations)中标记旧模型已关闭，并在 [release notes](https://ai.google.dev/gemini-api/docs/changelog)中说明旧 Pro Preview 线已指向 Gemini 3.1 Pro Preview | 这一天之后，旧 ID 已不再是安全目标 |

当前的 [models 页面](https://ai.google.dev/gemini-api/docs/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`

![比较 Gemini 3.1 Pro Preview 直接替代路径与 Gemini 2.5 Pro 稳定回退路径的决策图](https://www.aifreeapi.com/posts/zh/gemini-3-pro-preview-not-found/img/replacement-decision-board.png)

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

| 你的真实目标 | 建议模型 | 原因 |
|---|---|---|
| 保持在 Gemini 3 的官方继任路径上 | `gemini-3.1-pro-preview` | 这是 Google 为旧 Pro Preview 指定的直接替代 |
| 想继续使用 Pro 级能力，但尽量减少新的 preview 风险 | `gemini-2.5-pro` | 它仍处于活跃状态，是更稳妥的回退路线 |
| 你做的是图像生成/编辑 | `gemini-3-pro-image-preview` 或其他图像模型 | 这是单独的图像模型线，不是文本 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 对比](/zh/posts/gemini-3-1-pro-vs-gemini-2-5-pro)。但对当前这个“找不到模型”的问题来说，重点不是理论对比，而是先做出正确迁移选择。

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

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

| 模型名 | 它是什么 | 什么时候该用 |
|---|---|---|
| `gemini-3-pro-preview` | 已退役的旧文本 Pro Preview 模型 | 现在不要再用 |
| `gemini-3.1-pro-preview` | 旧 Pro Preview 的当前继任模型 | 你要继续走 Gemini 3 Pro 路线时使用 |
| `gemini-2.5-pro` | 活跃中的 Pro 级稳定回退方案 | 你更重视稳定性时使用 |
| `gemini-3-pro-image-preview` | 图像生成模型 | 只在图像生成或图像编辑工作流中使用 |

最常见的误改就是从 `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 指南](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/get-started-with-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，建议按这个顺序做迁移，能减少很多来回试错：

| 步骤 | 要检查什么 | 为什么这样排 |
|---|---|---|
| 1 | 先把 `gemini-3-pro-preview` 改成 `gemini-3.1-pro-preview` 或 `gemini-2.5-pro` | 先移除退役模型 |
| 2 | 全局搜索代码仓库和配置面 | 防止隐藏引用继续触发旧错误 |
| 3 | 如果用 Vertex AI，改成 `GOOGLE_CLOUD_LOCATION=global` | 这是改名后最常见的第二层故障 |
| 4 | 用最小请求做一次验证 | 先确认迁移链路打通 |
| 5 | 更新 AI Studio 提示词、截图与 runbook | 防止团队后续再次带回旧写法 |
| 6 | 再对比 3.1 Preview 与 2.5 Pro 的真实任务表现 | 决定是否要把 3.1 提升为默认模型 |

“最小请求验证”这一步非常重要。不要一上来就用最复杂的旧生产请求去测试迁移。先发一个最小化 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：改完模型名后仍报错，应该怎么排查

![展示更换模型名后仍然报错时排查顺序的决策树](https://www.aifreeapi.com/posts/zh/gemini-3-pro-preview-not-found/img/post-migration-troubleshooting-map.png)

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

### 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 错误排查完全指南](/zh/posts/gemini-api-error-troubleshooting-guide)。

另一个很实用的原则是：一旦发生模型生命周期变更，不要再拿“我之前那套旧请求明明能跑”为唯一参照。此时真正应该对齐的是当前官方文档。对于这个问题来说，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 超时修复指南](/zh/posts/gemini-3-1-pro-timeout-fix)。

## 常见问题

**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`，再排查其他问题。