面向开发者的 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 模型页面
• 入门笔记本