Gemini 3.5 Flash 開發人員指南

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

本文說明 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 慣例：
   • 移除溫度、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 呼叫。

工具前文字規定解決方法

如果提示詞要求模型在進行工具呼叫前，立即輸出結構化文字 (XML、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 模型頁面
• 入門筆記本