Gemini 3.5 Flash 开发者指南

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

本文档介绍了 3.5 Flash 的新功能、何时应使用该模型、如何迁移到 3.5 Flash，并提供了 3.5 Flash 的快速入门指南。

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

下表对 3.5 Flash、3.1 Pro 和 3.1 Flash-Lite 的一些规范进行了比较：

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

应用场景细分

针对 Agentic Workflows 的推荐策略采用分层方法，以优化质量、速度和成本：

• Gemini Pro：留给需要深度推理的高复杂度认知任务，例如初始根规划、复杂问题解决、困难编码和关键决策。
• Gemini Flash：用作执行任务、工具调用和中间推理步骤的主要“主力”，在性能和效率之间实现最佳平衡。
• Gemini Flash-Lite：部署用于高容量、低延迟的预处理和结构化任务，其中速度和成本至关重要，例如意图路由、数据提取、标记和分类。

Gemini 3.5 Flash 有哪些新功能？

Gemini 3.5 Flash 为 Gemini 模型系列带来了以下变化和改进：

• 持续提供前沿性能：Google 最智能的 Flash 模型，针对大规模智能体和编程任务进行了优化。
• 智能体执行：子智能体部署、问题解决和大规模快速智能体循环。
• 改进了编码：迭代编码周期、快速探索和原型设计，以测试替代路径并动态探索解决方案。
• 长跨度：多步骤工作流和大规模工具使用。
• 思维保留：模型会自动在多轮对话中保留中间推理。无需更改 API。
• 新的默认思考等级：默认思考等级从 HIGH 更改为 MEDIUM。
• 改进了 LOW 思考功能：现在，对于需要较少步骤的代码和智能体任务，低思考等级的效果显著提升，能够以更低的延迟和成本提供更高的质量。

如需了解更多详情，请参阅主要变更部分。

快速入门

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

主要变化

本部分将进一步详细介绍 Gemini 3.5 Flash 中引入的以下变更：

• 新的默认思考等级 (MEDIUM)
• 思维保留
• 已弃用：采样参数
• 已弃用：thinking_budget

新的默认思考等级

Gemini 3 模型的默认思考级别现已从 Gemini 3 Flash 预览版中的 HIGH 更改为 MEDIUM。思考等级 MEDIUM 可在各种任务中产生出色的结果，同时速度更快、更经济实惠。

支持的思考等级包括：

• MINIMAL：对于大多数查询，与“不思考”设置相匹配。对于编程等复杂任务，模型可能只会进行极少量的思考。最大限度地减少聊天或高吞吐量应用的延迟时间。
• LOW：适用于大多数任务的轻量推理，速度快、成本低。
• MEDIUM：（默认）适用于大多数需要推理的任务的均衡设置。
• HIGH：最大限度地提高推理能力，以优化任务执行效果。模型生成第一个词元所需的时间可能比 MEDIUM 设置更长，但输出会更全面。

例如，对于逻辑谜题、数学应用题或模型需要通过多个步骤进行推理的棘手场景，请使用 HIGH：

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

thinking_level 参数是可选的。如果省略，3.5 Flash 将使用其默认设置 (MEDIUM)。

思维保留

模型会自动在多轮对话中保留中间推理。当对话历史记录中存在推理上下文时，推理上下文会自动延续，从而提高迭代调试和代码重构等复杂多步骤任务的性能。无需更改 API。

现在，系统会默认保留之前对话轮次的思考过程。该服务不再从对话上下文中清除思考历史记录，而是直接将其传递给模型。

发送对话历史记录时，请与之前的对话轮次保持一致：要么包含完整上下文（思考、函数调用、回答），要么完全省略。部分上下文可能会降低模型性能。

已弃用：采样参数

对于 Gemini 3 模型，不再建议使用以下采样参数：

• temperature
• top_p
• top_k

模型会自行管理采样，以获得最佳结果。从所有请求中移除这些参数。为确保确定性，请针对您的特定应用场景定义包含明确规则的系统指令。

已弃用：thinking_budget

所有 Gemini 3 模型都不再支持原始数字 thinking_budget 参数。请改用 thinking_level 字符串枚举。

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

最佳做法

本部分介绍了使用 3.5 Flash 的以下最佳实践：

• 对函数调用使用严格的响应匹配
• 在函数响应 parts 中添加多模态内容
• 在函数回答中使用内嵌指令
• 减少不必要的工具调用

对函数调用使用严格响应匹配

在大多数情况下，不匹配的响应会导致模型返回带有 finish_reason: STOP 的空响应。请始终遵循以下惯例：

• 包含 id：每个 FunctionResponse 都必须包含来自相应 FunctionCall 的 id。
• 匹配 name：响应中的 name 必须与调用中的 name 匹配。
• 匹配计数：为收到的每个 FunctionCall 正好返回一个 FunctionResponse。

以下代码是正确函数调用的示例：

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

在函数响应 parts 中包含多模态内容

在函数回答之外提供图片可能会导致意外的模型行为（例如思维泄露），并导致质量降低。遵循函数调用简介中的建议，在发送给模型的函数响应部分中添加多模态内容。模型可以在下一轮对话中处理此多模态内容，从而生成更明智的回答。

例如：

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

在函数响应中使用内嵌指令

在后续 parts 中同时提供平台指令和函数响应可能会导致模型出现意外行为（例如思维泄露），并导致质量下降。而是将其附加到函数响应文本的末尾，并用两个换行符分隔。

例如：

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

减少不必要的工具调用

如果您遇到工具调用过度使用的情况，可以采用以下两种方法来尽可能减少这种情况：

1. 降低思考水平：思考水平越高，模型就越倾向于使用更多工具进行探索和验证，因此降低思考水平可以减少工具调用。

2. 添加系统指令：如果在调整思考级别后，过度使用工具的情况仍然存在，请考虑使用限制工具使用的提示。例如：

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

从 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.5 Flash 模型页面
• 入门笔记本