Prompt API 的實驗性 Polyfill

發布日期:2026 年 5 月 14 日

透過 Chrome 的 Prompt API,您可以在 window.LanguageModel 上使用高階瀏覽器 API 與 LLM 互動。不過,這項功能仍有支援限制,且實作程序相當複雜。

瀏覽器 支援的作業系統 不支援的作業系統 位置
Chrome Windows、macOS、Linux、ChromeOS (Chromebook Plus) Android、iOS ✅ 支援
Edge Windows、macOS Android、iOS ✅ 支援
Safari 📋 決定職位
Firefox 📋 決定職位

同時,搶先體驗計畫的開發人員也對 Prompt API 感到興奮。在可預見的未來,API 的可用性將帶來相容性挑戰。

解決方案

因此,我們發布了符合規格的實驗性 Prompt API Polyfill (請參閱 GitHub 上的原始碼),可透過可設定的雲端後端供應商,以及 Transformers.js 形式的本機後端供應商,準確實作 Prompt API。

使用 Polyfill

如要使用 Polyfill,請執行下列操作:

  1. 從 npm 下載 polyfill

    npm install prompt-api-polyfill
    
  2. 選擇要使用雲端後端供應商或本機後端供應商:

    • 雲端後端供應商:使用者資料會傳送至雲端進行遠端處理,但您不必等待本機模型可用。您必須根據雲端服務供應商的定價資訊,支付產生的任何費用。
    • 本機後端供應商:使用者資料會保留在瀏覽器中並在本機處理,但您需要下載模型,這與實際的 Prompt API 不同,無法在不同來源之間共用。本機處理不會產生任何費用。

雲端後端

選擇任一雲端後端,並取得後端供應商的 API 金鑰 (和任何其他憑證)。

取得 API 金鑰後,請在設定檔 .env.json 中輸入詳細資料。如未指定 modelName,填補程式會使用各後端的預設模型,但如果指定,則可選取各後端支援的模型。

{
  "apiKey": "y0ur-Api-k3Y",
  "modelName": "model-name"
}

本機後端

如果您決定採用以 Transformers.js 為基礎的本機後端供應商,只需要虛擬 API 金鑰。不過,您可以設定 Transformers.js 應使用的裝置。選擇 "webgpu" 可獲得最佳效能,選擇 "wasm" 則可獲得最佳相容性。你也可以變更預設設定。從 Hugging Face 相容模型目錄中選擇其他模型。部分模型可使用 dtype 參數選取不同的量化。

{
  "apiKey": "dummy",
  "device": "webgpu",
  "dtype": "q4f16",
  "modelName": "onnx-community/gemma-3-1b-it-ONNX-GQA"
};

設定 Polyfill

設定檔就位後,您現在可以在應用程式中使用 Polyfill。

  1. 匯入設定檔並指派給適當命名的全域變數,其中 $BACKEND 是您選擇的後端:window.$BACKEND_CONFIG
  2. 使用動態匯入,僅在基礎瀏覽器不支援時載入 Polyfill。
  3. 呼叫 Prompt API 函式
import config from './.env.json' with { type: 'json' };

// Set $BACKEND_CONFIG to select a backend
window.$BACKEND_CONFIG = config;

if (!('LanguageModel' in window)) {
  await import('prompt-api-polyfill');
}

const session = await LanguageModel.create({
  expectedInputs: [{type: 'text', languages: ['en']}],
  expectedOutputs: [{type: 'text', languages: ['en']}],
});
await session.prompt('Tell me a joke!');

這個 Polyfill 支援結構化輸出 (Transformers.js 後端除外)、處理多模態輸入 (OpenAI 後端除外,該後端不支援同時輸入音訊和圖片,只能分別輸入),並已針對 LanguageModel 進行完整的 Web 平台測試套件測試。

如要瞭解更多背景資訊、詳細用法和原始碼,請參閱 GitHub 存放區中的 README 檔案

與瀏覽器提示 API 的差異

如果 polyfill 是以雲端模型為基礎,在用戶端執行的部分優點就不再適用。也就是說,您無法再保證私密資料會在本地處理,但後端供應商的隱私權政策仍適用。使用者離線時,您的應用程式也無法再使用 AI。如要判斷是否連線,可以監聽對應的事件。

window.addEventListener("offline", (e) => {
  console.log("offline");
});

window.addEventListener("online", (e) => {
  console.log("online");
});

如果 AI 推論是針對雲端模型執行,則不需要下載本機模型。這個 Polyfill 會模擬 downloadprogress 事件,因此應用程式會以為內建模型已下載完畢,也就是說會有兩個事件,一個的 loaded 值為 0,另一個則為 1,這符合規格要求。

與裝置端推論不同,使用雲端推論時,從所選後端供應商呼叫 API 可能會產生費用。查看定價資訊,例如 Gemini API 的定價資訊。如果您知道每個權杖的費用,可以使用 Prompt API 的 contextUsage 資訊計算費用。

const COST_PER_TOKEN = 123;
const COST_LIMIT = 456;

let costSoFar = 0;

const session = await LanguageModel.create(options);

/…/

if (costSoFar < COST_LIMIT) {
  await session.prompt('Tell me a joke.');
  costSoFar = session.contextUsage * COST_PER_TOKEN;
} else {
  // Show premium AI plan promo.
}

如果您直接從行動或網頁應用程式呼叫 Cloud API (例如允許存取生成式 AI 模型的 API),API 金鑰就可能遭到未經授權的用戶端濫用。為保護這些 API,如果您使用 Firebase AI Logic Hybrid SDK,請務必使用 Firebase App Check 驗證所有傳入的 API 呼叫是否來自您的實際應用程式。使用 Google 等雲端服務供應商時,您也可以強制執行嚴格的來源檢查,確保只有允許的網站可以使用 API。

例如,後端供應商的限制會適用於工作階段的 contextWindow,而非提示 API 的限制。contextWindow 的限制通常遠高於裝置端,而且您可以在雲端處理大量資料,因此雖然您應該瞭解兩者之間的差異,但實際上可能不會遇到這類問題。

建立自己的後端

如要新增自己的後端供應商,請按照下列步驟操作:

擴充基礎後端類別

backends/ 目錄中建立新檔案,例如 backends/custom-backend.js。您需要擴充 PolyfillBackend 類別,並實作符合預期介面的核心方法。

import PolyfillBackend from './base.js';
import { DEFAULT_MODELS } from './defaults.js';

export default class CustomBackend extends PolyfillBackend {
  constructor(config) {
    // config typically comes from a window global (e.g., window.CUSTOM_CONFIG)
    super(config.modelName || DEFAULT_MODELS.custom.modelName);
  }

  // Check if the backend is configured (e.g., API key is present), if given
  // combinations of modelName and options are supported, or, for local model,
  // if the model is available.
  static availability(options) {
    return window.CUSTOM_CONFIG?.apiKey ? 'available' : 'unavailable';
  }

  // Initialize the underlying SDK or API client. With local models, use
  // monitorTarget to report model download progress to the polyfill.
  createSession(options, sessionParams, monitorTarget) {
    // Return the initialized session or client instance
  }

  // Non-streaming prompt execution
  async generateContent(contents) {
    // contents: Array of { role: 'user'|'model', parts: [{ text: string }] }
    // Return: { text: string, usage: number }
  }

  // Streaming prompt execution
  async generateContentStream(contents) {
    // Return: AsyncIterable yielding chunks
  }

  // Token counting for quota/usage tracking
  async countTokens(contents) {
    // Return: total token count (number)
  }
}

註冊後端

根據全域設定,這個 Polyfill 會採用「優先比對」策略。您需要在 prompt-api-polyfill.js 檔案中註冊後端,方法是將後端新增至靜態 #backends 陣列:

// prompt-api-polyfill.js
static #backends = [
  // ... existing backends
  {
    config: 'CUSTOM_CONFIG', // The global object to look for on `window`
    path: './backends/custom-backend.js',
  },
];

設定預設模型

backends/defaults.js 中定義備用模型 ID。使用者初始化工作階段時,如果沒有指定特定 modelName,就會使用這個值。

// backends/defaults.js
export const DEFAULT_MODELS = {
  // ...
  custom: 'custom-model-pro-v1',
};

啟用本機開發和測試

專案會使用探索指令碼 (scripts/list-backends.js) 產生測試矩陣。如要在測試執行器中加入新的後端,請在根目錄中建立 .env-[name].json 檔案 (例如 .env-custom.json):

{
  "apiKey": "your-api-key-here",
  "modelName": "custom-model-pro-v1"
}

使用 Web Platform Tests (WPT) 驗證

最後一步是確保符合法規。由於 Polyfill 是規格導向,任何新的後端都應通過官方 (或暫定) Web 平台測試:

npm run test:wpt

這個驗證步驟可確保後端處理 AbortSignal、系統提示和記錄格式等項目時,完全符合 Prompt API 規格。

結論

這個 Polyfill 可協助您在所有平台和裝置上使用 Prompt API。透過 Prompt API 的明確定義 API 進行編碼,可讓您更獨立於雲端供應商,並盡可能貼近平台。

在支援 Prompt API 的裝置上,系統甚至不會載入 Polyfill,因此使用者不必下載不會執行的程式碼。如有任何意見回饋或遇到錯誤,請在 GitHub 上開啟問題討論。希望您使用愉快!