Gemini API 模型 ID 集中配置

Gemini API 的模型 ID 只应写在配置一处，并在启动时校验可用性：模型会被自动路由（如 2.5-pro 到 3.8-flash）或按日关停，散落各处的字符串必然改漏。（核验 2026-11-05，F29、F31）

一、Gemini API 模型 ID 集中配置：问题不是写在哪，而是改名时要改几处

一个真实的排查过程：线上突然开始按更贵的费率计费，代码没动过。翻了半小时才发现，三个月前写死的 gemini-2.5-pro 被自动路由到了 gemini-3.8-flash（F29）——而团队里没人知道那个字符串还在哪些文件里。

把时间线拉长看，这个隐患是必然发生的：官方会按日关停 preview（最近一批是 November 17, 2026，F31），也会把老模型路由到接替模型（F29、F30）。只要模型 ID 散落在代码、脚本、文档、测试夹具里，每次变动都是一次全员搜索。

所以这一节要解决的不是「怎么调模型」，而是怎么让模型 ID 只有一个出处，并且在启动时就被验证。

二、集中配置与降级链：最小可运行示例

思路三段：配置里只写一份链；启动时用可用模型集合校验；运行时取链上第一个可用的。

## EXPECT: 主模型 gemini-4-argon 可用=True | 降级链 gemini-3.8-flash→gemini-3.5-flash-lite | 生效模型=gemini-4-argon
CHAIN = ["gemini-4-argon", "gemini-3.8-flash", "gemini-3.5-flash-lite"]
AVAILABLE = {"gemini-4-argon", "gemini-3.8-flash"}

def pick(chain, available):
    for m in chain:
        if m in available:
            return m
    raise RuntimeError("降级链全部不可用，应在上线前发现")

active = pick(CHAIN, AVAILABLE)
assert active == CHAIN[0]
assert pick(CHAIN, {"gemini-3.5-flash-lite"}) == CHAIN[2]
print(f"主模型 {CHAIN[0]} 可用={CHAIN[0] in AVAILABLE} | 降级链 {CHAIN[1]}→{CHAIN[2]} | 生效模型={active}")

AVAILABLE 在这里是示意集合，真实值来自 GET /v1beta/models（F73）——启动时拉一次，比在生产里踩 404 便宜得多。

关键在最后那个 raise：链上全部不可用时必须报错，不能返回空字符串或 None。一个会静默返回空模型的降级链，比没有降级链更危险。

三、解释与边界：三处必须写、两处不要写

必须写进配置的三处，其实是一处加两个伴生物。 一是模型 ID 本体；二是每条模型的用途标签（主链推理、降级、离线批处理）；三是它的价格档位——因为计费按被路由到的模型算（F29），配置里没有价格档，账单异常时你无法快速判断是哪一环变贵了。

不要写进代码的两处。 一是测试夹具里重复抄一份模型名，夹具应该从配置读；二是文档与注释里的示例 ID，一旦抄进正文，半年后就是「照着文档写却报 404」的源头（本教程因此把 ID 集中放在这一节讲，其他节只写语义）。

降级链的顺序不是拍脑袋。 顺序应体现「贵而强 → 便宜而够用」的梯度：主链用旗舰，第一降级用主力 Flash，第二降级用 Flash-Lite。这样在旗舰不可用时，你损失的是质量而不是可用性；反过来把 Lite 放第一降级，等于一出事就悄悄降质。

边界。 本教程不提供「模型不可用时自动切到别家厂商」的方案，也不讨论多区域容灾——那属于基础设施层，且各家的错误语义不同，混在一起会把问题搅乱。

四、预期输出与异常分支

真跑输出：

主模型 gemini-4-argon 可用=True | 降级链 gemini-3.8-flash→gemini-3.5-flash-lite | 生效模型=gemini-4-argon

四种分支。主模型不可用：把 AVAILABLE 改成只含 gemini-3.8-flash，active 会落到第一降级，此时必须打告警日志——降级是异常态，不是正常态。整条链都不可用：抛 RuntimeError，这是启动阶段该失败的情况，不要留到请求时。链里写了一个不存在的 ID：pick 不会报错，它只是永远跳不过去，所以启动校验要单独比对「链上每个 ID 都存在于 AVAILABLE」，而不是只比第一个。配置里两个模型同价同档：说明配置冗余，删掉一个，否则路由时你分不清用的是哪个。

五、判据卡：模型改名时必须改哪几处

六、来源与核验

• https://aistudio.google.com/docs/deprecations.md（核验 2026-11-05，F29、F30、F31、F71）
• https://aistudio.google.com/api-reference/models.md（核验 2026-11-05，F73）
• https://aistudio.google.com/docs/pricing.md（核验 2026-11-05，F33、F34）

模型 ID 与关停日属变动最快的一档，复核周期一个月，见 1.3。本节示例里的三个模型 ID 只作结构演示，实际取哪三个由你的业务决定，且必须以官方模型页的徽章为准（F70）。

七、动手试

1. 把 AVAILABLE 改成只含 gemini-3.5-flash-lite，重跑。预期 生效模型=gemini-3.5-flash-lite；验收标准是你说清「这种情况该打什么级别的日志」。
2. 把 CHAIN 里插一个不存在的 gemini-9-fake，重跑。预期输出不变——这暴露一个漏洞；验收标准是补一行启动校验，让链上每个 ID 都必须存在于 AVAILABLE。
3. 打开你自己的项目，全局搜一次模型名，数一下出现在几个文件里。验收标准：给出数字与文件清单；超过一处就说明还没集中，下一步是把它们收进配置并加启动校验。