使用裝置端和雲端託管模型，在 Apple 應用程式中建構混合式體驗

您可以使用 Firebase AI Logic，透過混合式推論建構 AI 輔助 Apple 應用程式和功能。混合推論功能可讓您在可用時，使用裝置端模型 (特別是 Apple 的 Foundation Models 架構) 執行推論，並在無法使用時，順暢地改用雲端託管的 Google 模型 (反之亦然)。

本頁說明如何開始使用用戶端 SDK，以及其他設定選項和功能，例如溫度參數。

請注意，如果 Apple 應用程式使用 Firebase AI Logic SDK 12.13.0 以上版本，並在已啟用 Apple Intelligence 的裝置上執行，則支援透過 Firebase AI Logic 進行裝置端推論。並受適用於 Apple 基礎模型架構的使用規定約束。

建議用途

  • 使用裝置端模型進行推論的優點：

    • 強化隱私
    • 免付費推論
    • 離線功能

  • 使用混合功能提供的服務：

    • 無論使用者的裝置為何，都能為所有消費者提供類似的應用程式體驗
    • 無論網際網路連線、配額限制或裝置功能如何，都能提高生成式 AI 功能的可用性

支援的功能、API 和裝置

使用 Firebase AI Logic 實作混合式和裝置端推論前，請先詳閱本節，瞭解 Apple 應用程式支援的功能。

裝置端推論支援的功能

裝置端推論僅支援文字生成，具體來說，就是以下文字生成功能：

請務必查看本頁底部的尚未支援的混合式或裝置端推論詳細清單。

支援的 API 和裝置

開始使用

請務必詳閱上述章節，瞭解支援的功能、API 和裝置。

這些入門步驟說明瞭傳送任何支援的提示要求時，所需的一般設定。

步驟 1：設定 Firebase 專案，並將應用程式連結至 Firebase

  1. 登入 Firebase 控制台，然後選取 Firebase 專案。

  2. 在 Firebase 控制台中，依序前往「AI Services」(AI 服務) >「AI Logic」(AI 邏輯)。

  3. 按一下「開始使用」，啟動導覽工作流程，協助您為專案設定必要 API 和資源。

  4. 如果出現提示，請按照畫面上的指示註冊應用程式，並將 Firebase 設定新增至應用程式。

  5. 系統要求選擇「Gemini API 供應商」時，建議選取 Gemini Developer API，即可快速開始使用，不必付費。

    日後隨時可以設定 Agent Platform Gemini API (formerly Vertex AI) (以及帳單相關規定)。

  6. 繼續執行工作流程，為 Firebase AI Logic 設定必要的 API 和相關聯服務。

    2026 年 7 月上旬起，這個工作流程階段會自動強制執行Firebase App Check，用於 AI Logic，這是一項重要服務，可在應用程式直接存取時，協助保護 Gemini API。在開始使用時 (請參閱本指南後續步驟)，您必須在本機開發環境中，設定 App Check 偵錯服務，以便強制執行 App Check。

  7. 請繼續閱讀本指南的下一個步驟，將必要的 SDK 新增至應用程式。

步驟 2：新增必要的 SDK

使用 Swift Package Manager (SPM) 安裝及管理 Xcode 依附元件。混合支援僅適用於 SPM。

Firebase AI Logic 程式庫提供 API，可與生成式模型互動。這個程式庫已納入適用於 Apple 平台的 Firebase SDK (firebase-ios-sdk)。

如果您已使用 Firebase，請確認 Firebase 套件為 12.13.0 以上版本。

  1. 在 Xcode 中保持開啟應用程式專案，然後依序點選「File」(檔案) 和「Add Package Dependencies」(新增套件依附元件)。

  2. 系統提示時，請新增 Firebase Apple 平台 SDK 存放區：

    https://github.com/firebase/firebase-ios-sdk

  3. 選取最新 SDK 版本。

  4. 選取 FirebaseAILogic 和 FirebaseAppCheck 程式庫。

完成後，Xcode 就會自動開始在背景中解析並下載依附元件。

步驟 3：設定 App Check 偵錯服務，以便在本機開發

2026 年 7 月上旬起，在控制台設定 AI Logic 的引導式工作流程中，系統會自動強制執行 Firebase App Check，以保護Gemini API。如要進行本機開發，您需要設定 App Check debug provider，略過認證程序，同時維持 App Check 的強制執行狀態。

在模擬器中以互動方式執行應用程式時 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

  1. 在 Xcode 專案中，匯入 FirebaseAppCheck 並使用偵錯服務工廠 初始化 App Check，然後再設定 Firebase。

    import SwiftUI
import FirebaseCore
import FirebaseAppCheck

@main
struct YourApp: App {
  init() {
    let providerFactory = AppCheckDebugProviderFactory()
    AppCheck.setAppCheckProviderFactory(providerFactory)
    FirebaseApp.configure()
  }

  var body: some Scene {
    WindowGroup {
      NavigationView {
        ContentView()
      }
    }
  }
}

  2. 取得偵錯權杖：

    1. 在模擬器或測試裝置上啟動應用程式。

    2. 開啟 Xcode 控制台，找出 App Check 偵錯權杖。例如：

      <Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.

    3. 複製權杖 (例如 123a4567-b89c-12d3-e456-789012345678)。

  3. 向 App Check 註冊偵錯權杖：

    1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」 >「Apps」(應用程式) 分頁標籤。

    2. 找到應用程式，按一下溢位選單 ()，然後選取「Manage debug tokens」。

    3. 按照畫面上的指示註冊偵錯權杖。

如要進一步瞭解偵錯服務 (包括如何取得新的偵錯權杖)，請參閱官方 App Check 文件。

步驟 4：初始化服務並建立模型工作階段例項

按一下您的Gemini API供應商，即可在這個頁面查看供應商專屬內容和程式碼。

將提示要求傳送至模型前，請先完成下列設定。

  1. 為所選 Gemini API 供應商初始化服務。

  2. 使用 HybridModel 建立 GenerativeModelSession 執行個體。

  3. 根據偏好設定 primary 和 secondary 模型。您可以設定嘗試推論的順序：

    • 先嘗試裝置端推論，但允許回退至雲端：將 primary 設為「系統」模型，並將 secondary 設為雲端模型。

    • 先嘗試雲端推論，但允許備援至裝置端：將 primary 設為雲端模型，並將 secondary 設為「系統」模型。

    請注意，SDK 只能設定單一 model，也就是說，SDK 只會嘗試在裝置端或雲端進行推論。不過，如要使用混合體驗，您需要建立 HybridModel，並設定 primary 和 secondary 模型。

    如要進一步瞭解「推論模式」的行為 (嘗試推論的順序)，請參閱設定選項。

以下範例說明如何先嘗試在裝置端推論，但允許改用雲端託管模型：

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Initialize a cloud model that supports your use case.
let cloudModel = ai.geminiModel(name: "GEMINI_MODEL_NAME")
// Initialize an on-device model that supports your use case.
let systemModel = FirebaseAI.SystemLanguageModel.default

// Create a Hybrid Model.
// Provide your preferred model as `primary` and your fallback model as `secondary`.
// In this example, attempt to use on-device model; otherwise, fall back to cloud.
let hybridModel = HybridModel(
  primary: systemModel,
  secondary: cloudModel
)

// Create a GenerativeModelSession with the HybridModel created earlier.
let session = firebaseAI.generativeModelSession(
  model: hybridModel,
)

步驟 5：向模型傳送提示要求

本節說明如何執行下列操作：

根據純文字輸入內容生成文字

試用這個範例前，請務必先完成本指南的「開始使用」一節。

如要從含有文字的提示生成文字，請使用 respond(to:)，如下所示：

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To generate text output, call `respond(to:)` with the text input
let response = try await session.respond(to: prompt)
print(response.content)

從純文字輸入串流文字

試用這個範例前，請務必完成本指南的「入門」一節。

您可以使用串流處理部分結果，不必等待模型生成完整結果，即可加快互動速度。如要從包含文字的提示逐句顯示生成的文字，請使用 streamResponse(to:)，如下所示：

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To stream generated text output, call `streamResponse(to:)` with the text input
let stream = session.streamResponse(to: prompt)
for try await snapshot in stream {
  print(snapshot.content)
}

你還可以做些什麼？

您可以為混合式體驗使用各種額外的設定選項和功能：

混合式或裝置端推論尚不支援的功能

由於這是實驗性版本，因此不支援 Firebase AI Logic 或雲端託管模型的所有功能。

  • 混合或裝置端實作不支援 Gemini Live API 和伺服器提示詞範本。此外，請勿依賴計數權杖，因為雲端託管模型和裝置端模型的計數會有所不同，因此沒有直覺式的備用方案。

  • 裝置端推論尚不支援下列功能。 如要使用上述任一功能，建議只使用雲端託管模型，確保體驗一致。

    • 依據圖片、音訊、影片和文件 (PDF) 等多模態輸入內容生成文字

    • 生成圖片、音訊或影片等媒體

    • 傳送超過 4096 個詞元 (或約 3000 個英文字) 的要求。

    • 為裝置端模型提供內建工具，協助生成回覆 (例如執行程式碼、網址背景資訊和以 Google 搜尋強化事實基礎)

  • Firebase 控制台中的 AI monitoring 功能不會顯示任何裝置端推論資料 (包括裝置記錄)。不過，任何使用雲端託管模型的推論，都可以像其他推論一樣，透過 Firebase AI Logic 監控。

其他限制

除了上述限制外，裝置端推論還有下列限制：


提供有關 Firebase AI Logic 的使用體驗意見回饋