疑難排解指南

本指南可協助您診斷及解決呼叫 Gemini API 時發生的常見問題。您可能會遇到 Gemini API 後端服務或用戶端 SDK 的問題。我們的用戶端 SDK 採用開放原始碼，位於下列存放區：

如果遇到 API 金鑰問題，請確認您已按照 API 金鑰設定指南正確設定 API 金鑰。

錯誤代碼

如需所有錯誤代碼的完整參考資料，包括 HTTP 狀態碼、生成遭封鎖代碼和內容錯誤代碼，請參閱「API 錯誤」頁面。

重試策略

如果收到錯誤訊息，指出您應重試要求 (例如 429 RESOURCE_EXHAUSTED 或 503 UNAVAILABLE)，建議您採用指數輪詢策略。也就是說，第一次重試前會等待一小段時間，然後逐漸延長後續重試之間的等待時間。

Gemini API 的官方用戶端 SDK (例如 Python SDK) 預設會包含自動重試邏輯，並採用指數輪詢間隔，處理逾時、網路問題和速率限制等暫時性錯誤 (429 和 5xx 狀態碼)。舉例來說，Python SDK 會自動重試暫時性錯誤，最多重試四次，初始延遲時間約為 1 秒，最長延遲時間為 60 秒。

如果您直接發出 REST API 要求或自訂重試邏輯，請按照下列最佳做法操作，提高要求成功的可能性，並避免服務負載過重：

  • 使用指數輪詢：第一次重試前先等待一小段時間 (例如 1 秒)，然後以指數方式增加延遲時間 (例如 2 秒、4 秒、8 秒)。
  • 加入時基誤差：在延遲時間中加入隨機「時基誤差」，避免所有用戶端在完全相同的時間重試。
  • 針對特定錯誤重試：僅針對暫時性錯誤 (例如 429、408 或 5xx) 重試。請勿針對用戶端錯誤 (例如 400 或 403) 重試，因為這類錯誤表示 API 金鑰無效或語法錯誤等問題。
  • 設定重試次數上限：定義重試次數上限，避免無限迴圈。

檢查 API 呼叫是否有模型參數錯誤

確認模型參數符合下列值：

模型參數 值 (範圍)
候選人數 1 到 8 (整數)
溫度 0.0 到 1.0
輸出詞元數量上限 請前往模型頁面，查看所用模型的權杖數量上限。
TopP 0.0 到 1.0

除了檢查參數值，請務必使用正確的 API 版本 (例如 /v1 或 /v1beta)，以及支援所需功能的模型。舉例來說，如果某項功能為 Beta 版，則僅適用於 /v1beta API 版本。

確認你是否使用正確的機型

確認您使用的是模型頁面上列出的支援模型。

使用思考模型時延遲時間較長或詞元用量較高

Gemini 3.x 模型預設會啟用思考功能，因此延遲時間較長或權杖用量較高。已淘汰的 Gemini 2.5 模型也會使用預設的思考方式。

思考型模型會生成內部推論詞元，以提升品質。這個推論過程會增加回應延遲時間和詞元總用量。

如果想縮短延遲時間或盡量降低費用，可以降低思考層級或關閉思考功能。

如需設定詳細資料和程式碼範例，請參閱思考指南。

安全問題

如果系統顯示提示遭到封鎖，是因為 API 呼叫中的安全設定，請根據您在 API 呼叫中設定的篩選器檢查提示。

如果看到 BlockedReason.OTHER，表示查詢或回應可能違反服務條款，或是不受支援。

背誦問題

如果模型因「RECITATION」原因停止生成輸出內容，表示模型輸出內容可能與特定資料相似。如要修正這個問題，請盡量讓提示詞 / 背景資訊獨一無二，並使用較高的溫度參數。

重複權杖問題

如果看到重複的輸出權杖，請嘗試下列建議，減少或消除這些權杖。

說明 原因 建議的解決方法
Markdown 表格中的連字號重複 如果資料表內容很長，模型會嘗試建立視覺上對齊的 Markdown 資料表，不過，Markdown 中的對齊方式並非正確算繪的必要條件。

在提示中加入指令，為模型提供生成 Markdown 表格的具體規範。請提供符合這些規範的範例。你也可以嘗試調整溫度。如要生成程式碼或 Markdown 表格等結構化輸出內容，高溫 (>= 0.8) 的效果較佳。

以下是您可以新增至提示的範例規範，避免發生這種情況：

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.
Markdown 表格中的重複權杖 與重複的連字號類似，這是因為模型嘗試在視覺上對齊表格內容。Markdown 中的對齊方式不影響正確的算繪結果。
  • 請嘗試在系統提示中加入下列指令： 
                FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING.
  • 請嘗試調整溫度。溫度越高 (>= 0.8)，輸出內容就越不會重複。
結構化輸出內容中重複出現換行符 (\n) 如果模型輸入內容包含 Unicode 或逸出序列 (例如 \u 或 \t)，可能會導致重複換行。
  • 檢查提示中是否有禁止使用的逸出序列，並以 UTF-8 字元取代。舉例來說，JSON 範例中的 \u 逸出序列可能會導致模型在輸出內容中也使用這些序列。
  • 指示模型可接受的逸出字元。新增類似這樣的系統指令： 
                In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8.
使用結構化輸出內容時重複的文字 如果模型輸出內容的欄位順序與定義的結構化結構定義不同，可能會導致文字重複。
  • 請勿在提示中指定欄位順序。
  • 將所有輸出欄位設為必填。
重複呼叫工具 如果模型失去先前想法的脈絡，且/或呼叫無法使用的端點，就可能發生這種情況。 引導模型在思考過程中維持狀態。 在系統指示的結尾新增以下內容： 
        When thinking silently: ALWAYS start the thought with a brief
        (one sentence) recap of the current progress on the task. In
        particular, consider whether the task is already done.
重複的文字，不屬於結構化輸出內容 如果模型無法解決要求，就可能會發生這種情況。
  • 如果開啟「思考」功能，請避免在指令中明確指示如何思考問題。只要要求最終輸出內容即可。
  • 請嘗試將溫度調高至 0.8 以上。
  • 新增「簡潔扼要」、「不要重複」或「只提供一次答案」等指令。

遭封鎖或無法使用的 API 金鑰

本節說明如何檢查 Gemini API 金鑰是否遭到封鎖，以及如何解決這個問題。

瞭解金鑰遭封鎖的原因

我們發現部分 API 金鑰可能已公開，為保護您的資料並防止未授權存取，我們已主動封鎖這些已知的洩漏金鑰，避免存取 Gemini API。

確認金鑰是否受影響

如果金鑰外洩，您就無法再透過 Gemini API 使用該金鑰。您可以透過 Google AI Studio 查看是否有任何 API 金鑰遭到封鎖，無法呼叫 Gemini API，並產生新的金鑰。嘗試使用這些金鑰時，您也可能會看到下列錯誤訊息：

Your API key was reported as leaked. Please use another API key.

遭封鎖 API 金鑰的動作

請使用 Google AI Studio，為 Gemini API 整合項目產生新的 API 金鑰。我們強烈建議您檢查 API 金鑰管理做法，確保新金鑰安全無虞，且不會公開。

因安全漏洞而產生意外費用

提交帳單客服案件。 我們的帳單團隊正在處理這項問題，一有最新消息就會盡快通知您。

Google 針對外洩金鑰採取的安全措施

如果我的 API 金鑰外洩，Google 會如何協助保護帳戶，避免費用超出預算和遭到濫用？

  • 我們將逐步調整，日後透過 Google AI Studio 申請新金鑰時，系統預設只會發放 Google AI Studio 專用的 API 金鑰，不會接受其他服務的金鑰。這麼做有助於防範非預期的跨金鑰使用情況。
  • 我們預設會封鎖遭洩漏並搭配 Gemini API 使用的 API 金鑰，協助您避免費用遭到濫用，以及保護應用程式資料。
  • 您可以在 Google AI Studio 中查看 API 金鑰的狀態。如果我們發現您的 API 金鑰外洩，會主動通知您立即採取行動。

提升模型輸出內容品質

如要取得更高品質的模型輸出內容，請嘗試撰寫結構更完整的提示。「提示工程指南」頁面介紹了一些基本概念、策略和最佳做法，協助您入門。

瞭解權杖限制

詳閱權杖指南，進一步瞭解如何計算權杖和權杖限制。

已知問題

  • 這項 API 僅支援部分語言。如果以不支援的語言提交提示，可能會生成非預期的回覆，甚至遭到封鎖。如要瞭解最新支援的語言，請參閱這篇文章。

回報錯誤

如有任何問題，歡迎前往 Google AI 開發人員論壇參與討論。