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 allgemeine Browser-API auf window.LanguageModel mit einem LLM interagieren. Die Unterstützung dafür ist jedoch noch begrenzt und die Implementierung ist ein komplexer Prozess.

Gleichzeitig haben Entwickler im Early-Access-Programm ihre Begeisterung für die Prompt API zum Ausdruck gebracht. Die Verfügbarkeit der API stellt in absehbarer Zukunft eine Herausforderung für die Kompatibilität dar.

Lösung

Aus diesem Grund veröffentlichen wir ein experimentelles spezifikationskonformes Prompt API-Polyfill (siehe den Quellcode auf GitHub), das die Prompt API genau auf konfigurierbaren Cloud-Backend-Anbietern und auch auf einem lokalen Backend-Anbieter in Form von Transformers.js 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 an die Cloud gesendet. Sie müssen jedoch nicht warten, bis ein lokales Modell verfügbar ist. Für alle anfallenden Kosten sind Sie 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. Für die lokale Verarbeitung fallen keine Kosten an.

Cloud-Backend

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

Geben Sie die Details in der Konfigurationsdatei .env.json ein, sobald Sie Ihren API-Schlüssel haben. Wenn Sie keinen modelName angeben, verwendet das Polyfill das Standardmodell des jeweiligen Backends. Andernfalls können Sie eines der unterstützten Modelle des jeweiligen Backends auswählen.

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

Lokales Backend

Wenn Sie sich für einen lokalen Backend-Anbieter auf Basis 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. Optional können Sie die Standardeinstellungen ä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 auswä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 entsprechend benannten globalen Variablen zu, wobei $BACKEND das von Ihnen ausgewählte Backend ist: window.$BACKEND_CONFIG.
2. Verwenden Sie einen dynamischen Import, um das Polyfill nur dann zu laden, wenn der zugrunde liegende Browser es nicht unterstützt.
3. Rufen Sie die Prompt API-Funktionen auf.

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 Ausgaben (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 wurde mit der vollständigen Web Platform Tests-Suite für das LanguageModel getestet.

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

Unterschied zur Prompt API des Browsers

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, obwohl die Datenschutzerklärungen Ihres Backend-Anbieters weiterhin gelten. Ihre App kann KI auch nicht mehr verwenden, wenn der Nutzer offline ist. Sie können auf die entsprechenden Ereignisse warten, 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 mit einem Modell in der Cloud ausgeführt wird, muss kein lokales Modell heruntergeladen werden. Das Polyfill simuliert die downloadprogress-Ereignisse, sodass es für Ihre App so aussieht, als wäre das integrierte Modell bereits heruntergeladen worden. Das bedeutet, dass es zwei Ereignisse gibt, eines mit dem Wert 0 für loaded und eines mit dem Wert 1. Das ist gemäß Spezifikation erforderlich.

Bei der cloudbasierten Inferenz fallen im Gegensatz zur Inferenz auf dem Gerät möglicherweise Kosten an, wenn Sie APIs von Ihrem bevorzugten Backend-Anbieter aufrufen. Informationen zu den Preisen finden Sie beispielsweise unter Gemini API-Preise. 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 Web-App aufrufen (z. B. die APIs, die Zugriff auf generative KI-Modelle ermöglichen), kann der API-Schlüssel von nicht autorisierten Clients missbraucht werden. Wenn Sie das Firebase AI Logic Hybrid SDK verwenden, sollten Sie Firebase App Check verwenden, 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 nur zulässige Websites die API verwenden können.

Anstelle der Beschränkungen der Prompt API, z. B. in Bezug auf das contextWindow der Sitzung, gelten die Beschränkungen des Backend-Anbieters. Für das contextWindow sind diese Beschränkungen in der Regel viel höher als auf dem Gerät und Sie können größere Datenmengen in der Cloud verarbeiten. Sie sollten sich zwar des Unterschieds bewusst sein, aber in der Praxis werden Sie 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 Klasse PolyfillBackend erweitern und die Kernmethoden implementieren, die die erwartete Schnittstelle erfüllen.

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 Strategie mit Priorität für die erste Übereinstimmung, 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 wird verwendet, wenn ein Nutzer eine Sitzung initialisiert, ohne einen bestimmten modelName anzugeben.

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

Lokale Entwicklung und Tests aktivieren

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

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

Mit Web Platform Tests (WPT) überprüfen

Im letzten Schritt müssen Sie die Konformität sicherstellen. 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, System-Prompts und die Formatierung des Verlaufs genau so verarbeitet, wie es in der Prompt API-Spezifikation erwartet wird.

Fazit

Mit dem Polyfill können Sie die Prompt API auf allen Plattformen und Geräten verwenden. Wenn Sie mit der genau definierten API der Prompt API programmieren, machen Sie sich 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 Ihre Nutzer keinen Code herunterladen, der nicht ausgeführt wird. Wenn Sie Feedback haben oder einen Fehler finden, erstellen Sie ein Problem auf GitHub. Viel Vergnügen!