问题排查指南

本指南可帮助您诊断和解决调用 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 会自动重试暂时性错误，最多重试 4 次，初始延迟约为 1 秒，最大延迟为 60 秒。

如果您要发出直接 REST API 请求或自定义重试逻辑，请遵循以下最佳实践，以提高请求成功的可能性，并防止服务过载：

  • 使用指数退避算法：在第一次重试之前等待一小段时间（例如 1 秒），然后以指数方式增加延迟时间（例如 2 秒、4 秒、8 秒）。
  • 添加抖动值：在延迟时间中添加随机“抖动值”，以防止所有客户端在同一时间重试。
  • 针对特定错误重试：仅针对暂时性错误（例如 429、408 或 5xx）重试。请勿针对客户端错误（例如 400、402 或 403）重试，因为这些错误表示存在 API 密钥无效、预付款余额不足或语法错误等问题。
  • 设置重试次数上限：定义重试次数上限，以防止无限循环。

检查 API 调用是否存在模型参数错误

验证您的模型参数是否在以下值范围内：

模型参数 值（范围）
候选数量 1-8（整数）
温度 0.0-1.0
输出 token 数量上限 使用模型页面确定您所用模型的词元数上限。
TopP 0.0-1.0

除了检查参数值之外，还要确保您使用的是正确的 API 版本（例如 /v1 或 /v1beta）以及支持所需功能的模型。例如，如果某项功能处于 Beta 版，则该功能仅在 /v1beta API 版本中可用。

检查您是否拥有合适的模型

验证您使用的是模型页面上列出的受支持模型。

思考模型的延迟时间或 token 用量较高

Gemini 3.x 模型默认启用思考功能，因此通常会出现延迟时间较长或 token 用量较高的情况。已弃用的 Gemini 2.5 模型也使用默认思考。

思考模型会生成内部推理 token，以提高回答质量。此推理过程会增加响应延迟时间和总 token 消耗量。

如果您优先考虑降低延迟时间或需要最大限度地降低费用，可以降低思考级别或关闭思考功能。

如需了解配置详情和代码示例，请参阅思考指南。

安全问题

如果您看到提示因 API 调用中的安全设置而被屏蔽，请根据您在 API 调用中设置的过滤器检查提示。

如果您看到 BlockedReason.OTHER，则表示查询或回答可能违反了服务条款，或者不受支持。

背诵问题

如果您看到模型因 RECITATION 原因而停止生成输出，则表示模型输出可能与某些数据类似。如需解决此问题，请尝试使提示 / 上下文尽可能具有唯一性，并使用更高的温度。

重复词元问题

如果您看到重复的输出 token，请尝试以下建议，以帮助减少或消除这些 token。

说明 原因 建议的解决方法
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 账号关联，并显示需要付款（或返回 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 请求新密钥时，系统会签发默认仅限用于 Google AI Studio 的 API 密钥，并且不接受来自其他服务的密钥。这有助于防止任何意外的跨密钥使用。
  • 默认情况下，我们会屏蔽泄露并与 Gemini API 搭配使用的 API 密钥，以帮助防止滥用费用和应用数据。
  • 您可以在 Google AI Studio 中查看 API 密钥的状态。如果我们发现您的 API 密钥泄露，会主动与您联系，以便您立即采取行动。

改进模型输出

如需获得更高质量的模型输出，请尝试撰写更结构化的提示。提示词工程指南页面介绍了一些基本概念、策略和最佳实践，可帮助您开始使用。

了解 token 限制

请仔细阅读我们的 Token 指南，更好地了解如何统计 token 及其限制。

已知问题

  • 该 API 仅支持部分语言。如果使用语言不受支持的语言提交提示，可能会导致系统生成意外回答，甚至导致回答被屏蔽。如需了解最新动态，请参阅支持的语言。

提交 bug

如果您有任何疑问，请加入 Google AI 开发者论坛参与讨论。