Gemini 3.7 Flash 迁移到 3.8 Flash 要改什么？model ID、thinking_level 和废弃参数一次改对

这次迁移最危险的坑不是报错，而是不报错。temperature、top_p、top_k 这三个采样参数传给 Gemini 3.8 Flash 不会抛任何异常，但会被后端直接忽略，Google 官方文档的原话是 "ignored by the backend"。依赖这些参数控制输出风格的应用，会在无报错、无日志的情况下悄悄行为漂移。如果你的项目正在 3.7 Flash 上跑，这篇文章给你一份可勾选的迁移清单：model ID 替换、thinking_budget 改 thinking_level、废弃参数清理、回归测试，外加一个“迁还是留”的判断框架。想省事的读者可以直接用官方提供的自动化迁移指令 /gemini-api-dev migrate my app to Gemini 3.8 Flash，配合 coding agent 执行。

先把整份清单放在这里，后文逐项展开，做完再上线：

• 全局替换 model ID：gemini-3.7-flash 改 gemini-3.8-flash，并排查配置、日志、A/B、缓存里的硬编码
• 删除 thinking_budget，改传 thinking_level（low / medium / high，默认 medium）
• 清理废弃参数：temperature/top_p/top_k 会被静默忽略，frequency_penalty/presence_penalty/candidate_count 传入即报错
• 对照官方清单过一遍多轮会话与 function calling：previous_interaction_id、prefill 禁令、call_id 和 name
• 跑四条回归线：功能、质量、延迟、成本，成本按任务算总账

model ID 改完就完事了？先排查这些容易漏的硬编码位置

先给结论：model ID 本身只有一行，gemini-3.7-flash 改成 gemini-3.8-flash，Gemini API 和 Agent Platform 两个平台的写法一致，没有第二套命名。真正的坑不是改错，而是改不全。

建议按下面这份清单逐项排查：

• API 调用点：直接写在代码里的 model 字符串，全局搜索旧 ID 即可命中
• 配置文件和环境变量：模型名通常收敛在配置层，但历史项目常有“配置文件一份、代码里兜底硬编码一份”的情况
• 日志与监控：埋点和监控配置里如果单独硬编码了一份旧 ID，迁移后代码调用的是新模型、看板统计的还是旧 ID，按模型维度统计的调用量和错误率会全部失真
• A/B 测试配置：实验分桶如果按 model ID 区分，漏改会让实验组悄悄跑在旧模型上，结论直接作废
• 缓存键：响应缓存的键里如果没把 model ID 算进去，迁移后 3.8 的请求会命中 3.7 留下的旧响应，新旧输出混用；按 model ID 分桶的缓存则要接受迁移后新桶为空、命中率短暂下滑

如果你的团队是通过 LiteLLM 这类 LLM 网关统一接入的，model ID 只需要改网关配置一处，还可以给 3.7 到 3.8 配上 fallback 做灰度切换，出问题时回退到旧版本。

最后提醒一句：改完 ID、调用返回 200，不等于迁移完成。下一步的参数问题才是重头。

thinking_budget 改成 thinking_level：三档怎么选，行为差在哪

先纠正一个普遍误解：thinking_budget 改 thinking_level 不是 3.8 Flash 的新变化，而是 Gemini 3 全系的既有规则。Google 在官方文档中明确写道，原始的数字型 thinking_budget 参数在所有 Gemini 3 模型上都不再被支持，应改用 thinking_level 字符串枚举。也就是说，如果你的 3.7 Flash 项目代码里还留着 thinking_budget，它在旧版本上可能就已经没按你的预期工作了，只是你还没发现。迁 3.8 正是彻底清掉它的时机。

语义上的差异要理解清楚：thinking_budget 是“连续整数 token 预算”，你告诉模型最多花多少 token 思考；thinking_level 是“离散三档 effort level”，你只选一档，花多少 token 由模型自己决定。控制粒度变粗了，但换来的是不用再猜“7500 够不够”这种问题。官方迁移示例给出的对照是：原来传整数预算 7500，迁移后改传 "MEDIUM"。

三档的取值和官方语义如下：

两个好消息：第一，3.8 Flash 的默认档是 medium，3.7 Flash 的默认档也是 medium，不显式传参的项目行为连续性有保障；第二，两版本支持的档位都是 low、medium、high 三档，显式传档位的代码不需要改档位名。另有一点要注意：3.8 Flash 不支持 minimal 档，如果你的代码里传过这个值，迁移时必须一并处理。

从旧预算映射到新档位，建议按这个思路：原来设低预算的（比如压到几百 token 省成本）对应 low；原来用默认值或中等预算的对应 medium；原来给高预算跑难题的对应 high。映射完不要直接上线，先在回归测试里验证同档位下的实际行为。

两个坑要记牢：

1. thinking_level 和 thinking_budget 同传必报错。 Google 在官方文档中明确：对 Gemini 3 模型，同一请求里同时指定这两个参数，模型直接返回错误。这是迁移中少数会立刻炸的情况，反而是好事，CI 阶段就能拦住。
2. 单独传 thinking_budget 会怎样，官方文档没有说明。 是报错还是被静默忽略，目前没有明确答案。建议的处理方式：直接从代码里删掉，迁移完成后抓包验证一次请求体，确认这个参数已经不在 payload 里。

至于三档之间 latency 和 cost 的具体差异，官方文档只有定性描述，没有给出任何数字，这里标注为待实测核验，不做编造。你需要在回归测试里用自己的任务集测出真实差异。

这些参数传了不报错，但模型已经不理你了

这一节是整个迁移里最值得打印出来贴在显示器旁边的一节。核心论点：静默忽略比报错危险得多。报错类参数在 CI 里半小时就能修完；静默忽略类参数没有任何报错和日志，问题会潜伏到线上。

按废弃方式分三类：

处理建议统一是“删除而非注释保留”。注释掉的参数迟早被后人解开，而那时没人记得它已经废弃。

时间线上提一句：采样参数的废弃公告是 2026 年 7 月 21 日随 3.6 Flash 正式版一起发布的，不是 3.8 才有的坑。如果你的 3.7 Flash 项目一直在传 temperature，它可能已经带着无效参数跑了一段时间，输出风格早就不是你以为的样子了。

对依赖 temperature 控制输出多样性的应用（创意生成、数据增广、需要调节随机性的场景），要诚实面对一个现实：官方迁移指南没有给出等价的替代参数。靠这几个参数做采样控制，在 Gemini 3 上已经行不通，需要改用提示词设计来补偿，比如在指令里显式描述期望的输出风格。这超出了参数替换的范围，但迁移评估时必须把它算进工作量。

多轮对话和工具调用别漏查：prefill 禁令、call_id 要求逐项过

除了参数替换，Google 的官方迁移清单还要求对多轮会话和 function calling 做一轮审计。先说口径：这些要求大多属于 Gemini 3 家族的基线规则，而 3.7 Flash 本身就是 Gemini 3 模型。如果你的项目在 3.7 上已经稳定跑通了多轮会话和工具调用，这一步大概率是“逐项确认合规”，不是“推倒重写”。官方清单没有按版本区分每条规则的生效时间，所以不要假设哪条是 3.8 新增的，对照清单逐项确认即可。

重点过两个最容易炸的点：

多轮会话。 官方要求改用服务端的 previous_interaction_id 来维护对话历史，同时禁止 prefilled model turns：如果你的对话历史末尾是一个 model turn（这是早期 prefill 引导输出的常见用法），会触发严格校验错误。从旧版本一路升级过来的项目，prefill 用法的遗留是最常见的翻车点。

Function calling。 在 generateContent API 里，FunctionResponse 必须带上 call_id 和 name 两个字段，缺一个调用就失败。另外官方清单还提到：多模态资产要放进 response payload、inline 指令用 \n\n 分隔、遇到 Malformed_Function_Call 报错时官方文档里有对应的 workaround，这几条按清单核对即可。

thought signature 用一句话带过：做过 function calling 历史回放或响应缓存的项目，确认 signature 在整个链路里没有被剥离，否则回放历史时会校验失败。

迁移完怎么确认没退化：功能、质量、延迟、成本四条线

模型发布当天，社区还没有积累一手踩坑反馈，所以这一节只给通用方法论，不编造“开发者常见报错”。四条线各有一个关键动作：

功能回归。 挑出核心用例，校验输出一致性：结构化输出跑 schema 校验，工具调用校验参数正确性。这一步能拦住大部分静默行为漂移。

质量回归。 准备一组 golden set 任务，迁移前后各跑一遍，评分对照。重点不是绝对分数，而是找出“迁移后明显变差的任务类型”。

延迟回归。 对比 P50/P95。注意先固定 thinking_level 档位再测，否则档位这个变量会污染数据，你分不清延迟变化来自模型还是来自档位。

成本回归。 这是最容易被忽略的一条，也是这次迁移最需要盯的一条。两版本 token 单价完全相同，成本变量只剩一个：token 消耗量。而 Google 在发布材料中明确说了 3.8 Flash 在复杂任务上“更努力”：执行额外的推理步骤、迭代调用工具，在高 effort 档位可能消耗更多 token。第三方评测机构 Artificial Analysis 的实测数据显示，3.8 Flash 每任务平均输出 token 比 3.7 Flash 高约 30%，每任务成本按档位分化明显：high 档约 0.58 美元、medium 档约 0.41 美元、low 档约 0.24 美元，3.7 Flash 约为 0.40 美元。注意这是第三方实测数据，非官方口径，测的是其自家任务集，你的任务分布不同，结论也会不同。但方向性信号值得参考：medium 档成本与 3.7 大致持平，high 档明显更贵，low 档反而更省。

所以成本回归的正确姿势是“按任务算总账，不是按 token 单价算账”：取一组有代表性的生产任务，迁移前后各跑一遍，对比每任务总成本。灰度建议：先小流量切 3.8，盯一周成本曲线，再决定全量。

什么场景该迁，什么场景留在 3.7 Flash 反而更划算

先清掉三个伪决策变量，它们经常干扰判断但其实不构成迁移动机：

1. 价格。 两版本单价完全相同：输入 0.75 美元/百万 token、输出 3.75 美元/百万 token（含 thinking tokens），这个价格执行到 2026 年 12 月 31 日；2027 年 1 月 1 日起两版本一起涨到每百万 token 输入 1.50 美元、输出 7.50 美元。不存在“新版本溢价”，也不存在“赶在涨价前迁移”的窗口。
2. 下线压力。 Google 的废弃参数页面显示 3.7 Flash 目前没有公布关停日期。留在旧版本短期没有被迫迁移的时钟。
3. 规格差异。 两版本都是 1M token 上下文、64K 最大输出、知识截止 2026 年 3 月，规格层面没有升级诱因。

真正的判断维度是这四条：

任务时长与结构。 Google 对两版本的官方定位差异说得很直白：3.8 Flash 是“最智能的 Flash 模型，面向 long-horizon 软件工程、autonomous agents 和复杂企业工作流”；3.7 Flash 是“高速、高效的 Flash 模型，面向日常编码、agentic 工具使用和可靠的多步执行”。如果你的负载是多步软件工程任务、跨会话的 agent 长任务，3.8 的能力增量正是为你设计的。如果是短平快的单步任务，增量大概率用不上。

是否 autonomous agent 场景。 工具编排密集度越高、任务链越长，越接近 3.8 的设计目标。

成本敏感度。 单价相同不代表成本相同。官方明示 3.8 会“更努力”，第三方实测也指向 token 消耗上升。高频短任务的总账可能变差，这是成本敏感项目要算清楚的一笔。

对 thinking 行为的依赖。 已经在 3.7 上调好档位的项目，同档位迁移后行为是否漂移，官方没有承诺，只能靠你的回归数据说话。

能力增量的参考数据：3.7 Flash 在 DeepSWE v1.1 上的官方模型卡分数是 65.3%；3.8 Flash 的发布帖称其在同一基准上达到 73.7%，并称超越了多数更大的前沿模型，该数字以官方模型卡为准。3.8 Flash 在 HLE-Verified 上拿到 54.9%，官方页面有原句，但官方没有给出 3.7 的对照数字，只能作为能力信号，不能直接做版本对比。Terminal-Bench 2.1 上 3.8 Flash 较 3.7 Flash 有明显提升，但不同来源报道的具体分数存在出入，官方模型卡的表格暂未能核实到确切数字，这里不引用具体分。

两个典型画像，供对号入座但不构成绝对结论：跑 agent 长任务、多步代码工程的项目，倾向尽快迁，迁后第一周重点盯成本回归曲线；跑分类、抽取、客服问答这类高频短任务、成本敏感的项目，3.7 可能仍然更经济，而且没有下线风险，完全可以等社区一手反馈积累起来再定。

迁移优先级建议

跑 long-horizon 任务或 autonomous agent 的项目，建议尽快迁，迁移后第一周盯紧成本曲线；短任务、高频、成本敏感的项目不必抢跑，3.7 没有关停日期，等更多一手反馈出来再定。还没用 3.8 Flash 发过第一个请求的读者，可以先看站内的 3.8 Flash 入门教程，再回来过这份迁移清单。

常见问题

Gemini 3.8 Flash 的 model ID 怎么写？
gemini-3.8-flash，Gemini API 和 Agent Platform 写法一致。

thinking_budget 还能传吗？
不能。Gemini 3 全系不再支持这个参数，改用 thinking_level。两者同传必报错；单独传 thinking_budget 的行为官方文档未说明，建议直接删除并抓包验证。

temperature、top_p、top_k 传了会报错吗？
不会报错，但会被后端静默忽略，这是本次迁移中最危险的坑，依赖采样参数的应用会在无报错的情况下行为漂移。

frequency_penalty、presence_penalty、candidate_count 传了会怎样？
这三个参数传入即抛出 API 错误，调用直接失败，必须在迁移时删除。

thinking_level 的 minimal 档还能用吗？
3.8 Flash 不支持 minimal，只有 low、medium、high 三档，代码里如果传过 minimal 要一并处理。

Gemini 3.8 Flash 比 3.7 Flash 贵吗？
单价完全相同：输入 0.75 美元、输出 3.75 美元每百万 token，执行到 2026 年 12 月 31 日，2027 年起两版本一同涨到 1.50/7.50 美元。成本差异来自 token 消耗：官方明示 3.8 在复杂任务上更努力，高 effort 档可能消耗更多 token。

Gemini 3.7 Flash 什么时候下线？
官方未公布关停日期，短期内没有强制迁移压力。

有官方迁移工具吗？
官方提供自动化迁移指令 /gemini-api-dev migrate my app to Gemini 3.8 Flash，配合 coding agent 使用。