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


在 2026 年的 WWDC 上，Apple 向第三方模型适配器开放了 Foundation Models 框架，这意味着您可以通过 Foundation Models 框架访问云端托管的模型（例如 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.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. 点击注册应用。

  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 API 提供方”时，我们建议您选择 Gemini Developer API，这样您就可以免费快速开始使用。

    在以后的任何时间，您都可以随时设置 Agent Platform Gemini API (formerly Vertex AI)（以及其结算要求）。

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

    从 2026 年 7 月初开始，此工作流程阶段将自动针对 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 的基础模型框架访问 Gemini API