Eksperymentalny polyfill interfejsu Prompt API

Thomas Steiner

Data publikacji: 14 maja 2026 r.

Interfejs Prompt API w Chrome umożliwia interakcję z LLM za pomocą interfejsu API przeglądarki wysokiego poziomu na window.LanguageModel. Jednak obsługa tego rozwiązania jest nadal ograniczona, a jego wdrożenie jest złożonym procesem.

Jednocześnie deweloperzy uczestniczący w programie wcześniejszego dostępu wyrazili swój entuzjazm w związku z interfejsem Prompt API. Dostępność interfejsu API stanowi wyzwanie związane ze zgodnością w przewidywalnej przyszłości.

Rozwiązanie

Dlatego udostępniamy eksperymentalny zgodny ze specyfikacją kod polyfill interfejsu Prompt API (zobacz kod źródłowy w GitHubie), który dokładnie implementuje interfejs Prompt API na podstawie konfigurowalnych dostawców backendu w chmurze, a także na podstawie dostawcy backendu lokalnego w postaci Transformers.js.

Używanie polyfillu

Aby użyć kodu polyfill, wykonaj następujące czynności:

1. Pobierz polyfill z npm:

   npm install prompt-api-polyfill
   

2. Wybierz, czy chcesz używać dostawcy backendu w chmurze czy lokalnego dostawcy backendu:

   • Dostawca backendu w chmurze: dane użytkownika są wysyłane do chmury w celu zdalnego przetwarzania, ale nie musisz czekać na dostępność modelu lokalnego. Ponosisz odpowiedzialność za wszelkie poniesione koszty zgodnie z informacjami o cenach dostawcy chmury.
   • Lokalny dostawca backendu: dane użytkownika pozostają w przeglądarce i są przetwarzane lokalnie, ale musisz pobrać model, którego w przeciwieństwie do prawdziwego interfejsu Prompt API nie można udostępniać w różnych źródłach. Lokalne przetwarzanie danych nie wiąże się z żadnymi kosztami.

Backend w chmurze

Wybierz dowolny backend w chmurze i uzyskaj klucz interfejsu API (oraz wszelkie dodatkowe dane logowania) dla dostawcy backendu.

Gdy uzyskasz klucz interfejsu API, wpisz szczegóły w pliku konfiguracyjnym .env.json. Jeśli nie określisz parametru modelName, polyfill użyje domyślnego modelu każdego backendu. Jeśli jednak to zrobisz, możesz wybrać jeden z obsługiwanych modeli każdego backendu.

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

Lokalny backend

Jeśli zdecydujesz się na lokalnego dostawcę backendu opartego na Transformers.js, potrzebujesz tylko fikcyjnego klucza API. Możesz jednak skonfigurować, jakiego urządzenia ma używać Transformers.js. Wybierz "webgpu", aby uzyskać maksymalną wydajność, a "wasm", aby uzyskać maksymalną zgodność. Możesz opcjonalnie zmienić ustawienia domyślne. Wybierz inny model z katalogu zgodnych modeli Hugging Face. W przypadku niektórych modeli możesz wybrać różne kwantyzacje za pomocą parametru dtype.

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

Konfigurowanie kodu polyfill

Gdy plik konfiguracji będzie gotowy, możesz zacząć używać polyfill w aplikacji.

1. Zaimportuj plik konfiguracji i przypisz go do odpowiednio nazwanej zmiennej globalnej, gdzie $BACKEND to wybrany backend: window.$BACKEND_CONFIG.
2. Użyj dynamicznego importu, aby wczytywać polyfill tylko wtedy, gdy przeglądarka nie obsługuje tej funkcji.
3. Wywoływanie funkcji 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 obsługuje dane wyjściowe o strukturze (z wyjątkiem backendu Transformers.js), radzi sobie z danymi wejściowymi multimodalnymi (z wyjątkiem backendu OpenAI, który nie obsługuje jednocześnie dźwięku i obrazu, tylko oddzielnie) i jest testowany w ramach pełnego pakietu testów platformy internetowej dla LanguageModel.

Więcej informacji o kontekście i szczegółach użycia, a także kod źródłowy znajdziesz w pliku README w repozytorium GitHub.

Różnica w stosunku do interfejsu Prompt API w przeglądarce

Jeśli kod polyfill jest oparty na modelach w chmurze, niektóre korzyści działania po stronie klienta nie mają już zastosowania. Nie możesz już zagwarantować lokalnego przetwarzania danych wrażliwych, ale nadal obowiązują polityki prywatności dostawcy backendu. Gdy użytkownik jest offline, aplikacja nie może też korzystać z AI. Aby sprawdzić, czy jesteś online czy offline, możesz nasłuchiwać odpowiednich zdarzeń.

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

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

Jeśli wnioskowanie AI jest przeprowadzane na modelu w chmurze, nie ma lokalnego modelu do pobrania. Polyfill symuluje zdarzenia downloadprogress, więc w aplikacji będzie wyglądać tak, jakby wbudowany model został już pobrany. Oznacza to, że będą 2 zdarzenia: jedno z wartością loaded równą 0 i jedno z wartością 1, co jest wymagane przez specyfikację.

W przypadku wnioskowania w chmurze, w przeciwieństwie do wnioskowania na urządzeniu, wywoływanie interfejsów API od wybranego dostawcy backendu może wiązać się z kosztami. Sprawdź informacje o cenach, np. Gemini API. Jeśli znasz koszt za token, możesz użyć informacji contextUsage z interfejsu Prompt API, aby obliczyć koszt.

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

Gdy wywołujesz interfejs API w chmurze bezpośrednio z aplikacji mobilnej lub internetowej (np. interfejsy API, które umożliwiają dostęp do modeli generatywnej AI), klucz interfejsu API jest narażony na nadużycia ze strony nieautoryzowanych klientów. Aby chronić te interfejsy API, jeśli używasz hybrydowego pakietu SDK Firebase AI Logic, musisz używać Sprawdzania aplikacji Firebase, aby weryfikować, czy wszystkie przychodzące wywołania interfejsu API pochodzą z Twojej aplikacji. W przypadku niektórych dostawców usług w chmurze, takich jak Google, możesz też wymuszać ścisłe sprawdzanie pochodzenia, aby mieć pewność, że z interfejsu API mogą korzystać tylko dozwolone witryny.

Zamiast limitów interfejsu Prompt API, np. dotyczących contextWindow sesji, obowiązują limity dostawcy backendu. W przypadku contextWindow limity te są zwykle znacznie wyższe niż na urządzeniu i możesz przetwarzać większe ilości danych w chmurze. Chociaż warto znać tę różnicę, w praktyce prawdopodobnie nie napotkasz z tego powodu problemów.

Tworzenie własnego backendu

Aby dodać własnego dostawcę backendu, wykonaj te czynności:

Rozszerzanie podstawowej klasy backendu

Utwórz nowy plik w katalogu backends/, np. backends/custom-backend.js. Musisz rozszerzyć klasę PolyfillBackend i wdrożyć podstawowe metody, które spełniają wymagania interfejsu.

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

Rejestrowanie backendu

Polyfill używa strategii „Pierwsze dopasowanie wygrywa” opartej na konfiguracji globalnej. Musisz zarejestrować backend w pliku prompt-api-polyfill.js, dodając go do statycznej tablicy #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',
  },
];

Ustawianie modelu domyślnego

Zdefiniuj tożsamość modelu rezerwowego w polu backends/defaults.js. Używane, gdy użytkownik inicjuje sesję bez podawania konkretnego modelName.

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

Włączanie lokalnego programowania i testowania

Projekt używa skryptu wykrywania (scripts/list-backends.js) do generowania macierzy testowych. Aby uwzględnić nowy backend w programie do uruchamiania testów, utwórz w katalogu głównym plik .env-[name].json (np. .env-custom.json):

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

Weryfikacja za pomocą testów platformy internetowej (WPT)

Ostatnim krokiem jest zapewnienie zgodności. Ponieważ polyfill jest zgodny ze specyfikacją, każdy nowy backend powinien przejść oficjalne (lub wstępne) testy platformy internetowej:

npm run test:wpt

Ten krok weryfikacji zapewnia, że backend obsługuje takie elementy jak AbortSignal, prompt systemowy i formatowanie historii dokładnie tak, jak tego wymaga specyfikacja Prompt API.

Podsumowanie

Polyfill pomaga korzystać z interfejsu Prompt API na wszystkich platformach i urządzeniach. Dzięki programowaniu z użyciem dobrze zdefiniowanego interfejsu API Prompt API możesz uniezależnić się od dostawców usług w chmurze i pozostać jak najbliżej platformy.

Na urządzeniach obsługujących interfejs Prompt API polyfill nie jest nawet wczytywany, więc użytkownicy nie muszą pobierać kodu, który nie zostanie wykonany. Jeśli masz opinię lub napotkasz błąd, zgłoś problem na GitHubie. Udanego pisania promptów!