Een experimentele polyfill voor de Prompt API

Thomas Steiner

Gepubliceerd: 14 mei 2026

Met de Prompt API in Chrome kun je via een geavanceerde browser-API op window.LanguageModel communiceren met een LLM. De ondersteuning hiervoor is echter nog beperkt en de implementatie is een complex proces.

Tegelijkertijd hebben ontwikkelaars in het vroege previewprogramma hun enthousiasme voor de Prompt API gedeeld. De beschikbaarheid van de API vormt voor de nabije toekomst een compatibiliteitsuitdaging.

Oplossing

Daarom brengen we een experimentele, aan de specificaties voldoenende Prompt API-polyfill uit (zie de broncode op GitHub) die de Prompt API nauwkeurig implementeert bovenop configureerbare cloudbackendproviders en ook bovenop een lokale backendprovider in de vorm van Transformers.js .

Gebruik de polyestervulling.

Om de polyfill te gebruiken, ga als volgt te werk:

1. Download de polyfill via npm :

   npm install prompt-api-polyfill
   

2. Kies of u een cloudbackendprovider of een lokale backendprovider wilt gebruiken:

   • Cloudbackendprovider: Gebruikersgegevens worden naar de cloud verzonden voor verwerking op afstand, maar u hoeft niet te wachten tot een lokaal model beschikbaar is. U bent verantwoordelijk voor alle gemaakte kosten volgens de prijsinformatie van uw cloudprovider.
   • Lokale backend-provider: Gebruikersgegevens blijven in de browser en worden lokaal verwerkt, maar u moet een model downloaden dat, in tegenstelling tot de echte Prompt API, niet kan worden gedeeld tussen verschillende bronnen. Lokale verwerking brengt geen kosten met zich mee.

Cloud-backend

Kies een van de cloudbackends en ontvang een API-sleutel (en eventuele aanvullende inloggegevens) voor uw backendprovider.

Zodra je je API-sleutel hebt, voer je de gegevens in je configuratiebestand .env.json in. Als je geen modelName opgeeft, gebruikt de polyfill het standaardmodel van elke backend. Als je dat wel doet, kun je een van de ondersteunde modellen van elke backend selecteren.

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

Lokale backend

Als u kiest voor een lokale backend-provider op basis van Transformers.js, heeft u alleen een dummy API-sleutel nodig. U kunt echter wel configureren welk apparaat Transformers.js moet gebruiken. Kies "webgpu" voor maximale prestaties en "wasm" voor maximale compatibiliteit. U kunt de standaardinstellingen eventueel wijzigen. Kies een ander model uit de Hugging Face-catalogus met compatibele modellen . Voor sommige modellen kunt u verschillende kwantiseringen selecteren met behulp van de parameter dtype .

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

Configureer uw polyfill

Nu het configuratiebestand is aangemaakt, kunt u de polyfill in uw app gaan gebruiken.

1. Importeer het configuratiebestand en wijs het toe aan een globale variabele met een passende naam, waarbij $BACKEND de door u gekozen backend is: window.$BACKEND_CONFIG .
2. Gebruik een dynamische import om de polyfill alleen te laden wanneer de onderliggende browser deze niet ondersteunt.
3. Roep de Prompt API-functies aan .

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

De polyfill ondersteunt gestructureerde uitvoer (met uitzondering van de Transformers.js-backend), kan multimodale invoer verwerken (met uitzondering van de OpenAI-backend die geen ondersteuning biedt voor audio en beeld samen, maar alleen afzonderlijk), en is getest met de volledige Web Platform Tests- suite voor het LanguageModel .

Voor meer achtergrondinformatie, gedetailleerde gebruiksaanwijzingen en de broncode, zie het README bestand in de GitHub-repository .

Verschil met de Prompt API van de browser

Als de polyfill gebruikmaakt van cloudmodellen, vervallen sommige voordelen van client-side implementatie . Zo kunt u bijvoorbeeld de lokale verwerking van gevoelige gegevens niet langer garanderen, hoewel het privacybeleid van uw backendprovider nog steeds van toepassing is. Uw app kan ook geen AI meer gebruiken wanneer de gebruiker offline is. Om te bepalen of u online of offline bent, kunt u luisteren naar de bijbehorende gebeurtenissen.

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

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

Als de AI-inferentie wordt uitgevoerd met een model in de cloud, is er geen lokaal model om te downloaden. De polyfill simuleert de downloadprogress gebeurtenissen, waardoor het voor uw app lijkt alsof het ingebouwde model al is gedownload. Dit betekent dat er twee gebeurtenissen zullen zijn, één met een loaded waarde van 0 en één met een waarde van 1 , wat voldoet aan de specificaties.

Bij cloudgebaseerde inferentie, in tegenstelling tot inferentie op het apparaat zelf, zijn er potentiële kosten verbonden aan het aanroepen van API's van uw gekozen backendprovider. Controleer de prijsinformatie, bijvoorbeeld die van de Gemini API . Als u de kosten per token weet, kunt u de contextUsage informatie van de Prompt API gebruiken om de kosten te berekenen.

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

Wanneer je een cloud-API rechtstreeks vanuit een mobiele of webapp aanroept (bijvoorbeeld de API's die toegang bieden tot generatieve AI-modellen), is de API-sleutel kwetsbaar voor misbruik door onbevoegde clients. Om deze API's te beschermen, is het raadzaam om, als je de Firebase AI Logic Hybrid SDK gebruikt, Firebase App Check in te zetten om te controleren of alle inkomende API-aanroepen daadwerkelijk van je app afkomstig zijn. Bij sommige cloudproviders, zoals Google, kun je bovendien strikte herkomstcontroles afdwingen om ervoor te zorgen dat alleen geautoriseerde websites de API kunnen gebruiken.

In plaats van de beperkingen van de Prompt API, bijvoorbeeld met betrekking tot het contextWindow van de sessie, gelden hier de beperkingen van de backendprovider. Voor het contextWindow zijn deze limieten doorgaans veel hoger dan op het apparaat zelf, en je kunt grotere hoeveelheden data in de cloud verwerken. Hoewel je je dus bewust moet zijn van het verschil, zul je er in de praktijk waarschijnlijk geen problemen mee ondervinden.

Ontwikkel je eigen backend.

Volg deze stappen om uw eigen backend-provider toe te voegen:

Breid de basis backend-klasse uit

Maak een nieuw bestand aan in de map backends/ , bijvoorbeeld backends/custom-backend.js . Je moet de klasse PolyfillBackend uitbreiden en de kernmethoden implementeren die voldoen aan de verwachte 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)
  }
}

Registreer je backend

De polyfill gebruikt een "First-Match Priority"-strategie op basis van de globale configuratie. Je moet je backend registreren in het prompt-api-polyfill.js -bestand door deze toe te voegen aan de statische #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',
  },
];

Stel een standaardmodel in.

Definieer de fallback-modelidentiteit in backends/defaults.js . Deze wordt gebruikt wanneer een gebruiker een sessie initialiseert zonder een specifieke modelName op te geven.

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

Maak lokale ontwikkeling en testen mogelijk.

Het project maakt gebruik van een discovery-script ( scripts/list-backends.js ) om testmatrices te genereren. Om je nieuwe backend in de testrunner op te nemen, maak je een .env-[name].json bestand (bijvoorbeeld .env-custom.json ) aan in de hoofdmap:

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

Verifieer met Web Platform Tests (WPT)

De laatste stap is het waarborgen van de naleving. Omdat de polyfill gebaseerd is op specificaties, moet elke nieuwe backend de officiële (of voorlopige) webplatformtests doorstaan:

npm run test:wpt

Deze verificatiestap zorgt ervoor dat uw backend zaken als AbortSignal , systeemprompts en geschiedenisopmaak precies afhandelt zoals de Prompt API-specificatie voorschrijft.

Conclusie

Met de polyfill kunt u de Prompt API op alle platforms en apparaten gebruiken. Door te programmeren met de goed gedefinieerde API van de Prompt API, wordt u onafhankelijker van cloudproviders en blijft u zo dicht mogelijk bij het platform.

Op geschikte apparaten die de Prompt API ondersteunen, wordt de polyfill niet eens geladen, waardoor je je gebruikers behoedt voor het downloaden van code die ze niet zullen uitvoeren. Als je feedback hebt of een bug tegenkomt, open dan een Issue op GitHub. Veel plezier met prompts!