疑難排解指南

本指南可協助您診斷及解決呼叫 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、402 或 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 開發人員論壇參與討論。