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

Prompt API в Chrome позволяет взаимодействовать с LLM через высокоуровневый браузерный API window.LanguageModel. Однако поддержка пока ограничена, а реализация остается сложным процессом.

Браузер	Поддерживаемые ОС	Неподдерживаемые ОС	Статус
Chrome	Windows, macOS, Linux, ChromeOS (Chromebook Plus)	Android, iOS	✅ Поддерживается
Edge	Windows, macOS	Android, iOS	✅ Поддерживается
Safari	---	---	📋 Позиция определена
Firefox	---	---	📋 Позиция определена

В то же время разработчики из программы раннего доступа уже поделились своим интересом к Prompt API. Доступность API создает проблему совместимости на обозримое будущее.

Решение¶

Именно поэтому мы выпускаем экспериментальный полифилл Prompt API, соответствующий спецификации (исходный код доступен на GitHub). Он точно реализует Prompt API поверх настраиваемых облачных бэкендов, а также поверх локального бэкенда на базе Transformers.js.

Примечание:

Для production-использования мы рекомендуем напрямую применять Firebase AI Logic Hybrid SDK.

Использование полифилла¶

Чтобы использовать полифилл:

Установите полифилл из npm:
1
npm install prompt-api-polyfill
Выберите облачный или локальный бэкенд:
- Облачный бэкенд: пользовательские данные отправляются в облако для удаленной обработки, зато не нужно ждать доступности локальной модели. Вы отвечаете за возможные расходы согласно тарифам вашего облачного провайдера.
- Локальный бэкенд: пользовательские данные остаются в браузере и обрабатываются локально, но нужно скачать модель. В отличие от настоящего Prompt API, такую модель нельзя разделять между разными origin. При локальной обработке расходов нет.

Облачный бэкенд¶

Выберите один из облачных бэкендов и получите API-ключ, а при необходимости и дополнительные учетные данные.

Когда API-ключ готов, укажите данные в конфигурационном файле .env.json. Если не задать modelName, полифилл будет использовать модель по умолчанию для выбранного бэкенда. Если задать modelName, можно выбрать одну из поддерживаемых моделей этого бэкенда.

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

Предупреждение:

Firebase AI Logic Hybrid SDK с App Check — самый безопасный способ обеспечить работу Prompt API. Только App Check защищает ваш API-ключ от несанкционированного использования. Не раскрывайте напрямую ключи Gemini или OpenAI API.

Локальный бэкенд¶

Если вы выбираете локальный бэкенд на базе 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"
};

Настройка полифилла¶

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

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

Вызывайте функции Prompt API.

import config from './.env.json' with { type: 'json' };

// Установите $BACKEND_CONFIG, чтобы выбрать бэкенд
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!');

Полифилл поддерживает структурированный вывод, кроме бэкенда Transformers.js, работает с мультимодальным вводом, кроме бэкенда OpenAI, который не поддерживает аудио и изображение вместе, только по отдельности, и тестируется на полном наборе Web Platform Tests для LanguageModel.

Дополнительные сведения, подробности использования и исходный код смотрите в README в GitHub-репозитории.

Отличия от браузерного Prompt API¶

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

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

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

Если AI-инференс выполняется на модели в облаке, локальную модель скачивать не нужно. Полифилл имитирует события downloadprogress, поэтому для приложения будет выглядеть так, будто встроенная модель уже скачана. Это означает два события: одно со значением loaded равным 0, второе — 1, как и требует спецификация.

При облачном инференсе, в отличие от выполнения на устройстве, вызовы API выбранного бэкенд-провайдера могут стоить денег. Проверьте тарифы, например цены Gemini API. Если вы знаете стоимость одного токена, можно использовать информацию contextUsage из Prompt API для расчета расходов.

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 {
    // Показать промо премиального AI-тарифа.
}

Когда облачный API вызывается напрямую из мобильного или веб-приложения, например API для доступа к генеративным AI-моделям, API-ключ уязвим для злоупотреблений со стороны неавторизованных клиентов. Чтобы защитить такие API, при использовании Firebase AI Logic Hybrid SDK следует применять Firebase App Check, который проверяет, что все входящие API-вызовы действительно исходят от вашего приложения. У некоторых облачных провайдеров, например Google, также можно включить строгую проверку origin, чтобы 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 обычно берется из глобального объекта window,
        // например window.CUSTOM_CONFIG
        super(config.modelName || DEFAULT_MODELS.custom.modelName);
    }

    // Проверяет, настроен ли бэкенд, например есть ли API-ключ,
    // поддерживаются ли заданные комбинации modelName и options,
    // или, для локальной модели, доступна ли модель.
    static availability(options) {
        return window.CUSTOM_CONFIG?.apiKey ? 'available' : 'unavailable';
    }

    // Инициализирует нижележащий SDK или API-клиент. Для локальных моделей
    // используйте monitorTarget, чтобы сообщать полифиллу
    // о прогрессе скачивания модели.
    createSession(options, sessionParams, monitorTarget) {
        // Вернуть инициализированную сессию или экземпляр клиента
    }

    // Выполнение prompt без стриминга
    async generateContent(contents) {
        // contents: Array of { role: 'user'|'model', parts: [{ text: string }] }
        // Return: { text: string, usage: number }
    }

    // Выполнение prompt со стримингом
    async generateContentStream(contents) {
        // Return: AsyncIterable yielding chunks
    }

    // Подсчет токенов для отслеживания квот и использования
    async countTokens(contents) {
        // Return: total token count (number)
    }
}

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

Полифилл использует стратегию First-Match Priority на основе глобальной конфигурации. Нужно зарегистрировать бэкенд в файле prompt-api-polyfill.js, добавив его в статический массив #backends:

// prompt-api-polyfill.js
static #backends = [
    // ... существующие бэкенды
    {
    config: 'CUSTOM_CONFIG', // Глобальный объект, который нужно искать в `window`
    path: './backends/custom-backend.js',
    },
];

Задайте модель по умолчанию¶

Определите резервный идентификатор модели в backends/defaults.js. Он используется, когда пользователь инициализирует сессию без конкретного modelName.

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

Включите локальную разработку и тестирование¶

Проект использует discovery-скрипт scripts/list-backends.js для генерации тестовых матриц. Чтобы включить новый бэкенд в тестовый раннер, создайте файл .env-[name].json, например .env-custom.json, в корне проекта:

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

Проверьте через Web Platform Tests (WPT)¶

Последний шаг — убедиться в соответствии спецификации. Поскольку полифилл основан на спецификации, любой новый бэкенд должен проходить официальные или предварительные Web Platform Tests:

1	`npm run test:wpt`

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

Заключение¶

Полифилл помогает использовать Prompt API на всех платформах и устройствах. Разрабатывая поверх четко определенного API Prompt API, вы становитесь более независимыми от облачных провайдеров и остаетесь максимально близко к платформе.

На устройствах, которые поддерживают Prompt API, полифилл вообще не загружается, поэтому пользователям не приходится скачивать код, который не будет выполняться. Если у вас есть обратная связь или вы столкнулись с ошибкой, создайте Issue на GitHub. Удачного prompting!

Источник: https://developer.chrome.com/docs/ai/prompt-api-polyfill