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


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

在此版本中，您可以使用适用于 Web 的 Firebase AI Logic 客户端 SDK 实现混合推理，并支持桌面版 Chrome 的设备端推理。

跳转到代码示例

推荐的使用场景和支持的功能

推荐的使用场景：

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

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

  • 使用混合功能可带来以下好处：

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

设备端推理支持的功能和特性：

  • 单轮内容生成，流式和非流式
  • 根据纯文本输入生成文本
  • 根据文本和图片输入生成文本，具体而言，输入图片类型为 JPEG 和 PNG
  • 生成结构化输出，包括 JSON 和枚举

开始使用

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

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

第 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：设置为启用。

    如需详细了解如何在 localhost 上使用 API，请参阅 Chrome 文档。（可选）加入 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 项目。

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

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

  4. 选择要与 Firebase AI Logic SDK 搭配使用的“Gemini API”提供程序。建议首次使用此 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 添加到您的应用。

第 3 步：添加 SDK

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

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

    npm install --save-exact firebase@eap-ai-hybridinference

    Hybrid 功能是通过其他 npm 标记发布的，因此请务必在安装命令中添加该标记。

    标记会作为补丁版本实现，因此 --save-exact 标志会指示 NPM 在有可用的新版本（可能不相关）时不要自动升级。

  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 模型发送提示之前，请为所选的 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。

// 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 是一款实验性版本，因此其并非所有功能都适用于设备端推理。以下功能尚不支持设备端推理（但通常适用于基于云的推理）。

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

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

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

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

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

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

  • 在多模态请求中使用网址提供文件。您必须将文件作为内嵌数据提供给设备端模型。

  • 多轮聊天

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

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

    • 请注意，适用于 Web 的 Firebase AI Logic 客户端 SDK 不支持此操作，即使是云托管的模型也是如此。

  • 函数调用

    • 即将推出！

  • 统计 token 数量

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

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

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


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