疑難排解指南

這份指南可協助您診斷及解決呼叫 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 字元取代。舉例來說，\uJSON 範例中的逸出序列可能會導致模型也在輸出內容中使用這些序列。
  • 指示模型可用的逸出字元。新增類似這樣的系統指令： 
                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 開發人員論壇參與討論。