Gemini 3.8 Flash 開發人員指南

Gemini 3.8 Flash 是我們迄今最聰明、效能最強大的主力模型，在軟體工程、代理程式任務，以及專業領域中關鍵的多步驟推論方面，都比 3.7 Flash 有顯著進步。3.8 Flash 的效能比 3.7 Flash 大幅提升，通常接近高成本前沿模型的表現。

本文將說明 3.8 Flash 的新功能、在 Gemini 模型系列中的定位、如何遷移至 3.8 Flash，以及如何快速開始使用 3.8 Flash。

在 Gemini 系列中扮演什麼角色？

Gemini Flash 系列是 Gemini 3 系列中的主要代理主力模型，可彌補深度推論 Pro 模型與高處理量 Gemini Flash-Lite 模型之間的差距，同時提供高詞元效率和多步驟多模態處理。

與 3.7 Flash 相比，3.8 Flash 的準確度更高，效能也更可靠，但詞元消耗量較高。不過，3.8 Flash 也提供思考程度的努力控制，方便您調整用量。在中等思考等級下，您仍可解決複雜的代理工作，同時減少詞元消耗。您也可以針對延遲時間敏感型工作使用較低的思考層級，完全避免運算負荷。如要提高運算效率，建議使用 3.7 Flash。

模型規格和比較

下表比較 3.8 Flash、3.7 Flash 和 3.1 Pro 的部分規格：

如需支援功能、工具和使用選項的完整清單，請參閱 3.8 Flash 模型頁面。

Gemini 3.8 Flash 的最新功能

下表比較 Gemini 3.8 Flash 和 3.7 Flash 的標準開發人員評估基準：

快速入門導覽課程

開始之前，您必須使用應用程式預設憑證 (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.8-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.8-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

強制性 API 規則和行為慣例

Gemini 3.8 Flash 嚴格遵循下列標準 Gemini 3 系列 API 慣例：

• 已淘汰的取樣參數 (temperature、top_k、top_p)：後端會忽略這些參數。不過，您可以使用 thinking_level (LOW、MEDIUM、HIGH) 和 response_schema 或 json_schema 控制決定性。
• 不支援的參數 (frequency_penalty、presence_penalty、candidate_count)：傳遞 frequency_penalty、presence_penalty 或 candidate_count 會擲回有效的 API 錯誤。從舊版用戶端程式碼中移除。

• 嚴格的函式呼叫規則：FunctionResponse 回合必須嚴格符合前一個 FunctionCall 的 id、name 和執行次數。

  • 多模態素材資源：一律將多模態素材資源放在回應酬載中。
  • 格式和工具前文字：使用 \n\n 格式設定行內指令。如果遇到與工具前文字相關的 Malformed_Function_Call 錯誤，請在呼叫工具前清除前置註解。

  • 如要在呼叫工具前傳遞中間工作附註或狀態更新，請將這些內容包裝在專屬的 update() 函式呼叫中，而非發出原始 XML 或文字：

    {
      "name": "update",
      "description": "Update working notes before tool execution",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "previous_step": {"type": "STRING"},
          "plan": {"type": "STRING"},
          "next_step": {"type": "STRING"}
        },
        "required": ["previous_step", "plan", "next_step"]
      }
    }
    

• 驗證對話順序：

  • 歷史記錄酬載不得以「model」角色對話結尾。
  • 系統不支援預填模型輪次，升級時必須移除。
  • 對話記錄中的空白輪流會自動捨棄，或產生驗證錯誤。

從 3.7 Flash 或 3.6 Flash 升級至 3.8 Flash

如要從 3.7 Flash 或 3.6 Flash 遷移至 3.8 Flash，請按照下列步驟操作：

1. 更新模型 ID：將 API 呼叫中的模型字串變更為 gemini-3.8-flash。
2. 替換推論預算參數：將整數 thinking_budget 設定替換為字串列舉 thinking_level，並設為下列其中一個值：
   • HIGH：建議用於密集視覺問答、瞬間動作偵測 (運動、編輯)，或超過 60 分鐘影片的多步驟推論。
   • MEDIUM：預設思考程度。這個等級最適合用於一般影片問答、講座摘要和片段檢索。
   • LOW：建議用於快速搜尋轉錄稿或擷取基本中繼資料等工作。
3. 移除已淘汰和不支援的參數：
   • 移除 temperature、top_p 和 top_k。
   • 移除 candidate_count、frequency_penalty 和 presence_penalty。
   • 從對話記錄中移除所有預填模型輪次。

開發人員摘要檢查清單

其他資源

• Gemini 3.8 Flash 模型頁面
• 簡介筆記本