# 问题排查指南

使用本指南可帮助您诊断和解决致电 Gemini API 时出现的常见问题。您可能会遇到来自 Gemini API 后端服务或客户端 SDK 的问题。我们的客户端 SDK 在以下存储库中开源：

* [python-genai](https://github.com/googleapis/python-genai)
* [js-genai](https://github.com/googleapis/js-genai)
* [后下内](https://github.com/googleapis/go-genai)

如果您遇到 API 密钥问题，请验证您是否已按照以下说明正确设置 API 密钥 [API 密钥设置指南](/docs/api-key).

## 错误代码  {% #error-codes %}

有关所有错误代码（包括 HTTP 状态代码、生成阻止代码和内容错误代码）的完整参考，请参阅 [API 错误](/docs/api-errors) 页。

## 重试策略  {% #retry-strategy %}

如果您收到一条错误，指示您应该重试您的请求（例如 `429 RESOURCE_EXHAUSTED` 或 `503 UNAVAILABLE`），我们建议实施指数退避策略。这意味着您在第一次重试之前等待一小段时间，然后逐渐增加后续重试之间的等待时间。

Gemini API的官方客户端SDK，例如 [Python SDK](https://github.com/googleapis/python-genai)，包括默认情况下具有指数退避的自动重试逻辑，用于处理超时、网络问题和速率限制等瞬态错误（`429` 和 `5xx` 状态代码）。例如，Python SDK 自动重试瞬态错误最多四次，初始延迟约为 1 秒，最大延迟为 60 秒。

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

* **使用指数退避：** 在第一次重试之前等待一小段时间（例如，1 秒），然后以指数方式增加延迟（例如，2s、4s、8s）。
* **添加抖动：** 在延迟中添加随机“抖动”，以帮助防止所有客户端同时重试。
* **重试特定错误：** 仅重试暂时性错误（例如 `429`, `408`, 或 `5xx`）。不要重试客户端错误（例如 `400`, `402`, 或 `403`），因为它们表明存在无效的 API 密钥、预付积分耗尽或语法错误等问题。
* **设置最大重试次数：** 定义最大重试次数以防止无限循环。

## 检查您的 API 调用是否存在模型参数错误  {% #check-api %}

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

| **型号参数**   | **值（范围）**                                              |
| ---------- | ------------------------------------------------------ |
| 候选人数       | 1-8（整数，Gemini 3 和 4 不支持）                               |
| 温度         | 0.0-1.0（在 Gemini 3.6+ 和 4 上被忽略；在早期的 Gemini 3 型号上保留默认值） |
| 最大输出 token | 使用 [型号页面](/docs/models) 确定您正在使用的型号的 token 的最大数量。       |
| 顶级P        | 0.0-1.0（在 Gemini 3.6+ 和 4 上被忽略；在早期的 Gemini 3 型号上保留默认值） |

除了检查参数值之外，还要确保您使用的是正确的 [API版本](/api-reference/api-versions) (e.g., `/v1` 或 `/v1beta`）和支持您需要的功能的模型。例如，如果某个功能处于 Beta 版本，则该功能仅在 Beta 版本中可用 `/v1beta` API版本。

## 检查您是否有正确的型号  {% #check-if %}

确认您使用的是我们的列表中列出的受支持型号 [型号页面](/docs/models).

## 更高的延迟或 token 使用思维模型  {% #high-latency-or-token-usage %}

由于 Gemini 3.x 模型默认启用了思考，因此经常会出现较高的延迟或 token 使用情况。已弃用的 Gemini 2.5 模型也使用默认思维。

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

如果你优先考虑降低延迟或者需要最小化成本，你可以降低思维水平或者关闭思维。

有关配置详细信息和代码示例，请参阅 [思维指南](/docs/thinking#thinking-levels).

## 安全问题  {% #safety-issues %}

如果您看到提示由于 API 调用中的安全设置而被阻止，请查看与您在 API 调用中设置的过滤器相关的提示。

如果你看到 `BlockedReason.OTHER`，查询或响应可能违反 [服务条款](/docs/terms) 或以其他方式不受支持。

## 背诵题  {% #recitation-issue %}

如果您看到模型由于 RECITATION 原因而停止生成输出，这意味着模型输出可能类似于某些数据。要解决此问题，请尝试使提示/上下文尽可能独特。对于支持采样参数的早期型号，您还可以使用更高的温度。

{% callout type="note" %}
该 `temperature`, `top_p`, 和 `top_k` 参数控制早期模型如何生成响应。 Gemini 4 和 Gemini 3.6+ 型号忽略自定义值 `temperature`, `top_p`, 和 `top_k` 并返回弃用警告标头（并将返回 `400` 未来版本中的错误）。删除 `temperature`, `top_p`, 和 `top_k` 从您的请求配置。对于早期的 Gemini 3 模型，请将这些参数保留为默认值，以避免推理性能下降。
{% /callout %}

## 重复的 token 问题  {% #repetitive-tokens %}

如果您看到重复的输出 token，请尝试以下建议来帮助减少或消除它们。温度调节仅适用于支持采样参数的早期型号；对于 Gemini 3 和 Gemini 4 型号，请改用提示和系统指令解决方法。

| 说明                   | 原因                                                                          | 建议的解决方法                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Markdown 表格中重复的连字符   | 当模型尝试创建视觉上对齐的 Markdown 表格时，表格内容较长时可能会发生这种情况。然而，Markdown 中的对齐对于正确渲染来说并不是必需的。 | 在提示中添加说明，为模型提供生成 Markdown 表的特定指南。提供遵循这些准则的示例。对于支持采样参数的早期型号，您还可以尝试调整温度（>= 0.8）。以下是一组指南示例，您可以添加到提示中以防止出现此问题： \# Markdown 表格格式 * 分隔线：Markdown 表格必须在标题行下方包含分隔线。每列分隔行只能使用 3 连字符，例如：|---|---|---|。使用更多连字符（例如 ----、-----、------）可能会导致错误。始终使用 |:---|、|---:| 或 |---|在这些分隔符字符串中。例如：|日期 |描述 |与会者| |---|---|---| | 2024-10-26 |年会| 500 | | 2025-01-15 |第一季度规划会议 | 25 | * 对齐：不对齐列。始终使用|---|。对于三列，使用|---|---|---|作为分隔线。对于四列，使用|---|---|---|---|等等。 * 简洁：保持单元格内容简明扼要。 * 切勿用大量空格填充列标题或其他单元格以与其他内容的宽度相匹配。每侧只需要一个空间。例如，始终执行“|列名称|”而不是“|列名|”。多余的空间是浪费。 Markdown 渲染器会自动以视觉上吸引人的形式显示内容。 |
| Markdown 表中重复 token  | 与重复的连字符类似，当模型尝试在视觉上对齐表格内容时，就会发生这种情况。正确渲染不需要 Markdown 中的对齐。                  | 尝试将如下指令添加到系统提示符中：对于表标题，立即添加“|”在表格标题之后。对于支持采样参数的早期模型，请尝试更高的温度 (>= 0.8) 以减少输出的重复次数。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 重复换行符 (`\n`) 在结构化输出中 | 当模型输入包含 unicode 或转义序列时，例如 `\u` 或 `\t`，它可能会导致重复换行。                           | 检查提示中禁止的转义序列并将其替换为 UTF-8 字符。例如， `\u` JSON 示例中的转义序列也可能导致模型在其输出中使用它们。指导模型允许逃逸。添加如下系统指令：在带引号的字符串中，唯一允许的转义序列是 \、\n 和 "。使用 UTF-8. 代替 \u 转义                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 使用结构化输出中的重复文本        | 当模型输出的字段顺序与定义的结构化模式不同时，可能会导致重复文本。                                           | 不要指定提示中的字段顺序。将所有输出字段设为必填。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 重复的工具调用              | 如果模型丢失先前想法的上下文和/或被迫调用不可用的端点，则可能会发生这种情况。                                     | 指示模型在其思维过程中维持状态。将其添加到系统说明的末尾：默默思考时：始终以任务当前进度的简短（一句话）回顾来开始思考。特别要考虑任务是否已经完成。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 不属于结构化输出的重复文本        | 如果模型陷入无法解决的请求，就会发生这种情况。                                                     | 如果开启思考，请避免在说明中明确指示如何思考问题。只需要最后的输出即可。对于支持采样参数的早期型号，请尝试更高的温度 >= 0.8. 添加“简洁”、“不要重复”或“提供一次答案”等说明。                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

## 项目受限或不可用  {% #project-unavailable %}

您的 API 请求可能会返回 `403 PERMISSION_DENIED` （“您的项目已被拒绝访问”）。您的项目状态为 [Google AI Studio](https://aistudio.google.com/) 还可能显示 **需要验证**, **受限**, **免费套餐不可用**, **需要付款**, 或 **不可用**。以下部分描述如何对每种类型进行故障排除。请参阅适用于您的项目的部分：

### 需要项目或帐户验证  {% #verification-required %}

如果您的项目显示 **需要验证** 或返回 `403 PERMISSION_DENIED`
使用 `FREE_TIER_VERIFICATION_REQUIRED`，或者如果 Google AI Studio 在异常活动后要求您验证帐户，请执行以下操作之一：

* 关注 [项目与账号验证](/docs/verification) 使用 Google AI Studio 中的移动设备进行验证。
* [设置结算](/docs/billing#setup-billing) 在不验证设备的情况下使用付费套餐。

### Gemini API 免费套餐不可用  {% #free-tier-unavailable %}

并非所有 Google Cloud 项目或帐户都有资格获得 Gemini API 免费套餐。如果您的项目被限制使用免费套餐：

* **在同一项目中创建新的 API 密钥无法解决该错误。**
  Google 在 Google Cloud 项目级别评估资格。
* **要在该项目中使用 Gemini API，您必须升级到付费层** 通过链接一个活动的 [云账单账户](https://aistudio.google.com/billing).
* 注意：将项目升级到付费层不会解锁免费层配额。 Google 根据以下标准对付费使用量进行计费 [Gemini API 定价](/docs/pricing)，或从符合资格的 Google Cloud 积分中扣除。

### 需要云结算帐户付款  {% #payment-needed %}

如果您的项目已链接到 Cloud Billing 帐号并显示 **需要付款** （或返回 `403 PERMISSION_DENIED` 引用未清余额）：

* 参观 [AI Studio 计费页面](https://aistudio.google.com/billing) 或 [Google Cloud 计费控制台](https://console.cloud.google.com/billing)
  解决任何逾期余额或更新您的付款方式。
* 一旦您的计费帐户恢复良好信誉，您的项目就会自动重新获得 API 访问权限。

### 泄漏或被阻止 API 密钥  {% #api-key-leaked-or-blocked %}

如果 `403 PERMISSION_DENIED` 错误表明您的 API 密钥被报告为泄露或被阻止：

* 前往 [AI Studio API 按键页面](https://aistudio.google.com/apikeys) 生成新的 API 密钥并更新您的应用程序凭据。
* 切勿将 API 密钥直接嵌入客户端代码或公共存储库中。

### 项目或结算帐户政策暂停  {% #policy-suspension %}

如果 Google 因违反政策而暂停您的 Google Cloud 项目或 Cloud Billing 帐号，请检查关联的电子邮件地址。参观 [Google Cloud控制台](https://console.cloud.google.com/) 查看任何暂停通知并遵循 [项目暂停指南](https://cloud.google.com/resource-manager/docs/project-suspension-guidelines).

{% callout type="note" %}
只读元数据端点，例如 `models.list` (`GET /v1beta/models`) 仅验证您的 API 密钥是否存在，而不检查项目级别资格或计费状态。一个 `200 OK` 来自的回应 `models.list` 不保证推理调用 (`generateContent`, `streamGenerateContent`, 或 `interactions`）已为您的项目启用。
{% /callout %}

## 阻塞或不工作 API 密钥  {% #api-keys-not-working %}

本节介绍如何检查您的 Gemini API 密钥是否被阻止以及如何处理。

### 了解密钥被阻止的原因

我们发现了一个漏洞，其中一些 API 密钥可能已被公开暴露。为了保护您的数据并防止未经授权的访问，我们已主动阻止这些已知泄露的密钥访问 Gemini API。

### 确认您的密钥是否受到影响

如果已知您的密钥已泄露，您将无法再将该密钥与 Gemini API 一起使用。您可以使用 [Google AI Studio](/docs/api-key) 查看您的 API 密钥是否被阻止调用 Gemini API 并生成新密钥。尝试使用这些键时，您可能还会看到返回以下错误：

```none
Your API key was reported as leaked. Please use another API key.
```

### 针对被阻止的 API 密钥的操作

您应该使用以下命令为您的 Gemini API 集成生成新的 API 密钥 [Google AI Studio](/docs/api-key)。我们强烈建议您检查您的 API 密钥管理实践，以确保您的新密钥安全且不会公开暴露。

### 由于漏洞而产生的意外费用

[提交计费支持案例](https://console.cloud.google.com/support/chat)。我们的计费团队正在努力解决此问题，我们将尽快通报最新情况。

### 谷歌针对泄露密钥的安全措施

**如果我的 API 密钥泄露，Google 将如何帮助保护我的帐户免遭成本超支和滥用？**

- 当您使用以下方式请求新密钥时，我们将逐步发放 API 密钥 [Google AI Studio](/docs/api-key) 默认情况下仅限于 Google AI Studio 并且不接受来自其他服务的密钥。这将有助于防止任何意外的交叉密钥使用。
- 我们默认阻止泄露并与 Gemini API 一起使用的 API 密钥，有助于防止滥用成本和您的应用程序数据。
- 您将能够在以下位置找到您的 API 密钥的状态： [Google AI Studio](/docs/api-key) 当我们发现您的 API 密钥被泄露时，我们将积极主动沟通并立即采取行动。

## 改进模型输出  {% #improve-model %}

为了获得更高质量的模型输出，请探索编写更结构化的提示。的 [及时的工程指南](/docs/prompting-strategies) 页面介绍了一些基本概念、策略和最佳实践，以帮助您入门。

## 了解 token 限制  {% #understand-token %}

通读我们的 [代币指南](/docs/tokens) 更好地了解如何计算 token 及其限制。

## 已知问题  {% #known-issues %}

* API 仅支持多种选定语言。以不受支持的语言提交提示可能会产生意外甚至被阻止的响应。参见 [模型详细信息页面](/docs/models) 用于更新。

## 提交错误  {% #file-bug %}

加入讨论 [谷歌人工智能开发者论坛](https://discuss.ai.google.dev)
如果您有疑问。
