快速结论：迁移到 Gemini 3.6 Flash、3.5 Flash 或 3.5 Flash-Lite 时，除了更新模型 ID，还要升级 SDK、用 thinking_level 替换旧思考预算、移除已弃用采样参数和 candidate_count、取消 assistant/model 预填充，并回归 FunctionResponse、工具调用和多轮状态。出现 400 或 Malformed_Function_Call 时，先检查旧请求结构，不要盲目重试。
选择明确的迁移目标
Google 当前建议：从 Gemini 3.5 Flash、3 Flash Preview 或 3.1 Pro 迁往 3.6 Flash；从 3.1 Flash-Lite 或 2.5 Flash 迁往 3.5 Flash-Lite。若业务仍需要 3.5 Flash 的能力，也应使用稳定模型 ID 并按当前文档保留回滚。
| 目标 | 模型 ID | 默认思考档位 | 优先场景 |
|---|---|---|---|
| Gemini 3.6 Flash | gemini-3.6-flash |
medium | 代码、多模态、复杂智能体 |
| Gemini 3.5 Flash | gemini-3.5-flash |
以当前模型页为准 | 长任务、持续高能力工作流 |
| Gemini 3.5 Flash-Lite | gemini-3.5-flash-lite |
minimal | 高吞吐提取、分类和子任务 |
迁移前先保存当前模型、SDK、请求 JSON、系统指令、工具 Schema、代表性输入、错误样本和费用基线。若仍在 Gemini 2.x，可结合Gemini 2.x 生命周期指南核对停用状态。
需要删除或替换的旧参数
Gemini 最新迁移文档要求从 3.6 Flash 和 3.5 Flash-Lite 开始移除 temperature、top_p、top_k；同时不再支持 candidate_count。旧的 thinking_budget 应替换为字符串枚举 thinking_level。继续携带已弃用字段可能被忽略，或在后续模型中直接返回 400。
# 迁移检查示意，不包含真实密钥
model = "gemini-3.6-flash"
config = {
"thinking_level": "medium",
# 删除 temperature / top_p / top_k / candidate_count
}
若希望输出更稳定，应通过清晰的 system instruction、结构化输出和服务器端校验控制，而不是继续依赖已弃用的采样参数。具体 SDK 调用方式以当前 google-genai 文档为准。
多轮消息和工具响应的兼容变化
新接口不允许请求以非空 model 角色消息结尾，因此过去为了强制前缀而加入的预填充会导致 400。应使用 system instruction 或 Structured Outputs 描述格式。多轮会话优先使用服务端 previous_interaction_id，避免手工重建历史时丢失状态。
FunctionResponse 要保留匹配的 call_id 与 name；多模态函数结果应放进函数响应内部。若函数调用前出现额外文本导致 Malformed_Function_Call，先保存原始响应、核对工具 Schema 和官方 workaround，不要让无限重试制造重复副作用。工具权限与幂等可参考Tool Use 生产验收。
四步完成迁移和灰度
- 升级 SDK：确认目标 API、客户端版本和破坏性变更，不在同次发布中修改无关业务。
- 清理参数：更新模型 ID，移除采样参数和 candidate_count，设置合适的 thinking_level。
- 修复消息：取消模型预填充，验证 previous_interaction_id、FunctionResponse 和错误处理。
- 回放并灰度：从离线保留集、影子流量到 1%/10% 切流，每级设置停止条件。
常见 400 与成本异常怎么排查
| 现象 | 优先检查 | 处理 |
|---|---|---|
| 400 参数错误 | temperature、top_p、top_k、candidate_count | 删除旧参数并保存请求/响应 |
| 400 消息错误 | 最后一条是否为 model 预填充 | 改用 system instruction 或结构化输出 |
| 工具调用畸形 | call_id、name、Schema 和前置文本 | 暂停真实动作，服务端校验后再执行 |
| Token 或费用上升 | thinking_level、历史状态、媒体分辨率和工具重试 | 与旧基线逐请求对照并设置上限 |
迁移成功的标准是任务完成和可恢复，不是 HTTP 200。可使用AI 产品可用性测试记录失败恢复和人机控制，并通过智能体专题设置最小权限、人工审批和回滚。
上线前最后检查
- 固定模型 ID、SDK 与请求 Schema，并记录复核日期。
- 关键请求通过离线回放、影子流量和小流量灰度。
- 400、工具错误、超时和费用异常均有明确降级路径。
- 搜索、URL Context、代码执行和自定义函数分别统计费用与失败。
- 免费/付费层的数据使用和组织权限已完成审查。
- 旧模型或人工流程在观察期内仍可恢复。
来源与复核记录
本文依据 Google 最新 Gemini 模型迁移指南、Gemini 3.5 Flash 迁移说明、Gemini API 模型目录和Gemini API 更新记录整理，复核日期为 2026 年 8 月 5 日。代码为迁移结构示意，不含凭据；参数、SDK 和预览工具可能继续变化，实施当天应再次核对官方文档。
