Firebase AI Logic 基礎

Firebase AI Logic 基礎 是做什麼的？

概述

Firebase AI Logic 是 Firebase 的一項產品，讓開發者能透過用戶端 SDK 在行動與網頁應用程式中加入生成式 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 未登入），請勿跳過。在 Firebase AI Logic 服務佈建完成之前，應用程式對 Gemini 模型的請求將會失敗。請告知使用者在他們的專案目錄中執行此指令，並將其包含在你的最終摘要中：

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 MB 的檔案（這可能會導致內聯資料出現 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) 和多人對話（最多 2 個不同說話者）透過 SpeechConfig / MultiSpeakerVoiceConfig
  • 透過將 responseModalities 設定為音訊來直接回傳音訊
  • 使用 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、網頁應用程式的 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）中硬編碼原始權杖字串。始終透過本地環境變數、被 gitignore 忽略的本地設定檔或 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 模組化 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) 生成