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


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

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

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

您可以通过使用 Firebase SDK for Apple 平台（具体来说是 Firebase AI Logic 库），通过 Apple's Foundation Models 框架访问云端托管的 Gemini 模型 。本指南将向您展示如何开始使用。

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

前提条件

  • 安装最新的 Xcode 27 Beta 版。

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

  • 使用 SwiftUI 界面的 Apple 平台应用的新 Xcode 项目。

受支持的 Gemini 模型

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

  • 通用模型

    • gemini-3.1-pro-preview
    • gemini-3.5-flash
    • 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 模型和 Imagen 模型 不受 支持。 请注意，从技术上讲，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. 选择依赖项规则作为 Branch （分支），然后输入 wwdc26-preview 。

    4. 点击 Add Package （添加软件包）。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 Services > AI Logic。

  2. 点击 Get started （开始使用）以启动引导式设置工作流。

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

    您以后随时可以 设置 Vertex AI Gemini API （及其结算要求）。

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

    从 2026 年 7 月初开始，工作流的此阶段会自动 为 AI Logic强制执行 Firebase App Check， 这是一项 至关重要 的服务，有助于在直接从应用访问 Gemini API 时保护该 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 控制台中，依次前往 Security（安全）> App Check > Apps（应用）标签页。

    2. 找到您的应用，点击溢出菜单 ()，然后选择 Manage debug tokens（管理调试令牌）。

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