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


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

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

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

跳转到代码示例

推荐的用例和支持的功能

推荐的用例：

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

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

  • 使用混合功能可提供：

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

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

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

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

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

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

准备工作

请注意以下几点：

在 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 中；不过，设备端模型默认不可用。如果您在首次请求设备端推理之前尚未下载该模型，则该请求会自动在后台启动模型下载。

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

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

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

  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 安装 Firebase JS SDK for Web：

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

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

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

  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

    • 以编程方式提供令牌 。

你还可以做些什么？

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

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

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

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

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

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

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

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

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

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

  • 多轮对话

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

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

  • 向模型提供工具 以帮助其生成响应（例如函数调用、代码执行、网址上下文以及依托 Google 搜索进行接地）

  • 统计 token 数量

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

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

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


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