使用入门：通过 Apple 的基础模型框架访问 Gemini API


在 WWDC 2026 上，Apple 向第三方模型适配器开放了 Foundation Models 框架，这意味着您可以通过 Foundation Models 框架，使用与访问设备端模型相同的 API 来访问云端托管的模型（例如 Gemini）。

在应用中，您可以切换模型实例，将请求路由到设备端推理或云端推理，以适应您的用例：

  • 设备端模型可提供极高的隐私性、零成本和离线支持。
  • 云托管的 Gemini 模型提供大上下文窗口、高级功能和更强的推理能力。

您可以通过 Apple 的 Foundation Models 框架，使用适用于 Apple 平台的 Firebase SDK（具体而言，是 Firebase AI Logic 库）访问云托管的 Gemini 模型。本指南介绍了如何开始使用。

为了保护对 Gemini 模型的访问，本指南还介绍了如何设置 Firebase App Check，这至关重要，即使在开发期间也是如此。

前提条件

  • 从 Mac App Store 下载 Xcode 27。

  • Apple 平台模拟器或实体设备，两者均运行相应的操作系统版本（例如 iOS 27）。

  • 使用 SwiftUI 接口的 Apple 平台应用的新 Xcode 项目。

支持的 Gemini 模型

与 Apple 的 Foundation Models 框架的集成支持以下 Gemini 模型。

  • 通用模型

    • gemini-4-argon
    • gemini-3.8-flash
    • gemini-3.5-flash-lite（以及旧版 gemini-3.1-flash-lite）

  • 图片生成 (Nano Banana) 模型

    • gemini-nano-banana-2.1 (Nano Banana 2.1)
    • gemini-3.1-flash-image (Nano Banana 2)
    • gemini-3.1-flash-lite-image (Nano Banana 2 Lite)
    • gemini-3-pro-image (Nano Banana Pro)

不支持 Gemini Live API 模型。较旧的通用 Gemini 3.x Flash 模型支持此功能，但由于即将到来的关停日期和/或自动路由到较新模型，因此不再建议使用这些模型。

第 1 步：创建 Firebase 项目

我们建议您先创建一个新的 Firebase 项目，以便探索此集成。

  1. 登录 Firebase 控制台。

  2. 点击创建新的 Firebase 项目。

  3. 按照屏幕上的说明操作。您无需启用 Google Analytics。

第 2 步：将应用关联至 Firebase

如需将应用与 Firebase 相关联，您必须在 Firebase 项目中注册该应用，并向代码库添加配置文件。

  1. 在项目概览页面的中心位置，点击 iOS+ 图标，启动设置工作流。

  2. 注册您的应用：

    1. 输入应用的软件包 ID。确保它与您在 Xcode 中构建的项目的软件包 ID 一致。

    2. 点击注册应用。

  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，您需要启用 Firebase AI Logic 服务，并使用 Firebase App Check 保护对其关联 API 的访问。

第 4a 步：在 Firebase 项目中设置 Firebase AI Logic

  1. 在 Firebase 控制台中，依次前往 AI 服务 > AI Logic。

  2. 点击开始，启动引导式设置工作流。

  3. 当系统要求您选择“Gemini API 提供方”时，我们建议您选择 Gemini Developer API，这样您就可以免费快速开始使用。

    之后，您可以随时设置 Agent Platform Gemini API (formerly Vertex AI)（及其结算要求）。

  4. 继续执行工作流，为 Firebase AI Logic 设置所需的 API 和关联服务。

    此工作流阶段会自动为 AI Logic 强制执行 Firebase App Check，这是一项关键服务，有助于在从应用直接访问 Gemini API 时保护它。在开始使用时（请参阅本指南后面的步骤），您需要为本地开发配置 App Check 调试提供程序，以便在强制执行 App Check 时使用。

第 4b 步：为本地开发配置 App Check 调试提供程序

对于本地开发，您需要配置 App Check 调试提供程序，以绕过证明，同时仍强制执行 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 控制台中，依次前往安全性 > App Check > 应用标签页。

    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 的体验