面向开发者的 Gemini 3.7 Flash 指南

Gemini 3.7 Flash 是我们为开发者打造的智能日常主力模型，在软件工程方面实现了进步，使用体验明显更好。此模型可为您的日常工作流程带来更出色的智能，以处理复杂任务、执行指令和调用工具。

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

它在 Gemini 系列中的定位是什么？

Gemini 3.7 Flash 是 Gemini 3 系列中的主要智能体主力模型，它弥合了深度推理 Pro 模型与高吞吐量 Gemini Flash-Lite 模型之间的差距，同时提供高 token 效率和多步多模态处理能力。

模型规范和比较

下表比较了 3.7 Flash、3.6 Flash 和 3.1 Pro 的部分规范：

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

Gemini 3.7 Flash 的新功能

下表比较了 Gemini 3.7 Flash 和 3.6 Flash 之间的标准开发者评估基准：

快速入门

在开始之前，您必须使用应用默认凭据 (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.7-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.7-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

强制性 API 规则和行为惯例

Gemini 3.7 Flash 严格执行以下标准 Gemini 3 系列 API 惯例：

• 已废弃的抽样参数（temperature、top_k、top_p） ：后端会忽略这些参数。您可以改用 thinking_level（LOW、MEDIUM、HIGH）和 response_schema 或 json_schema 来控制确定性。
• 不受支持的参数（frequency_penalty、presence_penalty、candidate_count） ：传递 frequency_penalty、presence_penalty 或 candidate_count 会抛出活跃的 API 错误。请从旧版客户端代码中移除这些参数。

• 严格的函数调用规则：FunctionResponse 轮次必须与前面的 FunctionCall 的 id、name 和执行计数完全 匹配。

  • 多模态素材资源：始终将多模态素材资源放在 响应载荷内。
  • 格式设置和工具前文本：使用 \n\n设置内嵌指令的格式。如果您遇到与工具前文本相关的 Malformed_Function_Call 错误，请清理工具调用之前的开头注释。

  • 如需在工具调用之前传递中间工作备注或状态更新，请将其封装在专用的 update() 函数调用中，而不是发出原始 XML 或文本：

    {
      "name": "update",
      "description": "Update working notes before tool execution",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "previous_step": {"type": "STRING"},
          "plan": {"type": "STRING"},
          "next_step": {"type": "STRING"}
        },
        "required": ["previous_step", "plan", "next_step"]
      }
    }
    

• 聊天序列验证：

  • 历史记录载荷不能以“model”角色轮次结尾。
  • 预填模型轮次不受支持，必须在升级时移除。
  • 对话记录中的空轮次会自动丢弃，或产生验证错误。

从 3.5 Flash 或 3.6 Flash 迁移到 3.7 Flash

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

1. 更新模型 ID：将 API 调用中的模型字符串更改为 gemini-3.7-flash。
2. 替换推理预算参数：将整数 thinking_budget配置替换为字符串枚举thinking_level，并将其 设置为以下某个值：
   • HIGH：建议用于密集视觉质量保证、瞬间运动检测（体育、编辑）或跨 60 分钟以上视频的多步推理。
   • MEDIUM：默认思考等级。此等级为一般视频问答、讲座摘要和剪辑检索提供了最佳平衡。
   • LOW：建议用于快速以文字记录为中心的搜索或基本元数据提取等任务。
3. 剥离已废弃和不受支持的参数：
   • 移除 temperature、top_p 和 top_k。
   • 移除 candidate_count、frequency_penalty 和 presence_penalty。
   • 从对话记录中移除所有预填模型轮次。

面向开发者的摘要核对清单

其他资源

• Gemini 3.7 Flash 模型页面
• 简介笔记本