常见问题解答和问题排查

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

Firebase AI Logic 及其客户端 SDK 之前称为“Vertex AI in Firebase”。2025 年 5 月，我们将服务重命名并重新打包为 Firebase AI Logic，以便更好地反映我们扩展的服务和功能，例如，我们现在支持 Gemini Developer API！

状态信息中心

• 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 模型	支持	支持
支持 Imagen 模型	支持	支持
对 Veo 模型的支持	尚不支持	尚不支持
Gemini Live API 支持服务	支持 （仅限 Android、Flutter、Web 和 Unity）	支持 （仅限 Android、Flutter、Web 和 Unity）
与 Firebase App Check 集成	支持	支持
与 Firebase Remote Config 兼容	支持	支持
支持在 Firebase 控制台中进行 AI 监控	支持	支持

注意： 使用 Firebase AI Logic 时，不支持以下功能：上下文缓存、代码执行、模型微调、嵌入生成、语义检索以及 Imagen 模型的一些高级功能。

我可以同时使用 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 AI Logic SDK 搭配使用？

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

• 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。

型号停产后该怎么办？

发布稳定版模型时，我们会尽力确保该版本至少可用一年。我们在 Firebase 和 Gemini API 提供商文档中的多个位置列出了此“停用日期”（例如，在 Firebase 文档的“模型”页面中）。

模型退役后，对该模型的所有请求都会失败并显示 404 错误。 因此，我们强烈建议您设置并使用 Firebase Remote Config，以便您在不发布新应用版本的情况下动态更改应用中的模型和版本。

将应用更新为使用新模型版本后，我们建议您测试应用，确保响应仍符合预期。请注意，使用 Firebase AI Logic 时，通常不需要对实际调用模型的任何代码进行修改。

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

以下是各种稳定模型的退役日期：

• 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 日）

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

默认情况下，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。

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。
   “生成式语言 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 控制台中称为“生成式语言 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 密钥的安全。

排查错误

如何修正此 404 错误？Firebase AI Logic genai config not found

如果您尝试使用 Gemini Developer API，但收到一条 404 错误，指出 Firebase AI Logic genai config not found，这通常意味着您的 Firebase 项目没有可与 Firebase AI Logic 客户端 SDK 搭配使用的有效 Gemini API 密钥。

以下是此错误最可能的原因：

• 您尚未为 Gemini Developer API 设置 Firebase 项目。

  操作步骤：
  在 Firebase 控制台中，前往 Firebase AI Logic 页面。点击开始，然后选择 Gemini Developer API。启用该 API，控制台将为 Gemini Developer API 设置您的项目。完成工作流程后，请再次尝试您的请求。

• 如果您最近在 Firebase 控制台中完成了 Firebase AI Logic 设置工作流程，则您的 Gemini API 密钥可能尚未在所有区域中提供给所有必需的后端服务。

  解决方法：
  等待几分钟，然后再次尝试发出请求。

• 您的 Gemini API 密钥可能已从 Firebase 项目中删除。

  操作步骤：
  了解如何更改 Firebase AI Logic 使用的 Gemini API 密钥。

如何修正此 400 错误？Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

如果您尝试发送包含 Cloud Storage for Firebase 网址的多模态请求，可能会遇到以下 400 错误：
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

此错误是由以下原因造成的：当项目中启用 Vertex AI API 时，未正确自动预配该项目所需的必要服务代理。这是某些项目的已知问题，我们正在努力寻找全局修复方案。

以下是解决项目问题并正确配置这些服务代理的解决方法，以便您开始在多模态请求中添加 Cloud Storage for Firebase 网址。您必须是项目的所有者，并且只需为项目完成一次这组任务。

1. 使用 gcloud CLI 进行访问和身份验证。
   最简单的方法是从 Cloud Shell 中执行此操作。如需了解详情，请参阅 Google Cloud 文档。

2. 如果系统提示，请按照终端中显示的说明针对您的 Firebase 项目运行 gcloud CLI。

   您需要 Firebase 项目 ID，该 ID 可在 Firebase 控制台的 项目设置顶部找到。

3. 运行以下命令，在项目中预配所需的服务代理：

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
   

4. 等待几分钟，确保服务代理已完成预配，然后重试发送包含 Cloud Storage for Firebase 网址的多模态请求。

如果您在等待几分钟后仍收到此错误，请与 Firebase 支持团队联系。

如何修正此 400 错误？API key not valid. Please pass a valid API key.

如果您收到一条显示 API key not valid. Please pass a valid API key. 的 400 错误，通常意味着 Firebase 配置文件/对象中的 API 密钥不存在，或者未设置为与您的应用和/或 Firebase 项目搭配使用。

检查 Firebase 配置文件/对象中列出的 API 密钥是否与应用的 API 密钥一致。您可以在 Google Cloud 控制台的 API 和服务 > 凭据面板中查看所有 API 密钥。

如果您发现它们不匹配，请获取新的 Firebase 配置文件/对象，然后替换应用中的旧文件/对象。新的配置文件/对象应包含适用于您的应用和 Firebase 项目的有效 API 密钥。

如何解决此 403 错误？Requests to this API firebasevertexai.googleapis.com ... are blocked.

如果您收到一条显示 Requests to this API firebasevertexai.googleapis.com ... are blocked. 的 403 错误，这通常意味着您应用中 Firebase 配置中的 API 密钥具有限制，导致其无法调用所需的 API。

如需解决此问题，您需要在 Google Cloud 控制台中更新 API 密钥的限制，以包含所需的 API。对于 Firebase AI Logic，您必须确保 Firebase AI Logic API (firebasevertexai.googleapis.com) 包含在可以使用 API 密钥调用的所选 API 列表中。

请按照以下步骤操作：

1. 在 Google Cloud 控制台中，打开 API 和服务 > 凭据面板。

2. 选择您的应用配置为使用的 API 密钥（例如，iOS 应用的“iOS 密钥”）。

3. 在修改 API 密钥页面上，找到 API 限制部分。

4. 确保已选择限制密钥选项。如果不是，则您的密钥不受限制，这可能不是错误来源。

   注意 ：如果您拥有不受限制的 API 密钥，我们强烈建议您对 Firebase API 密钥应用 “API 限制”。

5. 在选定的 API 下拉菜单中，搜索并选择 Firebase AI Logic API，以将其添加到可以使用该 API 密钥调用的选定 API 列表中。

6. 点击保存。

   更改最多可能需要五分钟才能生效。

注意： Firebase 相关 API 仅使用 API 密钥来标识 Firebase 项目或应用，不用于授权调用 API（某些其他 API 允许这样做）。Firebase 相关 API 的授权是通过 Google Cloud IAM 权限、Firebase Security Rules 或 Firebase App Check 单独处理的，而不是通过 API 密钥。详细了解 Firebase API 密钥。

如何解决此 403 错误？PERMISSION_DENIED: The caller does not have permission.

如果您收到显示 PERMISSION_DENIED: The caller does not have permission. 的 403 错误，通常意味着 Firebase 配置文件/对象中的 API 密钥属于其他 Firebase 项目。

检查 Firebase 配置文件/对象中列出的 API 密钥是否与应用的 API 密钥一致。您可以在 Google Cloud 控制台的 API 和服务 > 凭据面板中查看所有 API 密钥。

如果您发现它们不匹配，请获取新的 Firebase 配置文件/对象，然后替换应用中的旧文件/对象。新的配置文件/对象应包含适用于您的应用和 Firebase 项目的有效 API 密钥。

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