Prompt API 的实验性 Polyfill

Published: May 14, 2026

借助 Chrome 中的 Prompt API,您可以使用 高级浏览器 API 与 LLM 进行交互,该 API 位于 window.LanguageModel。不过,此 API 的支持仍然有限,并且实现过程非常复杂。

浏览器 支持的操作系统 不支持的操作系统 位置
Chrome Windows、macOS、Linux、ChromeOS (Chromebook Plus) Android、iOS ✅ 支持
Edge Windows、macOS Android、iOS ✅ 支持
Safari 📋 位置已确定
Firefox 📋 位置已确定

与此同时,抢先试用计划中的开发者也对 Prompt API 表现出了极大的热情。在可预见的未来,此 API 的可用性将带来兼容性方面的挑战。

解决方案

因此,我们发布了一个实验性 符合规范Prompt API Polyfill(请参阅 GitHub 上的 源代码),该 Polyfill 在可配置的 后端提供商以及 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 后端除外,该后端不支持同时使用音频和图片,仅支持单独使用),并针对 完整的 Web 平台测试 套件对 LanguageModel 进行了测试。

如需了解更多背景信息和详细的使用信息以及源代码,请参阅 GitHub 代码库中的 README 文件

与浏览器 Prompt API 的区别

如果 Polyfill 由云模型提供支持,则在客户端运行的一些 优势 将不再适用。也就是说,您无法再保证敏感数据的本地处理,不过后端提供商的隐私权政策仍然适用。当用户处于离线状态时,您的应用也无法再使用 AI。如需了解您是处于在线状态还是离线状态,您可以监听相应的事件。

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

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

如果 AI 推理针对云中的模型运行,则无需下载本地模型。Polyfill 会伪造 downloadprogress 事件,因此对于您的应用,它会显示内置模型已下载,这意味着将有两个事件,一个事件的 loaded 值为 0,另一个事件的 loaded 值为 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.
}

当您直接从移动应用或 Web 应用调用云 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 中定义回退模型身份。当用户初始化会话而不指定特定 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

此验证步骤可确保您的后端完全按照 Prompt API 规范的要求处理 AbortSignal、系统提示和历史记录格式设置等内容。

总结

借助 Polyfill,您可以在所有平台和设备上使用 Prompt API。通过针对 Prompt API 的 定义明确的 API 进行编码,您可以让自己更加独立于云提供商,并尽可能贴近平台。

在支持 Prompt API 的设备上,Polyfill 甚至不会加载,因此您可以避免用户下载他们不会执行的代码。如果您有反馈或遇到 bug,请在 GitHub 上打开问题。希望您享受撰写提示的过程!

另请参阅

内置 AI 任务 API 的实验性 Polyfill