在 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，这样您就可以快速免费开始使用。

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

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

    从 2026 年 7 月初开始，工作流的此阶段会自动 强制执行 Firebase App Check，以保护 AI Logic（ 这是一项至关重要的服务，可帮助保护直接从应用访问的 Gemini 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 或云托管的模型并非支持所有功能。

  • 以下功能 不支持混合实现或设备端 实现：Imagen 模型、Gemini Live API 和提示 模板。此外，不应依赖于词元计数，因为云托管模型和设备端模型的计数会有所不同，因此没有直观的回退。

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

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

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

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

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

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

其他限制

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

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

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


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