Gemini API 模型怎么选

Gemini API 的模型分 Stable 与 Preview 两类，官方模型页逐个打徽章；Preview 会按弃用页公布的关停日下线，选型要同时看徽章和关停日。（核验 2026-11-05，F70、F71）

一、Gemini API 模型怎么选：问题不是哪个最强，而是哪个明天还在

从一篇博客抄来 gemini-3.1-pro-preview，代码跑了两周，某天开始报 404。你回头找那篇文章，它还写着「推荐用这个」。

模型选型的真实难点从来不是「哪个效果最好」，而是哪个下个月还在。官方给了两个可直接查的判据，可惜大部分人只看第一个。

判据一：徽章。 官方 Models 页给每个模型打 Stable 或 Preview（F70）。这个名字很直白：Stable 是稳定版，Preview 是预览版。两者都能调，但只有前者会跟着大版本走完整生命周期。

判据二：关停日。 弃用页（deprecations）逐条列 Model / Release date / Shutdown date / Recommended replacement 四列（F71）。近期已经排上日程的有：November 17, 2026 一批 preview（3.1-flash-tts-preview、3.1-flash-live-preview、2.5-flash-native-audio-preview-12-2025 等，F31）；March 15, 2027 的 2.5-flash-image、May 7, 2027 的 3.1-flash-lite、May 14, 2028 的 embedding-001（F32）。

还有一个官方注脚必须看清：表里的 shutdown date 是最早可能的日期，不是承诺那天一定关（F71）。所以日期到了没关，不代表你可以不管；日期没到就关，也不是官方违规——它会提前通知，但通知发在变更日志里，不看就错过。

二、模型筛选：最小可运行示例

把两份判据合成一个筛选函数：徽章决定「能不能上生产」，关停日决定「还能用多久」。

## EXPECT: 可用于生产 2 个：gemini-4-argon、gemini-3.8-flash | Preview 1 个：gemini-3-flash-preview | 临近关停 1 个：gemini-3.1-flash-tts-preview
MODELS = [
    {"id": "gemini-4-argon", "badge": "Stable", "shutdown": None},
    {"id": "gemini-3.8-flash", "badge": "Stable", "shutdown": None},
    {"id": "gemini-3-flash-preview", "badge": "Preview", "shutdown": None},
    {"id": "gemini-3.1-flash-tts-preview", "badge": "Preview", "shutdown": "2026-11-17"},
]

def verdict(m, cutoff="2027-01-01"):
    if m["shutdown"] and m["shutdown"] < cutoff:
        return "临近关停"
    return "可用于生产" if m["badge"] == "Stable" else "Preview"

groups = {}
for m in MODELS:
    groups.setdefault(verdict(m), []).append(m["id"])
order = ["可用于生产", "Preview", "临近关停"]
out = " | ".join(f"{k} {len(groups[k])} 个：{'、'.join(groups[k])}" for k in order if k in groups)
assert verdict(MODELS[3]) == "临近关停"
assert groups["可用于生产"] == ["gemini-4-argon", "gemini-3.8-flash"]
print(out)

MODELS 里的四条是本教程抄下来的片段，不是完整清单——真实清单要调 GET /v1beta/models 拿（F73），或者直接看官方模型页。这段代码的价值在于判断顺序：先看关停日，再看徽章。反过来会让一个下周关停的 preview 被判成「Preview，可用」。

三、解释与边界：三条容易搞混的线

第一条，deprecation 不等于 shutdown。 官方对这两个词的定义是分开的：deprecation 是「宣布不再提供支持」，shutdown 是「彻底关停、端点不可用」（F71）。所以看到「已弃用」不要慌，但也别当没事——弃用到关停之间就是你改代码的窗口。

第二条，能调通不代表能上生产。 Preview 模型今天能调，明天可能改 schema，后天可能整体下线。判断标准不是「我的测试过了」，而是「我能不能接受它随时变」。这条判据卡下面会展开。

第三条，免费层能不能用是另一个维度。 旗舰模型 Argon 在价格页明确标 Not available（F35），而 3.8 Flash 标 Free of charge（F72）。选型时把「我想要强模型」和「我想先在免费层验证」分开看，否则会得到「选了 Argon 却跑不起来 demo」这种结果，见 3.3。

边界。 本教程不给模型排行榜，也不评价哪个模型「更聪明」——那类结论三个月就过期，而且各家评测口径不同。这里只给「怎么判断一个模型 ID 现在能不能用、还能用多久」。两个都稳定可用时差多少钱，不在本节，见 3.3。

四、预期输出与异常分支

真跑输出：

可用于生产 2 个：gemini-4-argon、gemini-3.8-flash | Preview 1 个：gemini-3-flash-preview | 临近关停 1 个：gemini-3.1-flash-tts-preview

三类分支。把 cutoff 设成「今天」：所有已排关停的模型都会进「临近关停」，这是上线前体检该用的口径。关停日写成 2026/11/17：字符串比较会失真（斜杠与连字符混用），程序不报错但判断错，所以日期统一用 YYYY-MM-DD。清单里出现了一个你从没见过的 ID：不要猜它是什么，去模型页查徽章，查不到就说明它已经下线了。

还有一类不算异常但常被忽略：模型页会出现「同一个家族多个版本」的情况（3.6 Flash、3.5 Flash-Lite、3.1 Flash-Lite 都标 Stable，F70）。徽章只回答「稳不稳」，不回答「该选谁」——后者要看你的任务类型和成本，见 3.3。

五、判据卡：preview 能不能上生产

该这么做	不该这么做
生产环境只用 `Stable` 徽章的模型	因为「效果更好」把 preview 写进主链路
上线前查一次弃用页，登记关停日	等报 404 才发现模型下线
preview 只用于验证，且能随时换回	把 preview 的 schema 当成稳定契约
日期统一 `YYYY-MM-DD` 再比较	斜杠与连字符混用做字符串比较
看徽章也看关停日，两处一起	只看到 Stable 就以为永远不会变

六、来源与核验

https://aistudio.google.com/docs/models.md（核验 2026-11-05，F70）
https://aistudio.google.com/docs/deprecations.md（核验 2026-11-05，F31、F32、F71）
https://aistudio.google.com/api-reference/models.md（核验 2026-11-05，F73）
https://aistudio.google.com/docs/pricing.md（核验 2026-11-05，F35、F72）

模型与关停日属于变动最快的一档事实，复核周期一个月，下次复核排在 2026-11-16（早于 11-17 那批关停），见 1.3。

七、动手试

把 MODELS 里 gemini-3.1-flash-tts-preview 的 shutdown 改成 None，重跑。会先在第 56 行抛 AssertionError——那行断言把它写死成「临近关停」。把该行改成 assert verdict(MODELS[3]) == "Preview" 再跑，输出里它会从「临近关停」移到「Preview」；验收标准是你能说出「关停日缺失时，函数为什么把它当成可用」这个漏洞该怎么补。
把 cutoff 改成 "2026-11-06"，重跑。预期所有带历史关停日的模型都进「临近关停」；验收标准是说明这个口径适合上线前体检、不适合日常选型。
打开官方模型页，找出你正在用的模型徽章，再去弃用页确认它有没有关停日。验收标准：写下两行——徽章是什么、关停日是哪天（没有就写「未公布」）；有一行写不出来，就说明你还没验证过它。