THE3RDTRAINER/Homepage

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 App：

   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 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) 以及透過 SpeechConfig / MultiSpeakerVoiceConfig 進行多說話者對話（最多 2 個不同的說話者）
  • 透過將 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 控制台的 Security > App Check > Apps > Manage debug tokens 中註冊此權杖。

💡 提示（防止除錯權杖流失）： 模擬器或模擬器重置、全新安裝以及清除瀏覽器資料可能會導致 SDK 生成新的除錯權杖，您必須再次註冊。若要在不硬編碼的情況下保持穩定的除錯權杖，請參閱平台參考文件的 App Check 部分。

CI/CD 管道（預先佈建）

1. 在 Firebase 控制台的 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

[!WARNING] 關鍵事項：使用最新的模型名稱： 請務必查閱 Firebase AI Logic 模型文件 以取得當前支援的模型名稱。請勿使用 gemini-2.0-pro 或 gemini-2.0-flash 或其他已下架的舊版模型。

參考資料

Android (Kotlin) SDK 使用模式 iOS SDK 程式碼範例與使用模式 Web SDK 設定、程式碼範例與使用模式

Flutter SDK 程式碼範例與使用模式 用戶端文字轉語音（TTS）生成