在 Apple 应用中构建混合体验，使用设备端模型和云端托管模型

您可以使用 Firebase AI Logic 通过混合推理构建 AI 赋能的 Apple 应用和功能。混合推理支持在可用时使用设备端模型（特别是 Apple 的 Foundation Models 框架）运行推理，并在不可用时无缝回退到云托管的 Google 模型（反之亦然）。

本页面介绍了如何开始使用客户端 SDK，并展示了其他配置选项和功能，例如温度。

请注意，对于使用 Firebase AI Logic SDK v12.13.0 及更高版本且在启用了 Apple Intelligence 的设备上运行的 Apple 应用，支持通过 Firebase AI Logic 进行设备端推理。它受 Apple 基础模型框架的使用限制要求约束。

推荐的用例

  • 使用设备端模型进行推理具有以下优势：

    • 隐私保护更完善
    • 免费推理
    • 离线功能

  • 使用混合功能可提供：

    • 无论最终用户使用何种设备，都为所有客户提供类似的应用体验
    • 无论互联网连接、配额限制或设备功能如何，都能提高生成式 AI 功能的可用性

支持的功能、API 和设备

在使用 Firebase AI Logic 实现混合推理和设备端推理之前，请先查看本部分，了解 Apple 应用支持的功能。

设备端推理支持的功能和特性

设备端推理仅支持文本生成，具体而言，支持以下文本生成功能：

请务必查看本页底部尚不支持混合或设备端推理的详细列表。

支持的 API 和设备

  • 云端推理使用您选择的 Gemini API 提供方（Gemini Developer API 或 Agent Platform Gemini API (formerly Vertex AI)）。

  • 设备端推理使用 Apple 的 Foundation Models 框架，该框架仅适用于启用了 Apple Intelligence 的设备。启用 Apple 智能后，系统会自动下载设备端模型。

开始使用

请确保您已查看上文，其中介绍了支持的功能、API 和设备。

这些入门步骤介绍了您要发送的任何受支持提示请求所需的一般设置。

第 1 步：设置 Firebase 项目并将您的应用连接到 Firebase

  1. 登录 Firebase 控制台，然后选择您的 Firebase 项目。

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

  3. 点击开始，启动引导式工作流，帮助您为项目设置所需的 API 和资源。

  4. 如果系统提示，请按照屏幕上的说明注册您的应用，并将 Firebase 配置添加到您的应用中。

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

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

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

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

  7. 继续执行本指南中的下一步，将所需的 SDK 添加到您的应用中。

第 2 步：添加所需的 SDK

使用 Swift Package Manager (SPM) 安装和管理 Xcode 依赖项。只有在使用 SPM 时，混合支持才可用。

Firebase AI Logic 库提供了用于与生成模型交互的 API。该库包含在 Firebase SDK for Apple 平台 (firebase-ios-sdk) 中。

如果您已在使用 Firebase，请确保您的 Firebase 软件包为 v12.13.0 或更高版本。

  1. 在 Xcode 中打开您的应用项目，依次点击 File（文件）> Add Package Dependencies（添加软件包依赖项）。

  2. 出现提示时，添加 Firebase Apple 平台 SDK 代码库：

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

  3. 选择最新的 SDK 版本。

  4. 选择 FirebaseAILogic 和 FirebaseAppCheck 库。

完成之后，Xcode 将会自动开始在后台解析和下载您的依赖项。

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

自 2026 年 7 月初起，作为控制台中 AI Logic 引导式设置工作流的一部分，系统会自动强制执行 Firebase App Check 以保护 Gemini API。对于本地开发，您需要配置 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 文档。

第 4 步：初始化服务并创建模型会话实例

点击您的 Gemini API 提供商，以查看此页面上特定于提供商的内容和代码。

在向模型发送提示请求之前，请先完成以下设置。

  1. 为您选择的 Gemini API 提供商初始化服务。

  2. 使用 HybridModel 创建 GenerativeModelSession 实例。

  3. 根据您的偏好设置 primary 和 secondary 模型。您可以设置尝试推理的顺序：

    • 首先尝试设备端推理，但允许回退到云端：将 primary 设置为“系统”模型，并将 secondary 设置为云端模型。

    • 首先尝试云端推理，但允许回退到设备端：将 primary 设置为云端模型，并将 secondary 设置为“系统”模型。

    请注意，SDK 仅支持设置单个 model，这意味着 SDK 仅会尝试设备端推理或云端推理。不过，对于混合体验，您需要创建一个 HybridModel 并设置 primary 和 secondary 模型。

    如需详细了解“推理模式”（尝试推理的顺序）的行为，请参阅配置选项。

以下示例展示了如何先尝试设备端推理，但允许回退到云托管模型：

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Initialize a cloud model that supports your use case.
let cloudModel = ai.geminiModel(name: "GEMINI_MODEL_NAME")
// Initialize an on-device model that supports your use case.
let systemModel = FirebaseAI.SystemLanguageModel.default

// Create a Hybrid Model.
// Provide your preferred model as `primary` and your fallback model as `secondary`.
// In this example, attempt to use on-device model; otherwise, fall back to cloud.
let hybridModel = HybridModel(
  primary: systemModel,
  secondary: cloudModel
)

// Create a GenerativeModelSession with the HybridModel created earlier.
let session = firebaseAI.generativeModelSession(
  model: hybridModel,
)

第 5 步：向模型发送提示请求

本部分介绍了如何执行以下操作：

根据纯文本输入生成文本

在尝试此示例之前，请确保您已完成本指南的入门部分。

如需根据包含文本的提示生成文本，请使用 respond(to:)，如下所示：

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To generate text output, call `respond(to:)` with the text input
let response = try await session.respond(to: prompt)
print(response.content)

通过纯文本输入流式传输文本

在尝试此示例之前，请确保您已完成本指南的入门部分。

您可以通过不等待模型生成的完整结果，而是使用流式传输来处理部分结果，从而实现更快的互动。如需从包含文本的提示中流式传输生成的文本，请使用 streamResponse(to:)，如下所示：

// Imports + initialization of Gemini API backend service + creation of model session

// Provide a prompt that contains text
let prompt = "Write a story about a magic backpack."

// To stream generated text output, call `streamResponse(to:)` with the text input
let stream = session.streamResponse(to: prompt)
for try await snapshot in stream {
  print(snapshot.content)
}

你还可以做些什么？

您可以为混合体验使用各种其他配置选项和功能：

混合推理或设备端推理尚不支持的功能

作为实验性版本，并非所有 Firebase AI Logic 或云托管模型的功能都受支持。

  • 混合或设备端实现不支持以下内容：Gemini Live API 和服务器提示模板。此外，不应依赖于计数令牌，因为云托管模型和设备端模型的计数会有所不同，因此没有直观的回退。

  • 设备端推理尚不支持以下功能。 如果您想使用上述任何功能，我们建议您仅使用云托管模型，以获得更一致的体验。

    • 根据多模态输入（例如图片、音频、视频和文档 [PDF]）生成文本

    • 生成媒体内容，例如图片、音频或视频

    • 发送超过 4096 个 token（或大约 3000 个英文单词）的请求。

    • 为设备端模型提供内置工具，帮助其生成回答（例如代码执行、网址上下文和依托 Google 搜索进行接地）

  • Firebase 控制台中的 AI 监控不会显示任何设备端推理数据（包括设备端日志）。不过，任何使用云托管模型的推理都可以像通过 Firebase AI Logic 进行的其他推理一样进行监控。

其他限制

除上述限制外，设备端推理还具有以下限制：


就您使用 Firebase AI Logic 的体验提供反馈