问题排查指南

本指南可帮助您诊断和解决调用 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 数量上限 使用 模型页面 确定您所用模型的 token 数量上限。
TopP 0.0-1.0

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

检查您是否拥有正确的模型

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

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

延迟时间较长或 token 用量较高通常是因为 Gemini 3.x 模型默认启用了思考功能。已废弃的 Gemini 2.5 模型也使用默认思考功能。

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

如果您优先考虑缩短延迟时间或需要尽可能降低费用，则可以降低思考级别或关闭思考功能。

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

安全问题

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

如果您看到 BlockedReason.OTHER，则查询或响应可能违反 服务 条款或不受支持。

背诵问题

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

重复 token 问题

如果您看到重复的输出 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 表格中重复的 token 与重复的连字符类似，当模型尝试 直观地对齐表格内容时，就会出现这种情况。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 密钥泄露时，我们会主动通知您，以便您立即采取行动。

改进模型输出

如需获得更高质量的模型输出，请探索编写结构化程度更高的提示。 提示工程指南页面 介绍了一些基本概念、策略和最佳实践，可帮助您 入门。

了解 token 限制

请通读我们的 token 指南，以便更好地了解如何 统计 token 及其限制。

已知问题

  • 该 API 仅支持部分精选语言。以语言不受支持的语言提交提示可能会产生意外甚至被屏蔽的响应。如需了解最新信息，请参阅 支持的语言。

提交 bug

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