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

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

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

请注意，设备端推理支持在桌面版 Chrome 上运行的 Web 应用 。

跳转到代码示例

推荐的用例和支持的功能

推荐的用例：

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

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

• 使用混合功能可提供：

  • 覆盖 100% 的受众群体，无论设备端模型是否可用或互联网连接情况如何

设备端推理支持的功能：

设备端推理仅支持单轮文本生成（而非聊天） ，并提供流式或非流式输出。它支持以下文本生成功能：

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

• 根据文本和图片输入生成文本，具体来说， 输入图片类型为 JPEG 和 PNG

您还可以 生成结构化输出， 包括 JSON 和枚举。

准备工作

请注意以下几点：

• 使用设备端模型进行推理时，系统会使用 Chrome 的 Prompt API； 而使用云端托管模型进行推理时，系统会使用您选择的 Gemini API 提供方（Gemini Developer API 或 Vertex AI Gemini API）。

• 本页面介绍了如何开始使用 localhost 进行开发 （如需详细了解如何在 localhost 上使用 API，请参阅 Chrome 文档）。

  完成此标准设置后，请查看 其他配置选项和功能（例如 结构化输出）。

• 实现相应功能后，您可以 让最终用户在实际应用中试用该功能 。

在 localhost 上开始使用

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

第 1 步：为设备端推理设置 Chrome 和 Prompt API

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

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

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

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

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

   从 2026 年 7 月初开始，工作流的此阶段会自动 强制执行 Firebase App Check，以保护 AI Logic， 这是一项 至关重要 的服务，有助于在直接从应用访问 Gemini API 时保护该 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, DebugProvider } 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);
   

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

从 2026 年 7 月初开始，在控制台中针对 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(app, { /* 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 的情况下使用您的功能。

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

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

在向模型发送提示请求之前，请进行以下设置：

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

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

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

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

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

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

注意： 对于发送到设备端模型的请求，请确保设备端推理 支持该模型。
对于发送到设备外的请求，设备必须处于在线状态。此外， 默认的云端托管模型为 gemini-2.5-flash-lite，但您可以 替换默认模型。

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 });

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

您必须在最终用户页面 互动（例如点击按钮）之后或之时调用 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：请求会自动 回退到使用云端托管模型。

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

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

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

如果您想生成结构化输出（例如 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。

**重要提示：** 对于设备端推理，token 数量上限为 6, 000 个。

// 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 {
    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）流式传输文本响应。

让最终用户试用您的功能

如需让最终用户在您的应用中试用您的功能，您必须 注册 Chrome 原始试用。 请注意，这些试用的持续时间和使用量有限。

1. 注册 Prompt API Chrome 原始试用。您将获得一个令牌。

2. 在您希望启用试用功能的每个网页上提供该令牌。使用以下任一选项：

   • 在 <head> 标记中以元标记的形式提供令牌： <meta http-equiv="origin-trial" content="TOKEN">

   • 以 HTTP 标头的形式提供令牌： Origin-Trial: TOKEN

   • 以编程方式提供令牌 。

你还可以做些什么？

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

• 设置推理模式

• 替换默认的云端托管回退模型

• 使用模型配置来控制响应（例如温度）

• 生成结构化输出（例如 JSON）

设备端推理尚不可用的功能

作为预览版，Web SDK 的并非所有功能都可用于设备端推理 。以下功能尚不支持设备端推理 （但通常可用于基于云的推理）。

**注意：** 对于许多此类功能，如果您将模式设置为 PREFER_ON_DEVICE，SDK 只会自动回退到使用 云端托管模型来处理这些尚不可用的功能。

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

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

• 根据音频、视频和文档（例如 PDF）输入生成文本

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

• 使用 Gemini 或 Imagen 模型生成图片

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

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

• 多轮对话

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

• 使用 Gemini Live API 进行双向流式传输

• 向模型提供工具以帮助其生成响应 （例如函数调用、代码执行、网址上下文、 使用 Google Search 进行 Grounding 和使用 Google Maps 进行 Grounding）

• 统计 token 数量

  • 始终抛出错误。云端托管模型和设备端模型的统计结果会有所不同，因此没有直观的回退。

• 在 Firebase 控制台中针对设备端推理进行 AI 监控。

  • 请注意，使用云端托管模型进行的任何推理都可以像使用 Firebase AI Logic 客户端 SDK for Web 进行的其他推理一样进行监控。

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