Gemini 3.6 Flash 开发者指南

Gemini 3.6 Flash 是 Gemini 3 系列中一款高速、高性价比的主力模型。该模型旨在提供接近 Pro 模型的智能体功能，同时兼顾性能和价值。现在，使用 Gemini API 的开发者和使用 Gemini Enterprise Agent Platform 的企业均可使用该模型的正式版 (GA)。

本文档介绍了 3.6 Flash 的新功能、它在 Gemini 模型系列中的定位、如何迁移到 3.6 Flash，并提供了使用 3.6 Flash 的快速入门。

它在 Gemini 系列中扮演什么角色？

Gemini 3.6 Flash 是 Gemini 3 系列中的主要智能体主力模型。它弥合了深度推理 Pro 模型与高吞吐量 Flash-Lite 模型之间的差距。与 Gemini 3.5 Flash 相比，3.6 Flash 在多步工具编排、全栈代码重构和视觉推理方面的质量显著提高，同时使用的 token 和推理轮次更少。 它以 Flash 的速度和价格提供接近 Pro 级别的功能。

模型规格和比较

下表比较了 3.6 Flash、3.5 Flash 和 3.1 Pro 的一些规格：

如需查看受支持的功能、工具和使用选项的完整列表，请参阅 3.6 Flash 模型页面。

Gemini 3.6 Flash 有哪些新变化？

3.6 Flash 针对多步骤编排、全栈代码重构和通用推理进行了优化，其 token 效率明显高于前代模型。

功能和性能更新

以下是 3.6 Flash 与先前模型相比在功能和性能方面的变化：

• 减少 token 和对话轮次：与 3.5 Flash 相比，消耗更少的 token，并以更少的推理步骤和对话轮次完成多步骤工作流。
• 改进的代码生成：在应用构建、原型设计和 IDE 智能体环境中，生成更简洁的代码，降低编译失败率和修订率。
• 减少操作偏差：解决只读诊断任务，而不会主动修改工作区或过早更改状态。
• 多模态和空间推理：在图表解读、视觉蓝图转换和多元素网页布局生成方面提供更出色的性能。
• 计算机使用支持：作为内置工具支持，用于智能体界面自动化。
• 界面样式偏好：更擅长创建功能性代码，但人工评估员指出，在前端呈现和图文并茂方面，他们更偏好之前的模型。您可以通过提供明确的设计指南来缓解这一问题。

行为和 API 参数变更

以下是 3.6 Flash 与先前模型相比的行为和 API 参数变更列表：

• 步骤简洁性：使用的推理步骤少于 3.5 Flash。虽然这可以减少代码重构和工具工作流的延迟时间和费用，但可能会导致在需要更长迭代链的扩展多轮对话跟进中提前退出。
• 预先程序化检查：更倾向于运行诊断代码脚本 (execute_code) 来检查问题，而不是像 3.5 Flash 那样频繁地改变状态。虽然这提高了复杂后端重构的诊断准确性，但有时可能会导致在简单的前端 Web 和脚本任务中运行额外的探索性检查步骤，而之前的版本会直接生成代码。
• 默认努力程度：沿用 3.5 Flash 中引入的中等默认努力程度。
• 无采样替换：不再支持 temperature、top-k 或 top-p 参数的自定义值。在 API 接口中，设置自定义值将被忽略。请改用 thinking_level 或结构化 JSON 架构来控制输出的确定性。
• 频率和存在惩罚限制：这些参数不再支持自定义值。现在，设置这些属性会抛出活跃 API 错误。
• 不支持最后一个输入轮次的角色为“Model”的 API 请求。
• 对话记录中的空轮次会被丢弃。
• 现在，无效的思考特征会产生错误。
• 严格函数调用：FunctionResponse 必须与前面的 FunctionCall 的 id、name 和执行次数严格匹配。直接在函数响应文本中附加内嵌指令，并用两个换行符 (\n\n) 分隔。

快速入门

在开始之前，您必须使用应用默认凭据 (ADC) 或 API 密钥向 Agent Platform 进行身份验证。如需了解详情，请参阅 Gemini Enterprise Agent Platform 使用入门。

在以下代码块中，将 PROJECT_ID 替换为您的项目 ID。

安装

确保您使用的是最新版 google-genai SDK：

pip install --upgrade google-genai

基本请求

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-3.6-flash",
  contents="How does AI work?",
)
print(response.text)

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.6-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

从 3.5 Flash 或 3.1 Pro 迁移到 3.6 Flash

如需从 3.5 Flash 或 3.1 Pro 迁移到 3.6 Flash，请执行以下步骤：

1. 更新模型 ID：将 API 调用中的模型字符串更改为 gemini-3.6-flash。
2. 根据新的 Gemini 3 系列 API 规则调整代码：Gemini 3.6 Flash 严格执行 Gemini 3 系列中建立的参数规则和 API 惯例：
   • 移除温度、Top-K 和 Top-P：从载荷中移除这些自定义参数。虽然它们不会抛出错误，但模型会完全忽略它们。请改用 thinking_level 参数或 json_schema 结构化输出来控制输出确定性。
   • 移除频率和存在惩罚：移除频率或存在惩罚的所有自定义配置，以防止 API 调用抛出运行时错误。
   • 确保您的聊天集成不会尝试模型预填充：检查您的消息记录数组，确保 API 载荷不会以空的用户轮次或模型轮次结尾。如果历史记录数组中的最后一个对象是“model”角色 (GenerateContent API) 或“model_output”类型 (Interactions API)，请重构序列，以免触发严格验证错误。
   • 使用 thinking_level：移除已弃用的 thinking_budget 参数的实例，并改用 thinking_level。
   • 强制执行严格的函数调用惯例：FunctionResponse 必须与前面的 FunctionCall 的 id、name 和执行次数严格匹配。如果您需要附加内嵌指令，请将其直接放在函数响应文本中，并用两个换行符 (\n\n) 分隔。
3. 考虑工作流程的变化：
   • 如果您的应用依赖于多轮对话循环，请测试您的工作流，确保模型的新步骤简洁性不会触发过早退出。
   • 如果构建前端或基本脚本代理，请监控由于模型对预先程序化检查的新偏好而导致的不必要的探索性 execute_code 调用。

针对工具前文本要求的解决方法

如果您的提示要求模型在进行工具调用之前立即输出结构化文本（XLM、YAML、Json 等）（例如 <UPDATE>...</UPDATE>），则工具调用有时可能会失败，并显示 Malformed_Function_Call 错误。您可以使用以下任一解决方法来解决此问题：

• （推荐）指示模型将其工具前备注放在专用 update() 函数调用中，而不是原始文本中。如需了解详细的实现说明，请参阅下一部分。
• 指示模型将笔记写为 Markdown 标题（例如 # UPDATE、## PLAN），而不是结构化文本。
• 不要要求模型在工具调用之前输出文本。

推荐解决方案：将工作笔记封装在专用函数调用中

而不是原始指令：

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

请使用以下更新后的指令：

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

更新客户请求中对旧版 <UPDATE> XML 格式的所有引用。 然后，为更新函数添加相应的函数声明：

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

模型将在同一步骤中进行两次调用：替换结构化 XML 的 update() 调用，以及它想要进行的实际函数调用。

其他资源

• Gemini 3.6 Flash 模型页面
• 入门笔记本