Gemini 3.5 Flash 开发者指南

Gemini 3.5 Flash 是 Gemini 3 系列中速度快、性价比高的强大模型。该模型旨在提供接近专业水平的智能体功能，同时不影响性能或价值，现在已面向使用 Gemini API 的开发者和使用 Gemini Enterprise Agent Platform 的企业正式版 (GA) 发布。

本文档介绍了 3.5 Flash 的新功能、何时应使用 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 模型的默认思考级别现在为 MEDIUM，与 Gemini 3 Flash 预览版中的 HIGH 相比有所变化。思考等级 MEDIUM 在各种任务中都能取得出色的结果，同时速度更快、成本更低。

支持的思考等级包括：

• MINIMAL：适用于大多数查询的“无需思考”设置。对于编码等复杂任务，模型可能只会进行非常简单的思考。最大限度缩短聊天或高吞吐量应用的延迟时间。
• LOW：以高速度和低成本完成大多数任务的轻量级推理。
• MEDIUM：（默认）平衡设置，适用于需要推理的大多数任务。
• HIGH：最大限度地提高推理能力，以优化任务表现。模型可能需要比 MEDIUM 设置更长的时间来生成第一个 token，但输出会更全面。

例如，对于逻辑谜题、数学应用题或模型需要进行多步推理的棘手场景，请使用 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 英寸闪存的最佳实践：

• 对函数调用使用严格的响应匹配
• 在函数响应中包含多模态内容 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 模型页面
• 入门笔记本