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,Polyfill 會使用各後端的預設模型,但如果指定,則可選取各後端支援的模型。

{
  "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。

舉例來說,這類限制並非 Prompt API 的限制 (例如工作階段的 contextWindow),而是後端供應商的限制。就 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 平台測試 (WPT) 驗證

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

npm run test:wpt

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

結論

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

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

另請參閱

內建 AI 任務 API 的實驗性 Polyfill