Ein experimentelles Polyfill für die Prompt API

Thomas Steiner

Veröffentlicht am 14. Mai 2026

Mit der Prompt API in Chrome können Sie über eine Browser-API auf hoher Ebene auf window.LanguageModel mit einem LLM interagieren. Der Support für diese Funktion ist jedoch noch eingeschränkt und die Implementierung ist ein komplexer Prozess.

Gleichzeitig haben Entwickler im Programm für den Vorabzugriff ihre Begeisterung für die Prompt API zum Ausdruck gebracht. Die Verfügbarkeit der API stellt in absehbarer Zukunft eine Kompatibilitätsherausforderung dar.

Lösung

Aus diesem Grund veröffentlichen wir ein experimentelles spezifikationskonformes Prompt API-Polyfill (siehe Quellcode auf GitHub), das die Prompt API auf konfigurierbaren Cloud-Backend-Anbietern und auch auf einem lokalen-Backend-Anbieter in Form von Transformers.js genau implementiert.

Polyfill verwenden

So verwenden Sie das Polyfill:

1. Laden Sie das Polyfill von npm herunter:

   npm install prompt-api-polyfill
   

2. Wählen Sie aus, ob Sie einen Cloud-Backend-Anbieter oder einen lokalen Backend-Anbieter verwenden möchten:

   • Cloud-Backend-Anbieter:Nutzerdaten werden zur Remote-Verarbeitung in die Cloud gesendet. Sie müssen aber nicht warten, bis ein lokales Modell verfügbar ist. Sie sind für alle anfallenden Kosten gemäß den Preisinformationen Ihres Cloud-Anbieters verantwortlich.
   • Lokaler Backend-Anbieter:Nutzerdaten verbleiben im Browser und werden lokal verarbeitet. Sie müssen jedoch ein Modell herunterladen, das im Gegensatz zur echten Prompt API nicht für verschiedene Ursprünge freigegeben werden kann. Die lokale Verarbeitung ist kostenlos.

Cloud-Backend

Wählen Sie eines der Cloud-Back-Ends aus und rufen Sie einen API-Schlüssel (und alle zusätzlichen Anmeldedaten) für Ihren Back-End-Anbieter ab.

Sobald Sie Ihren API-Schlüssel haben, geben Sie die Details in Ihre Konfigurationsdatei .env.json ein. Wenn Sie kein modelName angeben, verwendet das Polyfill das Standardmodell des jeweiligen Back-Ends. Wenn Sie es angeben, können Sie eines der unterstützten Modelle des jeweiligen Back-Ends auswählen.

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

Lokales Backend

Wenn Sie sich für einen lokalen Backend-Anbieter auf Grundlage von Transformers.js entscheiden, benötigen Sie nur einen Dummy-API-Schlüssel. Sie können jedoch konfigurieren, welches Gerät von Transformers.js verwendet werden soll. Wählen Sie "webgpu" für maximale Leistung und "wasm" für maximale Kompatibilität aus. Sie können die Standardeinstellungen optional ändern. Wählen Sie ein anderes Modell aus dem Hugging Face-Katalog kompatibler Modelle aus. Bei einigen Modellen können Sie mit dem Parameter dtype zwischen verschiedenen Quantisierungen wählen.

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

Polyfill konfigurieren

Nachdem Sie die Konfigurationsdatei erstellt haben, können Sie das Polyfill in Ihrer App verwenden.

1. Importieren Sie die Konfigurationsdatei und weisen Sie sie einer globalen Variable mit einem passenden Namen zu. Dabei ist $BACKEND das von Ihnen ausgewählte Backend: window.$BACKEND_CONFIG.
2. Verwenden Sie einen dynamischen Import, um das Polyfill nur zu laden, wenn der zugrunde liegende Browser es nicht unterstützt.
3. Prompt API-Funktionen aufrufen

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

Das Polyfill unterstützt strukturierte Ausgabe (außer für das Transformers.js-Backend), verarbeitet multimodale Eingaben (außer für das OpenAI-Backend, das Audio und Bilder nicht zusammen, sondern nur separat unterstützt) und wird anhand der vollständigen Web Platform Tests für LanguageModel getestet.

Weitere Informationen und detaillierte Nutzungshinweise sowie den Quellcode finden Sie in der Datei README im GitHub-Repository.

Unterschied zur Browser Prompt API

Wenn das Polyfill von Cloud-Modellen unterstützt wird, gelten einige der Vorteile der clientseitigen Ausführung nicht mehr. Sie können die lokale Verarbeitung sensibler Daten nicht mehr garantieren, die Datenschutzerklärungen Ihres Backend-Anbieters gelten jedoch weiterhin. Ihre App kann KI auch nicht mehr verwenden, wenn der Nutzer offline ist. Sie können auf die entsprechenden Ereignisse achten, um herauszufinden, ob Sie online oder offline sind.

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

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

Wenn die KI-Inferenz für ein Modell in der Cloud ausgeführt wird, ist kein lokales Modell zum Herunterladen vorhanden. Das Polyfill simuliert die downloadprogress-Ereignisse. Für Ihre App sieht es also so aus, als wäre das integrierte Modell bereits heruntergeladen worden. Das bedeutet, dass es zwei Ereignisse gibt: eines mit dem loaded-Wert 0 und eines mit 1. Das ist gemäß Spezifikation erforderlich.

Im Gegensatz zur Inferenz auf dem Gerät fallen bei der cloudbasierten Inferenz möglicherweise Kosten an, wenn Sie APIs von Ihrem bevorzugten Backend-Anbieter aufrufen. Sehen Sie sich die Preisinformationen an, z. B. für die Gemini API. Wenn Sie die Kosten pro Token kennen, können Sie die Kosten anhand der contextUsage-Informationen der Prompt API berechnen.

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

Wenn Sie eine Cloud-API direkt über eine mobile App oder Webanwendung aufrufen (z. B. die APIs, die den Zugriff auf generative KI-Modelle ermöglichen), ist der API-Schlüssel anfällig für Missbrauch durch nicht autorisierte Clients. Um diese APIs zu schützen, sollten Sie Firebase App Check verwenden, wenn Sie das Firebase AI Logic Hybrid SDK nutzen, um zu überprüfen, ob alle eingehenden API-Aufrufe von Ihrer tatsächlichen App stammen. Bei einigen Cloud-Anbietern wie Google können Sie auch strenge Ursprungsprüfungen erzwingen, um sicherzustellen, dass die API nur von zulässigen Websites verwendet werden kann.

Anstelle der Limits der Prompt API, z. B. in Bezug auf die contextWindow der Sitzung, gelten die Limits des Backend-Anbieters. Für contextWindow sind diese Grenzwerte in der Regel viel höher als auf dem Gerät. Sie können größere Datenmengen in der Cloud verarbeiten. Daher sollten Sie sich zwar des Unterschieds bewusst sein, in der Praxis werden Sie aber wahrscheinlich keine Probleme damit haben.

Eigenes Backend erstellen

So fügen Sie einen eigenen Backend-Anbieter hinzu:

Basis-Backend-Klasse erweitern

Erstellen Sie im Verzeichnis backends/ eine neue Datei, z. B. backends/custom-backend.js. Sie müssen die PolyfillBackend-Klasse erweitern und die Kernmethoden implementieren, die der erwarteten Schnittstelle entsprechen.

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

Backend registrieren

Das Polyfill verwendet eine „First-Match Priority“-Strategie, die auf der globalen Konfiguration basiert. Sie müssen Ihr Backend in der Datei prompt-api-polyfill.js registrieren, indem Sie es dem statischen Array #backends hinzufügen:

// prompt-api-polyfill.js
static #backends = [
  // ... existing backends
  {
    config: 'CUSTOM_CONFIG', // The global object to look for on `window`
    path: './backends/custom-backend.js',
  },
];

Standardmodell festlegen

Definieren Sie die Fallback-Modellidentität in backends/defaults.js. Diese Option wird verwendet, wenn ein Nutzer eine Sitzung initialisiert, ohne ein bestimmtes modelName anzugeben.

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

Lokale Entwicklung und Tests aktivieren

Im Projekt wird ein Erkennungsskript (scripts/list-backends.js) verwendet, um Testmatrizen zu generieren. Wenn Sie Ihr neues Backend in den Test-Runner aufnehmen möchten, erstellen Sie im Stammverzeichnis eine .env-[name].json-Datei (z. B. .env-custom.json):

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

Mit Web Platform Tests (WPT) prüfen

Im letzten Schritt müssen Sie für die Einhaltung der Spezifikationen sorgen. Da das Polyfill spezifikationsbasiert ist, sollte jedes neue Backend die offiziellen (oder vorläufigen) Web Platform Tests bestehen:

npm run test:wpt

Mit diesem Überprüfungsschritt wird sichergestellt, dass Ihr Backend Dinge wie AbortSignal, Systemprompts und die Formatierung des Verlaufs genau wie in der Prompt API-Spezifikation erwartet behandelt.

Fazit

Das Polyfill hilft Ihnen, die Prompt API auf allen Plattformen und Geräten zu verwenden. Wenn Sie die gut definierte API der Prompt API verwenden, sind Sie unabhängiger von Cloud-Anbietern und bleiben so nah wie möglich an der Plattform.

Auf Geräten, die die Prompt API unterstützen, wird das Polyfill nicht einmal geladen. So müssen Nutzer keinen Code herunterladen, der nicht ausgeführt wird. Wenn Sie Feedback haben oder auf einen Fehler stoßen, erstellen Sie ein Problem auf GitHub. Viel Vergnügen!

Weitere Informationen

Experimentelle Polyfills für die integrierten APIs für KI-Aufgaben