问题排查指南

本指南可帮助您诊断和解决调用 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 2.5 Pro 切换到 Gemini 2.5 Flash），看看是否有效。或者，稍等片刻，然后重试您的请求。如果重试后问题仍然存在，请使用 Google AI Studio 中的发送反馈 按钮报告该问题。
503 UNAVAILABLE 服务可能暂时过载或关闭。 服务暂时容量不足。 暂时切换到其他模型（例如从 Gemini 2.5 Pro 切换到 Gemini 2.5 Flash），看看是否有效。或者，稍等片刻，然后重试您的请求。如果重试后问题仍然存在，请使用 Google AI Studio 中的发送反馈 按钮报告该问题。
504 DEADLINE_EXCEEDED 服务无法在截止期限内完成处理。 您的提示（或上下文）过大，无法及时处理。 在客户端请求中设置较大的“超时”时间，以避免此错误。

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

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

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

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

检查您是否使用了正确的模型

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

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

如果您发现 2.5 Flash 和 Pro 模型的延迟时间较长或 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 请求新密钥时，系统会发出 API 密钥，该密钥默认仅限于 Google AI Studio，并且不接受来自其他服务的密钥。 这有助于防止任何意外的跨密钥使用。
  • 我们默认屏蔽泄露并与 Gemini API 搭配使用的 API 密钥，以帮助防止滥用费用和您的应用数据。
  • 您将能够在 Google AI Studio 中找到 API 密钥的状态，并且当我们发现您的 API 密钥泄露时，我们会主动通知您，以便您立即采取行动。

改进模型输出

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

了解 token 限制

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

已知问题

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

提交 bug

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