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

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

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

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

推荐的用例

  • 使用设备端模型进行推理 可提供：

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

  • 使用混合 功能可提供：

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

支持的功能、API 和设备

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

设备端推理支持的功能

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

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

支持的 API 和设备

开始使用

请确保您已查看上面介绍支持的功能、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. 继续执行工作流，为所需的 API 和关联服务设置 Firebase AI Logic。

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

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

第 2 步：添加所需的 SDK

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

Firebase AI Logic 库提供对用于与生成模型交互 的 API 的访问权限。该库作为适用于 Apple 平台的 Firebase SDK (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 并使用调试提供方工厂初始化 App Check，在配置 Firebase之前。

    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 个令牌（或大约 3000 个英文单词）的请求。

    • 为设备端模型提供 内置工具 ，以帮助其生成响应（例如代码执行、网址上下文和 Google 搜索的 Grounding）

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

其他限制

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

  • 您的应用的最终用户必须使用启用了 Apple Intelligence 的 设备。

  • 只有当应用在前台运行时，应用才能运行设备端推理。


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