疑難排解指南

本指南可協助您診斷及解決呼叫 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 要求傳回 403 PERMISSION_DENIED (「您的專案存取權遭拒」)，或專案狀態在 Google AI Studio 中顯示為「受限」、「無法使用免費方案」、「需要付款」或「無法使用」，請查看下列哪一節適用於您的專案：

Gemini API 免費方案無法使用

並非所有 Google Cloud 專案或帳戶都符合 Gemini API 免費方案的資格。如果專案無法使用免費方案：

  • 在同一專案中建立新的 API 金鑰，無法解決這項錯誤。 Google 會在 Google Cloud 專案層級評估資格。
  • 如要在這項專案中使用 Gemini API，必須連結有效的 Cloud Billing 帳戶，升級至付費 方案。
  • 注意：將專案升級至付費方案，並不會解鎖免費方案配額。Google 會根據 Gemini API 定價，向付費級別用量收取費用，或從符合資格的 Google Cloud 抵免額中扣除。

必須支付 Cloud Billing 帳戶款項

如果專案已連結至 Cloud Billing 帳戶，並顯示「Payment needed」(需要付款) (或傳回 403 PERMISSION_DENIED，指出有未付餘額)：

外洩或遭封鎖的 API 金鑰

如果 403 PERMISSION_DENIED 錯誤狀態指出 API 金鑰遭檢舉外洩或封鎖：

  • 前往 AI Studio API 金鑰頁面，產生新的 API 金鑰並更新應用程式憑證。
  • 請勿直接在用戶端程式碼或公開存放區嵌入 API 金鑰。

專案或帳單帳戶因違反政策而遭停權

如果 Google 因違反政策而停權您的 Google Cloud 雲端專案或 Cloud Billing 帳戶，請檢查相關聯的電子郵件地址。請前往 Google Cloud 控制台查看停權通知，並按照專案停權指南操作。

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 要求新金鑰時，系統會核發 API 金鑰，且預設僅限 Google AI Studio 使用，不接受其他服務的金鑰。這有助於防止任何非預期的跨金鑰使用。
  • 根據預設，我們會封鎖外洩且用於 Gemini API 的 API 金鑰，避免費用和應用程式資料遭到濫用。
  • 您可以在 Google AI Studio 查看 API 金鑰狀態。如果我們發現您的 API 金鑰外洩，會主動通知您，以便您立即採取行動。

改善模型輸出內容

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

瞭解詞元數量上限

請詳閱詞元指南，進一步瞭解如何計算詞元和相關限制。

已知問題

  • 這個 API 僅支援部分語言。如果使用不支援的語言提交提示，可能會產生非預期的回覆，甚至遭到封鎖。如要瞭解最新資訊，請參閱支援的語言。

回報錯誤

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