您可以使用 Firebase AI Logic 通过混合推理构建 AI 赋能的 Apple 应用和功能。混合推理支持在可用时使用设备端模型(特别是 Apple 的 Foundation Models 框架)运行推理,并在不可用时无缝回退到云托管的 Google 模型(反之亦然)。
本页介绍了如何开始使用客户端 SDK。完成此标准设置后,请查看其他配置选项和功能。
请注意,对于使用 Firebase AI Logic SDK v12.13.0 及更高版本且在启用了 Apple Intelligence 的设备上运行的 Apple 应用,支持通过 Firebase AI Logic 进行设备端推理。它受《Apple 基础模型框架的使用限制要求》约束。
应用场景和支持的功能
根据应用的使用场景,您可以利用设备端或混合体验的以下几项优势:
使用设备端模型进行推理的好处:
- 隐私保护更完善
- Local Context
- 免费推理
- 离线功能
使用混合方法的优势:
- 无论最终用户使用何种设备,都能提供类似的应用体验
- 提高生成式 AI 功能的可用性,不受网络连接、配额限制或设备功能的限制
支持的设备端推理功能
设备端推理仅支持文本生成,具体而言,支持以下功能:
生成结构化输出,包括 JSON 和枚举。(文档即将推出!)
请务必查看本页底部的混合推理或设备端推理尚不支持的功能列表。
支持的 API 和设备
以下部分介绍了支持的 API 以及支持的设备(及其设备端模型)。
支持的 API(云端推理与设备端推理)
云端推理使用您选择的 Gemini API 提供方(Gemini Developer API 或 Agent Platform Gemini API (formerly Vertex AI))。
设备端推理使用 Apple 的 Foundation Models 框架,该框架仅适用于启用了 Apple Intelligence 的设备。启用 Apple Intelligence 后,系统会自动下载设备端模型。
支持的 Apple 设备及其设备端模型
对于设备端推理(使用 Apple 的 Foundation Models 框架),您可以在 Apple 文档中找到已启用 Apple Intelligence 的设备列表。
开始使用
这些入门步骤介绍了您要发送的任何受支持的提示请求所需的一般设置。
第 1 步:设置 Firebase 项目并将您的应用连接到 Firebase
登录 Firebase 控制台,然后选择您的 Firebase 项目。
在 Firebase 控制台中,依次前往 AI 服务 > AI Logic。
点击开始,启动引导式工作流,该工作流可帮助您为项目设置所需的 API 和资源。
如果系统提示,请按照屏幕上的说明注册您的应用,并将 Firebase 配置添加到您的应用中。
当系统要求您选择“Gemini API 提供方”时,我们建议您选择 Gemini Developer API,这样您就可以免费快速开始使用。
之后,您可以随时设置 Agent Platform Gemini API (formerly Vertex AI)(及其结算要求)。
继续执行工作流,为 Firebase AI Logic 设置所需的 API 和关联服务。
此工作流阶段会自动为 AI Logic 强制执行 Firebase App Check,这是一项关键服务,有助于在从应用直接访问 Gemini API 时保护它。在开始使用时(请参阅本指南后面的步骤),您需要为本地开发配置 App Check 调试提供程序,以便在强制执行 App Check 时使用。
继续执行本指南中的下一步,将所需的 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 或更高版本。
在 Xcode 中打开您的应用项目,依次点击 File(文件)> Add Package Dependencies(添加软件包依赖项)。
出现提示时,添加 Firebase Apple 平台 SDK 代码库:
https://github.com/firebase/firebase-ios-sdk选择最新的 SDK 版本。
选择
FirebaseAILogic和FirebaseAppCheck库。
完成之后,Xcode 将会自动开始在后台解析和下载您的依赖项。
第 3 步:为本地开发配置 App Check 调试提供程序
在控制台中,作为 AI Logic 引导式设置工作流的一部分,系统会自动强制执行 Firebase App Check,以保护 Gemini API。 对于本地开发,您需要配置 App Check 调试提供程序,以绕过证明,同时仍保持 App Check 的强制执行。
如需在模拟器中以交互方式运行应用时(例如在本地开发期间)使用调试提供程序,请执行以下操作:
在 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() } } } }获取调试令牌:
在模拟器或测试设备上启动您的应用。
打开 Xcode 控制台,然后查找 App Check 调试令牌。例如:
<Warning> [AppCheckCore][I-GAC004001] App Check debug token: '123a4567-b89c-12d3-e456-789012345678'.复制令牌(例如
123a4567-b89c-12d3-e456-789012345678)。
向 App Check 注册调试令牌:
在 Firebase 控制台中,前往安全性 > App Check > 应用标签页。
找到您的应用,点击溢出菜单 (),然后选择管理调试令牌。
按照屏幕上的说明注册调试令牌。
如需详细了解调试提供程序(包括如何获取新的调试令牌),请参阅官方 App Check 文档。
第 4 步:初始化服务并创建模型会话实例
|
点击您的 Gemini API 提供商,以查看此页面上特定于提供商的内容和代码。 |
在向模型发送提示请求之前,请先完成以下设置。
为您选择的 Gemini API 提供商初始化服务。
使用
HybridModel创建GenerativeModelSession实例。根据您的偏好设置
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 SDK 的所有功能都可用于混合或设备端推理。
混合实现尚不支持的功能
以下功能无法与混合实现搭配使用(无论是设备端还是通过云端回退):
Gemini Live API:不支持双向实时流式传输。
服务器提示模板:不支持托管式服务器提示模板。
统计词元数:不应依赖于统计词元数,因为云托管模型和设备端模型的词元数会有所不同,因此没有直观的后备方案。
设备端推理尚不支持的功能
设备端推理尚不支持以下功能,但云托管模型支持这些功能。
生成媒体内容,例如图片、音频或视频
根据图片、音频、视频和文档 (PDF) 的多模态输入生成文本
发送超过 4096 个 token(或大约 3000 个英文单词)的请求
为设备端模型提供内置工具,以帮助其生成回答(例如代码执行、网址上下文、使用
Google Search 建立依据,以及使用Google Maps 建立依据)。不过,支持使用函数调用提供您自己的工具。Firebase 控制台中的 AI 监控不会显示设备端推理的任何数据(包括设备日志)。不过,任何使用云托管模型的推理都可以像通过 Firebase AI Logic 进行的其他推理一样进行监控。
其他限制
除上述限制外,设备端推理还具有以下限制:
应用的最终用户必须使用已启用 Apple Intelligence 的设备。
您的应用只能在前台运行时执行设备端推理。