此页面由 Cloud Translation API 翻译。

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

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

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

开始使用

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

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

按照本部分所述，开始使用 localhost 进行开发（您还可以参阅 Chrome 文档，详细了解在 localhost 上使用 API）。然后，在实现功能后，您可以选择允许最终用户试用该功能。

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

请确保您使用的是最新版 Chrome。在 chrome://settings/help 中更新。
Chrome v139 及更高版本支持设备端推理。
通过将以下标志设置为 Enabled 来启用设备端多模态模型：
- chrome://flags/#prompt-api-for-gemini-nano-multimodal-input
重新启动 Chrome。
（可选）在首次请求之前下载设备端模型。

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

登录 Firebase 控制台，然后选择您的 Firebase 项目。
还没有 Firebase 项目？

如果您还没有 Firebase 项目，请点击创建项目，然后使用以下任一方法：
- 方法 1：在“创建项目”工作流的第一步中输入新项目名称，创建一个全新的 Firebase 项目（该操作会自动创建相应的底层 Google Cloud 项目）。
- 方法 2：在“创建项目”工作流的第一步中从下拉菜单中选择一个现有 Google Cloud 项目的名称，将 Firebase 添加到该现成的 Google Cloud 项目。
请注意，如果系统提示您是否要设置 Google Analytics，您无需进行此项设置即可使用 Firebase AI Logic SDK。
在 Firebase 控制台中，前往 Firebase AI Logic 页面。
点击开始，启动引导式工作流，帮助您为项目设置必需的 API 和资源。
选择要与 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。
如果控制台的工作流程中出现提示，请按照屏幕上的说明注册您的应用并将其连接到 Firebase。
继续执行本指南中的下一步，将 SDK 添加到您的应用。

。

第 3 步：添加 SDK

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

使用 npm 安装适用于 Web 的 Firebase JS SDK：
```
npm install firebase
```

在您的应用中初始化 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, 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 to use on-device model when possible
const model = getGenerativeModel(ai, { mode: InferenceMode.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();

您还可以做些什么？

除了上述示例之外，您还可以让最终用户试用您的功能、使用替代推理模式、替换默认回退模型，以及使用模型配置来控制回答。

让最终用户试用您的功能

如需让最终用户试用您的功能，您可以注册 Chrome Origin 试用。请注意，这些试用方案的使用期限和使用量有限。

注册参加 Prompt API Chrome 源试用。您将获得一个令牌。
在您希望启用试用功能的每个网页上提供令牌。使用以下任一选项：
- 在 <head> 标记中以元标记的形式提供令牌： <meta http-equiv="origin-trial" content="TOKEN">
- 以 HTTP 标头的形式提供令牌： Origin-Trial: TOKEN
- 以编程方式提供令牌。

使用其他推理模式

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

使用 ONLY_ON_DEVICE 模式，以便 SDK 只能使用设备端模型。在此配置中，如果设备端模型不可用，API 将抛出错误。
```
const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_ON_DEVICE });
```

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

const model = getGenerativeModel(ai, { mode: InferenceMode.ONLY_IN_CLOUD });

替换默认的后备模型

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

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

const model = getGenerativeModel(ai, {
  mode: InferenceMode.PREFER_ON_DEVICE,
  inCloudParams: {
    model: "gemini-2.5-flash"
  }
});

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

使用模型配置来控制回答

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

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

为云托管模型设置配置

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

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

为设备端模型设置配置

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

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

const model = getGenerativeModel(ai, {
  mode: InferenceMode.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: InferenceMode.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 的双向数据流
- 请注意，Firebase AI Logic Web 版客户端 SDK 不支持此功能，即使是云托管模型也不支持。
使用“工具”，包括函数调用和依托 Google 搜索进行接地
- 即将推出！
统计 token 数量
- 始终抛出错误。云端托管模型和设备端模型的数量会有所不同，因此没有直观的后备方案。
Firebase 控制台中的 AI 监控功能，用于监控设备端推理。
- 请注意，使用云端托管模型进行的任何推理都可以像使用 Firebase AI Logic Web 客户端 SDK 进行的其他推理一样受到监控。

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