疑難排解指南

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

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

Gemini API 後端服務錯誤代碼

下表列出您可能遇到的常見後端錯誤代碼，並說明原因和疑難排解步驟：

HTTP 程式碼 狀態 說明 範例 解決方案
400 INVALID_ARGUMENT 要求主體格式錯誤。 要求中有錯別字，或缺少必填欄位。 如需要求格式、範例和支援版本，請參閱 API 參考資料。如果使用舊版端點搭配新版 API 的功能，可能會導致錯誤。
400 FAILED_PRECONDITION 你所在的國家/地區不支援 Gemini API 免費方案。請在 Google AI Studio 中啟用專案的計費功能。 您在不支援免費層級的區域提出要求，且尚未在 Google AI Studio 中啟用專案的帳單。 如要使用 Gemini API，請透過 Google AI Studio 設定付費方案。
403 PERMISSION_DENIED 您的 API 金鑰沒有必要權限。 您使用的 API 金鑰有誤；您嘗試使用微調模型，但未經過適當的驗證。 確認 API 金鑰已設定且具有適當的存取權。請務必完成適當的驗證程序，才能使用微調模型。
404 NOT_FOUND 找不到要求的資源。 系統找不到要求中參照的圖片、音訊或影片檔案。 檢查要求中的所有參數是否適用於您的 API 版本。
429 RESOURCE_EXHAUSTED 你已超過速率限制。 您使用免費層級的 Gemini API 時，每分鐘傳送的要求過多。 確認您未超出模型的速率限制。如有需要，請申請提高配額。
500 INTERNAL Google 發生未預期的錯誤。 輸入內容過長。 減少輸入內容的脈絡，或暫時切換至其他模型 (例如從 Gemini 1.5 Pro 切換至 Gemini 1.5 Flash)，看看是否能正常運作。或是稍後再試一次。如果重試後問題仍未解決，請使用 Google AI Studio 的「提供意見」按鈕回報問題。
503 無法使用 該服務可能暫時超載或關閉。 這項服務的容量暫時不足。 暫時切換至其他模型 (例如從 Gemini 1.5 Pro 切換至 Gemini 1.5 Flash)，看看是否能正常運作。或是稍後再試一次。如果重試後問題仍未解決，請使用 Google AI Studio 的「提供意見」按鈕回報問題。
504 DEADLINE_EXCEEDED 服務無法在期限內完成處理。 提示 (或情境) 過大，無法及時處理。 在用戶端要求中設定較大的「逾時」，即可避免這個錯誤。

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

確認模型參數是否在下列值範圍內：

模型參數 值 (範圍)
候選人數 1 到 8 (整數)
溫度 0.0-1.0
輸出詞元數量上限 使用 get_model (Python) 判斷所用模型的權杖數量上限。
TopP 0.0-1.0

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

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

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

使用 2.5 模型時延遲時間較長或權杖用量較高

如果使用 2.5 Flash 和 Pro 模型時，發現延遲時間較長或權杖用量較高，可能是因為這些模型預設啟用思考功能，以提升品質。如果想優先提升速度或盡量降低成本，可以調整或停用思考功能。

如需指引和程式碼範例，請參閱思考頁面。

安全問題

如果系統顯示提示因 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 僅支援特定語言。如果以不支援的語言提交提示，可能會產生非預期的回覆，甚至遭到封鎖。如需最新資訊，請參閱支援的語言。

回報錯誤

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