# 策展 · X (Twitter) 🔥🔥🔥🔥🔥

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 作者：Google AI Studio (@GoogleAIStudio) · 平台：X (Twitter) · 日期：2026-05-20

> 原始來源：https://x.com/GoogleAIStudio/status/2056797490553540756

## 中文摘要

# Gemini 3.5 Flash 開發者指南

Gemini 3.5 Flash 現已正式發布（GA），穩定且適用於大規模生產環境。作為我們最聰明的 Flash 模型，它在 Agentic 程式開發、程式撰寫以及大規模長跨度任務中，能持續提供頂尖的效能。

本指南概述了 Gemini 3.5 Flash 的改進內容、API 變更以及遷移建議。

## 新模型

Gemini 3.5 Flash：我們最聰明的模型，專為在 Agentic 任務與程式撰寫任務中提供持續的頂尖效能而設計。

模型 ID：`gemini-3.5-flash`

Gemini 3.5 Flash 支援 1M token 的 context window、65k 最大輸出 token、思考（thinking）功能，以及與 Gemini 3 Flash 相同的工具集與平台功能。目前暫不支援 Computer Use。

如需完整規格，請參閱模型總覽。如需定價資訊，請參閱定價頁面。

## 快速入門

安裝最新的 Google Gen AI SDK：

```bash
pip install -U google-genai
```

本指南中的所有程式碼範例均使用 Interactions API。Interactions API 是使用 Gemini 進行開發的全新標準原語（primitive），建議所有新專案採用。它針對 Agentic 工作流程、伺服器端狀態管理以及複雜的多模態、多輪對話進行了最佳化。GenerateContent API 同樣受到支援；適用的設定選項與建議皆相同。

```python
# Interactions API
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="用三句話解釋平行 Agentic 執行是如何運作的。"
)
print(interaction.output_text)
```

```python
# Generate Content API
from google import genai

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="AI 是如何運作的？",
)
print(response.text)
```

## 新功能亮點

- 持續的頂尖效能：我們最聰明的 Flash 模型，針對大規模的 Agentic 任務與程式撰寫任務進行了最佳化。

- Agentic 執行：支援大規模的子 Agent 部署、問題解決以及快速的 Agentic 迴圈。

- 程式撰寫：支援迭代式程式撰寫週期、快速探索與原型設計，以測試替代路徑並動態探索解決方案。

- 長跨度任務：支援大規模的多步驟工作流程與工具使用。

- 思考保留（Thought preservation）：模型會自動在多輪對話中維護中間推理過程。無需進行任何 API 變更。

- 新的預設努力等級：預設的思考努力等級已從 high 改為 medium。詳情請參閱「新的預設努力等級」。

- 改進的低階思考：low 等級現在針對需要較少步驟的程式碼與 Agentic 任務進行了顯著改進，能在更低的延遲與成本下提供優異的品質。

- GA 發布：適用於大規模生產環境的穩定模型。

## 行為變更

新的預設努力等級：medium

預設的思考努力等級現在為 medium，取代了 Gemini 3 Flash Preview 中的 high。medium 等級在廣泛的任務中能產生非常好的結果，同時速度更快且更具成本效益。針對複雜問題，high 等級則會鼓勵模型進行更深度的思考。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1779246395435-iaHIso9qfbQAAIV2vjpg.jpg)

若要覆寫預設值，請在你的設定中調整 `thinking_level`：

```python
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="證明 2 的平方根是無理數。",
    generation_config={"thinking_level": "high"},
)
print(interaction.output_text)
```

提示：建議從 medium 開始，它能為絕大多數任務提供最佳品質。若追求更快速、更低成本且具備強大品質的體驗，請嘗試 low。若遇到複雜推理、高難度數學或困難的程式撰寫挑戰，請切換至 high。若需針對簡單查詢最佳化速度，則可使用 minimal。

思考保留

模型會自動在多輪對話中維護中間推理過程。當對話歷史中存在推理內容時，推理 context 會持續傳遞，這能提升複雜多步驟任務（如迭代式除錯與程式碼重構）的效能。無需進行任何 API 變更：

- Interactions API：思考過程會自動保留。行為無變更。

- GenerateContent API：從 Gemini 3.5 Flash 開始，當對話歷史中存在思考簽名（thought signatures）時，模型會使用先前所有輪次的推理 context。若要啟用此功能，請在 `contents` 中傳遞完整且未經修改的對話歷史（包含思考簽名）。SDK 會自動處理這些內容。

## Gemini 3.x 的參數更新與最佳實踐

以下內容適用於所有 Gemini 3.x 模型，包含 Gemini 3.5 Flash。

- `temperature`、`top_p`、`top_k`：我們強烈建議不要更改預設值。Gemini 3 的推理能力已針對預設設定進行最佳化。

- 請使用 `thinking_level` 取代 `thinking_budget`。

- 函式呼叫（Function calling）回應匹配：`id`、`name` 以及回應計數必須與先前的呼叫相符。

- 多模態函式回應：請將多模態內容包含在函式回應內部，而非外部。

- 函式回應中的內嵌指令：請附加在函式回應文字的末尾，不要作為獨立的部分。

- 減少不必要的工具呼叫：在 Agentic 工作流程中，使用較低的思考等級或透過系統指令（system instructions）來減少工具呼叫。

請參閱下方章節，了解如何更新你的程式碼。

取樣參數（不再建議使用）

對於所有 Gemini 3.x 模型，不再建議使用 `temperature`、`top_p` 與 `top_k`。Gemini 3 的推理能力已針對預設設定進行最佳化。請從所有請求中移除這些參數。

```python
# ⚠️ 移除這些參數（不再建議使用）
generation_config = {
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 40,
}
```

為了確保確定性，我們建議針對你的特定使用情境定義系統指令，並設定明確的規則。

`thinking_budget`（不再建議使用）

在所有 Gemini 3.x 模型中，不再建議使用原始的數值型 `thinking_budget` 參數。請改用字串列舉 `thinking_level`。

```python
# ⚠️ 變更前（不再建議使用）
generation_config = {
    "thinking": {"thinking_budget": 7500},
}

# ✅ 變更後
generation_config = {
    "thinking": {"thinking_level": "medium"},
}
```

可用值：`minimal`、`low`、`medium`（預設）、`high`。

函式呼叫：嚴格回應匹配

Interactions API 對於不匹配的函式回應已經會拋出錯誤。GenerateContent API 尚未強制拋出錯誤，但在大多數情況下，不匹配的回應會導致模型回傳空回應，並帶有 `finish_reason: STOP`。請務必遵守以下慣例：

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1779246395380-iaHIsqKpybEAAvnbQjpg.jpg)

```python
# ✅ 在 function_result 中包含匹配的 call_id 與 name
final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    tools=[my_tool],
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [{"type": "text", "text": json.dumps(result)}],
    }],
)
```

多模態函式回應

我們經常發現客戶將圖片放在函式回應之外。這可能導致非預期的模型行為（例如思考洩漏），並導致輸出品質下降。請改為遵循多模態函式回應 API 文件中的建議，將多模態內容包含在你發送給模型的函式回應部分中。模型可以在下一輪處理這些多模態內容，從而產生更精確的回應。

```python
# ✅ 將多模態內容包含在函式回應中
final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": tool_call.name,
            "call_id": tool_call.id,
            "result": [
                {"type": "text", "text": "instrument.jpg"},
                {
                    "type": "image",
                    "mime_type": "image/jpeg",
                    "data": base64_image_data,
                },
            ],
        }
    ],
)
```

函式回應中的內嵌指令

我們經常發現客戶將額外指令作為後續的部分（Parts）與函式回應一同提供。這可能導致非預期的模型行為（例如思考洩漏），並導致輸出品質下降。請改為將任何額外指令附加在函式回應文字的末尾，並以兩個換行符號分隔。

```python
# ✅ 將內嵌指令附加在函式回應末尾，並以兩個換行符號分隔
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_interaction = client.interactions.create(
    model="gemini-3.5-flash",
    previous_interaction_id=interaction.id,
    tools=[my_tool],
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": result_text}],
        }
    ],
)
```

減少不必要的工具呼叫

如果你遇到工具呼叫過多的情況，以下兩種技巧有助於將其最小化：

1. 從降低思考等級開始（`medium`、`low` 或 `minimal`）：較高的思考等級會鼓勵模型使用更多工具來探索與驗證，因此降低等級可以減少工具呼叫。

1. 加入系統指令：如果調整思考等級後問題依然存在，請考慮使用限制工具使用的提示詞。例如：

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


## 遷移檢查清單

注意：你可以使用程式撰寫 Agent 自動化此遷移過程。如果你使用的程式撰寫 Agent 支援 skill（例如 Antigravity），請安裝 Gemini Interactions API skill 並執行：

```bash
/gemini-interactions-api migrate my app to Gemini 3.5 Flash
```

我們強烈建議更新至 `google-genai` SDK v2.0.0 或更高版本。此版本對 Interactions API 引入了重大變更。詳情請參閱重大變更遷移指南。

## 從 Gemini 3 Flash Preview 遷移

- 更新模型名稱：`gemini-3-flash-preview` → `gemini-3.5-flash`

- 檢閱定價。Gemini 3.5 Flash 比 Gemini 3 Flash Preview 價格更高。詳情請參閱定價頁面。

- 從你的設定中移除 `temperature`、`top_p`、`top_k`（不再建議使用）。

- 將 `thinking_budget` 取代為 `thinking_level`。

- 為所有 `FunctionResponse` 部分加入 `id` 與匹配的 `name`。

- 測試你的提示詞。預設努力等級已從 `high` 改為 `medium`；請驗證品質、速度與成本。

- 思考保留功能現在預設為開啟。推理 context 會在輪次間持續傳遞，這能提升效能，但可能會增加 token 使用量。

- 減少不必要的工具呼叫：從降低思考等級開始（`medium`、`low` 或 `minimal`）；若過度使用情況持續，請加入系統指令來限制工具使用。

- Gemini 3.5 Flash 目前不支援 Computer Use。若有 Computer Use 工作負載需求，請繼續使用 Gemini 3 Flash Preview。

## 從 Gemini 2.5 遷移

除了上述所有項目外，還需注意：

- 簡化提示詞。如果你過去使用思維鏈（chain-of-thought）提示詞工程來強制推理，請改用 `thinking_level: "medium"` 或 `"high"` 搭配更簡單的提示詞。

- 測試 PDF 與媒體工作負載。如果你依賴特定行為來進行密集文件解析，請測試 `media_resolution_high` 設定以確保準確性。遷移至 Gemini 3 預設值可能會增加 PDF 的 token 使用量，但會減少影片的 token 使用量；若請求超過 context window，請明確降低 `media_resolution`。詳情請參閱媒體解析度文件。

- 利用組合工具使用。Google Search、URL context、程式碼執行與自訂函式現在可以在同一個請求中使用。

- 若使用多模態函式回應，請將多模態內容移至函式回應部分內部，而非與其並列。

- 若在函式回應中使用內嵌指令，請將其附加在函式回應文字末尾並以兩個換行符號分隔，而非作為獨立的部分。

- Gemini 3.x 不支援影像分割（Image segmentation）。若有分割工作負載需求，請繼續使用關閉思考功能的 Gemini 2.5 Flash，或使用 Gemini Robotics-ER 1.6。

## Gemini 3 系列功能

Gemini 3.5 Flash 繼承了 Gemini 3 系列的所有功能（Computer Use 除外）。Gemini 3 中引入並延續的功能包括：

- 思考：在 API 呼叫間保留加密的推理 context。在 Interactions API 中為自動執行；在 GenerateContent 中為隱含執行。

- 具備工具的結構化輸出：結合 JSON 模式與內建工具（搜尋、URL context、程式碼執行、函式呼叫）。

- 多模態函式回應：在函式呼叫結果中回傳圖片、音訊與其他媒體。

- 具備圖片處理能力的程式碼執行：執行可處理與產生圖片的程式碼。

- 組合工具使用：在同一個請求中使用內建工具與自訂函式呼叫。

## 後續步驟

- 在 Gemini 3 開發者指南中閱讀更多關於 Gemini 3 系列的資訊。

- 在提示詞工程指南中了解更多關於提示詞設計策略的資訊。

- 開始使用 Gemini 3 Cookbook。

- 了解 Gemini API 最佳化與推論。

## 標籤

Gemini, 新產品, 功能更新, Agent, LLM, Google, Gemini