Gemini 3.5 Flash 開發人員指南

Gemini 3.5 Flash 是 Gemini 3 系列中速度快、成本效益高的強大模型，這款模型旨在提供接近 Pro 的代理能力，同時兼顧效能和價值，現已正式發布 (GA)，開發人員可透過 Gemini API 使用，企業則可透過 Gemini Enterprise Agent Platform 使用。

本文將說明 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 設定，但輸出內容會更完整。

舉例來說，如果模型需要透過多個步驟進行推論，例如邏輯謎題、數學應用題或棘手情境，請使用 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 慣例：
   • 移除 temperature、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 模型頁面
• 入門筆記本