使用 Firebase AI Logic 建構 AI 技術輔助應用程式和功能，並採用混合式推論。混合式推論可在可用情況下使用裝置端模型執行推論，並在其他情況下順暢地改用雲端代管模型。
在這個版本中，您可以使用 Firebase AI Logic 用於網際網路的用戶端 SDK 進行混合推論，並支援在電腦上使用 Chrome 進行裝置端推論。
建議用途和支援的功能
建議用途：
使用裝置端模型進行推論可提供下列優勢：
- 強化隱私權
- 查看當地特色
- 免付費推論
- 離線功能
使用混合功能可提供：
- 無論裝置型號是否可用，都能觸及 100% 的目標對象
支援的裝置端推論功能和功能：
- 單回合內容產生、串流和非串流
- 從純文字輸入內容產生文字
- 從文字和圖片輸入內容生成文字，特別是 JPEG 和 PNG 的輸入圖片類型
- 產生結構化輸出內容，包括 JSON 和列舉
開始使用
本指南說明如何開始使用 Firebase AI Logic SDK for Web 執行混合推論。
使用裝置端模型進行推論時，會使用 Chrome 的 Prompt API；而使用雲端代管模型進行推論時，則會使用您選擇的 Gemini API 供應器 (Gemini Developer API 或 Vertex AI Gemini API)。
步驟 1：設定 Chrome 和 Prompt API，以便在裝置上執行推論
下載最新的 Chrome Beta 版。
裝置端推論功能適用於 Chrome 138 以上版本。
設定下列標記，為 Chrome 例項啟用提示 API：
chrome://flags/#optimization-guide-on-device-model：設為「已啟用」。chrome://flags/#prompt-api-for-gemini-nano：設為「已啟用」。
如要進一步瞭解如何在 localhost 上使用 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 專案。
按一下「開始使用」即可啟動引導式工作流程，協助您為專案設定必要的 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 的提示 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 不支援這項功能，即使是雲端代管的模型也不行。
函式呼叫
- 即將推出！
計算詞元數
- 一律會擲回錯誤。雲端代管和裝置端模式的計數方式不同，因此沒有直覺的備用方案。
在 Firebase 控制台中監控 AI 裝置端推論功能。
- 請注意，使用雲端代管模型的任何推論，都可以像使用 Firebase AI Logic 用於網頁的用戶端 SDK 的其他推論一樣，進行監控。
針對使用 Firebase AI Logic 的體驗提供意見回饋