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：
-
确保你位于包含
firebase.json的 Firebase 目录中。 -
验证你正在针对预期的 Firebase 项目运行 Firebase CLI 命令。运行此命令时，活动项目会标有 "current"：
npx -y firebase-tools@latest projects:list -
确保当前 Firebase 项目中至少有一个目标平台的 Firebase 应用已注册：
npx -y firebase-tools@latest apps:list -
为 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 Models 文档 以获取当前支持的模型名称。不要使用
gemini-2.0-pro或gemini-2.0-flash或其他已停用的旧模型。
文本生成
多模态（文本 + 图像/音频/视频/PDF 输入）
Firebase AI Logic 允许 Gemini 模型直接从你的应用分析图像文件。这可以实现创建标题、回答图像相关问题、检测对象和对图像进行分类等功能。除了图像，Gemini 还可以分析其他媒体类型，如音频、视频和 PDF，方式是将它们作为内联数据（附上 MIME 类型）传递。对于大于 20 兆字节的文件（作为内联数据可能导致 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 - 功能：
- 通过
voiceName选择单说话人声音角色，以及通过SpeechConfig/MultiSpeakerVoiceConfig实现多说话人对话（最多 2 个不同说话人） - 通过将
responseModalities设置为音频来直接返回音频响应 - 使用
generateContentStream进行流式语音响应，实现低延迟播放 - 音频指令（
[Audio Profile: ...]、[Scene: ...]、[Director's Note: ...]）和情感标签（[whispers]、[laughs]、[slowly]） - 客户端解码和播放 24 kHz 16 位线性 PCM（
audio/l16）或 WAV 容器格式（audio/x-wav）
- 通过
有关完整的实现细节、流模式以及 iOS (Swift)、Android (Kotlin) 和 Web 的复制粘贴代码片段，请参阅文本转语音 (TTS) 生成指南。
使用 Nano Banana 生成图像
[!WARNING] 使用当前图像模型名称 始终查看 Firebase AI Logic Models 文档 以获取当前支持的图像生成（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 控制台中撤销它。
本地开发（自动生成）
- 配置你代码的 App Check 提供方以使用调试工厂。API 是特定于平台的；请参阅平台参考的 App Check 部分或上面链接的 App Check 文档。
- 在模拟器/localhost 中运行你的应用。
- 在运行时调试控制台 / Logcat 日志中查找生成的 UUID：
- 示例：
AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678"
- 示例：
- 在 Firebase 控制台的 安全性 > App Check > 应用 > 管理调试令牌 中注册此令牌。
💡 提示（防止调试令牌变动）： 模拟器或模拟器重置、全新安装和清除浏览器数据可能导致 SDK 生成新的调试令牌，你必须重新注册。要保持稳定的调试令牌而不进行硬编码，请参阅平台参考的 App Check 部分。
CI/CD 流水线（预配）
- 在 Firebase 控制台的 安全性 > App Check > 应用 > 管理调试令牌 中生成并注册一个新的调试令牌。
- 将此令牌字符串作为加密密钥添加到你的 CI 系统中（例如
APP_CHECK_DEBUG_TOKEN）。 - 配置你的构建，将此密钥作为环境变量传递给测试执行期间的 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 Models 文档 以获取当前支持的模型名称。不要使用
gemini-2.0-pro或gemini-2.0-flash或其他已停用的旧模型。
参考
Android (Kotlin) SDK 使用模式 iOS SDK 代码示例和使用模式 Web SDK 设置、代码示例和使用模式