本指南說明如何將應用程式更新至最新 Gemini 版本。本指南假設您的應用程式已使用舊版 Gemini。如要瞭解如何在 Gemini Enterprise Agent Platform 中開始使用 Gemini，請參閱「開始使用 Gemini Enterprise Agent Platform」。
本指南不會說明如何將應用程式從 Vertex AI SDK 切換至目前的 Google Gen AI SDK。如需相關資訊，請參閱 Vertex AI SDK 遷移指南。
會有什麼變化？
將大多數生成式 AI 應用程式更新至最新版 Gemini 時，幾乎不需要變更程式碼或提示。不過，部分應用程式可能需要調整提示。如果不先使用新版本測試提示，就很難預測這些變化。建議您先進行完整測試，再全面遷移。如需建立有效提示的訣竅，請參閱提示策略指南。使用提示健康檢查清單，找出並修正提示問題。
詞元數報表更新
升級後的基礎架構現在能準確擷取所有要求元件，包括回覆結構定義和函式呼叫等複雜中繼資料，這些資料在舊版系統中可能未完整計入，因此回報的詞元數可能會增加。
只有在遇到某些破壞性變更，或想使用 Gemini 新功能時，才需要大幅修改程式碼。
我應該遷移至哪個 Gemini 模型？
請根據應用程式需求，選擇合適的 Gemini 模型：
| 功能 | 3.1 Pro | 3.5 Flash-Lite | 3.5 Flash | 3.6 Flash | 3.7 Flash | 3.8 Flash | 4 Argon |
|---|---|---|---|---|---|---|---|
| 發布階段 | 預覽 | 正式發布版 | 正式發布版 | 正式發布版 | 正式發布版 | 正式發布版 | 正式發布版 |
| 輸入模態 |
|
|
|
|
|
|
|
| 輸出模態 |
|
|
|
|
|
|
|
| 脈絡窗口、詞元總數上限 | 1,048,576 | 1,048,576 | 1,048,576 | 1,048,576 | 1,048,576 | 1,048,576 | 1,048,576 |
| 輸出內容脈絡長度 | 65,536 | 65,536 | 65,536 | 65,536 | 65,536 | 65,536 | 1,048,576 |
| 以 Google 搜尋強化事實基礎 | |||||||
| 函式呼叫 | |||||||
| 執行程式碼 | |||||||
| 隱含脈絡快取 | |||||||
| 明確脈絡快取 | |||||||
| 批次推論 | |||||||
| Gemini Live API | |||||||
| 微調 | |||||||
| 延遲時間 | |||||||
| 淘汰日期 | 2027 年 7 月 21 日或之後 | 2027 年 5 月 19 日或之後 | 2026 年 11 月 19 日 | 2027 年 1 月 28 日 |
開始遷移前的準備
開始遷移程序前，請考量下列事項：
資訊安全、治理和法規核准
盡早取得資訊安全 (InfoSec)、風險和法規遵循團隊的核准。涵蓋任何特定風險和法規遵循規則，特別是醫療保健和金融等受監管的產業。
位置資訊可用性
如要使用 Gemini Enterprise Agent Platform 上的 Google 和合作夥伴模型，以及生成式 AI 功能，請透過特定區域端點和全球端點存取。全球端點涵蓋全世界，與單一區域相比，可用性和可靠性更高。
區域端點的可用性因模型而異。如要進一步瞭解各個模型，請參閱位置指南。
依模式和權杖化計費的差異
每個 Gemini 模型的定價不盡相同。我們的定價頁面列出了各模型所有模態 (文字、程式碼、圖片、語音等) 的費用。
購買或變更佈建輸送量訂單
如有需要，請購買更多已佈建的處理量，或變更現有的已佈建處理量訂單。
監督式微調
最新 Gemini 模型的輸出內容品質更佳。這可能表示您的應用程式不再需要微調模型。如果您的應用程式使用監督式微調搭配舊版 Gemini 模型，請先使用最新模型測試應用程式，不要進行微調，然後評估結果。
如果選擇使用監督式微調，您無法從舊版 Gemini 遷移現有的微調模型。您必須為新版 Gemini 執行新的調整工作。
微調新的 Gemini 模型時，請先使用預設微調設定。請勿重複使用舊版 Gemini 的超參數值，因為調整服務已針對最新版本進行最佳化。沿用舊設定不太可能獲得最佳成效。
迴歸測試
升級至最新版 Gemini 時，您需要進行三種主要類型的迴歸測試：
- 程式碼迴歸測試：從軟體工程和開發人員作業 (DevOps) 的角度進行迴歸測試。這類迴歸測試一律為必要。
-
模型效能迴歸測試：從資料科學或機器學習的角度進行迴歸測試。也就是說，新版 Gemini 模型提供的輸出內容，至少要維持與舊版相同的品質水準。
模型效能迴歸測試是在系統或基礎模型變更時進行的模型評估。包括：
- 離線效能測試：這類測試會在專屬實驗環境中，根據各種模型輸出內容品質指標，判斷模型輸出內容的品質。
- 線上模型成效測試：這類測試會根據使用者隱性或顯性意見回饋，在線上部署環境中驗證模型輸出內容的品質。
- 負載測試：這類測試會檢查應用程式能否同時處理大量要求。使用佈建輸送量的應用程式必須進行負載測試。
如何遷移至最新版本
以下各節將概述遷移至最新 Gemini 版本的步驟。為獲得最佳結果，請依序完成這些步驟。
1. 記錄模型評估和測試需求
- 準備好重複執行您在首次建構應用程式時進行的任何相關評估，以及之後進行的任何評估。
- 如果目前的評估作業無法完整涵蓋或評估應用程式執行的所有工作，請設計並準備更多評估作業。您可以參考評估教戰手冊和評估方法，瞭解如何著手。
- 如果應用程式涉及 RAG、工具使用、複雜的 Agentic Workflows 或提示詞鏈結，請確保現有的評估資料可獨立評估每個元件。如果沒有，請為每個元件收集輸入/輸出範例。
- 如果應用程式至關重要，或是大型面向使用者即時系統的一部分，請加入線上評估。
2. 升級程式碼並執行測試
升級程式碼需要進行三項主要變更：
以下各節將進一步說明這些異動。
升級至 Google Gen AI SDK
如果 Gemini 1.x 應用程式使用 Vertex AI SDK，請改用 Google Gen AI SDK。如需詳細資料，包括使用 Google Gen AI SDK 進行類似呼叫的程式碼範例，請參閱 Vertex AI SDK 遷移指南。2026 年 6 月之後發布的 Vertex AI SDK 不支援 Gemini，且 Google Gen AI SDK 才會提供新的 Gemini 功能。
強烈建議您更新至 google-genai SDK 2.0.0 以上版本，以便使用 Gemini 3.5 Flash 和後續模型的所有新功能。
如果您是第一次使用 Google Gen AI SDK，請參閱這份筆記本，瞭解如何透過 Google Gen AI SDK 開始使用 Google 生成式 AI。
變更 Gemini 通話
更新預測程式碼，使用最新的 Gemini 模型。至少要變更模型端點名稱。
實際的程式碼變更會因應用程式的建構方式而異，尤其是您是否使用 Google Gen AI SDK 或 Vertex AI SDK。
變更程式碼後，請執行程式碼迴歸測試和其他軟體測試，確保程式碼能正常運作。這個步驟會檢查程式碼是否正常運作，但不會檢查模型回覆的品質。
修正破壞性程式碼變更
- 動態擷取：改用以 Google 搜尋強化事實基礎。這項功能需要 Google Gen AI SDK，Vertex AI SDK 不支援。
- 內容篩選器：請留意預設內容篩選器設定。如果程式碼依賴已變更的預設值，請修改程式碼。
Top-K權杖取樣參數：gemini-1.0-pro-vision之後的模型不支援變更Top-K參數。- 思考型：Gemini 3 Pro 和後續模型使用
thinking_level參數，而非thinking_budget。詳情請參閱「控制模型思考」。 - 思考簽章：對於 Gemini 3 Pro 和後續模型，如果某個回合應有思考簽章，但未提供，模型會傳回錯誤，而非警告。請參閱「想法簽名」。
- 媒體解析度和符記化：Gemini 3 Pro 和後續版本模型會使用媒體符記化的可變序列長度，而非 Pan and Scan，並為圖片、PDF 和影片提供新的預設解析度和符記費用。請參閱「圖像解讀」和「影片解讀」。
- 用量中繼資料：如果是 Gemini 3 Pro 和後續版本模型，系統會將
usage_metadata中的 PDF 權杖計數回報為IMAGE模態，而非DOCUMENT。 - 影像分割：Gemini 3 Pro 和後續模型不支援影像分割。
- 多模態函式回覆：Gemini 3 Pro 和後續模型支援在函式回覆中加入圖片和 PDF 資料。請參閱「多模態函式回覆」。
- PDF 處理：對於 Gemini 3 Pro 和後續模型，處理掃描的 PDF 時，預設不會使用 OCR。
在這個步驟中，請只專注於程式碼變更。您可能需要稍後再進行其他變更，但請等到開始評估後再進行。評估完成後，請根據評估結果考慮進行下列調整：
- 如果從動態擷取功能改用這項功能，您可能需要調整系統指令，控管 Google 搜尋的使用時機 (例如
"Only generate queries for the Google Search tool if the user asks about sports. Don't generate queries for any other topic.")。不過，請先評估再變更提示。 - 如果使用
Top-K參數，請調整其他詞元取樣參數 (例如Top-P)，以取得類似結果。
3. 執行離線評估
重複您在首次開發及發布應用程式時執行的評估、自此之後進行的任何離線評估，以及您在步驟 1 中發現的任何額外評估。如果您仍認為評估結果無法完全涵蓋應用程式的範圍，請進行進一步評估。
如果沒有自動執行離線評估的方法，建議使用 Gen AI 評估服務。
如果應用程式使用微調功能，請先執行離線評估，再使用最新版本 Gemini 重新調整模型。最新模型可提供更優質的輸出內容，因此您的應用程式可能不再需要微調模型。
4. 評估結果並調整提示和超參數
如果離線評估結果顯示應用程式成效不佳，請持續改善應用程式，直到成效與舊版模型相當。做法如下：
- 反覆修正提示，提升成效 (「爬坡法」)。如果您不熟悉爬坡法，請參閱 Vertex Gemini 爬坡法線上訓練。Gemini Enterprise Agent Platform 提示最佳化工具 (筆記本範例) 也能提供協助。
- 如果應用程式受到動態檢索和 Top-K 破壞性變更的影響，請嘗試調整提示和權杖取樣參數。
5. 執行負載測試
如果應用程式需要一定的最低處理量，請執行負載測試，確保最新版本應用程式符合處理量需求。
負載測試必須在線上評估之前進行，因為線上評估會將模型暴露在實際流量中。請使用現有的負載測試工具和檢測設備完成這個步驟。
如果應用程式已符合處理量需求，請考慮使用佈建輸送量。您需要額外的短期佈建輸送量來進行負載測試，而目前的佈建輸送量訂單則用於處理正式版流量。
6. (選用) 執行線上評估
只有在離線評估顯示 Gemini 輸出內容品質良好，且應用程式需要線上評估時，才應進行線上評估。
線上評估是線上測試的一種。請盡量使用貴機構現有的工具和方法進行線上評估。例如：
您也可以在應用程式中加入新的意見回饋和評估功能，進行線上評估。不同的應用程式需要不同的意見回饋方法。例如：
- 在模型輸出內容旁新增「喜歡」和「不喜歡」按鈕，並比較舊模型與最新 Gemini 模型的評分。
- 並排顯示舊模型和最新模型的輸出內容，請使用者挑選偏好的版本。
- 追蹤使用者覆寫或手動調整舊版模型輸出內容的頻率，與最新模型進行比較。
如要使用這些意見回饋方法，通常需要同時執行最新版 Gemini 和現有版本。這種平行部署有時稱為「影子模式」或「藍綠部署」。
如果線上評估結果與離線評估結果差異很大，表示離線評估未擷取到實際環境或使用者體驗的重要層面。根據線上評估結果，建立新的離線評估，涵蓋落差部分，然後返回步驟 3。
如果您使用佈建輸送量，可能需要購買額外的短期佈建輸送量，才能繼續滿足線上評估使用者的輸送量需求。
7. 部署至正式環境
如果評估結果顯示最新 Gemini 模型的效能與舊版模型相當或更佳，請將現有應用程式版本替換為新版本。請按照貴組織的標準程序，將模型部署至正式環境。
如果您使用佈建輸送量，請將佈建輸送量訂單變更為所選 Gemini 模型。如果應用程式是逐步推出，請使用短期佈建輸送量，滿足兩種不同 Gemini 模型的處理量需求。
Gemini 3.x 的參數更新和最佳做法
以下內容適用於所有 Gemini 3.x 模型，包括 Gemini 3.5 Flash。這些功能在 Gemini 3 中推出，此處列出僅供參考。
取樣參數 (已淘汰)
temperature、top_p 和 top_k 不再建議用於所有 Gemini 3.x 模型。模型會自行管理取樣，以獲得最佳結果。從所有要求中移除這些參數。
為盡可能提高確定性，建議您根據特定用途，定義具有明確規則的系統指令。
thinking_budget (已淘汰)
不建議在所有 Gemini 3.x 模型中使用原始數值 thinking_budget 參數，且在 Gemini 4 模型中會傳回 HTTP 400 驗證錯誤。請改用 thinking_level 字串列舉。
函式呼叫：嚴格比對回覆
API 尚未發生錯誤，但回應不一致會導致模型在大多數情況下傳回空白回應，並附上 finish_reason: STOP。請務必遵循下列慣例：
- 包含
id：每個FunctionResponse都必須包含對應FunctionCall的id。 - 比對
name：回應中的name必須與呼叫中的name相符。 - 相符次數：針對收到的每個
FunctionCall，傳回正好一個FunctionResponse。
多模態函式回覆
在回應函式呼叫時提供多模態內容 (例如圖片) 時，請將內容放在函式回應部分內，而非外部。這可避免模型出現非預期行為，例如洩漏思考過程。
內嵌指令和函式回應
如需在函式回覆中提供平台指令，請將指令附加在函式回覆文字的結尾，並以兩個換行符號分隔，而非分成不同部分。
減少不必要的工具呼叫
如果工具呼叫次數過多，請按照下列步驟操作：
1. 降低思考程度 (medium、low 或 minimal)。
2. 新增系統指令，限制工具的使用方式 (例如 "You have a
limited action budget of <n> tool calls. Use them efficiently.")。
遷移工作檢查清單
從舊版模型遷移時，請參考下列檢查清單：
從 Gemini 3.1 Pro 預先發布版到 Gemini 4 Argon
- 更新模型名稱：
gemini-3.1-pro-preview→gemini-4-argon(或 Fairwind 核准的網路安全工作負載為gemini-4-argon-cyber-permissive)，並升級至最新版 Google Gen AI SDK (Python 為google-genai >= 2.30.1)。 - 請注意，輸入、思考和輸出內容會共用 1,048,576 個詞元的脈絡窗口，且單一要求的輸出上限為 65,536 個詞元 (非串流直接 HTTP 呼叫為 32,768 個詞元)。如要單次輸出最多 1,048,576 個詞元，請在
GenerateContent設定長解碼 (如果max_output_tokens設為大於 65,536，或在自訂迴圈中使用continuation_token，Google Gen AI SDK 會自動處理)。 - 將
thinking_budget和thinking_level="MINIMAL"(兩者都會傳回 HTTP400錯誤) 替換為設為LOW、MEDIUM(gemini-4-argon上的預設值) 或HIGH(gemini-4-argon-cyber-permissive上的預設值) 的thinking_level。 - 移除明確的
cached_content呼叫；將靜態提示詞前置字元 (6,144 個以上符記) 放在提示詞開頭，即可自動進行隱含快取。 - 移除
temperature、top_p、top_k、frequency_penalty、presence_penalty、candidate_count和預先填入的model回合。 - 如需完整詳細資料，請參閱「從 Gemini 3.1 Pro 遷移」和「Gemini 4 Argon 開發人員指南」。
來自 Gemini 3 Flash 預先發布版
- 更新模型名稱：
gemini-3-flash-preview→gemini-3.5-flash。 - 查看定價。Gemini 3.5 Flash 的費用高於 Gemini 3 Flash 預先發布版。
- 從設定中移除
temperature、top_p、top_k。 - 將
thinking_budget替換為thinking_level。 - 測試提示。預設工作量已從
high變更為medium。 - 思維保留功能現在預設為開啟。推理情境會跨輪次延續。
- 調整思考等級或新增系統指令，減少不必要的工具呼叫。
- 減少諂媚行為：如果
gemini-3.5-flash開始出現諂媚跡象，可以嘗試透過系統指令加入下列內容，減少這種行為：- Keep your responses concise. - Provide a summary of your work when you end your turn. Ground your response in the work you did. Keep your tone professional and avoid overconfident language, bragging, or overclaiming success. - AVOID using superlatives such as "perfectly", "flawlessly", "100% correct", "Summary of Accomplishments" etc. to summarize your work for the user. Be humble. - AVOID over-the-top politeness or complimenting the user excessively. - Format your responses in github-style markdown.
Gemini 2.5
- 測試 PDF 和文件工作負載。PDF 的詞元用量可能會增加。
- 簡化提示。請嘗試使用
thinking_level: "medium"或"high"，並搭配較簡單的提示，而非複雜的思維鏈提示。 - 結合使用多種工具 (搜尋、網址背景資訊、執行程式碼、函式)。
- 將多模態內容移至函式回覆部分。
- 在函式回應文字中附加內嵌指令。
提高模型效能
遷移時，請參考下列提示，讓所選 Gemini 模型發揮最佳效能：
- 所有 Gemini 3 模型皆已淘汰取樣參數 (
temperature、top_p和top_k)。模型會自行管理取樣，以達到最佳效果。Google 建議從所有要求中移除這些參數。 - 檢查系統指令、提示和少量樣本學習範例，看看是否有不一致、矛盾或不相關的指令和範例。
- 測試更強大的模型。舉例來說，如果評估的是 Flash-Lite 模型，請改用 Flash 或 Pro 模型。
- 查看自動評估結果，確保結果與人工判斷一致，尤其是使用評估模型的結果。確保評估模型指令清楚、一致且明確。
- 如要改善評估模型指令，請讓多位人員分別測試指令。如果人類對指令的解讀不同，並提供不同的判斷，代表您的評判模型指令不夠明確。
- 微調模型。
- 檢查評估輸出內容，找出特定類型失敗的模式。依模型、類型或類別將失敗分組，可提供更精確的評估資料，方便您調整提示來修正這些錯誤。
- 請務必獨立評估不同的生成式 AI 元件。
- 嘗試調整詞元取樣參數。
取得說明
如需協助， Google Cloud 提供多種支援方案，滿足不同的需求，例如全年無休的 24 小時支援、電話支援，以及技術支援經理諮詢服務。詳情請參閱「Google Cloud 支援」。