使用入门：通过 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.7-flash、gemini-3.6-flash 和 gemini-3.5-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.1-pro-preview 和 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. 点击注册应用。

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