Firebase AI Logic 基础

Firebase AI Logic 基础 是做什么的？

概述

Firebase AI Logic 是 Firebase 的一个产品，允许开发者使用客户端 SDK 为其移动和 Web 应用添加生成式 AI。应用可以通过 Firebase AI Logic 直接调用 Gemini 模型，无需开发者管理专用后端。Firebase AI Logic 之前称为“Vertex AI for Firebase”。

它支持两个 Gemini API 提供者：

• Gemini Developer API：提供免费套餐，适合原型开发，以及按需付费的生产环境
• Agent Platform Gemini API（原品牌 Vertex AI）：适合大规模企业级生产就绪环境，需要 Blaze 定价计划

默认使用 Gemini Developer API，仅在应用需要时才使用 Agent Platform Gemini API（原品牌 Vertex AI）。

---

设置与初始化

前提条件

• 在开始之前确定用户感兴趣的构建平台：Android、iOS、Web 或 Flutter。
• 如果平台不受支持，请指导用户访问 Firebase 文档了解如何为其应用设置 AI Logic（与用户分享此链接 https://firebase.google.com/docs/ai-logic/get-started）
• 以下 Firebase CLI 命令通过 npx 在所有平台上运行，因此需要 Node.js 20+ 和 npm。使用 firebase-basics 技能检查这些要求并登录 Firebase CLI。如果 Node.js 缺失或版本低于 20，请按照该技能描述要求用户安装。不要自行安装系统包，例如使用 sudo apt-get，因为这会在未经用户同意的情况下更改其机器。

1. 预配 Firebase AI Logic（所有平台）

使用 Firebase CLI 为 Firebase 项目预配 Firebase AI Logic：

1. 确保你在一个 firebase 目录中（带有 firebase.json）。

2. 验证你正在针对预期的 Firebase 项目运行 Firebase CLI 命令。运行此命令时，活动项目会标记为“current”：

   npx -y firebase-tools@latest projects:list
   

3. 确保当前 Firebase 项目中至少有一个针对目标平台注册的 Firebase 应用：

   npx -y firebase-tools@latest apps:list
   

4. 为 Firebase 项目预配 Firebase AI Logic：

   npx -y firebase-tools@latest init ailogic
   

   此命令将在 Firebase 项目中启用 Gemini Developer API。

[!WARNING] 关键：预配 Firebase AI Logic 是必需的 对于所有平台（Android、iOS、Web 或 Flutter），即使应用已使用 Firebase，你都必须运行 npx -y firebase-tools@latest init ailogic 来预配服务。GoogleService-Info.plist、google-services.json 和 firebase_options.dart 的配置文件仅处理客户端配置，并未启用 Firebase AI Logic 服务，会导致 PERMISSION_DENIED 错误。

如果你无法自行运行 init ailogic（例如因为 Node.js 缺失或 Firebase CLI 未登录），不要跳过它。应用对 Gemini 模型的请求将失败，直到 Firebase AI Logic 服务被预配。告诉用户在其项目目录中运行此命令，并将其包含在你的最终总结中：

npx -y firebase-tools@latest init ailogic

2. 在应用中添加 SDK 并初始化服务

添加 SDK 依赖项和初始化服务是平台相关的。在编写代码之前，请阅读目标平台在初始化代码参考下列出的参考资料。

更多信息请参阅 Firebase AI Logic 入门

---

核心功能

[!WARNING] 关键：使用当前模型名称： 始终检查 Firebase AI Logic 模型文档 以获取当前支持的模型名称。不要使用 gemini-2.0-pro 或 gemini-2.0-flash 或其他已停用的旧模型。

纯文本生成

多模态（文本 + 图像/音频/视频/PDF 输入）

Firebase AI Logic 允许 Gemini 模型直接从你的应用中分析图像文件。这可以实现创建标题、回答关于图像的问题、检测对象和对图像进行分类等功能。除了图像，Gemini 还可以通过将其他媒体类型（如音频、视频和 PDF）作为内联数据（附带其 MIME 类型）传递来分析它们。对于超过 20 兆字节的文件（可能导致 HTTP 413 错误的 inline data），请将其存储在 Cloud Storage for Firebase 中，并将其 URL 传递给 Gemini Developer API。

聊天会话（多轮）

使用 startChat 自动维护历史记录。

流式响应

为了改善用户体验，在部分结果到达时立即显示（如打字效果），使用 generateContentStream 代替 generateContent 以获得更快的结果显示。

文本转语音 (TTS) 生成

直接在客户端设备上生成语音音频，无需自定义语音后端。Firebase AI Logic 支持使用专用的 Gemini TTS 模型进行语音合成：

• 支持的模型：gemini-3.1-flash-tts-preview
• 功能：
  • 单人说话人声音角色选择（voiceName）和多人说话人对话（最多 2 个不同说话人），通过 SpeechConfig / MultiSpeakerVoiceConfig
  • 通过将 responseModalities 设置为 audio 直接返回音频响应
  • 使用 generateContentStream 进行低延迟播放的流式语音响应
  • 音频指令（[Audio Profile: ...]、[Scene: ...]、[Director's Note: ...]）和情感标签（[whispers]、[laughs]、[slowly]）
  • 客户端解码和播放 24 kHz 16 位线性 PCM（audio/l16）或 WAV 容器格式（audio/x-wav）

请参阅文本转语音 (TTS) 生成指南以获取完整的实现细节、流式模式以及适用于 iOS (Swift)、Android (Kotlin) 和 Web 的复制粘贴代码片段。

使用 Nano Banana 生成图像

[!WARNING] 使用当前的图像模型名称： 始终检查 Firebase AI Logic 模型文档 以获取当前支持的图像生成（Nano Banana）模型名称。

• 需要升级的 Blaze 按需付费结算计划。

使用内置 googleSearch 工具的搜索接地

---

支持的平台和框架

支持的平台和框架包括 Android 的 Kotlin 和 Java、iOS 的 Swift、Web 应用的 JavaScript、Flutter 的 Dart 以及 Unity 的 C Sharp。

高级功能

结构化输出 (JSON)

为响应强制执行特定的 JSON 架构。

设备端 AI（混合）

混合推理在设备端模型可用时使用设备端模型运行提示，否则回退到云端模型（或反之亦然）。可用性和设置步骤因平台而异，更多信息请参阅混合和设备端文档，其中链接到每个平台的指南。

---

安全与生产

Firebase App Check

[!WARNING] 关键安全要求： 为了安全使用 AI Logic，你必须在你的应用上设置 App Check。这可以防止未经授权的客户端使用你的 API 配额并访问你的后端资源。

请参阅 Firebase AI Logic 的 App Check 获取设置说明。每个平台使用其自己的证明提供者，因此请遵循目标平台的说明。

用于本地开发和 CI/CD 的 App Check 调试令牌

由于 App Check 证明提供者（如 Play Integrity 或 DeviceCheck）会拒绝模拟器、模拟器或 CI 环境，因此在开发和测试期间，你必须使用 App Check 调试令牌来绕过标准证明。

[!WARNING] 关键：切勿硬编码或提交调试令牌 App Check 调试令牌允许客户端绕过证明并无需真实设备即可访问后端资源。将它们视为私有密钥。切勿将调试令牌提交到版本控制或在客户端代码中硬编码原始令牌字符串（Web、Android、iOS 或 Flutter）。始终通过本地环境变量、gitignored 本地配置或 CI 密钥注入它们。如果令牌泄露，请立即在 Firebase 控制台中撤销它。

本地开发（自动生成）

1. 配置你的代码的 App Check 提供者以使用调试工厂。该 API 是平台相关的；请参阅平台参考的 App Check 部分或上面链接的 App Check 文档。
2. 在模拟器/localhost 中运行你的应用。
3. 查看你的运行时调试器控制台 / Logcat 日志，查找生成的 UUID：
   • 示例： AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678"
4. 在 Firebase 控制台中注册此令牌，路径为 安全 > App Check > 应用 > 管理调试令牌。

💡 提示（防止调试令牌轮换）： 模拟器或模拟器重置、全新安装和清除浏览器数据可能导致 SDK 生成一个新的调试令牌，你必须再次注册。为了在不硬编码的情况下保持稳定的调试令牌，请参阅平台参考的 App Check 部分。

CI/CD 流水线（预配）

1. 在 Firebase 控制台中生成并注册一个新的调试令牌，路径为 安全 > App Check > 应用 > 管理调试令牌。
2. 将此令牌字符串作为加密密钥添加到你的 CI 系统中（例如 APP_CHECK_DEBUG_TOKEN）。
3. 配置你的构建以在测试执行期间将此密钥作为环境变量传递给 SDK。

Firebase Remote Config

注意，你无需硬编码模型名称（例如特定的模型版本字符串）。使用 Firebase Remote Config 动态更新模型版本，而无需部署新的客户端代码。请参阅 远程更改模型名称

---

初始化代码参考

• Android (Kotlin)

  • Gemini API 提供者：Gemini Developer API
  • 参考：usage_patterns_android.md

• iOS (Swift)

  • Gemini API 提供者：Gemini Developer API
  • 参考：ios_setup.md

• Web Modular API

  • Gemini API 提供者：Gemini Developer API
  • 参考：usage_patterns_web.md

• Flutter (Dart)

  • Gemini API 提供者：Gemini Developer API
  • 参考：flutter_setup.md

[!WARNING] 关键：使用当前模型名称： 始终检查 Firebase AI Logic 模型文档 以获取当前支持的模型名称。不要使用 gemini-2.0-pro 或 gemini-2.0-flash 或其他已停用的旧模型。

参考

Android (Kotlin) SDK 使用模式 iOS SDK 代码示例和使用模式 Web SDK 设置、代码示例和使用模式

Flutter SDK 代码示例和使用模式 客户端文本转语音 (TTS) 生成