Экспериментальный полифил для API Prompt.

Thomas Steiner

Опубликовано: 14 мая 2026 г.

With the Prompt API in Chrome, you can interact with an LLM using a high-level browser API on window.LanguageModel . However there is still limited support for this and implementation is a complex process.

At the same time, developers in the early preview program have shared their enthusiasm for the Prompt API. The availability of the API poses a compatibility challenge for the foreseeable future.

Решение

This is why we are releasing an experimental spec-compliant Prompt API polyfill (see the source code on GitHub) that accurately implements the Prompt API on top of configurable cloud backend providers and also on top of a local backend provider in the form of Transformers.js .

Используйте полифил.

Для использования полифила выполните следующие действия:

1. Скачайте полифилл из npm :

   npm install prompt-api-polyfill
   

2. Выберите, хотите ли вы использовать облачного или локального поставщика серверной части:

   • Cloud backend provider: User data is sent to the cloud for remote processing, but you don't have to wait for a local model to be available. You are responsible for any incurred cost according to the pricing information of your cloud provider.
   • Local backend provider: User data stays in the browser and is processed locally, but you need to download a model, which, unlike with the real Prompt API, can't be shared across different origins. There's no cost involved with local processing.

Облачная серверная часть

Выберите любой из облачных бэкэндов и получите ключ API (а также любые дополнительные учетные данные) для вашего поставщика бэкэнда.

Once you have your API key, enter the details in your configuration file .env.json . If you don't specify a modelName , the polyfill will use each backend's default model, but if you do, you can select one of the supported models of each backend.

{
  "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"
};

Настройте свой полифил

После того, как файл конфигурации будет готов, вы можете начать использовать полифилл в своем приложении.

1. Импортируйте файл конфигурации и присвойте его глобальной переменной с соответствующим именем, где $BACKEND — это выбранный вами бэкенд: window.$BACKEND_CONFIG .
2. Используйте динамический импорт, чтобы загружать полифилл только в том случае, если используемый браузер его не поддерживает.
3. Вызовите функции API Prompt .

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!');

The polyfill supports structured output (except for the Transformers.js backend), deals with multimodal input (except for the OpenAI backend that doesn't support audio and image together, only separately), and is tested against the complete Web Platform Tests suite for the LanguageModel .

Более подробную информацию об использовании, а также исходный код можно найти в файле README в репозитории GitHub .

Отличие от API подсказок браузера

Если полифил использует облачные модели, некоторые преимущества работы на стороне клиента перестают действовать. В частности, вы больше не можете гарантировать локальную обработку конфиденциальных данных, хотя политика конфиденциальности вашего бэкэнд-провайдера по-прежнему применяется. Ваше приложение также больше не сможет использовать ИИ, когда пользователь находится в автономном режиме. Чтобы узнать, подключены вы к сети или нет, вы можете отслеживать соответствующие события.

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

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

If the AI inference runs against a model in the cloud, there is no local model to download. The polyfill fakes the downloadprogress events, so to your app it will appear as if the built-in model was already downloaded, which means there will be two events, one with a loaded value of 0 and one with 1 , which is what the spec requires.

With cloud-based inference, unlike with on-device inference, there's a potential cost involved when calling APIs from your backend provider of choice. Check the pricing information, like the one for Gemini API . If you know the cost per token, you can use the Prompt API's contextUsage information to calculate the cost.

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.
}

При прямом вызове облачного API из мобильного или веб-приложения (например, API, предоставляющие доступ к моделям генеративного ИИ) ключ API уязвим для злоупотреблений со стороны неавторизованных клиентов. Для защиты таких API, если вы используете Firebase AI Logic Hybrid SDK, следует использовать Firebase App Check , чтобы убедиться, что все входящие вызовы API поступают из вашего приложения. У некоторых облачных провайдеров, таких как Google, также можно применять строгие проверки источника, чтобы гарантировать, что API могут использовать только разрешенные веб-сайты .

Rather than the limits of the Prompt API, for example, regarding the session's contextWindow , the limits of the backend provider apply. For the contextWindow , these limits are typically a lot higher than on-device, and you can process larger amounts of data in the cloud, so while you should be aware of the difference, in practice, you likely won't run into problems with this.

Создайте собственную серверную часть.

Чтобы добавить собственный бэкэнд-провайдер, выполните следующие шаги:

Расширьте базовый класс бэкэнда.

Create a new file in the backends/ directory, for example, backends/custom-backend.js . You need to extend the PolyfillBackend class and implement the core methods that satisfy the expected interface.

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)
  }
}

Зарегистрируйте свой бэкэнд

The polyfill uses a "First-Match Priority" strategy based on global configuration. You need to register your backend in the prompt-api-polyfill.js file by adding it to the static #backends array:

// 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',
};

Обеспечьте локальную разработку и тестирование.

The project uses a discovery script ( scripts/list-backends.js ) to generate test matrixes. To include your new backend in the test runner, create a .env-[name].json file (for example, .env-custom.json ) in the root directory:

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

Проверьте с помощью тестов веб-платформы (WPT).

Последний шаг — обеспечение соответствия требованиям. Поскольку полифилл основан на спецификации, любой новый бэкенд должен пройти официальные (или предварительные) тесты веб-платформы:

npm run test:wpt

Этот этап проверки гарантирует, что ваш бэкэнд обрабатывает такие вещи, как AbortSignal , системные подсказки и форматирование истории, точно так, как ожидает спецификация Prompt API.

Заключение

The polyfill helps you use the Prompt API on all platforms and devices. By coding against the Prompt API's well-defined API , you make yourself more independent from cloud providers and stay as close to the platform as possible.

On capable devices that support the Prompt API, the polyfill isn't even loaded, so you spare your users from downloading code they won't execute. If you have feedback or run into a bug, open an Issue on GitHub. Happy prompting!