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 的部分规格：

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

Gemini 3.8 Flash 有哪些新变化？

下表比较了 Gemini 3.8 Flash 和 3.7 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.8-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.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.7 Flash 或 3.6 Flash 升级到 3.8 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。
   • 从对话记录中移除所有预填模型轮次。

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

其他资源

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