常见问题解答和问题排查

本页提供了有关 Gemini API 和 Firebase AI Logic SDK 的常见问题解答 (FAQ) 和问题排查信息。

如需排查错误代码，请参阅错误代码。

状态信息中心

• Firebase AI Logic

• Gemini Developer API

• Vertex AI Gemini API（Vertex Gemini API 和 Vertex Imagen API）

常规常见问题解答

为什么名称从“Vertex AI in Firebase”更改为“Firebase AI Logic”？

2024 年初，我们推出了一组 Firebase 客户端 SDK，这些 SDK 可以使用 Vertex AI Gemini API 以及 Firebase 代理网关来保护该 API 免遭滥用，并实现与其他 Firebase 产品的集成。我们将产品命名为“Vertex AI in Firebase”，这个产品名称准确地描述了当时产品的可用使用场景。

不过，自那以后，我们扩展了产品的功能。例如，截至 2025 年 5 月，我们现在支持 Gemini Developer API，包括能够通过与 Firebase App Check 的集成来保护 Gemini Developer API 免遭滥用。

因此，“Vertex AI in Firebase”这一名称已无法准确体现我们产品扩展后的范围。因此，新名称“Firebase AI Logic”能更好地反映我们不断发展的特征集，并让我们能够在未来继续扩展产品和服务！

请查看迁移指南，确保您能使用 Firebase AI Logic 的所有最新功能（还可以选择开始使用 Gemini Developer API）。

使用 Gemini Developer API 和 Vertex AI Gemini API 有什么区别？

下表列出了两个“Gemini API”提供程序（无论您如何访问它们）之间的一些重要区别：

	Gemini Developer API	Vertex AI Gemini API
价格	免费 Spark 定价方案和随用随付 Blaze 定价方案均提供此功能^1	始终需要采用随用随付 Blaze 定价方案^1（与 Firebase AI Logic 搭配使用时）
速率限制（配额）	明确的速率限制	使用动态共享配额 (DSQ)，该区域中使用相应模型的所有用户共享该配额。预配吞吐量 (PT) 可用。
指定访问模型的位置	API 不支持	受 API 支持
支持 Cloud Storage 网址	API 不支持 ^2	公开文件和受 Firebase Security Rules 保护的文件
支持 YouTube 网址和浏览器网址	仅限 YouTube 网址	YouTube 网址和浏览器网址

¹ 这两个 API 提供商的随用随付价格不同（如需了解详情，请参阅其各自的文档）。

² Gemini Developer API 的 Files API 不受 Firebase AI Logic SDK 支持。

下表列出了两个“Gemini API”提供商提供的常见功能。此表专门适用于使用 Firebase AI Logic 客户端 SDK 的情况。

功能	Gemini Developer API	Vertex AI Gemini API
Gemini 型号支持	支持	支持
支持 Gemini Live API	支持	支持
与 Firebase App Check 集成	支持	支持
与 Firebase Remote Config 兼容	支持	支持
支持在 Firebase 控制台中进行 AI 监控	支持	支持

注意： 使用 Firebase AI Logic 时，不支持以下功能：上下文缓存、模型微调、嵌入生成和语义检索。

我可以同时使用 Gemini Developer API 和 Vertex AI Gemini API 吗？

可以。您可以在 Firebase 项目中同时启用“Gemini API”提供程序，并且可以在应用本身中使用这两个 API。

如需在代码中切换 API 提供商，只需确保您已在代码中相应地设置后端服务。

重要提示： 如果您的项目采用的是随用随付 Blaze 定价方案（使用 Vertex AI Gemini API 以及 Firebase 和 Google Cloud 生态系统中的其他几种产品需要采用此方案），请注意，对 Gemini Developer API 的所有调用均按随用随付方式收费。

需要哪些 API？如何启用这些功能？

选择您的 Gemini API 提供方以查看特定于提供方的内容 Gemini Developer API Vertex AI Gemini API

如需将 Firebase AI Logic SDK 与 Gemini Developer API 搭配使用，您的项目必须启用以下两个 API：

• Gemini Developer API（generativelanguage.googleapis.com 人）
• Firebase AI Logic API (firebasevertexai.googleapis.com)

您应使用 Firebase 控制台启用以下两个 API：

1. 在 Firebase 控制台中，前往 Firebase AI Logic 页面。

2. 点击开始使用。

3. 选择即可开始使用 Gemini Developer API。

   系统随即会启动引导式工作流，以便您启用这两个 API。控制台还会生成 Gemini API 密钥，并将 Firebase AI Logic API 添加到 Firebase API 密钥的许可名单中。

如何在 Firebase 项目中停用 API？

对于 Firebase AI Logic，我们会尽力简化 Firebase 项目的设置，以便您尽可能轻松地使用所选的 Gemini API 提供商。这包括在特定流程（例如 Firebase 控制台中的引导式工作流）期间，在 Firebase 项目中启用必需的 API。

不过，如果您决定不使用 Firebase AI Logic 或任何 Gemini API 提供商，则可以在 Firebase 项目中停用关联的 API。

警告： 停用 API 之前，请注意以下事项：

• 如果您停用必需的 API，并且您的应用中有一项功能依赖于该 API，那么当您停用该 API 时，该功能将在您应用的所有版本中失效。
• 如果您在 Firebase 项目中停用 Gemini Developer API 或 Vertex AI API，则会停用该 API 的所有使用情形，而不仅仅是 Firebase AI Logic。确认您未使用该 API 的其他原因（例如使用 Genkit、GenAI 服务器端 SDK、ADK 等）。

在停用 API 之前，您可以在 Google Cloud 控制台中相应 API 的页面上查看其使用情况（请参阅下文中的说明，找到指向每个 API 页面的链接）。

停用与使用 Gemini Developer API 相关的 API

如需将 Firebase AI Logic SDK 与 Gemini Developer API 搭配使用，您的项目必须启用以下两个 API：

• Gemini Developer API（generativelanguage.googleapis.com 人）
• Firebase AI Logic API (firebasevertexai.googleapis.com)

如果您想完全停止使用 Firebase AI Logic：

1. 点击上方的每个 API 链接，前往 Google Cloud 控制台中的相应 API 页面，然后点击管理。

2. 查看指标标签页，验证 API 是否未被使用。

3. 如果您仍想停用该 API，请点击页面顶部的停用 API。

4. 从可以使用您的 Firebase API 密钥调用的所选 API 列表中移除 Firebase AI Logic API。请查看有关 Firebase API 密钥许可名单的这篇常见问题解答，了解如何修改此列表。

如果您想继续使用 Firebase AI Logic，但改用 Vertex AI Gemini API，请执行以下操作：

1. 前往 Google Cloud 控制台中的 Gemini Developer API 页面，然后点击管理。

2. 查看指标标签页，验证 API 是否未被使用。

3. 如果您仍想停用该 API，请点击页面顶部的停用 API。

4. 确保您的项目已启用 Vertex AI Gemini API 所需的 API。

停用与使用 Vertex AI Gemini API 相关的 API

如需将 Firebase AI Logic SDK 与 Vertex AI Gemini API 搭配使用，您的项目必须启用以下两个 API：

• Vertex AI API (aiplatform.googleapis.com)
• Firebase AI Logic API (firebasevertexai.googleapis.com)

如果您想完全停止使用 Firebase AI Logic：

1. 点击上方的每个 API 链接，前往 Google Cloud 控制台中的相应 API 页面，然后点击管理。

2. 查看指标标签页，验证 API 是否未被使用。

3. 如果您仍想停用该 API，请点击页面顶部的停用 API。

4. 从可以使用您的 Firebase API 密钥调用的所选 API 列表中移除 Firebase AI Logic API。请查看有关 Firebase API 密钥许可名单的这篇常见问题解答，了解如何修改此列表。

如果您想继续使用 Firebase AI Logic，但改用 Gemini Developer API，请执行以下操作：

1. 前往 Google Cloud 控制台中的 Vertex AI API 页面，然后点击管理。

2. 查看指标标签页，验证 API 是否未被使用。

3. 如果您仍想停用该 API，请点击页面顶部的停用 API。

4. 确保您的项目已启用 Gemini Developer API 所需的 API。

哪些模型可与 Firebase AI Logic SDK 搭配使用？

请参阅支持的型号列表。 我们会经常向 SDK 添加新功能，因此请定期查看此常见问题解答以了解最新动态（以及版本说明、博客和社交媒体帖子）。

所有 Imagen 模型均已弃用，并将于 2026 年 6 月 24 日关停。作为替代方案，您可以将应用迁移为使用 Gemini 图片模型（“Nano Banana”模型）。

• Gemini Developer API

  • Gemini 和 Imagen 基础模型。

    请注意，Gemini Developer API（无论以何种方式访问）仅支持特定的稳定 Imagen 模型。

• Vertex AI Gemini API

  • Gemini 和 Imagen 基础模型。

• 无论您选择哪个 Gemini API 提供商

  • Firebase AI Logic 不支持以下内容：

    • 非基础 Gemini 模型（例如 PaLM 模型、经过调优的模型或基于 Gemma 的模型）。

    • 较旧的 Imagen 型号或 imagen-3.0-capability-001。

模型关闭（停用）后该怎么办？

发布稳定版模型后，我们会尽力确保该模型至少在一年内可用，然后才会停用该模型。

注意： 当某个模型发布稳定版本后，该模型的所有实验版和预览版通常会在几天或几周内关闭（弃用）。此外，已宣布关闭的模型版本通常仅限于现有项目或之前使用过该模型的项目。

在哪里可以找到型号的停产日期？

您可以通过以下几种方式查找型号的停产日期：

• 发布时：我们在 Gemini API 提供商文档以及 Firebase 文档（请参阅支持的模型页面）中的多个位置列出了每个模型的预期关闭日期。

• 随着停用日期临近：Google 会向相应的项目成员发送电子邮件，并在版本说明和其他渠道中发布有关即将停用的提醒（例如，提醒 Gemini 1.5 和 1.0 稳定版模型的停用日期）。

如果您使用的型号即将停用，该怎么办？

1. 找到合适的当前支持的模型及其模型名称。

2. 在关停日期之前更新应用使用的模型名称；否则，对该模型的所有请求都会失败，并返回 404 错误。

   • 您可以在初始化期间创建 GenerativeModel、LiveModel 或 ImagenModel 实例时设置模型名称。请务必查看下文中有关使用 Firebase Remote Config 的重要建议。

   • 使用 Firebase AI Logic 时，您通常不需要修改任何实际调用模型的代码。

3. 测试应用，确保响应仍符合预期。

由于关闭模型的请求会失败，我们强烈建议您不要将模型和模型版本硬编码到应用的代码库中。请改为设置并使用 Firebase Remote Config 来控制应用中使用的模型和模型版本。

借助 Remote Config，您可以动态且远程更改应用使用的模型和模型版本，而无需发布应用的新版本。任何已发布的应用版本（配置为使用 Remote Config）都会立即开始使用新模型和模型名称。

Imagen 稳定模型 - 关闭日期和替代模型

• 所有 Imagen 模型将于 2026 年 6 月 24 日关停。

替代方案： 将应用迁移为使用 Gemini 图像模型（“Nano Banana”模型）。

Gemini 2.0 稳定模型 - 关闭日期和替代模型

• Gemini 2.0 Flash 和 Gemini 2.0 Flash‑Lite：

  gemini-2.0-flash-001（及其自动更新的别名 gemini-2.0-flash）
  gemini-2.0-flash-lite-001（及其自动更新的别名 gemini-2.0-flash-lite）

  • 2026 年 2 月 6 日：之前未使用过这些模型的项目将无法再使用这些模型。

  • 2026 年 3 月 31 日：这些模型将停止服务。

  请注意，稳定的 Gemini Live API 2.0 模型不受影响。

替代方案：迁移到使用 Gemini 2.5 模型（例如 gemini-2.5-flash-lite）或尝试使用新的 Gemini 3 模型（例如 gemini-3.1-flash-lite-preview）。

Gemini 1.5 和 1.0 稳定版模型 - 关闭日期和替代模型

• Gemini 1.5 Pro 个模型：

  • gemini-1.5-pro-002（和 gemini-1.5-pro）：2025 年 9 月 24 日
  • gemini-1.5-pro-001：2025 年 5 月 24 日

• Gemini 1.5 Flash 个模型：

  • gemini-1.5-flash-002（和 gemini-1.5-flash）：2025 年 9 月 24 日
  • gemini-1.5-flash-001：2025 年 5 月 24 日

• Gemini 1.0 Pro Vision 型号：2025 年 4 月 21 日（之前安排的时间为 2025 年 4 月 9 日）

• Gemini 1.0 Pro 型号：2025 年 4 月 21 日（之前安排的时间为 2025 年 4 月 9 日）

替代方案：迁移到使用 Gemini 2.5 模型（例如 gemini-2.5-flash-lite）或尝试使用新的 Gemini 3 模型（例如 gemini-3.1-flash-lite-preview）。

如何设置单个用户的速率限制？

默认情况下，Firebase AI Logic 将每个用户的请求限额设置为每分钟 100 个请求 (RPM)。

如果您想调整每用户的速率限制，则需要调整 Firebase AI Logic API 的配额设置。

详细了解 Firebase AI Logic API 配额。 在该页面上，您还可以了解如何查看和修改配额。

使用 Firebase AI Logic SDK 可能需要哪些权限？

操作	必需的 IAM 权限	默认包含所需权限的 IAM 角色
将结算升级为随用随付 (Blaze) 定价方案	firebase.billingPlans.update resourcemanager.projects.createBillingAssignment resourcemanager.projects.deleteBillingAssignment	Owner
在项目中启用 API	serviceusage.services.enable	Editor Owner
创建 Firebase 应用	firebase.clients.create	Firebase 管理员 编辑者 所有者

Firebase AI Logic 是否会使用我的数据来训练模型？

请参阅数据治理和 Responsible AI。

在多模态请求中是否需要提供 MIME 类型？（例如，对于图片、PDF、视频和音频输入）

是的，在每个多模态请求中，您都必须始终提供以下内容：

• 文件的 mimeType。请参阅下文中的例外情况。

• 文件。您可以以内嵌数据的形式提供文件，也可以使用文件的网址提供文件。

如需了解支持的输入文件类型、如何指定 MIME 类型以及提供文件的两种方式，请参阅支持的输入文件和要求。

在请求中包含 MIME 类型的例外情况

对于来自原生 Android 和 Apple 平台应用的请求，内嵌图片输入可不提供 MIME 类型。

适用于 Android 和 Apple 平台的 Firebase AI Logic SDK 提供了一种简化的平台友好型方式来处理请求中的图片 - 所有图片（无论其格式如何）都会在客户端转换为质量为 80% 的 JPEG 格式，然后再发送到服务器。这意味着，当您使用 Android 和 Apple 平台 SDK以内嵌数据的形式提供图片时，无需在请求中指定 MIME 类型。

这种简化的处理方式在 Firebase AI Logic 文档中发送 base64 编码图片的请求示例中有所体现。

以下是有关此功能的其他平台专用信息：

• 对于 Android 设备：

  • 您可以利用简化的方式来处理多模态提示中的平台原生图片类型 (Bitmap)，这些提示包含作为内嵌数据的图片（请参阅示例）。

  • 如需更精细地控制图片格式和转换，您可以将图片作为 InlineDataPart 提供，并提供具体的 MIME 类型。例如：

    content { inlineData(/* PNG as byte array */, "image/png") }

• 对于 Apple 平台：

  • 您可以利用一种简化的方式来处理包含内嵌数据的多模态提示中的平台原生图片类型（UIImage、NSImage、CIImage 和 CGImage）（请参阅示例）。

  • 如需更精细地控制图片格式和转换，您可以将图片作为 InlineDataPart 提供，并提供具体的 MIME 类型。例如：

    InlineDataPart(data: Data(/* PNG Data */), mimeType: "image/png")

使用 Firebase AI Logic 时是否可以使用这些功能？上下文缓存、模型微调、嵌入生成和语义检索？

以下功能受各种模型和 API 提供方支持，但在使用 Firebase AI Logic 时不可用：

• 上下文缓存
• 微调模型
• 生成嵌入
• 语义检索

如果您想将这些内容添加为功能请求或对现有功能请求进行投票，请访问 Firebase UserVoice。

对于 Apple 平台上的 Swift 应用 - 如何应对模块名称从 FirebaseAI 更改为 FirebaseAILogic？

对于 Apple 平台应用，从 Firebase SDK v12.5.0 开始，Firebase AI Logic 现在在 FirebaseAILogic 模块下分发。我们已将此更改设为非重大更改，并使其向后兼容。

注意： 如果您目前使用的是 FirebaseAI 模块，并且要升级到 Firebase SDK v12.5.0 及更高版本，则本常见问题解答适用。如果您使用的是旧版 FirebaseVertexAI 模块，请参阅我们的迁移指南。

我们为何要进行此项变更？

我们以前通过 FirebaseAI 模块分发此服务。不过，我们需要将其重命名为 FirebaseAILogic，原因如下：

• 避免模块和类之间出现名称冲突，从而导致二进制分发出现问题。

• 使我们能够使用 Swift 宏进行未来的功能开发。

如果您要升级到 v12.5.0 及更高版本，该怎么做？

将模块名称更改为 FirebaseAILogic 不会造成重大变更，并且向后兼容。不过，我们最终可能会在未来的 Firebase SDK 重大更改版本中移除旧模块（时间范围目前尚未确定）。

此次模块名称变更无需进行任何更改，但我们建议您执行以下操作：

1. 选择 Swift PM 依赖项时，请选择 FirebaseAILogic（而非 FirebaseAI）。

2. 将导入语句更改为 FirebaseAILogic（而不是 FirebaseAI）。

Gemini API 密钥常见问题解答

只有在使用 Gemini Developer API 时，这些常见问题解答才适用。

什么是 Gemini API 密钥？

Gemini Developer API 使用“Gemini API 密钥”来授权调用方。因此，如果您通过 Firebase AI Logic SDK 使用 Gemini Developer API，则需要在 Firebase 项目中使用有效的 Gemini API 密钥才能调用该 API。

“Gemini API 密钥”只是指在其 API 许可名单中包含 Gemini Developer API 的 API 密钥。

注意： 在 Google Cloud 控制台中，Gemini Developer API 有时称为“Generative Language API”。

当您在 Firebase 控制台中完成 Firebase AI Logic 设置工作流程时，我们会创建一个仅限于 Gemini Developer API 的 Gemini API 密钥，并设置 Firebase AI Logic 代理服务以使用此 API 密钥。此 Firebase 生成的 Gemini API 密钥在 Google Cloud 控制台的凭据页面中命名为 Gemini Developer API 密钥（由 Firebase 自动创建）。

详细了解 API 密钥的 API 限制。

使用 Firebase AI Logic SDK 时，您不会将 Gemini API 密钥添加到应用的代码库中。详细了解如何确保 Gemini API 密钥的安全。

我是否应将 Gemini API 密钥添加到移动应用或 Web 应用的代码库中？

使用 Firebase AI Logic SDK 时，请勿将 Gemini API 密钥添加到应用的代码库中。

事实上，在使用 Firebase AI Logic SDK 进行开发时，您不会直接与 Gemini API 密钥进行交互。相反，我们的 Firebase AI Logic 代理服务会在每个对 Gemini Developer API 的请求中内部包含 Gemini API 密钥，完全在后端进行。

开始认真开发应用后，务必要与 Firebase App Check 集成，以便只有来自实际应用和经过验证的设备的请求才能传递到后端。

如何更改用于调用 Gemini Developer API 的 Gemini API 密钥？

使用 Firebase AI Logic SDK 时，您不太可能需要更改 Gemini API 密钥。不过，在以下两种情况下，您可能需要执行此操作：

• 如果您不慎泄露了密钥，并想将其替换为新的安全密钥。

• 如果您不小心删除了密钥。请注意，您可以在删除密钥后的 30 天内恢复密钥。

以下是更改 Firebase AI Logic SDK 使用的 Gemini API 密钥的方法：

1. 如果 Firebase 生成的 Gemini API 密钥仍然存在，请将其删除。

   您可以在 Google Cloud 控制台的 API 和服务 > 凭据面板中删除此 API 密钥。其名称为：
   Gemini Developer API 密钥（由 Firebase 自动创建）。

2. 在 Google Cloud 控制台的同一页面中，创建新的 API 密钥。 建议您为其命名，例如：
   适用于 Firebase 的 Gemini Developer API 密钥。

3. 为这个新的 API 密钥添加 API 限制，并仅选择 Generative Language API。
   “Generative Language API”是 Gemini Developer API 在 Google Cloud 控制台中有时使用的名称。

   请勿添加任何应用限制；否则，Firebase AI Logic 代理服务将无法按预期运行。

4. 运行以下命令，将此新密钥设置为 Firebase AI Logic 代理服务应使用的 Gemini API 密钥。

   PROJECT_ID="PROJECT_ID"
   GENERATIVE_LANGUAGE_API_KEY="DEVELOPER_CREATED_GEMINI_API_KEY"
   curl \
     -X PATCH \
     -H "x-goog-user-project: ${PROJECT_ID}" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://firebasevertexai.googleapis.com/v1beta/projects/${PROJECT_ID}/locations/global/config" \
     -d "{\"generativeLanguageConfig\": {\"apiKey\": \"${GENERATIVE_LANGUAGE_API_KEY}\"}}"
   

   了解 gcloud CLI。

请务必不要将此新的 Gemini API 密钥添加到应用的代码库中。详细了解如何确保 Gemini API 密钥的安全。

注意： 在处理 API 密钥时，您可以随时与 Firebase 支持团队联系，以获取相关问题解答和指导。

我可以将“Firebase API 密钥”用作 Gemini API 密钥吗？

不可以，您不应将“Firebase API 密钥”用作 Gemini API 密钥。我们强烈建议您不要将 Gemini Developer API 添加到 Firebase API 密钥的许可名单中。

Firebase API 密钥是指您添加到应用代码库中以将应用连接到 Firebase 的 Firebase 配置文件或对象中所列的 API 密钥。如果您仅将 Firebase API 密钥用于 Firebase 相关 API（例如 Firebase AI Logic），则可以将其包含在代码中。 了解有关 Firebase API 密钥的重要信息。

在 Google Cloud 控制台的 API 和服务 > 凭据面板中，Firebase API 密钥如下所示：

由于您需要将 Firebase API 密钥添加到应用的代码库中，以便 Firebase 相关 API 正常运行，并且 Gemini Developer API 通过 API 密钥获得授权，因此我们强烈建议您不要将 Gemini Developer API（在 Google Cloud 控制台中称为“Generative Language API”）添加到 Firebase API 密钥的 API 许可名单中。如果您这样做，则会使 Gemini Developer API 容易受到滥用。

如何确保 Gemini API 密钥的安全？

此常见问题解答介绍了确保 Gemini API 密钥安全的一些推荐最佳实践。

如果您直接从移动应用或 Web 应用调用 Gemini Developer API：

• 使用 Firebase AI Logic 客户端 SDK。
• 请勿将 Gemini API 密钥添加到应用的代码库中。

Firebase AI Logic 提供了一种代理服务，该服务在内部将您的 Gemini API 密钥包含在对 Gemini Developer API 的每个请求中，完全在后端进行。

此外，我们强烈建议您执行以下操作：

• 一旦您开始认真开发应用，就应与 Firebase App Check 集成，以帮助保护您的后端资源以及用于访问生成式模型的 API。

• 请勿在 Firebase AI Logic 之外重复使用 Firebase 生成的 Gemini API 密钥。如果您需要 Gemini API 密钥用于其他用途，请创建单独的密钥。

• 一般来说，您不应修改 Firebase 生成的 Gemini API 密钥。此密钥在 Google Cloud 控制台中名为 Gemini Developer API key (auto created by Firebase)。

  • 请勿向 Firebase 生成的 Gemini API 密钥的 API 许可名单添加任何其他 API。在 API 许可名单中，您的 Gemini API 密钥应仅包含 Gemini Developer API（在 Google Cloud 控制台中称为“Generative Language API”）。

  • 请勿添加任何应用限制；否则，Firebase AI Logic 代理服务将无法按预期运行。

我的 Gemini API 密钥已被盗。我需要做什么？

如果您的 Gemini API 密钥已被泄露，请按照说明更改用于调用 Gemini Developer API 的 Gemini API 密钥。

另请查看推荐的最佳实践，以确保 Gemini API 密钥的安全。

就您使用 Firebase AI Logic 的体验提供反馈