Gemini 2.5 Flash、2.5 Pro 停用（12月1日）——自动转向 3.5 Flash-Lite、3.8 Flash 后会出错的写法与迁移步骤

Gemini API 中的 gemini-2.5-flash 和 gemini-2.5-pro 将从2026年12月1日起自动转到其他模型。即使不改模型名，请求也能送达，但回答的是新模型，费用也按新模型的单价计算。Google 于2026年11月2日在 Gemini API 的更新日志中公布了这一安排。

根据 Google 发给 AI Studio 用户的邮件，如果只是发送一次文本或图片并收到一个回答，代码可以照常运行。麻烦的是使用函数调用（function calling）、自行构建的对话历史，以及 thinking_budget、temperature 等细项设置的代码。新模型对请求写法的要求更严格，可能以 HTTP 400 错误中止，或者设置被悄悄忽略。本文介绍如何判断自己的代码是否受影响，以及在12月1日之前完成迁移的步骤（2026年11月7日确认）。

1. 有什么变化

根据 Google 的“Gemini deprecations”页面和更新日志，这两个模型的处理如下。两者都已无法在 Google AI Studio 中选择，只有原本就在使用的用户还能通过 API 调用。

出处：Google“Gemini API changelog”（2026年11月2日条目）、“Gemini deprecations”（2026年11月7日确认）。请注意，2.5 Pro 转向的是 Flash 系列，而不是 Pro 系列。

名称相近，但以下模型不在12月1日自动转向的范围内。

表中的停止日期是“最早在这一天”的意思，Google 表示会提前公布确切日期。gemini-2.5-flash 和 gemini-2.5-pro 的自动转向日期已确定为“2026年12月1日”。

1. 2026年11月2日Google 公布变更发布在更新日志中。AI Studio 中已无法选择这两个模型。
2. 现在（2026年11月7日）迁移期可以按自己的节奏改用新模型名并进行测试。
3. 2026年12月1日自动转向使用旧名称的请求由新模型回答，并按新模型的价格计费。
4. 至2026年12月31日 → 2027年1月1日起3.8 Flash 的推广价结束2.5 Pro 转向目标的价格上涨（第4节）。

2. 自己的代码是否受影响（判断表）

这两个新模型遵循自 Gemini 3.6 Flash 和 3.5 Flash-Lite 起引入的请求规则。下面按代码的写法，整理 Google 迁移指南中列出的差异。

出处：Google“What's new in Gemini 3.6 Flash and 3.5 Flash-Lite”“What's new in Gemini 3.8 Flash”，以及 Google 发给 AI Studio 用户的邮件（2026年11月3日）。candidate_count 为 2 以上时返回 HTTP 400 错误出自 Google 的邮件，Gemini 3 及以后不支持出自迁移指南。函数调用中 id 和 name 要对应，迁移指南和邮件中都有说明。3.8 Flash 的迁移指南写的是 call_id，但在 generateContent 中，FunctionResponse 的字段名是 id（API 参考中为可选字段）。

要在代码中找出受影响的地方，最快的办法是字符串搜索。Python、JavaScript 的 SDK 和 REST 的 JSON 写法不同（如 thinking_budget 与 thinkingBudget），所以要用能同时匹配两种写法的模式。

# 受影响的模型名（不含 2.5-flash-lite）
grep -rnE "gemini-2\.5-(flash|pro)([^-]|$)" .

# 会出错或被忽略的设置
grep -rnE "thinking_?[bB]udget|temperature|top_?[pPkK]|candidate_?[cC]ount" .

# 返回函数调用结果的地方
grep -rnE "function_?[rR]esponse|FunctionResponse" .

如果模型名放在配置文件或环境变量中，也要一并搜索。把每处搜索结果对应到表中的某一行，就能知道需要修改多少。

3. 迁移步骤

建议不要等到12月1日，而是自己先改用新模型名，通过测试后再上线到生产环境。如果交给自动转向，所有出问题的地方会在生产环境中一齐暴露。代码示例使用 Google 的 Python SDK（google-genai）的 generateContent。

1. 修改模型名：gemini-2.5-flash → gemini-3.5-flash-lite，gemini-2.5-pro → gemini-3.8-flash
2. 用 thinking_level 指定思考量：删除 thinking_budget，选择适合用途的级别
3. 删除采样设置：temperature、top_p、top_k
4. 修正函数调用的历史：保留 thought_signature，在 FunctionResponse 中填入 id 和 name
5. 停止预先填写回答，并去掉 candidate_count
6. 用较重的输入测试后再切换：运行多次调用工具的处理和长对话，检查错误、回答质量和令牌用量

3-1. 修改模型名

改名称只需改一行，但同一个名称往往出现在多个地方，所以先用第2节的搜索找出全部位置再修改。一旦切换，就按新模型的价格计费。

3-2. 把 thinking_budget 换成 thinking_level

Gemini 2.5 用数值 thinking_budget 指定用于思考的令牌数。新模型改为用级别名称指定的 thinking_level。可选的级别和默认值因模型而异。

出处：Google“Thinking”页面的表及各迁移指南（2026年11月7日确认）。

需要注意的是，2.5 Flash 的转向目标默认是 minimal。2.5 Flash 默认会思考，而 3.5 Flash-Lite 如果不指定，几乎不会思考。Google 的迁移指南表示，大批量的提取、路由、分类用 minimal 即可，但工具调用、代码执行、多步骤推理推荐用 medium 或 high。级别过低时，使用工具的处理可能会中途停下。

from google import genai
from google.genai import types

client = genai.Client()

# 修改前：gemini-2.5-flash
# config=types.GenerateContentConfig(
#     temperature=0.2,
#     thinking_config=types.ThinkingConfig(thinking_budget=1024),
# )

# 修改后：gemini-3.5-flash-lite
response = client.models.generate_content(
    model="gemini-3.5-flash-lite",
    contents=prompt,
    config=types.GenerateContentConfig(
        system_instruction="只输出 JSON。不要写任何开场白。",
        thinking_config=types.ThinkingConfig(thinking_level="medium"),
    ),
)
print(response.text)

如果通过 REST 直接发送 JSON，就把 generationConfig.thinkingConfig 中的 "thinkingBudget": 1024 改为 "thinkingLevel": "medium"。API 参考说明 thinkingLevel 是 Gemini 3 及以后的字段，发给更早的模型会报错。请把模型名和 thinking_level 放在同一次修改中一起改。

从 2.5 的数值预算到级别，没有官方的对应表。先参考下面的标准，再根据回答质量和令牌用量调整。

此标准依据 Google 迁移指南中各级别的用途说明整理。思考的令牌按输出单价计费，所以提高级别，费用也会增加。

3-3. 删除 temperature、top_p、top_k

Google 自 Gemini 3.6 Flash 和 3.5 Flash-Lite 起，已弃用 temperature、top_p、top_k。在目前的新模型上，它们不报错但会被忽略，Google 表示今后的世代会返回 HTTP 400 错误。因为不报错，很容易被忽视。把 temperature 设为 0 以求回答一致的处理，可能会变得不再一致。

Google 推荐的替代方法，是在系统指令中明确写出输出规则（例如“只输出 JSON”“不要写开场白”）。如果需要严格统一格式，就使用结构化输出（指定 JSON 架构的功能）。

Claude API 在较新的模型上也改变了 temperature 的处理方式。同样的思路，请参阅“temperature is deprecated for this model 的原因与解决方法”。

3-4. 修正函数调用的历史

Gemini 3 系列的模型会在响应中返回思维签名（thought signatures），即模型在回答前内部推理的加密表示。如果下一轮不把签名发回去，模型就无法延续之前的推理。在 generateContent 中，签名位于函数调用等 part 的 thoughtSignature 里。

容易出问题的写法，是只用名称和参数重建 model 轮次再加入历史。一旦重建，签名就会丢失。

# ❌ 只用名称和参数重建 model 轮次，thought_signature 会丢失
contents.append(types.Content(role="model", parts=[
    types.Part(function_call=types.FunctionCall(name=call.name, args=call.args))
]))

修正方法是把收到的 content 原样放回历史。另外，在函数的结果（FunctionResponse）中，填入与模型返回的 FunctionCall 相同的 id 和 name。

config = types.GenerateContentConfig(
    tools=[weather_tool],
    thinking_config=types.ThinkingConfig(thinking_level="medium"),
)
contents = [types.Content(role="user", parts=[
    types.Part.from_text(text="波士顿的天气怎么样？")
])]

response = client.models.generate_content(
    model="gemini-3.5-flash-lite", contents=contents, config=config)
call = response.function_calls[0]

# ✅ 模型的轮次，把收到的 content 原样加入（其中包含签名）
contents.append(response.candidates[0].content)

result = get_weather(**call.args)
contents.append(types.Content(role="user", parts=[
    types.Part(function_response=types.FunctionResponse(
        id=call.id,      # 与 FunctionCall 的 id 相同的值
        name=call.name,  # 与 FunctionCall 的 name 相同的值
        response={"result": result},
    ))
]))

response = client.models.generate_content(
    model="gemini-3.5-flash-lite", contents=contents, config=config)
print(response.text)

函数的结果中包含图片等媒体时，不要作为单独的 part，而是放进 FunctionResponse 里（parts）。Google 的“Function calling”页面表示，SDK 会自动处理签名。如果让 SDK 的聊天功能（client.chats）保存历史，就不需要自己传递签名。需要小心的是，把历史保存到自己的数据库等处、每次请求时重新组装的情况。请确认保存格式不会丢掉签名。

API 参考中，finishReason 的取值里有表示缺少签名的 MISSING_THOUGHT_SIGNATURE（Request has at least one thought signature missing）。如果在日志中看到这个值或类似的错误，先怀疑历史的组装方式。

import json

# Interactions API 的函数定义用字典编写（与 generateContent 的 weather_tool 形式不同）
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What's the weather in Boston?",
    tools=[weather_tool_dict],
)
for step in interaction.steps:
    if step.type == "function_call":
        result = get_weather(**step.arguments)
        interaction = client.interactions.create(
            model="gemini-3.8-flash",
            input=[{
                "type": "function_result",
                "name": step.name,
                "call_id": step.id,
                "result": [{"type": "text", "text": json.dumps(result)}],
            }],
            tools=[weather_tool_dict],
            previous_interaction_id=interaction.id,
        )
print(interaction.output_text)

迁移指南还指出，工具调用前的文本导致 Malformed_Function_Call 时的规避方法，在 Function calling 页面的“Workarounds for pre-tool text requirements”一节中。

3-5. 停止预先填写回答，去掉 candidate_count

预先填写回答的开头（让 contents 中最后一个非空的轮次是 model），在新模型上会返回 HTTP 400 错误。Google 的迁移指南也把它列为应避免的写法。

{
  "contents": [
    {"role": "user", "parts": [{"text": "Translate 'Hello world' to Spanish."}]},
    {"role": "model", "parts": [{"text": "Translation:"}]}
  ]
}

如果预先填写是为了去掉开场白或强制以 JSON 回答，就把规则写进系统指令，或使用结构化输出。

response = client.models.generate_content(
    model="gemini-3.5-flash-lite",
    contents="Translate 'Hello world' to Spanish.",
    config=types.GenerateContentConfig(
        system_instruction="只输出译文。不要写任何开场白。",
    ),
)

candidate_count（一次调用返回多个回答的设置）在 Gemini 3 及以后不受支持，设为 2 以上会返回 HTTP 400 错误。需要多个候选时，请分成多次调用。

Google 还为支持技能（skill）的编程代理提供了协助此次迁移的 Gemini API 技能（“Coding agents”）。即使使用它，也请自己对修改后的代码运行测试。

4. 费用如何变化

转向目标的单价，从 2.5 Flash 来看大致相同，从 2.5 Pro 来看更低。不过，3.8 Flash 到2026年12月31日为止是推广价，2027年1月1日起涨价。涨价后，输出仍比 2.5 Pro 便宜，但输入会比 2.5 Pro 贵（提示在 20万令牌以内时）。以下价格均为付费层的标准价格，单位为每 100万令牌的美元。

出处：Google“Gemini Developer API pricing”的 Standard 表（2026年11月7日确认）。Batch、Flex 等折扣层请查看价格页面。3.8 Flash 的单价不因提示长度而变化。

以 2.5 Pro 的用量来算一下。每月输入 1,000万令牌、输出 200万令牌（提示均在 20万令牌以内）时，2.5 Pro 为 $12.50 + $20.00 = $32.50。同样的令牌数用 3.8 Flash，2026年12月为 $7.50 + $7.50 = $15.00，2027年1月起为 $15.00 + $15.00 = $30.00。

不过，令牌数不一定保持不变。Google 表示，3.8 Flash 的设计会在长而复杂的任务中使用更多令牌，并表示日常任务可以通过降低 thinking_level 来减少用量。从 2.5 Flash 迁移到 3.5 Flash-Lite 时，如果把级别调到默认的 minimal 以上，用于思考的输出令牌也会增加。即使单价相同或更低，账单也取决于所选的级别。在测试时记录响应中的令牌数（usage_metadata），就能估算12月的费用。

Google 搜索接地（Grounding with Google Search）的计算方式也不同。2.5 Flash 和 2.5 Pro 每天前 1,500 次请求免费，之后每 1,000 个“接地提示”收费 $35。3.5 Flash-Lite 和 3.8 Flash 则在 Gemini 3 及以后的所有模型合计每月前 5,000 次请求免费，之后每 1,000 次搜索查询收费 $14，每天上限 1,500 次请求。一次请求中执行多次搜索时，每次搜索都会计费。大量使用接地功能的话，请重新核算次数。

Gemini 的整体费用（应用付费套餐与 API 的区别），请参阅“Gemini 的价格与免费功能”。API 费用的原理（令牌、输入与输出），请参阅“什么是 AI API？”。

5. 过了12月1日会怎样

如果什么都不做，会按代码的写法出现以下情况。

• 不会出现模型名的错误：仍使用 gemini-2.5-flash、gemini-2.5-pro 名称的请求会送达新模型
• 按新模型的价格计费：2.5 Pro 转向目标的价格在2027年1月1日还会再涨
• 预先填写回答的请求、candidate_count 为 2 以上的请求会以 HTTP 400 错误中止：自行重建历史而丢失签名的函数调用，也可能导致错误或意外行为
• 部分回答在不报错的情况下发生变化：temperature 等设置被忽略，2.5 Flash 的转向目标默认几乎不思考。表现为使用工具的处理中途停下，或回答的波动变大

不报错的变化很难在监控指标上体现出来。比较切换前后校验回答格式（能否解析为 JSON、必填字段是否齐全）的检查失败次数，就更容易发现。

6. 迁移目标沿用自动转向的模型就行吗

自动转向的目标，是 Google 作为各自替代所推荐的模型。不过，它们的特性和以前不同。

Flash 2.5 Flash → 3.5 Flash-Lite 是以相同单价转到“Lite”系列。Google 公布的数据是，推理基准 HLE 上 3.5 Flash-Lite 为 18.0%，2.5 Flash 为 11.0%；图表理解基准 CharXIV 上为 74.5% 对 63.7%（Google 自测）。如果主要是大批量的提取或分类，照原样迁移是合理的。如果主要是多步骤的代理或代码生成，并希望提升回答质量，也可以选择 Google 对比表中列为适合代码生成和多步骤任务的 gemini-3.6-flash。它到2026年12月31日的推广价为输入 $0.75、输出 $3.75，2027年1月1日起为 $1.50 和 $7.50，比 3.5 Flash-Lite 贵。

Pro 2.5 Pro → 3.8 Flash 是从 Pro 系列转到 Flash 系列。Google 称 3.8 Flash 是“最智能的 Flash 模型”（most intelligent Flash model），定位于长时间的软件开发和代理。与 2.5 Pro 相比，输出单价即使在2027年以后也更低（$10.00 → $7.50），而输入单价在2027年以后会更高（提示在 20万令牌以内时 $1.25 → $1.50）。

如果最看重回答质量，也可以选择价格更高的 Gemini 4 Argon（gemini-4-argon）。它到2026年11月30日的推广价为输入 $2.00、输出 $10.00，12月1日起为输入 $4.00、输出 $20.00，且没有免费层（“Pricing”，2026年11月7日确认）。

无论选择哪个模型，都先切换名称、运行相同的测试，再比较回答质量、错误和令牌数来决定。其他 Gemini 模型的知识截止日期和定位，请参阅“主流生成 AI 知识截止日期一览”。

切换模型时响应形式和设置处理方式的变化，并不是 Gemini 独有的。Claude API 改用新模型时出现的同类问题，整理在“'ThinkingBlock' object has no attribute 'text' 的原因与修复方法”中。

总结

• 从2026年12月1日起，gemini-2.5-flash 自动转向 gemini-3.5-flash-lite，gemini-2.5-pro 自动转向 gemini-3.8-flash，按目标模型的单价计费
• 一次完成的文本、图片请求照常运行。gemini-2.5-flash-lite 不在范围内
• 自行重建历史而丢失签名的函数调用、预先填写回答、candidate_count 为 2 以上的请求可能返回 HTTP 400 错误。Google 要求在 FunctionResponse 中填入 id 和 name（使用 SDK 的聊天功能时，SDK 会传递签名）
• thinking_budget 改为 thinking_level。3.5 Flash-Lite 默认是 minimal，工具和多步骤处理请用 medium 以上。temperature 等设置会被忽略
• 单价从 2.5 Flash 来看大致相同，从 2.5 Pro 来看更低。但 3.8 Flash 在2027年1月1日涨价（输入比 2.5 Pro 贵），令牌数也会随思考级别变化
• 不要等到12月1日：先切换模型名，用较重的输入测试，再上线到生产环境

FAQ

Q. 12月1日调用 gemini-2.5-flash，会出现“找不到模型”的错误吗？

A. 不会。根据 Google 的文档，请求会自动转到 gemini-3.5-flash-lite。不过回答的是新模型，并按新模型的价格计费。自行重建历史而丢失签名的函数调用、预先填写回答、candidate_count 为 2 以上的请求可能返回 HTTP 400 错误。

Q. 出现了思维签名（thought signature）的错误，该改哪里？

A. 改组装对话历史的部分。请检查是否只用名称和参数重建了模型在上一轮返回的 content。把收到的 content 原样放回历史，签名也会一起送回。使用 SDK 的聊天功能或 Interactions API 的 previous_interaction_id 时，签名会被自动处理。

Q. gemini-3.5-flash-lite 的价格是多少？

A. 付费层的输入为每 100万令牌 $0.30（文本、图片、视频、音频相同），输出为 $2.50（2026年11月7日确认）。与 2.5 Flash 相比，文本、图片、视频的输入和输出相同，音频输入从 $1.00 降到 $0.30。

Q. 之前把 thinking_budget 设为 0 来关闭思考，现在该怎么办？

A. 在 3.5 Flash-Lite 上，不指定 thinking_level（默认为 minimal），或者指定为 "minimal"。3.8 Flash 没有 minimal，指定会报错，所以请用最低的 "low"。

更新记录

• 2026年11月7日首次发布。依据 Gemini API 的更新日志（2026年11月2日）、Gemini deprecations、迁移指南（3.6/3.5 Flash-Lite、3.8 Flash）、价格、Thinking 和 API 参考撰写。

参考资料

• Google：Gemini API changelog、Gemini deprecations、Pricing
• Google：What's new in Gemini 3.6 Flash and 3.5 Flash-Lite、What's new in Gemini 3.8 Flash
• Google：Thinking、Function calling、Migrating to the Interactions API、generateContent API reference
• Google 发给 Google AI Studio 用户的邮件“Gemini 2.5 Flash redirects to 3.5 Flash-Lite Dec 1”（2026年11月3日）