firebase-ai-logic-basics

Firebase AI Logic 基础知识

概述

Firebase AI Logic 是 Firebase 的一款产品，可让开发者使用客户端 SDK 将生成式 AI 添加到移动和 Web 应用中。应用可以通过 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 CLI 命令针对的是预期的 Firebase 项目。运行此命令时，当前项目会标记为“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。

警告

关键：必须配置 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），请勿跳过此步骤。在配置 Firebase AI Logic 服务之前，应用对 Gemini 模型的请求都会失败。请告知用户在其项目目录中运行此命令，并在最终摘要中注明：

npx -y firebase-tools@latest init ailogic

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

添加 SDK 依赖项和初始化服务的方式因平台而异。编写代码之前，请阅读初始化代码参考中目标平台对应的参考内容。

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

---

核心功能

警告

**关键：使用当前模型名称：**始终查阅 Firebase AI Logic 模型文档，确认当前支持的模型名称。请勿使用已停用的 gemini-2.0-pro、gemini-2.0-flash 或其他旧版模型。

仅文本生成

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

Firebase AI Logic 允许 Gemini 模型直接分析应用中的图像文件。这可实现创建说明文字、回答有关图像的问题、检测对象和对图像分类等功能。除了图像，Gemini 还可以分析音频、视频和 PDF 等其他媒体类型，方法是将它们作为内联数据传递，并附上 MIME 类型。对于大于 20 megabytes 的文件（作为内联数据时可能导致 HTTP 413 错误），请将文件存储在 Cloud Storage for Firebase 中，并将其 URL 传递给 Gemini Developer API。

聊天会话（多轮）

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

流式响应

若要在结果生成时逐步显示（例如打字效果），从而改善用户体验，请使用 generateContentStream，而不是 generateContent，以更快地显示结果。

文本转语音（TTS）生成

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

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

如需了解完整的实现详情、流式处理模式，以及适用于 iOS（Swift）、Android（Kotlin）和 Web 的可直接复制粘贴的代码片段，请参阅文本转语音（TTS）生成指南。

使用 Nano Banana 生成图像

警告

**使用当前的图像模型名称：**请务必查看 Firebase AI Logic 模型文档， 了解当前支持的图像生成（Nano Banana）模型名称。

• 需要升级到 Blaze 按量付费套餐。

使用内置的 googleSearch 工具进行搜索 grounding

---

支持的平台和框架

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

高级功能

结构化输出（JSON）

强制响应遵循特定的 JSON 架构。

设备端 AI（混合模式）

混合推理会在设备端模型可用时使用它运行提示词，否则回退到云托管模型（反之亦然）。不同平台的可用性和设置步骤有所不同，更多信息请参阅混合模式和设备端文档，其中链接了各平台的指南。

---

安全与生产环境

Firebase App Check

警告

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

请参阅 Firebase AI Logic 的 App Check了解设置说明。每个平台使用各自的认证提供方，请按照目标平台的说明操作。

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

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

警告

重要：切勿硬编码或提交调试令牌 App Check 调试令牌允许客户端绕过证明流程，在没有真实设备的情况下访问后端资源。请将其视为私密密钥。切勿将调试令牌提交到版本控制系统，也不要在客户端代码中硬编码原始令牌字符串（Web、Android、iOS 或 Flutter）。始终通过本地环境变量、加入 gitignore 的本地配置或 CI 密钥注入令牌。如果令牌泄露，请立即在 Firebase Console 中撤销。

本地开发（自动生成）

1. 将代码中的 App Check 提供方配置为使用调试工厂。API 因平台而异；请参阅平台参考资料中的 App Check 部分，或上方链接的 App Check 文档。
2. 在模拟器/localhost 中运行应用。
3. 在运行时调试器控制台或 Logcat 日志中查找生成的 UUID：
   • 示例： AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678"
4. 在 Firebase Console 的 Security > App Check > Apps > Manage debug tokens 下注册此令牌。

**💡 提示（避免调试令牌频繁变更）：**重置仿真器或模拟器、全新安装以及清除浏览器数据，都可能导致 SDK 生成新的调试令牌，你必须重新注册该令牌。如需使用稳定的调试令牌而不将其硬编码，请参阅平台参考资料中的 App Check 部分。

CI/CD 流水线（预先配置）

1. 在 Firebase Console 的 Security > App Check > Apps > Manage debug tokens 下生成并注册新的调试令牌。
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

警告

**重要：使用当前的模型名称：**始终查阅 Firebase AI Logic 模型文档， 了解当前支持的模型名称。请勿使用已停用的 gemini-2.0-pro、gemini-2.0-flash 或其他旧版模型。

参考资料

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

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