使用裝置端和雲端代管模型，在網頁應用程式中建構混合式體驗

您可以使用 Firebase AI Logic，透過混合式推論建構 AI 輔助網頁應用程式和功能。混合式推論可讓您在可用時使用裝置端模型執行推論，並在其他情況下順暢切換至雲端託管模型 (反之亦然)。

本頁面說明如何開始使用用戶端 SDK。完成這項標準設定後，請查看其他設定選項和功能。

請注意，如果網頁應用程式使用 Firebase AI Logic SDK 12.5.0 以上版本，並在電腦版 Chrome (139 以上版本) 執行，則可透過 Firebase AI Logic 進行裝置端推論。

arrow_downward 跳至查看程式碼範例

用途和支援的功能

視應用程式用途而定，您可以善用裝置端或混合式體驗的多項優點：

• 使用裝置端模型進行推論的好處：

  • 強化隱私
  • 查看當地特色
  • 免付費推論
  • 離線功能

• 採用混合做法的好處：

  • 無論使用者使用何種裝置，都能提供類似的應用程式體驗
  • 無論網際網路連線、配額限制或裝置功能如何，都能提高生成式 AI 功能的可用性

支援的裝置端推論功能

裝置端推論僅支援單輪文字生成 (非對話) (串流或非串流輸出)，具體功能如下：

• 根據純文字輸入內容生成文字。

• 根據文字和圖片輸入內容生成文字，尤其是 JPEG 和 PNG 類型的輸入圖片。

• 生成結構化輸出內容，包括 JSON 和列舉。

請務必查看本頁底部的混合或裝置端推論尚不支援的功能清單。

支援的 API 和平台

以下各節將說明支援的 API，以及支援的平台和瀏覽器。

雲端與裝置端推論支援的 API

• 雲端內推論會使用您選擇的 Gemini API 供應商 (Gemini Developer API 或 Agent Platform Gemini API (formerly Vertex AI))。

• 裝置端推論會使用 Chrome 的 Prompt API。

支援的平台和瀏覽器

如要使用裝置端推論 (使用 Chrome 的 Prompt API)，應用程式的使用者必須在電腦上執行 Chrome (139 以上版本)。詳情請參閱 Chrome 說明文件。

在 localhost 開始使用

這些入門步驟說明瞭傳送任何支援的提示要求時，所需的一般設定。

如要進一步瞭解如何在本機主機上使用 API，請參閱 Chrome 說明文件。

步驟 1：設定 Chrome 和 Prompt API，以便在裝置端執行推論

1. 確認你使用的是新版 Chrome。請前往 chrome://settings/help 更新。
   Chrome 139 以上版本支援裝置端推論。

2. 將下列旗標設為「Enabled」，啟用裝置端多模態模型：

   • chrome://flags/#prompt-api-for-gemini-nano-multimodal-input

3. 重新啟動 Chrome。

4. (選用) 在提出第一個要求前，先下載裝置端模型。

   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

1. 登入 Firebase 控制台，然後選取 Firebase 專案。

   還沒有 Firebase 專案嗎？

   如果還沒有 Firebase 專案，請點選按鈕建立新的 Firebase 專案，然後使用下列任一選項：

   • 選項 1：在工作流程的第一個步驟中輸入新專案名稱，建立全新的 Firebase 專案 (系統會自動建立基礎 Google Cloud 專案)。

   • 方法 2：點按頁面底部的「將 Firebase 新增到 Google Cloud 專案」，將 Firebase 新增至現有的 Google Cloud 專案。在工作流程的第一個步驟中，開始輸入現有專案的專案名稱，然後從顯示的清單中選取該專案。

   完成畫面上工作流程的其餘步驟，建立 Firebase 專案。請注意，系統提示時，您不需要設定 Google Analytics 即可使用 Firebase AI Logic SDK。

2. 在 Firebase 控制台，依序前往「AI Services」(AI 服務) > 「AI Logic」。

3. 按一下「Get started」(開始使用)，啟動引導式工作流程，協助您設定專案所需的 API 和資源。

4. 如果出現提示，請按照畫面上的指示註冊應用程式，並將 Firebase 設定新增至應用程式。

5. 系統要求您選擇「Gemini API 供應商」時，建議選取 Gemini Developer API，即可快速開始使用，不必付費。

   日後隨時可以設定 Agent Platform Gemini API (formerly Vertex AI) (以及相關計費規定)。

6. 繼續執行工作流程，設定 Firebase AI Logic 的必要 API 和相關服務。

   這個工作流程階段會自動強制執行 AI Logic 的 Firebase App Check，這是一項重要服務，可在應用程式直接存取 Gemini API 時提供保護。在開始設定時 (請參閱本指南後續步驟)，您需要為本機開發環境設定 App Check 偵錯服務，以便強制執行 App Check。

7. 請繼續進行本指南的下一個步驟，將必要的 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";
   import { initializeAppCheck } from "firebase/app-check";
   
   // 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：設定 App Check 偵錯服務，以便在本機開發

在控制台設定 AI Logic 的引導式工作流程中，系統會自動強制執行 Firebase App Check，保護Gemini API。在本機開發環境中，您需要設定 App Check 偵錯服務，略過認證程序，同時維持 App Check 的強制執行。

如要在 localhost 中以互動方式執行應用程式 (例如在本機開發期間)，請按照下列步驟使用偵錯服務：

1. 在偵錯版本中，請先將 self.FIREBASE_APPCHECK_DEBUG_TOKEN 設為 true，再初始化 App Check，以啟用偵錯模式。例如：

   self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   initializeAppCheck(firebaseApp, { /* App Check options */ });
   

2. 在本機造訪網頁應用程式，並開啟瀏覽器的開發人員工具。偵錯控制台中會顯示偵錯權杖：

   AppCheck debug token: "123a4567-b89c-12d3-e456-789012345678".
   You will need to safelist it in the Firebase console for it to work.
   

3. 使用 App Check 註冊偵錯權杖：

   1. 在 Firebase 控制台中，依序前往「Security」(安全性) >「App Check」>「Apps」(應用程式) 分頁標籤。

   2. 找到應用程式，按一下溢位選單 (more_vert)，然後選取「Manage debug tokens」。

   3. 按照畫面上的指示註冊偵錯權杖。

如要進一步瞭解偵錯服務 (包括如何取得新的偵錯權杖)，請參閱官方 App Check 文件。

步驟 5：初始化服務並建立模型執行個體

向模型傳送提示要求前，請先完成下列設定：

1. 為所選 API 供應商初始化服務。

2. 建立 GenerativeModel 執行個體。請務必將 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
// Set the mode (for example, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

步驟 6：初始化裝置端模型

您必須在使用者與網頁互動 (例如點選按鈕) 之後或當下，以及向模型傳送提示要求之前，呼叫 initializeDeviceModel()。如要進一步瞭解使用者啟用要求，請參閱 Chrome 說明文件。

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, use the on-device model if it's available)
const model = getGenerativeModel(ai, { mode: InferenceMode.PREFER_ON_DEVICE });

// `initializeDeviceModel` must be called:
// (1) after or on an end-user page interaction such as a button click
// and
// (2) before any queries to the model (such as `generateContent()`)
// You may want to `await` this promise if using `ONLY_ON_DEVICE` (see note below).
model.initializeDeviceModel((val) =>
  // Example: "Download progress: 72.62%""
  console.log(`Download progress: ${Math.round(val*10000) / 100}%`)
);

步驟 7：傳送提示要求給模型

本節說明如何傳送各種輸入內容，生成不同類型的輸出內容，包括：

• 根據純文字輸入內容生成文字
• 根據文字和圖片 (多模態) 輸入內容生成文字

如要生成結構化輸出內容 (例如 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 {
    type: "inlineData",
    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) 串流文字回覆。

你還可以做些什麼？

您可以為混合式體驗使用各種額外的設定選項和功能：

• 設定推論模式。

• 判斷是使用裝置端或雲端推論。

• 覆寫預設的雲端託管備用模型。

• 使用模型設定控制回覆。

• 生成結構化輸出內容 (例如 JSON 和列舉)。

尚未支援的功能

Web SDK 或雲端託管模型的部分功能，不適用於混合或裝置端推論。

混合導入作業尚未支援的功能

下列功能無法與混合式實作搭配使用 (無論是在裝置端或透過雲端備用)：

• Gemini Live API：不支援雙向即時串流。

• 伺服器提示詞範本：不支援代管伺服器提示詞範本。

• 計算權杖：不應依賴計算權杖，因為雲端託管和裝置端模型的計算結果會有所不同，因此沒有直覺式的備用方案。

裝置端推論目前不支援的功能

裝置端推論尚不支援下列功能，但雲端託管模型可使用這些功能。

• 使用 Gemini Nano Banana 模型生成圖片

  • 可以改用雲端託管模型，但 ONLY_ON_DEVICE 模式會擲回錯誤。

• 從 JPEG 和 PNG 以外的圖片檔案輸入類型生成文字

  • 可以改用雲端託管模型，但 ONLY_ON_DEVICE 模式會擲回錯誤。

• 依據音訊、影片和文件 (PDF) 等多模態輸入內容生成文字

  • 可以改用雲端託管模型，但 ONLY_ON_DEVICE 模式會擲回錯誤。

• 在多模態要求中使用網址提供檔案。您必須以內嵌資料的形式，將檔案提供給裝置端模型。

• 多輪對話

  • 可以改用雲端託管模型，但 ONLY_ON_DEVICE 模式會擲回錯誤。

• 為模型提供工具，協助生成回覆 (例如呼叫函式、執行程式碼、網址背景資訊、使用 Google Search 建立基準，以及使用 Google Maps 建立基準)

• Firebase 控制台中的 AI monitoring 功能不會顯示任何裝置端推論資料 (包括裝置記錄)。不過，使用雲端託管模型的任何推論，都可以像其他推論一樣，透過 Firebase AI Logic 監控。

其他限制

除了上述限制外，裝置端推論還有下列限制：

• 應用程式的使用者必須在電腦上執行 Chrome (139 以上版本)，並啟用必要旗標。

• 裝置端模型需要使用者裝置有足夠的儲存空間，才能進行初始模型下載。

提供「Firebase AI Logic」使用體驗的意見回饋