使用裝置端和雲端代管模型建構混合式體驗


運用混合式推論技術,使用 Firebase AI Logic 建構 AI 技術輔助應用程式與功能。混合式推論功能可在裝置端模型可用時,使用該模型執行推論,否則會順暢地改用雲端代管模型。

在此版本中,您可以使用 Firebase AI Logic 用戶端 SDK for Web 進行混合推論,並支援在桌機版 Chrome 上進行裝置端推論。

直接查看程式碼範例

建議用途和支援的功能

建議用途:

  • 使用裝置端模型進行推論可提供以下優勢:

    • 強化隱私權
    • 查看當地特色
    • 免付費推論
    • 離線功能
  • 使用混合功能方案:

    • 觸及 100% 的目標對象,無論裝置型號是否適用

裝置端推論支援的功能:

  • 單輪內容生成 (串流和非串流)
  • 從純文字輸入內容生成文字
  • 根據文字和圖片輸入內容生成文字,特別是 JPEG 和 PNG 格式的輸入圖片
  • 生成結構化輸出內容,包括 JSON 和列舉

開始使用

本指南說明如何開始使用 Firebase AI Logic SDK for Web 執行混合式推論。

使用裝置端模型進行推論時,會使用 Chrome 的提示 API;使用雲端託管模型進行推論時,則會使用您選擇的Gemini API供應商 (Gemini Developer APIVertex AI Gemini API)。

步驟 1:設定 Chrome 和 Prompt API,以便在裝置上進行推論

  1. 下載最新版 Chrome Beta 版

    裝置端推論功能適用於 Chrome 138 以上版本。

  2. 設定下列標記,為 Chrome 執行個體啟用 Prompt API:

    • chrome://flags/#optimization-guide-on-device-model:設為「已啟用」
    • chrome://flags/#prompt-api-for-gemini-nano:設為「已啟用」

    如要進一步瞭解如何在本機主機上使用 API,請參閱 Chrome 說明文件中的這篇文章。你也可以加入 Chrome 搶先體驗計畫 (EPP),提供意見回饋。

  3. 設定下列標記,啟用裝置端多模態模型:

    • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input:設為「已啟用」
  4. 在本機驗證 API:

    1. 重新啟動 Chrome。

    2. 開啟「開發人員工具」>「控制台」

    3. 執行以下指令:

      await LanguageModel.availability();
      
    4. 確認輸出內容為 availabledownloadingdownloadable。。

    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 - 帳單為選用項目 (適用於免付費的 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。

    混合式功能是透過不同的 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 模型前,請先初始化所選 API 供應商的服務,並建立 GenerativeModel 執行個體。

mode 設為下列其中一個值:

  • prefer_on_device:設定 SDK 使用裝置端模型 (如有),或改用雲端代管模型。

  • only_on_device:設定 SDK 使用裝置端模型或擲回例外狀況。

  • only_in_cloud:將 SDK 設為永不使用裝置端模型。

預設情況下,使用 prefer_on_deviceonly_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_deviceonly_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 和列舉)。

如要進行混合推論,請同時使用 inCloudParamsonDeviceParams,將模型設為以結構化輸出內容回應。其他模式則只適用相關設定。

  • 適用於 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 模式會擲回錯誤。
  • 使用 GeminiImagen 模型生成圖片

    • 可改用雲端託管模型,但 only_on_device 模式會擲回錯誤。
  • 在多模態要求中,使用網址提供檔案。您必須以內嵌資料的形式,將檔案提供給裝置端模型。

  • 多輪對話

    • 可改用雲端託管模型,但 only_on_device 模式會擲回錯誤。
  • 使用 Gemini Live API 進行雙向串流

    • 請注意,Firebase AI Logic 網頁版用戶端 SDK 不支援這項功能,即使是雲端代管模型也不例外
  • 函式呼叫

    • 即將推出!
  • 計算詞元數

    • 一律會擲回錯誤。雲端代管和裝置端模型之間的計數不同,因此沒有直覺式的備援機制。
  • Firebase 控制台中監控裝置端推論的 AI。

    • 請注意,使用雲端代管模型進行的任何推論,都可以像使用 Firebase AI Logic 用戶端網頁 SDK 進行的其他推論一樣受到監控。


提供有關 Firebase AI Logic 的使用體驗意見回饋