Gemini 3.8 Flash 开发者指南

Gemini 3.8 Flash 是我们迄今为止最智能的主力模型，与 3.7 Flash 相比，在软件工程、智能体任务和专业领域中关键的多步推理方面有了显著改进。3.8 Flash 的性能比 3.7 Flash 有了大幅提升，通常接近于成本较高的前沿模型。

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

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

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

与 3.7 Flash 相比，3.8 Flash 的准确率更高，性能更可靠，但 token 消耗也更高。不过，3.8 Flash 还提供了通过思考等级来控制工作量的功能，让您可以调节这种消耗。在中等思考等级下，您仍然可以解决复杂的智能体任务，同时减少 token 消耗。您还可以针对对延迟敏感的任务使用较低的思考等级，以完全避免计算开销。如果您想优化计算效率，可以考虑使用 3.7 Flash。

模型规范和比较

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

Gemini 3.8 Flash Gemini 3.7 Flash Gemini 3.1 Pro
模型 ID gemini-3.8-flash gemini-3.7-flash gemini-3.1-pro-preview
发布阶段 GA GA 预览版
输入类型 文本、图片、音频、视频 文本、图片、音频、视频 文本、图片、音频、视频
输出类型 文本 文本 文本
上下文窗口 1,048,576 1,048,576 1,048,576
输出 token 长度上限 65,536 65,536 65,536
支持的区域 全球、 多区域 全球、 多区域 全球
支持的思考等级 LOW、MEDIUM、HIGH
（默认值：MEDIUM) 		LOW、MEDIUM、HIGH
（默认值：MEDIUM) 		LOW、MEDIUM、HIGH
（默认值：HIGH）
主要关注点 智能体工作流、编码、交互式视频理解 通用智能体工作流、多步编排、编码 深度推理、高复杂度任务

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

Gemini 3.8 Flash 的新功能

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

评估基准 3.8 Flash 3.7 Flash
Terminal-bench 2.1 90.8% 81.6%
SWE-Bench Pro 61.6% 60.4%
SWE-Atlas 51.9% 48.0%
τ³-bench Banking 38.1% 30.9%
CharXiv（多模态） 86.2% 84.5%
GDP.pdf 35.0% 34.0%
Humanity's Last Exam (HLE) 45.4% 45.7%

快速入门

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

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

安装

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

pip install --upgrade google-genai

基本请求

Python

from google import genai

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

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

REST

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.8-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

强制性 API 规则和行为惯例

Gemini 3.8 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.8 Flash（从 3.7 Flash 或 3.6 Flash 升级）

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

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

开发者摘要核对清单

其他资源