使用设备端和云端托管的模型打造混合体验

实验性：使用 Firebase AI Logic SDK 构建混合体验是一项实验性功能，这意味着它不受任何服务等级协议 (SLA) 或弃用政策的约束，并且可能会以不向后兼容的方式更改。

此初始版本仅支持在桌面版 Chrome 上运行的 Web 应用进行设备端推理。

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

在此版本中，Firebase AI Logic Web 客户端 SDK 支持在桌面版 Chrome 上进行设备端推理，从而实现混合推理。

跳转到代码示例

推荐的使用情形和支持的功能

推荐的使用场景：

• 使用设备端模型进行推理可带来以下优势：

  • 增强隐私保护
  • 当地环境
  • 免费推理
  • 离线功能

• 使用混合功能优惠：

  • 覆盖 100% 的受众群体，无论设备型号是否支持

设备端推理支持的功能：

• 单轮内容生成（流式和非流式）
• 根据纯文本输入生成文本
• 根据文本和图片输入生成文本，具体来说是根据 JPEG 和 PNG 格式的输入图片生成文本
• 生成结构化输出，包括 JSON 和枚举

开始使用

本指南介绍了如何开始使用 Firebase AI Logic Web 版 SDK 来执行混合推理。

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

重要提示： 此功能已于 2025 年 5 月 28 日升级到 Chrome Beta 版渠道。您需要同时升级到 Chrome Beta 版 v138 和我们的新 Firebase JS SDK 版本，以确保混合推理功能正常运行。

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

1. 下载最新的 Chrome Beta 版 build。

   从 Chrome v138 开始，即可使用设备端推理功能。

2. 通过设置以下标志，为您的 Chrome 实例启用 Prompt API：

   • chrome://flags/#optimization-guide-on-device-model：设置为已启用。
   • chrome://flags/#prompt-api-for-gemini-nano：设置为 Enabled。

   如需详细了解如何在 Chrome 文档中使用 localhost 上的 API，请参阅相关内容。（可选）加入 Chrome 的早期预览计划 (EPP)，以便提供反馈。

3. 通过设置以下标志来启用设备端多模态模型：

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input：设置为已启用。

4. 在本地验证 API：

   1. 重新启动 Chrome。

   2. 打开开发者工具 > 控制台。

   3. 运行以下命令：

      await LanguageModel.availability();
      

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

   5. 如果输出为 downloadable，您可以运行 await LanguageModel.create(); 来开始下载模型。否则，首次请求设备端推理将会在后台启动模型下载，这可能需要几分钟时间。

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

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

   还没有 Firebase 项目？

   如果您还没有 Firebase 项目，请点击创建项目，然后使用以下任一方法：

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

   • 方法 2：在“创建项目”工作流的第一步中从下拉菜单中选择一个现有 Google Cloud 项目的名称，将 Firebase 添加到该现成的 Google Cloud 项目。

   请注意，如果系统提示您是否要设置 Google Analytics，您无需进行此项设置即可使用 Firebase AI Logic SDK。

2. 在 Firebase 控制台中，前往 Firebase AI Logic 页面。

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

4. 选择要与 Firebase AI Logic SDK 搭配使用的“Gemini API”提供方。Gemini Developer API 建议首次使用该功能的用户选择此选项。如果您愿意，可以随时添加结算信息或设置 Vertex AI Gemini API。

   • Gemini Developer API - 结算可选（可使用免费的 Spark 定价方案，日后可根据需要升级）
     控制台将在您的项目中启用必需的 API 并创建 Gemini API 密钥。
     请勿将此 Gemini API 密钥添加到应用的代码库中。 了解详情。

   • Vertex AI Gemini API - 需要结算信息（需要采用随用随付的 Blaze 定价方案）
     控制台将帮助您设置结算信息并启用项目中的必需 API。

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

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

注意： 在 Firebase 控制台中，强烈建议您设置 Firebase App Check。如果您只是想试用 Gemini API，则无需立即设置 App Check；不过，我们建议您在开始认真开发应用后尽快设置

。

第 3 步：添加 SDK

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

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

   混合功能以不同的 npm 标记发布，因此请务必将其包含在安装命令中。

   npm install firebase@eap-ai-hybridinference
   

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 步：初始化服务并创建模型实例

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

在向 Gemini 模型发送提示之前，请为所选的 API 提供方初始化服务，并创建 GenerativeModel 实例。

将 mode 设置为以下值之一：

• prefer_on_device：将 SDK 配置为使用设备端模型（如果可用），否则回退到云端托管的模型。

• only_on_device：将 SDK 配置为使用设备端模型或抛出异常。

• only_in_cloud：将 SDK 配置为永远不使用设备端模型。

默认情况下，当您使用 prefer_on_device 或 only_in_cloud 时，云托管模型为 gemini-2.0-flash-lite，但您可以替换默认值。

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend } 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 to use on-device model when possible
const model = getGenerativeModel(ai, { mode: "prefer_on_device" });

向模型发送提示请求

本部分提供了示例，说明如何发送各种类型的输入来生成不同类型的输出，包括：

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

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

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

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

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

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

重要提示： 对于设备端推理，词元数量上限为 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();

您还可以做些什么？

除了上述示例之外，您还可以使用其他推理模式、替换默认回退模型，以及使用模型配置来控制回答。

使用其他推理模式

上述示例使用 prefer_on_device 模式将 SDK 配置为使用设备端模型（如果可用），或回退到云端托管的模型。该 SDK 提供了两种替代的推理模式：only_on_device 和 only_in_cloud。

• 使用 only_on_device 模式，以便 SDK 只能使用设备端模型。在此配置中，如果设备端模型不可用，API 将抛出错误。

  const model = getGenerativeModel(ai, { mode: "only_on_device" });
  

• 使用 only_in_cloud 模式，以便 SDK 只能使用云端托管的模型。

  const model = getGenerativeModel(ai, { mode: "only_in_cloud" });
  

替换默认的后备模型

如果您使用 prefer_on_device 模式，则当设备端模型不可用时，SDK 会回退为使用云端托管的模型。默认回退云托管模型为 gemini-2.0-flash-lite。当您使用 only_in_cloud 模式时，此云端托管模型也是默认模型。

您可以使用 inCloudParams 配置选项来指定其他默认的云托管模型：

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
  }
});

查找所有受支持的 Gemini 模型的模型名称。

使用模型配置来控制回答

在向模型发送的每个请求中，您都可以同时发送模型配置，以控制模型如何生成回答。云端托管模型和设备端模型提供不同的配置选项。

该配置在实例的整个生命周期内保持不变。如果您想使用其他配置，请使用该配置创建新的 GenerativeModel 实例。

为云托管模型设置配置

使用 inCloudParams 选项配置云端托管的 Gemini 模型。了解可用参数。

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
    temperature: 0.8,
    topK: 10
  }
});

为设备端模型设置配置

请注意，使用设备端模型进行推理时，会使用 Chrome 的 Prompt API。

使用 onDeviceParams 选项配置设备端模型。了解可用参数。

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  onDeviceParams: {
    createOptions: {
      temperature: 0.8,
      topK: 8
    }
  }
});

设置结构化输出的配置

使用云端托管模型和设备端模型进行推理时，支持生成结构化输出（例如 JSON 和枚举）。

对于混合推理，请同时使用 inCloudParams 和 onDeviceParams 将模型配置为以结构化输出进行回答。对于其他模式，请仅使用适用的配置。

• 对于 inCloudParams：指定适当的 responseMimeType（在此示例中为 application/json），以及您希望模型使用的 responseSchema。

• 对于 onDeviceParams：指定您希望模型使用的 responseConstraint。

JSON 输出

以下示例针对混合推理调整了常规 JSON 输出示例：

import {
  getAI,
  getGenerativeModel,
  Schema
} from "firebase/ai";

const jsonSchema = Schema.object({
 properties: {
    characters: Schema.array({
      items: Schema.object({
        properties: {
          name: Schema.string(),
          accessory: Schema.string(),
          age: Schema.number(),
          species: Schema.string(),
        },
        optionalProperties: ["accessory"],
      }),
    }),
  }
});

const model = getGenerativeModel(ai, {
  mode: 'prefer_on_device',
  inCloudParams: {
    model: "gemini-2.5-flash"
    generationConfig: {
      responseMimeType: "application/json",
      responseSchema: jsonSchema
    },
  }
  onDeviceParams: {
    promptOptions: {
      responseConstraint: jsonSchema
    }
  }
});

枚举输出

与上文类似，但针对混合推理调整了有关枚举输出的文档：

// ...

const enumSchema = Schema.enumString({
  enum: ["drama", "comedy", "documentary"],
});

const model = getGenerativeModel(ai, {

// ...

    generationConfig: {
      responseMimeType: "text/x.enum",
      responseSchema: enumSchema
    },

// ...

尚不适用于设备端推理的功能

作为实验性版本，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 的双向数据流

  • 请注意，Firebase AI Logic Web 版客户端 SDK 不支持此功能，即使是云托管模型也不支持。

• 函数调用

  • 即将推出！

• 统计 token 数量

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

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

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

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