本页面提供了有关 Firebase AI Logic 以及将其与 Gemini API 搭配使用的常见问题解答 (FAQ) 和问题排查信息：
如有需要，请参阅以下其他资源：
排查错误代码。
了解结算设置、价格和付款。
了解速率限制和配额。
状态信息中心
Agent Platform Gemini API (formerly Vertex AI) (
Vertex Gemini API)
常规常见问题解答
使用 Gemini Developer API 与使用 Agent Platform Gemini API (formerly Vertex AI) 的区别
下表列出了两个“Gemini API”提供商之间的重要区别，通常与您访问它们的方式无关：
| Gemini Developer API | Agent Platform Gemini API (formerly Vertex AI) | |
|---|---|---|
| 价格 | 免费 Spark 定价方案和随用随付 Blaze 定价方案1均可使用 | 始终需要采用随用随付 Blaze 定价方案1（与 Firebase AI Logic 搭配使用时） |
| 速率限制（配额） | 显式速率限制 | 使用动态共享配额 (DSQ)，该配额由在该区域中使用该模型的所有人共享。预配吞吐量 (PT) 可用。 |
| 指定访问模型的位置 | API 不支持 | API 支持 |
| 支持 Cloud Storage 网址 | API 2 不支持 |
公开文件和 受 Firebase Security Rules 保护的文件 |
| 支持 YouTube 网址和浏览器网址 | 仅限 YouTube 网址 | YouTube 网址和浏览器网址 |
1 这两个 API 提供商的随用随付价格不同（如需了解详情，请参阅各自的文档）。
2 Firebase AI Logic SDK 不支持 Gemini Developer API 的 Files API。
下表列出了两个“Gemini API”提供商的常见功能可用性。此表专门适用于使用 Firebase AI Logic 客户端 SDK 的情况。
| 功能 | Gemini Developer API | Agent Platform Gemini API (formerly Vertex AI) |
|---|---|---|
| 支持 Gemini 模型 | 支持 | 支持 |
| Gemini Live API 支持服务 | 支持 | 支持 |
| 与 Firebase App Check 集成 | 支持 | 支持 |
| 兼容 Firebase Remote Config | 支持 | 支持 |
| 支持在 Firebase 控制台中进行 AI 监控 | 支持 | 支持 |
如何同时使用 Gemini Developer API 和 Agent Platform Gemini API (formerly Vertex AI)
您可以在 Firebase 项目中同时启用这两个 Gemini API 提供方，也可以在应用本身中使用这两个 API。
如需在代码中切换 API 提供方，只需确保您已在代码中正确设置后端服务。
所需 API 以及如何启用
|
选择您的 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：
在 Firebase 控制台中，依次前往 AI 服务 > AI Logic。
点击开始使用。
选择此选项即可开始使用 Gemini Developer API。
这将启动引导式工作流，为您启用这两个 API。Firebase 还会预配一个 Google 管理的服务账号 (P4SA)，用于授权使用 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。
停用与使用 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：
点击上方的每个 API 链接，前往 Google Cloud 控制台中的相应 API 页面，然后点击管理。
查看指标标签页，确认该 API 没有使用量。
如果您仍想停用该 API，请点击页面顶部的停用 API。
从可使用 Firebase API 密钥调用的所选 API 列表中移除 Firebase AI Logic API。请参阅此常见问题解答，了解 Firebase API 密钥许可清单，了解如何修改此清单。
如果您想继续使用 Firebase AI Logic，但想改用 Agent Platform Gemini API (formerly Vertex AI)，请执行以下操作：
前往 Google Cloud 控制台中的 Gemini Developer API 页面，然后点击管理。
查看指标标签页，确认该 API 没有使用量。
如果您仍想停用该 API，请点击页面顶部的停用 API。
确保您的项目已为 Agent Platform Gemini API (formerly Vertex AI) 启用所需的 API。
停用与使用 Agent Platform Gemini API (formerly Vertex AI) 相关的 API
如需将 Firebase AI Logic SDK 与 Agent Platform Gemini API (formerly Vertex AI) 搭配使用，您的项目必须启用以下两个 API：
- Agent Platform API (
aiplatform.googleapis.com) - Firebase AI Logic API (
firebasevertexai.googleapis.com)
如果您想完全停止使用 Firebase AI Logic：
点击上方的每个 API 链接，前往 Google Cloud 控制台中的相应 API 页面，然后点击管理。
查看指标标签页，确认该 API 没有使用量。
如果您仍想停用该 API，请点击页面顶部的停用 API。
从可使用 Firebase API 密钥调用的所选 API 列表中移除 Firebase AI Logic API。请参阅此常见问题解答，了解 Firebase API 密钥许可清单，了解如何修改此清单。
如果您想继续使用 Firebase AI Logic，但想改用 Gemini Developer API，请执行以下操作：
前往 Google Cloud 控制台中的 Agent Platform API 页面，然后点击管理。
查看指标标签页，确认该 API 没有使用量。
如果您仍想停用该 API，请点击页面顶部的停用 API。
确保您的项目已为 Gemini Developer API 启用所需的 API。
使用 Firebase AI Logic 所需的权限
| 操作 | 必需的 IAM 权限 | 默认包含所需权限的 IAM 角色 |
|---|---|---|
| 将结算方案升级为随用随付 (Blaze) 定价方案 | firebase.billingPlans.updateresourcemanager.projects.createBillingAssignmentresourcemanager.projects.deleteBillingAssignment
|
Owner |
| 在项目中启用 API | serviceusage.services.enable |
Editor Owner |
| 创建 Firebase 应用 | firebase.clients.create |
Firebase Admin Editor Owner |
使用 Firebase AI Logic 时支持的模型
请参阅支持的模型列表。 我们会经常向 SDK 添加新功能，因此请不时查看此常见问题解答（以及版本说明、博客和社交帖子）以了解最新动态。
Firebase AI Logic 支持以下模型：
Gemini Developer API
- 大多数 Gemini 基础模型
Agent Platform Gemini API (formerly Vertex AI)
- 大多数 Gemini 基础模型
Firebase AI Logic 不支持以下模型（无论您选择的 Gemini API 提供方为何）：
微调模型
嵌入模型、 Veo 模型、 Lyria 模型、 机器人模型、 计算机使用模型、 Gemini Omni 模型或 Gemini Cyber 模型
如何设置每位用户的速率限制
默认情况下，Firebase AI Logic 将每个用户的请求限制设置为每分钟 100 个请求 (RPM)。
如果您想调整每用户速率限制，则需要调整 Firebase AI Logic API 的配额设置。
详细了解 Firebase AI Logic API 配额。 在该页面上，您还可以了解如何查看和修改配额。
如何减少延迟时间和高 token 用量
如果您遇到高延迟或高 token 用量，可能是因为您所用模型的思考级别配置。
Gemini 3及后续模型始终使用内部“思考过程”，这显著提升了其推理和多步规划能力，使其在处理编码、高级数学和数据分析等复杂任务时非常高效。
不过，根据任务的不同，并不总是需要更高级别的思考，您可以将模型配置为使用较低的思考级别。较低的思考级别有助于缩短延迟时间并减少 token 用量。如需帮助您确定模型可能需要多少思考能力，请查看任务难度比较。
请注意，对于大多数 Gemini 3 及更高版本的模型，默认思考级别设置为 HIGH。
多模态请求（例如图片、PDF、视频和音频输入）的 MIME 类型要求
在每个多模态请求中，您必须始终提供以下内容：
文件的
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 时尚无法使用的高级功能：依托 Google 图片搜索进行接地、微调模型、生成嵌入和语义检索
各种模型和 API 提供方都支持以下功能，但在使用 Firebase AI Logic 时无法使用这些功能：
- 依托 Google 图片搜索进行接地
- 微调模型
- 生成嵌入
- 语义检索
如果您想将这些功能作为功能请求添加，或对现有功能请求进行投票，请访问 Firebase UserVoice。
用于训练模型的数据
更改常见问题解答
本部分包含与模型弃用或关停以及 API、SDK 或品牌变更相关的常见问题解答。
已弃用或已关停（停用）的模型 - 列表和替换模型
Google 发布稳定版模型后，会努力确保该模型至少在 12 个月内可用，然后再将其关闭（停用）。
不过，请注意以下几点：
对于 Agent Platform Gemini API (formerly Vertex AI)，某些稳定模型仅具有短期可用性，这意味着它们可能会在替换模型发布后 45 天内关停（停用）。
对于 Gemini Developer API，有时服务不会关停模型，而是会自动将请求路由到较新的模型。对较新模型的请求将按较新模型的费率计费。
在关停日期前几周，之前未使用过某个模型的项目将无法开始使用该模型。
当某个模型的稳定版发布后，该模型的所有实验性模型和预览版通常会在几天或几周内关闭（弃用）（此常见问题解答未列出每个先前的预览版和实验性模型）。
通用模型
| 型号 | Gemini Developer API | Agent Platform Gemini API |
|---|---|---|
gemini-3.7-flash 1
发布日期：2026 年 8 月 13 日 发布阶段：稳定版 |
请求路由到 gemini-3.8-flash
替换： gemini-3.8-flash
|
停用日期：2027 年 1 月 28 日
替代产品： gemini-3.8-flash
|
gemini-3.6-flash 1
发布日期：2026 年 7 月 21 日 发布阶段：稳定版 |
停用日期：---
替代函数： gemini-3.8-flash
|
停用日期：2026 年 11 月 19 日
替代产品： gemini-3.8-flash
|
gemini-3.5-flash
发布日期：2026 年 5 月 19 日 发布阶段：稳定版 |
请求路由到 gemini-3.6-flash
替换： gemini-3.8-flash
|
停用日期：---
替代函数： gemini-3.8-flash
|
gemini-3.1-pro-preview
发布日期：2026 年 2 月 19 日 发布阶段：预览版 |
停用日期：---
替代函数： gemini-4-argon
|
停用日期：---
替代函数： gemini-4-argon
|
| 型号 | Gemini Developer API | Agent Platform Gemini API |
|---|---|---|
gemini-2.5-pro
发布日期：2025 年 6 月 17 日 发布阶段：稳定版 |
路由到 gemini-3.8-flash 的请求（自 2026 年 12 月 1 日起）
替换项： gemini-3.8-flash
|
停用日期：2026 年 10 月 20 日
替代产品： gemini-3.8-flash
|
gemini-2.5-flash
发布日期：2025 年 6 月 17 日 发布阶段：稳定版 |
路由到 gemini-3.5-flash-lite 的请求（自 2026 年 12 月 1 日起）
替换项： gemini-3.5-flash-lite
|
停用日期：2026 年 10 月 20 日
替代产品： gemini-3.5-flash-lite
|
gemini-2.5-flash-lite
发布日期：2025 年 7 月 22 日 发布阶段：稳定版 |
停用日期：---
替代函数： gemini-3.5-flash-lite
|
停用日期：2026 年 10 月 20 日
替代产品： gemini-3.5-flash-lite
|
| 型号 | Gemini Developer API | Agent Platform Gemini API |
|---|---|---|
gemini-2.0-flash-001
发布日期：2025 年 2 月 5 日 发布阶段：关停 |
停用日期：2026 年 6 月 1 日
替代产品： gemini-3.5-flash-lite
|
停用日期：2026 年 6 月 1 日
替代产品： gemini-3.5-flash-lite
|
gemini-2.0-flash
发布日期：2025 年 2 月 10 日 发布阶段：关停 |
停用日期：2026 年 6 月 1 日
替代产品： gemini-3.5-flash-lite
|
停用日期：2026 年 6 月 1 日
替代产品： gemini-3.5-flash-lite
|
gemini-2.0-flash-lite-001
发布日期：2025 年 2 月 25 日 发布阶段：关停 |
停用日期：2026 年 6 月 1 日
替代产品： gemini-3.5-flash-lite
|
停用日期：2026 年 6 月 1 日
替代产品： gemini-3.5-flash-lite
|
gemini-2.0-flash-lite
发布日期：2025 年 2 月 25 日 发布阶段：关停 |
停用日期：2026 年 6 月 1 日
替代产品： gemini-3.5-flash-lite
|
停用日期：2026 年 6 月 1 日
替代产品： gemini-3.5-flash-lite
|
1 对于 Agent Platform Gemini API (formerly Vertex AI)，这是一种“短期可用性模型”。请参阅模型版本控制和命名模式
以下所有通用模型也已停用：
gemini-1.0-pro、
gemini-1.0-pro-001、
gemini-1.0-pro-002、
gemini-1.0-pro-vision、
gemini-1.0-pro-vision-001
gemini-1.5-flash-001、
gemini-1.5-flash、
gemini-1.5-flash-002、
gemini-1.5-pro-001、
gemini-1.5-pro、
gemini-1.5-pro-002
图片生成（Nano Banana 和 Imagen）模型
| 型号 | Gemini Developer API | Agent Platform Gemini API |
|---|---|---|
gemini-2.5-flash-image
发布日期：2025 年 10 月 2 日 发布阶段：关停 |
停用日期：2026 年 10 月 2 日
替代产品： gemini-nano-banana-2.1
|
停用日期：2026 年 10 月 2 日
替代产品： gemini-nano-banana-2.1
|
| 型号 | Gemini Developer API | Agent Platform Gemini API |
|---|---|---|
imagen-4.0-generate-001
发布日期：2025 年 8 月 14 日 发布阶段：关停 |
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
imagen-4.0-fast-generate-001
发布日期：2025 年 8 月 14 日 发布阶段：关停 |
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
imagen-4.0-ultra-generate-001
发布日期：2025 年 8 月 14 日 发布阶段：关停 |
停用日期：2026 年 6 月 30 日
替代产品： gemini-3-pro-image
|
停用日期：2026 年 6 月 30 日
替代产品： gemini-3-pro-image
|
imagen-3.0-capability-001
发布日期：2024 年 12 月 10 日 发布阶段：关停 |
不支持 |
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
imagen-3.0-generate-002
发布日期：2025 年 1 月 23 日 发布阶段：关停 |
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
imagen-3.0-generate-001
发布日期：2024 年 7 月 31 日 发布阶段：关停 |
不支持 |
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
imagen-3.0-fast-generate-001
发布日期：2024 年 7 月 31 日 发布阶段：关停 |
不支持 |
停用日期：2026 年 6 月 30 日
替代产品： gemini-nano-banana-2.1
|
音频 - Live API 个模型
| 型号 | Gemini Developer API | Agent Platform Gemini API |
|---|---|---|
gemini-live-2.5-flash-preview
发布日期：2025 年 6 月 17 日 发布阶段：关停 |
关停日期：2025 年 12 月 9 日
替代产品： gemini-3.1-flash-live-preview
|
关停日期：2025 年 12 月 9 日
替代产品： gemini-live-2.5-flash-native-audio
|
gemini-2.0-flash-live-001
发布日期：2025 年 4 月 9 日 发布阶段：关停 |
关停日期：2025 年 12 月 9 日
替代产品： gemini-3.1-flash-live-preview
|
关停日期：2025 年 12 月 9 日
替代产品： gemini-live-2.5-flash-native-audio
|
gemini-2.0-flash-live-preview-04-09
发布日期：2025 年 4 月 9 日 发布阶段：关停 |
不支持 |
关停日期：2025 年 12 月 9 日
替代产品： gemini-live-2.5-flash-native-audio
|
模型弃用或关停（停用）时需要进行的更改
在哪里可以找到模型的关停日期？
您可以通过以下几种方式查找模型的关停日期：
Google 会向相应的项目成员发送电子邮件。
我们会通过各种渠道发布有关即将关停的公告和提醒：
- 版本说明（请参阅示例）
- 文档、支持的模型页面以及弃用和关停的模型常见问题解答中的页面级横幅
如果您使用的模型即将关停，该怎么办？
您需要在关停日期之前进行这些更改；否则，对已关停模型的任何请求都将失败，并显示 404 错误。
-
我们还在弃用和关停的模型常见问题解答中提供了建议的替换模型。
更新应用使用的模型名称。
您可以在创建
GenerativeModel、LiveModel或ImagenModel实例时，在初始化期间设置模型名称。请务必查看以下关于使用 Firebase Remote Config 或服务器提示模板的重要建议。检查您是否需要更新任何代码。
您通常无需修改实际调用模型的任何代码。以下是一些例外情况：
不支持的采样参数：最新的 Gemini 4.x 和 Gemini 3.x 模型不支持多个参数（具体包括温度、top-K、top-P、频率惩罚、存在惩罚和候选数量）。
思考级别与思考预算：从 Gemini 3.x 模型开始，您应使用
thinkingLevel，而不是thinkingBudget（但为了向后兼容，thinkingBudget仍受支持）。不过，从 Gemini 4.x 模型开始，不支持thinkingBudget。详细了解思考。尝试思考级别值：升级到新一代（例如，从 2.5 升级到 3.8）并希望确保相同的性能和行为（例如延迟时间）时，我们建议尝试将思考级别设置为较低的值。详细了解思考。
测试您的应用，确保响应仍符合预期。
“Vertex AI”更名为“Agent Platform”后需要进行的更改
2026 年年中，Google Cloud 将“Vertex AI”更名为“Gemini Enterprise Agent Platform”（或“Agent Platform”）。在 Firebase 生态系统中，我们将此服务称为“Agent Platform Gemini API”。
对于 Google Cloud，此次品牌重塑包括以下内容。请注意，还有其他更改，但这些更改不适用于 Firebase AI Logic。
将产品名称从“Vertex AI”更改为“Gemini Enterprise Agent Platform”（或“Agent Platform”），其中包括 Google Cloud 控制台和文档的新网址。
将 API 的显示名称从“Vertex AI API”更改为“Agent Platform API”。请注意，服务名称保持不变：
aiplatform.googleapis.com。将“Vertex AI Studio”更名为“Agent Studio”。
底层 API 或支持的模型的功能没有变化。
对于 Firebase AI Logic SDK，我们通过更新“Gemini API”后端服务的初始化语法以及更新使用此新语法访问模型的默认位置，来适应此次品牌更名。
“Gemini API”后端服务的新初始化语法：
Swift
将
vertexAI更改为agentPlatform。agentPlatform语法从 SDK v12.17.0 及更高版本开始提供。vertexAI语法已在 SDK v13.0.0 中移除。
之前
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the legacy `vertexAI` syntax, the default location is `us-central1`, so // specifying a location is usually required since most models are *not* supported in `us-central1`. let ai = FirebaseAI.firebaseAI(backend: .vertexAI(location: "LOCATION")) // ...升级后
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the `agentPlatform` syntax, the default location is `global`, so // specifying a location is usually optional since most models are supported in `global`. let ai = FirebaseAI.firebaseAI(backend: .agentPlatform(location: "LOCATION")) // ...Kotlin
将
vertexAI更改为agentPlatform。agentPlatform语法从 SDK v17.15.0+ 和 Firebase Android BoM v34.17.0+ 开始提供。vertexAI语法已在 SDK 的 v18.0.0 和 BoM 的 v35.0.0 中移除。
之前
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the legacy `vertexAI` syntax, the default location is `us-central1`, so // specifying a location is usually required since most models are *not* supported in `us-central1`. val ai = Firebase.ai(backend = GenerativeBackend.vertexAI(location = "LOCATION")) // ...升级后
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the `agentPlatform` syntax, the default location is `global`, so // specifying a location is usually optional since most models are supported in `global`. val ai = Firebase.ai(backend = GenerativeBackend.agentPlatform(location = "LOCATION")) // ...Java
将
vertexAI更改为agentPlatform。agentPlatform语法从 SDK v17.15.0+ 和 Firebase Android BoM v34.17.0+ 开始提供。vertexAI语法已在 SDK 的 v18.0.0 和 BoM 的 v35.0.0 中移除。
之前
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the legacy `vertexAI` syntax, the default location is `us-central1`, so // specifying a location is usually required since most models are *not* supported in `us-central1`. GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.vertexAI("LOCATION")); // ...升级后
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the `agentPlatform` syntax, the default location is `global`, so // specifying a location is usually optional since most models are supported in `global`. GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION")); // ...Web
将
VertexAIBackend更改为AgentPlatformBackend。AgentPlatformBackend语法从 Firebase JS SDK v12.17.0+ 开始提供。VertexAIBackend语法已在 SDK v13.0.0 中移除。
之前
import { getAI, getGenerativeModel, VertexAIBackend } from "firebase/ai"; // ... // Initialize FirebaseApp // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the legacy `VertexAIBackend` syntax, the default location is `us-central1`, so // specifying a location is usually required since most models are *not* supported in `us-central1`. const ai = getAI(firebaseApp, { backend: new VertexAIBackend('LOCATION') }); // ...升级后
import { getAI, getGenerativeModel, AgentPlatformBackend } from "firebase/ai"; // ... // Initialize FirebaseApp // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the `AgentPlatformBackend` syntax, the default location is `global`, so // specifying a location is usually optional since most models are supported in `global`. const ai = getAI(firebaseApp, { backend: new AgentPlatformBackend('LOCATION') }); // ...Dart
将
vertexAI更改为agentPlatform。agentPlatform语法从插件 v3.15.0+ 和 Firebase Flutter BoM v4.18.0+ 开始提供。vertexAI语法已在插件 v5.0.0 和 Firebase Flutter BoM v5.0.0+ 中移除。
之前
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the legacy `vertexAI` syntax, the default location is `us-central1`, so // specifying a location is usually required since most models are *not* supported in `us-central1`. final ai = await FirebaseAI.vertexAI(location: 'LOCATION'); // ...升级后
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the `agentPlatform` syntax, the default location is `global`, so // specifying a location is usually optional since most models are supported in `global`. final ai = await FirebaseAI.agentPlatform(location: 'LOCATION'); // ...Unity
将
VertexAI更改为AgentPlatform。- 从 Firebase SDK for Unity v13.15.0+ 开始，可以使用
AgentPlatform语法。 VertexAI语法已在 SDK v14.0.0 中移除。
之前
// ... // Initialize the Agent Platform Gemini API backend service (formerly branded Vertex AI). // For the legacy `VertexAI` syntax, the default location is `us-central1`, so // specifying a location is usually required since most models are *not* supported in `us-central1`. var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(location: "LOCATION")); // ...升级后
// ... // Initialize the Agent Platform Gemini API backend service (formerly Vertex AI). // For the `AgentPlatform` syntax, the default location is `global`, so // specifying a location is usually optional since most models are supported in `global`. var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(location: "LOCATION")); // ...使用新的初始化语法时，访问模型的新默认位置：
使用新的“Agent Platform”初始化语法时，位置默认为
global。之所以做出此项更改，是因为
global支持几乎所有 Gemini 模型，并且 Google Cloud 不再支持大多数 Gemini 模型新版本的us-central1位置。
对于 Swift 应用 - 从 FirebaseAI 迁移到 FirebaseAILogic 所需的更改
对于 Apple 平台应用，从 Firebase SDK v12.5.0 开始，Firebase AI Logic 在 FirebaseAILogic 模块下分发。在 SDK v13.0.0 中，FirebaseAI 模块已被移除。
我们为何要做出此项变更？
我们以前通过 FirebaseAI 模块分发此服务。不过，由于以下原因，我们需要将其重命名为 FirebaseAILogic：
避免模块和类之间的名称冲突，以免在二进制分发中引起问题。
使我们能够使用 Swift 宏进行未来的功能开发。
如果您要升级到 v12.5.0+ 或 v13.0.0+，该怎么做？
在 Firebase 12（从 v12.5.0+ 开始）中，模块名称更改为 FirebaseAILogic 是非破坏性的，并且向后兼容，因此在 Firebase 12 中建议进行这些更改。不过，在 Firebase SDK v13.0.0 中，旧版 FirebaseAI 模块已被移除，因此在升级到 Firebase 13 时，这些更改是必需的。
选择 Swift PM 依赖项时，请选择
FirebaseAILogic（而不是FirebaseAI）。将 import 语句更改为
FirebaseAILogic（而不是FirebaseAI）。
了解名称从“Vertex AI in Firebase”更改为“Firebase AI Logic”
早在 2024 年，我们就推出了一组 Firebase 客户端 SDK，这些 SDK 可以使用 Agent Platform Gemini API (formerly Vertex AI) 以及 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）。
安全常见问题解答
以下部分包含与安全相关（例如关于 App Check 或 Gemini API 密钥）的常见问题解答。
Firebase App Check 常见问题解答
对应用的所有版本强制执行 App Check
需要对使用 Firebase AI Logic 的所有应用版本强制执行 App Check。
请务必尽早强制执行 App Check，尤其是在您将应用提交到公开可用的源代码控制系统、分享应用或公开发布应用之前。
如果您立即在应用的代码库中实现 App Check，则所有应用版本都可以发送有效的 App Check 令牌。未发送有效令牌的请求会被视为未经验证，并且在强制执行 App Check 时会被屏蔽。
如果您已经向最终用户发布了未实现 App Check 的应用版本，请参阅常见问题解答，了解如何为已发布的应用实现并强制执行 App Check。
延迟自动强制执行Firebase AI Logic的App Check
自 2026 年 11 月 2 日起，Firebase 将自动在您的 Firebase 项目中对 Firebase AI Logic 强制执行 Firebase App Check（如果尚未强制执行）。
强制执行 App Check 后，任何没有有效 App Check 令牌的 Firebase AI Logic 请求都将被屏蔽。这包括未实现正式版认证提供程序的已发布应用版本。
如果您已发布的应用版本未实现 App Check，则可以暂时延迟自动强制执行 App Check 的时间，直到 Firebase AI Logic。不过，在 2027 年 1 月 21 日之前，请务必为已发布的应用实现并强制执行 App Check。
以下是推迟 Firebase AI Logic 的 App Check 自动强制执行的方法：
在 Firebase 控制台中，前往安全性 > App Check > API 标签页。
找到 Firebase AI Logic 对应的行。
在行末，找到强制执行：日期选择器及其
edit修改 图标。选择您希望 App Check 自动对 Firebase AI Logic 强制执行的日期。
最晚日期为 2027 年 1 月 21 日。在此日期之后，您将无法延迟 Firebase AI Logic 的 App Check 自动强制执行。
点击保存。
如何为已发布的应用实现并强制执行 App Check
对于未实现 App Check 的应用版本，从这些版本向 Firebase AI Logic 发出的请求没有有效的 App Check 令牌，会被视为未经验证。当针对 Firebase AI Logic 强制执行 App Check 时，这些请求将被屏蔽。
以下说明可帮助您迁移应用，以便您能够以避免已发布但没有 App Check 的应用出现服务中断的方式强制执行 App Check。
延迟自动强制执行 Firebase AI Logic 的 App Check：
在 Firebase 控制台中，前往安全性 > App Check > API 标签页。
找到 Firebase AI Logic 对应的行。
在行末，找到强制执行：日期选择器及其
edit修改 图标。选择您希望 App Check 自动对 Firebase AI Logic 强制执行的日期。
最晚日期为 2027 年 1 月 21 日。 在此日期之后，您将无法延迟对 Firebase AI Logic 自动强制执行 App Check。
点击保存。
尽快在您的应用中实现正式版认证提供程序。
- Apple 平台：DeviceCheck、App Attest 或 reCAPTCHA Enterprise
- Android：Play Integrity 或 reCAPTCHA Enterprise
- Web： reCAPTCHA Enterprise
- Flutter：支持上述所有提供方，包括 reCAPTCHA Enterprise
- Unity：支持上述所有提供商（即将支持 reCAPTCHA Enterprise）
监控来自应用的请求，以帮助您确定何时可以安全地强制执行 App Check。
例如，如果几乎所有近期请求都来自经过验证的客户端，则应考虑强制执行 App Check。
对于强制执行 App Check 时的本地开发，您可以设置 App Check 调试提供程序，并仍对 Firebase AI Logic 强制执行 App Check。
Gemini API 密钥常见问题解答
了解 Gemini Developer API 和 Firebase AI Logic 的安全升级（2026 年年中）
过去，Gemini Developer API 依赖标准 Gemini API 密钥来授权使用 Gemini Developer API (generativelanguage.googleapis.com)。如果您启用了 Firebase AI Logic 并选择使用 Gemini Developer API，Firebase 会为您创建一个仅限于 Gemini Developer API 的 Gemini API 密钥。此密钥名为 Gemini Developer API key (auto created by Firebase)
从 2026 年年中开始，Gemini Developer API 将升级为更安全的替代方案，称为“授权（身份验证）密钥”（本质上是服务账号）。Firebase AI Logic也同步升级。Firebase AI Logic 现在使用我们为您自动预配的 Google 管理的服务账号 (P4SA) 来处理 Gemini Developer API 的授权，而不是使用标准 Gemini API 密钥：
Firebase AI Logic Service Agent
(service-PROJECT_ID@
对于现有项目和新项目，如果您通过 Firebase AI Logic 访问 Gemini Developer API，则无需采取任何行动，即可从 2026 年年中开始享受这些安全升级。
如何将 Gemini API 密钥迁移到“授权（身份验证）密钥”
对于现有项目和新项目，如果您通过 Firebase AI Logic 访问 Gemini Developer API，则无需采取任何行动即可利用 2026 年年中推出的安全升级（包括迁移到“授权 [auth] 密钥”）。
Firebase AI Logic 会代表我们的开发者自动处理所有必要的安全更改，以适应 Gemini Developer API 要求提供“授权（身份验证）密钥”的过渡。
从 2026 年年中开始，Firebase AI Logic 将不再预配或使用标准 Gemini API 密钥。现在，Firebase AI Logic 会使用我们在您的 Firebase 项目中自动为您预配的 Google 管理的服务账号 (P4SA) 来处理 Gemini Developer API 的授权：
Firebase AI Logic Service Agent
(service-PROJECT_ID@
鉴于此项变更，您可以查看并删除名为 Gemini Developer API key (auto created by Firebase)
-
此 Gemini API 密钥由 Firebase 创建，仅用于 Firebase AI Logic，因此可以安全删除。
不过，在删除此密钥之前，您仍应检查并确保您没有错误地将该密钥用于其他可授予 Gemini Developer API 访问权限的工具，例如 GenAI 服务器 SDK 或 Genkit。以下是检查用量的方法：
- 在 Google Cloud 控制台中，前往 Gemini Developer API 页面，然后点击管理。
-
在指标标签页的凭证下拉菜单中，选择名为
Gemini Developer API key (auto created by Firebase) -
如果显示的图表表明自 2026 年 7 月初（Firebase AI Logic 停止使用这些 API 密钥的时间）以来没有任何使用记录，则可以安全地删除该密钥。
不过，如果图表显示有使用情况，则表示您正在将该密钥用于其他工具，您应该重命名该密钥，以便清楚地表明该密钥正用于该工具（而不是用于 Firebase AI Logic）。
-
请确保您不要删除名称中包含
(auto created by Firebase)
请勿将 Gemini API 密钥添加到移动或 Web 应用的代码库中
使用 Firebase AI Logic SDK 时，您无需使用 Gemini API 密钥来授权使用 Gemini Developer API，并且不应将 Gemini API 密钥添加到应用的代码库中。
请勿将“Firebase API 密钥”用作 Gemini API 密钥
切勿将“Firebase API 密钥”用作 Gemini API 密钥。我们强烈建议您不要将 Gemini Developer API 添加到 Firebase API 密钥的许可清单中。
Firebase API 密钥是 Firebase 配置文件或对象中列出的 API 密钥，您需要将其添加到应用的代码库中，以便将应用连接到 Firebase。如果您仅将 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 密钥的安全
就您使用 Firebase AI Logic 的体验提供反馈