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

Firebase AI LogicGemini API


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

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

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

您可以使用 Firebase SDK（适用于 Apple 平台，尤其是 Firebase AI Logic 库）通过 Apple 的基础模型框架访问云端托管的 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-preview（又称“Nano Banana Pro”）
    • gemini-3.1-flash-image-preview（又称“Nano Banana 2”）
    • gemini-2.5-flash-image（又称“Nano Banana”）

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。请确保该 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 中打开您的应用项目，然后依次选择文件 > 添加软件包。

    2. 输入 Firebase Apple SDK 代码库网址：

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

    3. 选择“依赖规则”作为分支，然后输入 wwdc26-preview。

    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 逻辑。

  2. 点击开始以启动设置工作流。

  3. 建议您选择 Gemini Developer API 提供方，以便快速免费开始使用。

第 4b 步：在 Firebase 项目中设置 Firebase App Check

强制执行时，Firebase App Check 只允许来自您的实际应用和未被篡改的设备的传入请求。Firebase App Check 支持许多证明提供方，包括 Apple 的 App Attest。

以下步骤适用于 App Check 的基准默认设置。详细了解 App Check 的其他配置选项（例如调整令牌的 TTL 和启用限次使用的令牌）。

在 Firebase 控制台中注册 App Attest 提供方的步骤如下：

  1. 在 Firebase 控制台中，依次前往安全性 > App Check。

  2. 点击开始使用。

  3. 在“应用”标签页中，注册您的应用，以便将 App Check 与 App Attest 提供方搭配使用。

  4. 在 API 标签页中，选择 Firebase AI Logic，然后点击强制执行。

第 4c 步：为本地开发配置 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. 在 Firebase 控制台中向 App Check 提供调试令牌：

    1. 在 Firebase 控制台中，依次前往安全性 > App Check > 应用。

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

    3. 点击添加调试令牌，输入名称（例如 My Simulator），粘贴令牌，然后点击保存。

如需详细了解调试提供程序（包括如何获取新的调试令牌），请参阅官方 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 的基础模型框架访问 Gemini API 的反馈