開始使用：透過 Apple 的基礎模型架構存取 Gemini API


在 2026 年的 WWDC 上，Apple 開放 Foundation Models 框架給第三方模型轉接程式，也就是說，您可以使用與存取裝置端模型相同的 API，透過 Foundation Models 框架存取雲端託管模型 (例如 Gemini)。

在應用程式中，您可以交換模型例項，將要求導向裝置端或雲端推論，以符合您的用途：

  • 裝置端模型可提供最高隱私權、零成本和離線支援。
  • 雲端託管 Gemini 模型提供大型脈絡窗口、進階功能和更強大的推論能力。

您可以使用 Firebase 適用於 Apple 平台的 SDK (特別是 Firebase AI Logic 程式庫)，透過 Apple 的基礎模型架構存取雲端託管的 Gemini 模型。本指南說明如何開始使用。

為保護 Gemini 模型的存取權，本指南也會說明如何設定 Firebase App Check，這項設定非常重要，即使在開發期間也一樣。

必要條件

  • 從 Mac App Store 下載 Xcode 27。

  • Apple 平台模擬器或實體裝置，兩者都執行對應的 OS 版本 (例如 iOS 27)。

  • 使用 SwiftUI 介面的 Apple 平台應用程式新 Xcode 專案。

支援的Gemini機型

與 Apple 的 Foundation Models 架構整合後，即可支援下列 Gemini 模型。

  • 一般用途模型

    • gemini-3.1-pro-preview
    • gemini-3.8-flash (以及舊版 gemini-3.7-flash、gemini-3.6-flash 和 gemini-3.5-flash)
    • gemini-3.5-flash-lite (和舊版 gemini-3.1-flash-lite)

  • 圖像生成模型

    • gemini-3-pro-image (又稱「Nano Banana Pro」)
    • gemini-3.1-flash-image (又稱「Nano Banana 2」)
    • gemini-3.1-flash-lite-image (又稱「Nano Banana 2 Lite」)

Gemini Live API 模型不受支援。 請注意，技術上支援 Gemini 2.5 模型，但不建議用於新專案，且需要特殊設定，這些指南未涵蓋相關內容。

步驟 1：建立 Firebase 專案

建議您先建立新的 Firebase 專案，再開始探索這項整合功能。

  1. 登入 Firebase控制台。

  2. 點按「建立新的 Firebase 專案」。

  3. 接著按照畫面上的指示操作。您不需要啟用 Google Analytics。

步驟 2：將應用程式連結至 Firebase

如要將應用程式連結至 Firebase，請透過 Firebase 專案註冊應用程式，並將設定檔新增至程式碼集。

  1. 在專案總覽頁面中間，按一下「iOS+」圖示，啟動設定工作流程。

  2. 註冊應用程式：

    1. 輸入應用程式的軟體包 ID。請確認這與您在 Xcode 中建構的專案軟體包 ID 相符。

    2. 按一下 [Register app] (註冊應用程式)。

  3. 新增 Firebase 設定檔。 這個檔案包含 Firebase SDK 的設定，可連線至您的 Firebase 專案。

    1. 按一下「下載」圖示 GoogleService-Info.plist 即可取得設定檔。

    2. 將 GoogleService-Info.plist 移至 Xcode 專案的根層級，並新增至所有目標。

    3. 在 Firebase 控制台中按一下「下一步」。

  4. 控制台中的工作流程會提供一般操作說明，協助您將 Firebase SDK 新增至應用程式，因此請跳至本指南的下一個步驟，查看 Firebase AI Logic 的具體操作說明。

步驟 3：在應用程式中新增 Firebase 程式庫並初始化 Firebase

  1. 使用 Swift Package Manager 新增必要的 Firebase 程式庫：

    1. 在 Xcode 中開啟應用程式專案，然後依序選取「File」 >「Add Packages」。

    2. 輸入 Firebase Apple SDK 存放區網址：

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

    3. 選擇至少 12.19.0 版。

    4. 按一下「新增套件」。Xcode 會解析並下載依附元件。

    5. 系統提示時，請將 FirebaseAILogic 和 FirebaseAppCheck 程式庫新增至應用程式目標。

  2. 在應用程式啟動時初始化 Firebase，方法是在應用程式的主要進入點加入下列程式碼：

    import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  init() {
    FirebaseApp.configure()
  }

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

步驟 4：啟用及保護 Firebase 服務

應用程式設定完成後，請啟用 Firebase AI Logic 服務，並使用 Firebase App Check 保護相關聯 API 的存取權。

步驟 4a：在 Firebase 專案中設定 Firebase AI Logic

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

  2. 按一下「開始使用」，啟動導覽式設定工作流程。

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

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

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

    自 2026 年 7 月初起，工作流程的此階段會自動強制執行Firebase App CheckAI Logic，這是重要服務，可協助保護Gemini API，避免直接從應用程式存取。開始使用時 (請參閱本指南稍後的步驟)，您需要為本機開發環境設定App Check 偵錯提供者，才能強制執行App Check。

步驟 4b：為本機開發設定 App Check 偵錯供應商

如要進行本機開發，您需要設定 App Check debug provider，略過認證程序，同時維持 App Check 的強制執行狀態。

  1. 在 Xcode 專案中，匯入 FirebaseAppCheck 並在設定 Firebase 前，使用偵錯供應商工廠初始化 App Check。

    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. 找到您的應用程式，按一下溢位選單 ()，然後選取「管理偵錯權杖」。

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

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

步驟 5：在應用程式中初始化 AI Logic 服務

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

設定 Firebase 和 App Check 後，您現在可以在應用程式中初始化 Firebase AI Logic 服務。

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.8-flash")

步驟 6：向 Gemini 模型傳送要求

在應用程式中設定、保護及初始化 Firebase AI Logic 後，即可向 Gemini 模型傳送要求。

以下範例顯示最基本的要求類型，也就是從純文字提示生成文字：

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.8-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a text response to a prompt.
let response = try await session.respond(to: "Write a story about a magic backpack.")
print(response.content)

Gemini 模型也支援其他類型的要求，例如分析圖片和 PDF、生成結構化 JSON 輸出內容，以及生成圖片 (使用「Nano Banana」模型)。如需這類要求的範例，請參閱文件或範例應用程式。

逐句顯示回覆

您可以不必等待模型生成完整結果，而是使用串流處理部分結果，加快互動速度。如要串流回應，請使用 streamResponse(to:)，而非 respond(to:)。

import FoundationModels
import FirebaseCore
import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())
// Initialize a `geminiLanguageModel` with a Gemini model that supports your use case.
let model = ai.geminiLanguageModel(name: "gemini-3.8-flash")


// Create a session by injecting the model into Apple's `LanguageModelSession`.
let session = LanguageModelSession(model: model)

// Generate a streamed text response to a prompt.
// To stream the response, use `streamResponse(to:)` instead of `respond(to:)`
let stream = session.streamResponse(to: "Write a story about a magic backpack.")
var response = ""
for try await snapshot in stream {
  // The snapshot contains *all* content generated so far.
  response = snapshot.content
}

後續步驟

  • 透過 Apple 的 Foundation Models 架構存取 Gemini API 時，請探索可用功能。
  • 瞭解如何設定模型來控管回覆內容，包括設定思考程度 (「推論」)。
  • 瞭解如何為模型提供工具，包括依據功能，確保模型能取得最新資訊。
  • 進一步瞭解 Firebase App Check，以及這項功能如何保護資源。


提供意見 瞭解如何透過 Apple 的基礎模型框架存取 Gemini API