在 Web 应用中利用设备端模型和云端托管模型打造混合体验

您可以使用 Firebase AI Logic 通过混合推理构建 AI 赋能的 Web 应用和功能。混合推理支持在可用时使用设备端模型运行推理，否则无缝回退到云托管模型（反之亦然）。

本页介绍了如何开始使用客户端 SDK。完成此标准设置后，请查看其他配置选项和功能。

请注意，对于使用 Firebase AI Logic SDK v12.5.0 及更高版本且在桌面版 Chrome（139 或更高版本）上运行的 Web 应用，支持通过 Firebase AI Logic 进行设备端推理。

跳转到查看代码示例

应用场景和支持的功能

根据应用的使用场景，您可以利用设备端或混合体验的以下几项优势：

• 使用设备端模型进行推理的好处：

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

• 使用混合方法的优势：

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

支持的设备端推理功能

设备端推理仅支持单轮文本生成（而非对话）（采用流式或非流式输出），具体包括以下功能：

• 根据纯文本输入生成文本。

• 根据文本和图片输入生成文本，特别是 JPEG 和 PNG 类型的输入图片。

• 生成结构化输出，包括 JSON 和枚举。

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

支持的 API 和平台

以下部分介绍了支持的 API 以及支持的平台和浏览器。

支持的 API（云端推理与设备端推理）

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

• 设备端推理使用 Chrome 中的 Prompt API。

支持的平台和浏览器

对于设备端推理（使用 Chrome 中的 Prompt API），应用的最终用户必须在桌面设备上运行 Chrome（版本 139 或更高版本）。 如需了解详情，请参阅 Chrome 文档。

在 localhost 上开始

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

如需详细了解如何在 localhost 上使用 API，请参阅 Chrome 文档。

第 1 步：设置 Chrome 和 Prompt API 以进行设备端推理

1. 请确保您使用的是最新版 Chrome。在 chrome://settings/help 中更新。
   Chrome 139 及更高版本支持设备端推理。

2. 通过将以下标志设置为已启用，启用设备端多模态模型：

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

3. 重启 Chrome。

4. （可选）在发出第一个请求之前下载设备端模型。

   Prompt API 内置于 Chrome 中；不过，设备端模型默认不可用。如果您在首次请求设备端推理之前尚未下载模型，则该请求会自动在后台启动模型下载。

   注意：下载模型可能需要几分钟时间，因此，如果等待第一个请求自动下载，可能会导致该请求的响应时间显著延迟。

   查看下载设备端模型的说明

   1. 依次打开开发者工具 > 控制台。

   2. 运行以下命令：

      await LanguageModel.availability();
      

   3. 确保输出为 available、downloading 或 downloadable。

   4. 如果输出为 downloadable，请运行以下命令开始下载模型：

      await LanguageModel.create();
      

   5. 您可以使用以下 monitor 回调来监听下载进度，并确保在发出请求之前模型已 available：

      const session = await LanguageModel.create({
        monitor(m) {
          m.addEventListener("downloadprogress", (e) => {
            console.log(`Downloaded ${e.loaded * 100}%`);
          });
        },
      });
      

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

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

   还没有 Firebase 项目？

   如果您还没有 Firebase 项目，请点击相应按钮以创建新的 Firebase 项目，然后使用以下任一选项：

   • 方法 1：在工作流的第一步中输入新项目名称，创建一个全新的 Firebase 项目（该操作会自动创建相应的底层 Google Cloud 项目）。

   • 方法 2：点击将 Firebase 添加到 Google Cloud 项目（位于页面底部），将 Firebase 添加到现有 Google Cloud 项目。在工作流的第一步中，开始输入现有项目的项目名称，然后从显示的列表中选择该项目。

   完成屏幕上工作流的其余步骤，以创建 Firebase 项目。请注意，如果系统提示您是否要设置 Google Analytics，您无需进行此项设置即可使用 Firebase AI Logic SDK。

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 和关联服务。

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

   注意：如需向最终用户发布应用的 AI 功能，您需要向正式版 App Check 认证提供方注册您的应用，以便用户在强制执行 App Check 时可以使用该功能。

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

第 3 步：添加 SDK

Firebase 库提供了用于与生成模型交互的 API。该库包含在 Firebase JavaScript SDK for Web 中。

1. 使用 npm 安装 Firebase JS SDK for Web：

   npm install firebase
   

2. 在您的应用中初始化 Firebase：

   import { initializeApp } from "firebase/app";
   import { initializeAppCheck } from "firebase/app-check";
   
   // TODO(developer) Replace the following with your app's Firebase configuration
   // See: https://firebase.google.com/docs/web/learn-more#config-object
   const firebaseConfig = {
     // ...
   };
   
   // Initialize FirebaseApp
   const firebaseApp = initializeApp(firebaseConfig);
   

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

在控制台中，作为 AI Logic 引导式设置工作流的一部分，系统会自动强制执行 Firebase App Check，以保护 Gemini API。 对于本地开发，您需要配置 App Check 调试提供程序，以绕过证明，同时仍保持 App Check 的强制执行。

重要提示：请确保为 AI Logic 强制执行 App Check。在 Firebase 控制台中，前往安全性 > App Check > API 标签页，然后找到 Firebase AI Logic 对应的行。如果显示 Unenforced，请按照自行强制执行 App Check 的说明操作。

如需在从 localhost 以交互方式运行应用时（例如在本地开发期间）使用调试提供程序，请执行以下操作：

警告： 请勿通过将 localhost 添加到 reCAPTCHA 允许的网域来尝试启用 localhost 调试。否则，任何人都可以从本地机器运行您的应用！

1. 在调试 build 中，请在初始化 App Check 之前将 self.FIREBASE_APPCHECK_DEBUG_TOKEN 设置为 true 以启用调试模式。例如：

   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   initializeAppCheck(firebaseApp, { /* App Check options */ });
   

2. 在本地访问 Web 应用，然后打开浏览器的开发者工具。在调试控制台中，您将看到一个调试令牌：

   AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
   You will need to safelist it in the Firebase console for it to work.
   

3. 向 App Check 注册调试令牌：

   1. 在 Firebase 控制台中，前往安全性 > App Check > 应用标签页。

   2. 找到您的应用，点击溢出菜单 ()，然后选择管理调试令牌。

   3. 按照屏幕上的说明注册调试令牌。

如需详细了解调试提供程序（包括如何获取新的调试令牌），请参阅官方 App Check 文档。

以下是关于 App Check 调试提供程序的一些要点：

• 请勿公开您的调试令牌和调试 build。请勿将调试令牌提交到公共代码库，也不要在应用的正式版 build 中发布调试令牌或调试 build。
• 在向最终用户发布应用之前，请向生产环境认证提供方注册您的应用。 您需要向生产环境 App Check 证明提供方（例如 Play Integrity）注册您的应用，以便最终用户可以在强制执行 App Check 的情况下使用您的功能。

第 5 步：初始化服务并创建模型实例

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

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

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

2. 创建一个 GenerativeModel 实例。请务必将 mode 设置为以下值之一：

   • PREFER_ON_DEVICE：使用设备端模型（如果可用）；否则，回退到云托管模型。

   • ONLY_ON_DEVICE：如果设备端模型可用，则使用该模型；否则，抛出异常。

   • PREFER_IN_CLOUD：使用云托管模型（如果可用）；否则，回退到设备端模型。

   • ONLY_IN_CLOUD：使用云托管模型（如果可用）；否则，抛出异常。

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

注意：请注意以下几点：

• 在实现混合推理或设备端推理之前，请务必查看尚不支持的功能列表。
• 默认的云托管模型为 gemini-3.5-flash-lite，但您可以替换默认模型。
• 作为回答的一部分，SDK 会告知您使用的是设备端推理还是云端推理。

第 6 步：初始化设备端模型

您必须在最终用户页面互动（例如点击按钮）之后或期间，以及向模型发送提示请求之前调用 initializeDeviceModel()。如需详细了解用户激活要求，请参阅 Chrome 文档。

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, InferenceMode } from "firebase/ai";

// TODO(developer) Replace the following with your app's Firebase configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize FirebaseApp
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Create a `GenerativeModel` instance
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

下载设备端模型可能需要几分钟时间。

如果您在首次请求设备端推理之前尚未下载模型，调用 initializeDeviceModel() 将自动在后台启动模型下载。等待 initializeDeviceModel() 完成可确保模型已准备好立即执行查询，但可能需要几分钟时间。

在下载完成之前调用 generateContent() 等方法会产生不同的结果，具体取决于模式：

• ONLY_ON_DEVICE：请求将等待下载完成，然后将提示发送到设备端模型并返回结果。这可能需要几分钟。
• PREFER_IN_CLOUD 或 PREFER_ON_DEVICE：请求不会等待下载完成，而是会自动回退到使用云托管模型。
• ONLY_IN_CLOUD：请求将自动回退到使用云托管模型。

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

本部分介绍了如何发送各种类型的输入来生成不同类型的输出，包括：

• 根据纯文本输入生成文本
• 根据文本和图片（多模态）输入生成文本

如果您想生成结构化输出（例如 JSON 或枚举），请使用以下“生成文本”示例之一，并将模型配置为根据提供的架构进行回答。

根据纯文本输入生成文本

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

您可以使用 generateContent() 根据包含文本的提示生成文本：

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Wrap in an async function so you can use await
async function run() {
  // Provide a prompt that contains text
  const prompt = "Write a story about a magic backpack."

  // To generate text output, call `generateContent` with the text input
  const result = await model.generateContent(prompt);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

请注意，Firebase AI Logic 还支持使用 generateContentStream（而不是 generateContent）流式传输文本回答。

根据文本和图片（多模态）输入生成文本

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

您可以使用 generateContent() 根据包含文本和图片文件的提示生成文本，同时提供每个输入文件的 mimeType 和文件本身。

设备端推理支持的输入图片类型为 PNG 和 JPEG。

重要提示：对于设备端推理，词元上限为 9216 个词元。

// Imports + initialization of FirebaseApp and backend service + creation of model instance

// Converts a File object to a Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    type: "inlineData",
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

async function run() {
  // Provide a text prompt to include with the image
  const prompt = "Write a poem about this picture:";

  const fileInputEl = document.querySelector("input[type=file]");
  const imagePart = await fileToGenerativePart(fileInputEl.files[0]);

  // To generate text output, call `generateContent` with the text and image
  const result = await model.generateContent([prompt, imagePart]);

  const response = result.response;
  const text = response.text();
  console.log(text);
}

run();

请注意，Firebase AI Logic 还支持使用 generateContentStream（而不是 generateContent）流式传输文本回答。

您还可以做些什么？

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

• 设置推理模式。

• 确定使用的是设备端推理还是云端推理。

• 替换默认的云托管后备模型。

• 使用模型配置来控制回答。

• 生成结构化输出（例如 JSON 和枚举）。

尚不支持的功能

Web SDK 或云托管模型的部分功能不适用于混合推理或设备端推理。

混合实现尚不支持的功能

以下功能无法与混合实现搭配使用（无论是设备端还是通过云端回退）：

• Gemini Live API：不支持双向实时流式传输。

• 服务器提示模板：不支持托管式服务器提示模板。

• 统计词元数：不应依赖于统计词元数，因为云托管模型和设备端模型的词元数会有所不同，因此没有直观的后备方案。

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

设备端推理尚不支持以下功能，但云托管模型支持这些功能。

注意：对于许多尚不支持的功能，如果您将模式设置为 PREFER_ON_DEVICE，SDK 会自动回退到使用云托管模型。不过，为了向用户提供更一致的体验，请考虑直接使用云托管模型。

• 使用 Gemini Nano Banana 模型生成图片

  • 可以回退到云托管模型；不过，ONLY_ON_DEVICE 模式会抛出错误。

• 根据 JPEG 和 PNG 以外的图片文件输入类型生成文本

  • 可以回退到云托管模型；不过，ONLY_ON_DEVICE 模式会抛出错误。

• 根据音频、视频和文档 (PDF) 的多模态输入生成文本

  • 可以回退到云托管模型；不过，ONLY_ON_DEVICE 模式会抛出错误。

• 在多模态请求中使用网址提供文件。您必须以 内嵌数据的形式向设备端模型提供文件。

• 多轮对话

  • 可以回退到云托管模型；不过，ONLY_ON_DEVICE 模式会抛出错误。

• 为模型提供工具，帮助其生成回答（例如函数调用、代码执行、网址上下文、依托 Google Search 进行接地以及依托 Google Maps 进行接地）

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

其他限制

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

• 应用的最终用户必须在桌面设备上运行 Chrome（版本 139 或更高版本），并启用所需的标志。

• 设备端模型需要用户设备上有足够的存储空间，以便进行初始模型下载。

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