本指南說明如何將應用程式更新至最新版 Gemini。本指南假設您的應用程式已使用舊版 Gemini。如要瞭解如何在 Gemini Enterprise Agent Platform 中開始使用 Gemini，請參閱 Gemini Enterprise Agent Platform 的 Gemini API 快速入門導覽課程。
本指南不會說明如何將應用程式從 Agent Platform SDK 換成目前的 Google Gen AI SDK。如需相關資訊，請參閱Agent Platform SDK 遷移指南。
我應該會看到哪些變化？
將大多數生成式 AI 應用程式更新至最新版 Gemini 時，只需要稍微修改程式碼或提示詞。不過，部分應用程式可能需要調整提示。如未先使用新版測試提示，很難預測這些變化。建議您先進行全面測試，再完全遷移。如需建立有效提示的訣竅，請參閱提示策略指南。使用提示健康檢查清單找出並修正提示問題。
詞元數報表更新
升級後的基礎架構現在可準確擷取所有要求元件，包括回應結構定義和函式呼叫等複雜中繼資料，因此您可能會發現回報的權杖數量有所增加，這是正常現象。舊版系統先前會低估這類資料。
只有在發生重大變更或使用新的 Gemini 功能時，才需要大幅修改程式碼。
我應該改用哪個 Gemini 模型？
您使用的 Gemini 模型取決於應用程式需求：
| 功能 | 2.5 Pro | 2.5 Flash | 2.5 Flash-Lite | 3 Flash | 3.1 Pro | 3.1 Flash-Lite | 3.5 Flash |
|---|---|---|---|---|---|---|---|
| 發布階段 | 正式發布版 | 正式發布版 | 正式發布版 | 預覽 | 預覽 | 正式發布版 | 正式發布版 |
| 輸入模態 |
|
|
|
|
|
|
|
| 輸出模態 |
|
|
|
|
|
|
|
| 脈絡窗口、詞元總數上限 | 1,048,576 | 1,048,576 | 1,048,576 | 1,048,576 | 1,048,576 | 1,048,576 | 1,048,576 |
| 輸出背景資訊長度 | 65,535 (預設) | 65,535 (預設) | 65,535 (預設) | 65,536 | 65,536 | 65,535 (預設) | 65,535 (預設) |
| 以 Google 搜尋強化事實基礎 | |||||||
| 函式呼叫 | |||||||
| 程式碼執行 | |||||||
| 隱含脈絡快取 | |||||||
| 明確脈絡快取 | |||||||
| 批次預測 | |||||||
| Gemini Live API | |||||||
| 微調 | |||||||
| 延遲時間 | |||||||
| 建議使用的 SDK | Gen AI SDK | Gen AI SDK | Gen AI SDK | Gen AI SDK | Gen AI SDK | Gen AI SDK | Gen AI SDK |
| 計價單位 | 權杖 | 權杖 | 權杖 | 權杖 | 權杖 | 權杖 | 權杖 |
| 淘汰日期 | 2026 年 10 月 16 日後 | 2026 年 10 月 16 日後 | 2026 年 7 月 22 日 |
開始遷移前
開始遷移程序前，請先考量下列事項：
資訊安全、治理和法規核准
盡早取得資訊安全、風險和法規遵循團隊的核准。涵蓋任何特定風險和法規遵循規則，特別是醫療照護和金融等受監管的產業。
位置資訊可用性
Gemini Enterprise Agent Platform 上的 Google 和合作夥伴模型，以及生成式 AI 功能，可透過特定區域和全球端點使用。全球端點涵蓋全球，與單一區域相比，可用性和可靠性更高。
區域端點的適用情形因模型而異。如要瞭解各個模型的詳細資訊，請參閱位置指南。
依模式和權杖化計費的差異
各個 Gemini 模型的價格不同。我們的定價頁面列出了各模型所有模態 (文字、程式碼、圖像、語音等) 的費用。
購買或變更佈建輸送量訂單
如有需要，請購買更多佈建輸送量，或變更現有的佈建輸送量訂單。
監督式微調
最新 Gemini 模型可提供更優質的輸出內容。這可能表示您的應用程式不再需要微調模型。如果您的應用程式使用監督式微調搭配舊版 Gemini 模型，請先使用最新模型測試應用程式，不要進行微調，然後評估結果。
如果選擇使用監督式微調，您無法從舊版 Gemini 遷移現有的微調模型。您需要為新版 Gemini 執行新的微調工作。
微調新的 Gemini 模型時，請先使用預設微調設定。請勿重複使用先前 Gemini 版本的超參數值，因為微調服務已針對最新版本進行最佳化。重複使用舊設定不太可能獲得最佳成效。
迴歸測試
升級至最新版 Gemini 時，您需要進行三種主要類型的迴歸測試：
- 程式碼迴歸測試：從軟體工程和開發人員作業 (DevOps) 的角度進行迴歸測試。這類迴歸測試一律為必要。
-
模型效能迴歸測試：從資料科學或機器學習的角度進行迴歸測試。也就是確保新版 Gemini 模型提供的輸出內容，至少能維持與舊版相同的品質水準。
模型效能迴歸測試是在系統或基礎模型變更時進行的模型評估。包括：
- 離線效能測試：這類測試會在專屬實驗環境中，根據各種模型輸出品質指標，判斷模型輸出內容的品質。
- 線上模型成效測試：這類測試會根據隱含或明確的使用者意見回饋，在線上部署環境中驗證模型輸出內容的品質。
- 負載測試：這類測試會檢查應用程式能否同時處理大量要求。如果應用程式使用佈建輸送量，則必須進行負載測試。
如何遷移至最新版本
以下各節將說明如何遷移至最新版 Gemini。為獲得最佳結果，請依序完成下列步驟。
1. 文件模型評估和測試規定
- 準備好重複執行您首次建構應用程式時進行的任何相關評估，以及之後進行的任何評估。
- 如果目前的評估作業無法完整涵蓋或評估應用程式執行的所有工作，請設計並準備更多評估作業。您可以參考評估劇本和評估配方，瞭解如何開始使用。
- 如果應用程式涉及 RAG、工具使用、複雜的代理工作流程或提示鏈，請確保現有的評估資料可獨立評估每個元件。如果沒有，請收集每個元件的輸入/輸出範例。
- 如果應用程式至關重要，或是屬於較大型的即時系統 (使用者會直接使用)，請加入線上評估。
2. 升級程式碼並執行測試
升級程式碼時，您需要進行三項主要變更：
下列各節將詳細說明這些變更。
升級至 Google Gen AI SDK
如果 Gemini 1.x 應用程式使用 Vertex AI SDK，請改用 Gen AI SDK。如需詳細資料，包括使用 Gen AI SDK 進行類似呼叫的程式碼範例，請參閱 Vertex AI SDK 遷移指南。2026 年 6 月之後發布的 Vertex AI SDK 將不支援 Gemini，且只有 Gen AI SDK 提供新的 Gemini 功能。
強烈建議更新至 google-genai SDK 2.0.0 以上版本，以便使用 Gemini 3.5 Flash 和後續模型的所有新功能。
如果您是 Gen AI SDK 的新手，請參閱「透過 Gen AI SDK 開始使用 Google 生成式 AI」筆記本。
變更 Gemini 通話
更新預測程式碼，使用最新的 Gemini 模型。至少要變更模型端點名稱。
實際程式碼變更內容會因應用程式的建構方式而異，特別是您是否使用 Gen AI SDK 或 Vertex AI SDK。
變更程式碼後，請執行程式碼迴歸測試和其他軟體測試，確保程式碼運作符合預期。這個步驟會檢查程式碼是否正常運作，但不會評估模型回覆的品質。
修正破壞性程式碼變更
- 動態擷取：改用以 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 推出時一併推出的，在此列出是為了提醒你。
取樣參數 (已淘汰)
我們不再建議所有 Gemini 3.x 模型使用 temperature、top_p 和 top_k。模型會自行管理取樣，以獲得最佳結果。從所有要求中移除這些參數。
為盡可能提升確定性，建議您根據特定用途定義系統指令，並明確指定規則。
thinking_budget (已淘汰)
在所有 Gemini 3.x 模型中，我們不再建議使用原始數值 thinking_budget 參數。請改用 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 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。 - 在所有
FunctionResponse部分中新增id和相符的name。 - 測試提示。預設工作量已從
high變更為medium。 - 系統現在預設會保留想法。推理情境會跨輪次延續。
- 調整思考層級或新增系統指令，減少不必要的工具呼叫。
- Gemini 3.5 Flash 目前不支援電腦使用。
- 減少奉承行為：如果
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 建議從所有要求中移除這些參數。 - 檢查系統指令、提示和少量樣本學習範例，找出任何不一致、矛盾或無關的指令和範例。
- 測試更強大的模型。舉例來說，如果您評估的是 Gemini 2.0 Flash-Lite，請試用 Gemini 2.0 Flash。
- 查看自動評估結果，確保結果與人工判斷一致，尤其是使用評估模型的結果。確保評估模型指令清楚、一致且明確。
- 如要改善評估模型指令，請讓多位人員分別測試指令。如果人類對指令的解讀方式不同，並提供不同的判斷結果，表示評估模型指令不夠清楚。
- 微調模型。
- 檢查評估輸出內容，找出顯示特定類型失敗的模式。按模型、類型或類別將失敗分組，可提供更精確的評估資料，方便調整提示來修正這些錯誤。
- 請務必獨立評估不同的生成式 AI 元件。
- 嘗試調整權杖取樣參數。
取得說明
如需協助， Google Cloud 提供多種支援方案，滿足不同的需求，例如全年無休的 24 小時支援、電話支援，以及技術支援經理諮詢服務。詳情請參閱Google Cloud 支援。