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

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

本页面介绍了如何开始使用客户端 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. （可选）在首次请求之前下载设备端模型。

   提示 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 逻辑。

3. 点击开始，启动引导式工作流，帮助您为项目设置必需的 API 和资源。

4. 设置项目以使用“Gemini API”提供方。

   我们建议您先使用 Gemini Developer API。 您可以随时设置 Vertex AI Gemini API（以及其对结算的要求）。

   对于 Gemini Developer API，控制台将在您的项目中启用所需的 API 并创建 Gemini API 密钥。
   请勿将此 Gemini API 密钥添加到应用的代码库中。了解详情。

5. 如果控制台的工作流程中出现提示，请按照屏幕上的说明注册您的应用并将其连接到 Firebase。

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

第 3 步：添加 SDK

Firebase 库提供对 API 的访问权限，以便与生成式模型进行交互。该库包含在 Firebase JavaScript SDK for Web 中。

1. 使用 npm 安装适用于 Web 的 Firebase JS SDK：

   npm install firebase
   

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

   import { initializeApp } from "firebase/app";
   
   // 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 步：初始化服务并创建模型实例

在向模型发送提示请求之前，请先设置以下内容。

1. 为所选的 API 提供商初始化服务。

2. 创建一个 GenerativeModel 实例。请务必执行以下操作：

   1. 在最终用户互动（例如点击按钮）后或在最终用户互动时调用 getGenerativeModel 。这是 inferenceMode 的前提条件。

   2. 将 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
// Call `getGenerativeModel` after or on an end-user interaction
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

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

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

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

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

// 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 的并非所有功能都可用于设备端推理。以下功能尚不支持设备端推理（但通常可用于基于云的推理）。

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

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

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

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

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

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

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

• 多轮聊天

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

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

• 为模型提供工具，帮助其生成回答（例如函数调用、代码执行、网址上下文和 Google Search 的 Grounding）

• 统计 token 数量

  • 始终抛出错误。云端托管模型和设备端模型的数量会有所不同，因此没有直观的后备方案。

• Firebase 控制台中的 AI 监控功能，用于监控设备端推理。

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

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