问题排查指南

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

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

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

模型形参 值（范围）
候选对象数量 1-8（整数）
温度 0.0-1.0
输出 token 数量上限 使用 get_model (Python) 确定所用模型支持的词元数上限。
TopP 0.0-1.0

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

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

确认您使用的是我们模型页面上列出的受支持型号。

2.5 模型延迟时间更长或令牌用量更高

如果您发现 2.5 Flash 和 Pro 模型的延迟时间或令牌用量更高，这可能是因为它们默认启用了思考功能，以提升质量。如果您优先考虑速度或需要尽可能降低费用，可以调整或停用思考功能。

如需相关指南和示例代码，请参阅思考页面。

安全问题

如果您看到系统提示因 API 调用中的安全设置而阻止了提示，请根据您在 API 调用中设置的过滤条件检查该提示。

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

朗诵问题

如果您发现模型因“背诵”原因而停止生成输出，则表示模型输出可能与某些数据相似。如需解决此问题，请尽量使提示 / 上下文保持唯一性，并使用较高的温度。

重复令牌问题

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

说明 原因 建议的解决方法
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 仅支持部分精选语言。以不支持的语言提交提示可能会生成意外甚至被屏蔽的回答。如需了解最新信息，请参阅支持的语言。

提交 bug

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