SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场firebase-ai-logic-basics

firebase-ai-logic-basics

智能体与模型

查看项目

更新于 10-14 14:14

技能介绍

用途

Firebase AI Logic（原名 Vertex AI for Firebase）是 Firebase 旗下产品，用于让开发者在移动端与 Web 应用（Android、iOS、Web、Flutter，以及 Unity 的 C#）中通过客户端 SDK 添加生成式 AI 能力。应用可直接经由 Firebase AI Logic 调用 Gemini 模型，开发者无需维护专用后端。

它支持两种 Gemini API 提供方：Gemini Developer API（含适合原型开发的免费额度与面向生产的按量付费）和 Agent Platform Gemini API（原品牌名 Vertex AI，面向企业级规模化生产，需 Blaze 定价方案）。默认使用 Gemini Developer API，仅在应用确有需要时使用 Agent Platform Gemini API。

初始化与配置

开始前需先确认目标平台（Android、iOS、Web 或 Flutter）。若平台不受支持，需引导用户查阅 Firebase 文档了解如何为其应用设置 AI Logic（https://firebase.google.com/docs/ai-logic/get-started）。

下列 Firebase CLI 命令在各平台均通过 npx 运行，因此需要 Node.js 20+ 和 npm。若 Node.js 缺失或低于 20 版本，需请用户安装，不要自行安装系统包（例如使用 sudo apt-get），以免未经同意更改用户机器。

所有平台都必须先开通 Firebase AI Logic：确保处于含有 firebase.json 的 firebase 目录中；使用 npx -y firebase-tools@latest projects:list 确认当前操作的 Firebase 项目（活动项目会标记为 "current"）；使用 npx -y firebase-tools@latest apps:list 确认当前项目至少注册了一个目标平台的 Firebase 应用；然后运行 npx -y firebase-tools@latest init ailogic 为该 Firebase 项目开通服务，该命令会在 Firebase 项目中启用 Gemini Developer API。

注意：所有平台（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 错误。若无法自行运行该命令（例如缺少 Node.js 或未登录 Firebase CLI），不要跳过，需告知用户在项目目录中运行该命令，并将其纳入最终总结。

第二步是按平台添加 SDK 依赖并在应用中初始化服务。编写代码前，需先阅读目标平台对应的初始化代码参考。更多信息见 Firebase AI Logic 入门文档。

主要能力

关键要求：始终使用当前模型名称，需查阅 Firebase AI Logic 模型文档确认当前受支持的模型名，不要使用 gemini-2.0-pro、gemini-2.0-flash 等已停用的旧模型。

  • 纯文本生成
  • 多模态（文本加图像/音频/视频/PDF 输入）：可分析图像文件，支持生成说明文字、回答图像相关问题、检测对象、图像分类等；还可通过内联数据加 MIME 类型分析音频、视频、PDF 等其他媒体。超过 20 MB 的文件（内联数据可能引发 HTTP 413 错误）应存入 Cloud Storage for Firebase，并将其 URL 传给 Gemini Developer API。
  • 聊天会话（多轮）：通过 startChat 自动维护历史记录。
  • 流式响应：使用 generateContentStream 替代 generateContent，以边到达边显示部分结果（类似打字效果）的方式改善用户体验。
  • 文本转语音（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）。完整实现细节、流式模式与可复制粘贴的 iOS（Swift）、Android（Kotlin）、Web 代码片段见文本转语音指南。
  • 使用 Nano Banana 生成图像：需使用当前图像模型名称（查阅模型文档）；需升级到 Blaze 按量付费方案。
  • 使用内置 googleSearch 工具进行搜索接地。

高级能力

  • 结构化输出（JSON）：为响应强制指定特定 JSON schema。
  • 端侧 AI（混合）：混合推理在有可用端侧模型时用端侧模型运行提示词，否则回退到云端模型（或反之）。可用性与设置步骤因平台而异，详见混合与端侧文档，其中链接到各平台指南。

安全与生产

Firebase App Check：这是关键安全要求。为安全使用 AI Logic，必须在应用上设置 App Check，以防未经授权的客户端使用你的 API 配额和访问后端资源。设置说明见 App Check for Firebase AI Logic；各平台使用各自的证明提供方，需按目标平台说明操作。

本地开发与 CI/CD 的 App Check 调试令牌：由于 App Check 证明提供方（如 Play Integrity 或 DeviceCheck）会拒绝模拟器、仿真器或 CI 环境，开发与测试期间必须使用 App Check 调试令牌绕过标准证明。

关键要求：切勿硬编码或提交调试令牌。调试令牌允许客户端绕过证明、在非真实设备上访问后端资源，应视为私密密钥。切勿将调试令牌提交到版本控制，或把原始令牌字符串硬编码到客户端代码中（Web、Android、iOS、Flutter）。始终通过本地环境变量、被 gitignore 的本地配置或 CI 密钥注入。若令牌泄露，应立即在 Firebase 控制台撤销。

本地开发（自动生成）：将代码的 App Check 提供方配置为使用 debug factory（API 因平台而异，参见平台参考的 App Check 部分或上述 App Check 文档）；在模拟器/localhost 中运行应用；查看运行时调试器控制台/Logcat 日志中生成的 UUID，例如：AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678"；在 Firebase 控制台的 Security > App Check > Apps > Manage debug tokens 中注册该令牌。小提示：模拟器或仿真器重置、全新安装、清除浏览器数据都可能导致 SDK 生成新的调试令牌，需重新注册。要在不硬编码的前提下保持稳定调试令牌，参见平台参考的 App Check 部分。

CI/CD 流水线（预配置）：在 Firebase 控制台 Security > App Check > Apps > Manage debug tokens 中生成并注册新调试令牌；将该令牌字符串作为加密密钥添加到 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 模块化 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）生成。