運用混合式推論技術，使用 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 API 或 Vertex AI Gemini API)。
步驟 1：設定 Chrome 和 Prompt API，以便在裝置上進行推論
下載最新版 Chrome Beta 版。
裝置端推論功能適用於 Chrome 138 以上版本。
設定下列標記，為 Chrome 執行個體啟用 Prompt API：
chrome://flags/#optimization-guide-on-device-model：設為「已啟用」。chrome://flags/#prompt-api-for-gemini-nano：設為「已啟用」。
如要進一步瞭解如何在本機主機上使用 API，請參閱 Chrome 說明文件中的這篇文章。你也可以加入 Chrome 搶先體驗計畫 (EPP)，提供意見回饋。
設定下列標記，啟用裝置端多模態模型：
chrome://flags/#prompt-api-for-gemini-nano-multimodal-input：設為「已啟用」。
在本機驗證 API：
重新啟動 Chrome。
開啟「開發人員工具」>「控制台」。
執行以下指令：
await LanguageModel.availability();確認輸出內容為
available、downloading或downloadable。。如果輸出內容為
downloadable，請執行await LanguageModel.create();，開始下載模型。否則，裝置端推論的第一個要求會啟動背景模型下載作業，可能需要幾分鐘才能完成。
步驟 2：設定 Firebase 專案，並將應用程式連結至 Firebase
登入 Firebase 控制台，然後選取 Firebase 專案。
前往 Firebase 控制台的「Firebase AI Logic」頁面。
按一下「開始使用」，即可啟動導覽工作流程，協助您為專案設定必要 API 和資源。
選取要搭配 Firebase AI Logic SDK 使用的「Gemini API」供應商。Gemini Developer API 適合初次使用者。如要新增帳單或設定Vertex AI Gemini API，之後隨時可以進行。
如果控制台的工作流程中出現提示，請按照畫面上的指示註冊應用程式並連結至 Firebase。
請繼續按照本指南的下一個步驟，將 SDK 新增至應用程式。
步驟 3：新增 SDK
Firebase 程式庫提供 API 存取權，可與生成模型互動。這個程式庫是 Firebase JavaScript SDK for Web 的一部分。
使用 npm 安裝適用於網頁的 Firebase JS SDK：
npm install --save-exact firebase@eap-ai-hybridinference混合式功能是透過不同的 npm 標記發布，因此請務必將其納入安裝指令。
標記會以修補程式版本的形式實作，因此
--save-exact旗標會告知 NPM，在推出可能不相關的新版本時，不要自動升級。在應用程式中初始化 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 進行雙向串流
- 請注意，Firebase AI Logic 網頁版用戶端 SDK 不支援這項功能，即使是雲端代管模型也不例外。
使用「工具」，包括函式呼叫和以 Google 搜尋為基礎
- 即將推出！
計算詞元數
- 一律會擲回錯誤。雲端代管和裝置端模型之間的計數不同，因此沒有直覺式的備援機制。
在 Firebase 控制台中監控裝置端推論的 AI。
- 請注意，使用雲端代管模型進行的任何推論，都可以像使用 Firebase AI Logic 用戶端網頁 SDK 進行的其他推論一樣受到監控。
提供有關 Firebase AI Logic 的使用體驗意見回饋